Sun GlassFish Enterprise Server v2.1.1 Developer's Guide

Automatic Schema Generation for CMP

The automatic schema generation feature provided in the Enterprise Server defines database tables based on the fields in entity beans and the relationships between the fields. This insulates developers from many of the database related aspects of development, allowing them to focus on entity bean 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 addresses the following topics:

Note –

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. 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.

Supported Data Types for CMP

CMP supports a set of JDBC data types that are used in mapping Java data fields to SQL types. Supported JDBC data types are as follows: BIGINT, BIT, BLOB, CHAR, CLOB, DATE, DECIMAL, DOUBLE, FLOAT, INTEGER, NUMERIC, REAL, SMALLINT, TIME, TIMESTAMP, TINYINT, VARCHAR.

The following table contains the mappings of Java types to JDBC types when automatic mapping is used.

Table 10–1 Java Type to JDBC Type Mappings for CMP


Java Type	JDBC Type	Nullability
`boolean`	`BIT`	No
`java.lang.Boolean`	`BIT`	Yes
`byte`	`TINYINT`	No
`java.lang.Byte`	`TINYINT`	Yes
`double`	`DOUBLE`	No
`java.lang.Double`	`DOUBLE`	Yes
`float`	`REAL`	No
`java.lang.Float`	`REAL`	Yes
`int`	`INTEGER`	No
`java.lang.Integer`	`INTEGER`	Yes
`long`	`BIGINT`	No
`java.lang.Long`	`BIGINT`	Yes
`short`	`SMALLINT`	No
`java.lang.Short`	`SMALLINT`	Yes
`java.math.BigDecimal`	`DECIMAL`	Yes
`java.math.BigInteger`	`DECIMAL`	Yes
`char`	`CHAR`	No
`java.lang.Character`	`CHAR`	Yes
`java.lang.String`	`VARCHAR` or `CLOB`	Yes
`Serializable`	`BLOB`	Yes
`byte[]`	`BLOB`	Yes
`java.util.Date`	`DATE` (Oracle only) `TIMESTAMP` (all other databases)	Yes
`java.sql.Date`	`DATE`	Yes
`java.sql.Time`	`TIME`	Yes
`java.sql.Timestamp`	`TIMESTAMP`	Yes

Note –

Java types assigned to CMP fields must be restricted to Java primitive types, Java Serializable types, java.util.Date, java.sql.Date, java.sql.Time, or java.sql.Timestamp. An entity bean local interface type (or a collection of such) can be the type of a CMR field.

The following table contains the mappings of JDBC types to database vendor-specific types when automatic mapping is used. For a list of the JDBC drivers currently supported by the Enterprise Server, see the Sun GlassFish Enterprise Server v2.1.1 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.

Table 10–2 Mappings of JDBC Types to Database Vendor Specific Types for CMP


JDBC Type	Java DB, Derby, CloudScape	Oracle	DB2	Sybase ASE 12.5	MS-SQL Server
`BIT`	`SMALLINT`	`SMALLINT`	`SMALLINT`	`TINYINT`	`BIT`
`TINYINT`	`SMALLINT`	`SMALLINT`	`SMALLINT`	`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`	`SMALLINT`	`SMALLINT`	`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`	`INTEGER`	`INTEGER`	`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`	`NUMBER`	`BIGINT`	`NUMERIC`	`NUMERIC`
`REAL`	`REAL`	`REAL`	`FLOAT`	`FLOAT`	`REAL`
`DOUBLE`	`DOUBLE PRECISION`	`DOUBLE PRECISION`	`DOUBLE`	`DOUBLE PRECISION`	`FLOAT`
`DECIMAL(p,s)`	`DECIMAL(p,s)`	`NUMBER(p,s)`	`DECIMAL(p,s)`	`DECIMAL(p,s)`	`DECIMAL(p,s)`
`VARCHAR`	`VARCHAR`	`VARCHAR2`	`VARCHAR`	`VARCHAR`	`VARCHAR`
`DATE`	`DATE`	`DATE`	`DATE`	`DATETIME`	`DATETIME`
`TIME`	`TIME`	`DATE`	`TIME`	`DATETIME`	`DATETIME`
`TIMESTAMP`	`TIMESTAMP`	`TIMESTAMP(9)`	`TIMESTAMP`	`DATETIME`	`DATETIME`
`BLOB`	`BLOB`	`BLOB`	`BLOB`	`IMAGE`	`IMAGE`
`CLOB`	`CLOB`	`CLOB`	`CLOB`	`TEXT`	`NTEXT`

