The automatic schema generation feature of the Enterprise Server defines database tables based on the fields or properties in entities and the relationships between the fields or properties. This insulates developers from many of the database related aspects of development, allowing them to focus on entity development. The resulting schema is usable as-is or can be given to a database administrator for tuning with respect to performance, security, and so on. This section covers the following topics:
Automatic schema generation is supported on an all-or-none basis: it expects that no tables exist in the database before it is executed. It is not intended to be used as a tool to generate extra tables or constraints.
Deployment won't fail if all tables are not created, and undeployment won't fail if not all tables are dropped. Instead, an error is written to the server log. This is done to allow you to investigate the problem and fix it manually. You should not rely on the partially created database schema to be correct for running the application.
The following annotations are used in automatic schema generation: @AssociationOverride, @AssociationOverrides, @AttributeOverride, @AttributeOverrides, @Column, @DiscriminatorColumn, @DiscriminatorValue, @Embedded, @EmbeddedId, @GeneratedValue, @Id, @IdClass, @JoinColumn, @JoinColumns, @JoinTable, @Lob, @ManyToMany, @ManyToOne, @OneToMany, @OneToOne, @PrimaryKeyJoinColumn, @PrimaryKeyJoinColumns, @SecondaryTable, @SecondaryTables, @SequenceGenerator, @Table, @TableGenerator, @UniqueConstraint, and @Version. For information about these annotations, see the Java Persistence Specification.
For @Column annotations, the insertable and updatable elements are not used in automatic schema generation.
For @OneToMany and @ManyToOne annotations, no ForeignKeyConstraint is created in the resulting DDL files.
The following table shows mappings of Java types to SQL types when the default persistence provider and automatic schema generation are used.
Table 7–1 Java Type to SQL Type Mappings
Java Type |
Java DB, Derby, CloudScape |
Oracle |
DB2 |
Sybase |
MS-SQL Server |
MySQL Server |
---|---|---|---|---|---|---|
boolean, java.lang.Boolean |
SMALLINT |
NUMBER(1) |
SMALLINT |
BIT |
BIT |
TINYINT(1) |
int, java.lang.Integer |
INTEGER |
NUMBER(10) |
INTEGER |
INTEGER |
INTEGER |
INTEGER |
long, java.lang.Long |
BIGINT |
NUMBER(19) |
INTEGER |
NUMERIC(19) |
NUMERIC(19) |
BIGINT |
float, java.lang.Float |
FLOAT |
NUMBER(19,4) |
FLOAT |
FLOAT(16) |
FLOAT(16) |
FLOAT |
double, java.lang.Double |
FLOAT |
NUMBER(19,4) |
FLOAT |
FLOAT(32) |
FLOAT(32) |
DOUBLE |
short, java.lang.Short |
SMALLINT |
NUMBER(5) |
SMALLINT |
SMALLINT |
SMALLINT |
SMALLINT |
byte, java.lang.Byte |
SMALLINT |
NUMBER(3) |
SMALLINT |
SMALLINT |
SMALLINT |
SMALLINT |
java.lang.Number |
DECIMAL |
NUMBER(38) |
DECIMAL(15) |
NUMERIC(38) |
NUMERIC(28) |
DECIMAL(38) |
java.math.BigInteger |
BIGINT |
NUMBER(38) |
BIGINT |
NUMERIC(38) |
NUMERIC(28) |
BIGINT |
java.math.BigDecimal |
DECIMAL |
NUMBER(38) |
DECIMAL(15) |
NUMERIC(38) |
NUMERIC(28) |
DECIMAL(38) |
java.lang.String |
VARCHAR(255) |
VARCHAR(255) |
VARCHAR(255) |
VARCHAR(255) |
VARCHAR(255) |
VARCHAR(255) |
char, java.lang.Character |
CHAR(1) |
CHAR(1) |
CHAR(1) |
CHAR(1) |
CHAR(1) |
CHAR(1) |
byte[], java.lang.Byte[], java.sql.Blob |
BLOB(64000) |
LONG RAW |
BLOB(64000) |
IMAGE |
IMAGE |
BLOB(64000) |
char[], java.lang.Character[], java.sql.Clob |
CLOB(64000) |
LONG |
CLOB(64000) |
TEXT |
TEXT |
TEXT(64000) |
java.sql.Date |
DATE |
DATE |
DATE |
DATETIME |
DATETIME |
DATE |
java.sql.Time |
TIME |
DATE |
TIME |
DATETIME |
DATETIME |
TIME |
java.sql.Timestamp |
TIMESTAMP |
DATE |
TIMESTAMP |
DATETIME |
DATETIME |
DATETIME |
Schema generation properties or asadmin command line options can control automatic schema generation by the following:
Creating tables during deployment
Dropping tables during undeployment
Dropping and creating tables during redeployment
Generating the DDL files
Before using these options, make sure you have a properly configured database. See Specifying the Database.
The following optional schema generation properties control the automatic creation of database tables at deployment. You can specify them in the persistence.xml file.
Table 7–2 Schema Generation Properties
Property |
Default |
Description |
---|---|---|
none |
Specifies whether tables and DDL files are created during deployment, and whether tables are dropped first if they already exist. Allowed values are create-tables, drop-and-create-tables, and none. If create-tables is specified, database tables are created for entities that need them. If drop-and-create-tables is specified, and if tables were automatically created when this application was last deployed, tables from the earlier deployment are dropped and fresh ones are created. If tables were not automatically created when this application was last deployed, no attempt is made to drop any tables. If tables with the same names as those that would have been automatically created are found, the deployment proceeds, but a warning is thrown to indicate that tables could not be created. If none is specified, no tables are created or dropped. The asadmin generation options listed in Table 7–3 and Table 7–4 override the value of this property. If you are using persistence outside the EJB container and would like to create the DDL files without creating tables, additionally define a Java system property INTERACT_WITH_DB and set its value to false. |
|
createDDL.jdbc |
Specifies the name of the JDBC file that contains the DDL statements required to create the required objects (tables, sequences, and constraints) in the database. |
|
dropDDL.jdbc |
Specifies the name of the JDBC file that contains the DDL statements required to drop the required objects (tables, sequences, and constraints) from the database. |
|
. for the current working directory |
Specifies the location where the DDL files are written. For persistence within the EJB container, if this property is not set, DDL files are written to one of the following locations, for applications and modules, respectively: domain-dir/generated/ejb/j2ee-apps/app-name domain-dir/generated/ejb/j2ee-modules/mod-name |
|
both |
Specifies the DDL generation target if you are in Java SE mode, outside the EJB container. Values are as follows:
|
The following options of the asadmin deploy or asadmin deploydir command control the automatic creation of database tables at deployment.
Table 7–3 The asadmin deploy and asadmin deploydir Generation Options
Option |
Default |
Description |
---|---|---|
--createtables |
none |
If true, causes database tables to be created for entities that need them. If false, does not create tables. If not specified, the value of the toplink.ddl-generation property in persistence.xml is used. |
--dropandcreatetables |
none |
If true, and if tables were automatically created when this application was last deployed, tables from the earlier deployment are dropped and fresh ones are created. If true, and if tables were not automatically created when this application was last deployed, no attempt is made to drop any tables. If tables with the same names as those that would have been automatically created are found, the deployment proceeds, but a warning is thrown to indicate that tables could not be created. If false, the toplink.ddl-generation property setting in persistence.xml is overridden. |
The following options of the asadmin undeploy command control the automatic removal of database tables at undeployment.
Table 7–4 The asadmin undeploy Generation Options
Option |
Default |
Description |
---|---|---|
--droptables |
none |
If true, causes database tables that were automatically created when the entities were last deployed to be dropped when the entities are undeployed. If false, does not drop tables. If not specified, tables are dropped only if the toplink.ddl-generation property setting in persistence.xml is drop-and-create-tables. |
For more information about the asadmin deploy, asadmin deploydir, and asadmin undeploy commands, see the Sun GlassFish Enterprise Server 2.1 Reference Manual.
When asadmin deployment options and persistence.xml options are both specified, the asadmin deployment options take precedence.
The asant tasks sun-appserv-deploy and sun-appserv-undeploy are equivalent to asadmin deploy and asadmin undeploy, respectively. These asant tasks also override the persistence.xml options. For details, see Chapter 3, The asant Utility.