Generation Options for CMP

Deployment descriptor elements 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
Specifying the database vendor
Specifying that table names are unique
Specifying type mappings for individual CMP fields

Note –

Before using these options, make sure you have a properly configured CMP resource. See Configuring the CMP Resource.

For a read-only bean, do not create the database schema during deployment. Instead, work with your database administrator to populate the data into the tables. See Using Read-Only Beans.

Automatic schema generation is not supported for beans with version column consistency checking. Instead, work with your database administrator to create the schema and add the required triggers. See Version Column Consistency Checking.

The following optional data subelements of the cmp-resource element in the sun-ejb-jar.xml file control the automatic creation of database tables at deployment. For more information about the cmp-resource element, see cmp-resource in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide and Configuring the CMP Resource.

Table 10–3 The sun-ejb-jar.xml Generation Elements


Element	Default	Description
`create-tables-at-deploy`	`false`	If `true`, causes database tables to be created for beans that are automatically mapped by the EJB container. If `false`, does not create tables.
`drop-tables-at-undeploy`	`false`	If `true`, causes database tables that were automatically created when the bean(s) were last deployed to be dropped when the bean(s) are undeployed. If `false`, does not drop tables.
`database-vendor-name`	none	Specifies the name of the database vendor for which tables are created. Allowed values are `javadb`, `db2`, `mssql`, `oracle`, `postgresql`, `pointbase`, `derby` (also for CloudScape), and `sybase`, case-insensitive. If no value is specified, a connection is made to the resource specified by the `jndi-name` subelement of the `cmp-resource` element in the `sun-ejb-jar.xml` file, and the database vendor name is read. If the connection cannot be established, or if the value is not recognized, SQL-92 compliance is presumed.
`schema-generator-properties`	none	Specifies field-specific column attributes in `property` subelements. Each property name is of the following format: `bean-name.field-name.attribute` For example: `Employee.firstName.jdbc-type` Also allows you to set the `use-unique-table-names` property. If `true`, this property specifies that generated table names are unique within each application server domain. The default is `false`. For further information and an example, see schema-generator-properties in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.

The following options of the asadmin deploy or asadmin deploydir command control the automatic creation of database tables at deployment.

Table 10–4 The asadmin deploy and asadmin deploydir Generation Options for CMP


Option	Default	Description
`--createtables`	none	If `true`, causes database tables to be created for beans that need them. If `false`, does not create tables. If not specified, the value of the `create-tables-at-deploy` attribute in `sun-ejb-jar.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 indicates that tables could not be created. If `false`, settings of `create-tables-at-deploy` or `drop-tables-at-undeploy` in the `sun-ejb-jar.xml` file are overridden.
`--uniquetablenames`	none	If `true`, specifies that table names are unique within each application server domain. If not specified, the value of the `use-unique-table-names` property in `sun-ejb-jar.xml` is used.
`--dbvendorname`	none	Specifies the name of the database vendor for which tables are created. Allowed values are `javadb`, `db2`, `mssql`, `oracle`, `postgresql`, `pointbase`, `derby` (also for CloudScape), and `sybase`, case-insensitive. If not specified, the value of the `database-vendor-name` attribute in `sun-ejb-jar.xml` is used. If no value is specified, a connection is made to the resource specified by the `jndi-name` subelement of the `cmp-resource` element in the `sun-ejb-jar.xml` file, and the database vendor name is read. If the connection cannot be established, or if the value is not recognized, SQL-92 compliance is presumed.

If one or more of the beans in the module are manually mapped and you use any of the asadmin deploy or asadmin deploydir options, the deployment is not harmed in any way, but the options have no effect, and a warning is written to the server log.

The following options of the asadmin undeploy command control the automatic removal of database tables at undeployment.

Table 10–5 The asadmin undeploy Generation Options for CMP


Option	Default	Description
`--droptables`	none	If `true`, causes database tables that were automatically created when the bean(s) were last deployed to be dropped when the bean(s) are undeployed. If `false`, does not drop tables. If not specified, the value of the `drop-tables-at-undeploy` attribute in `sun-ejb-jar.xml` is used.

For more information about the asadmin deploy, asadmin deploydir, and asadmin undeploy commands, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.

When command line and sun-ejb-jar.xml options are both specified, the asadmin 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 sun-ejb-jar.xml options. For details, see Chapter 3, The asant Utility.