Mapping refers to the ability to tie an object-based model to a relational model of data, usually the schema of a relational database. The CMP implementation provides the ability to tie a set of interrelated beans containing data and associated behaviors to the schema. This object representation of the database becomes part of the Java application. You can also customize this mapping to optimize these beans for the particular needs of an application. The result is a single data model through which both persistent database information and regular transient program data are accessed.

The mapping capabilities provided by the GlassFish Server include:

Each module with CMP beans must have the following files:

The sun-cmp-mappings.xml file can be automatically generated and does not have to exist prior to deployment. For details, see Generation Options for CMP.

The sun-cmp-mappings.xml file maps CMP fields and CMR fields (relationships) to the database. A primary table must be selected for each CMP bean, and optionally, multiple secondary tables. CMP fields are mapped to columns in either the primary or secondary table(s). CMR fields are mapped to pairs of column lists (normally, column lists are the lists of columns associated with primary and foreign keys).

The sun-cmp-mappings.xml file conforms to the sun-cmp-mapping_1_2.dtd file and is packaged with the user-defined bean classes in the EJB JAR file under the META-INF directory.

The GlassFish Server creates the mappings in the sun-cmp-mappings.xml file automatically during deployment if the file is not present.

To map the fields and relationships of your entity beans manually, edit the sun-cmp-mappings.xml deployment descriptor. Only do this if you are proficient in editing XML.

The mapping information is developed in conjunction with the database schema (.dbschema) file, which can be automatically captured when you deploy the bean (see Automatic Database Schema Capture). You can manually generate the schema using the capture-schema utility (Using the capture-schema Utility).

The following topics are addressed here:

The data types used in automatic schema generation are also suggested for manual mapping. These data types are described in 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 9-1 Java Type to JDBC Type Mappings for CMP

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 GlassFish Server, see the GlassFish Server Open Source Edition Release Notes. For configurations of supported and other drivers, see "Configuration Specifics for JDBC Drivers" in GlassFish Server Open Source Edition Administration Guide.

Table 9-2 Mappings of JDBC Types to Database Vendor Specific Types for CMP

Deployment descriptor elements or asadmin command line options can control automatic schema generation by the following:

The following optional data subelements of the cmp-resource element in the glassfish-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 GlassFish Server Open Source Edition Application Deployment Guide and Configuring the CMP Resource.

Table 9-3 The glassfish-ejb-jar.xml Generation Elements

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

Table 9-4 The asadmin deploy and asadmin deploydir Generation Options for CMP

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 9-5 The asadmin undeploy Generation Options for CMP

For more information about the asadmin deploy, asadmin deploydir, and asadmin undeploy commands, see the GlassFish Server Open Source Edition Reference Manual.

When command line and glassfish-ejb-jar.xml options are both specified, the asadmin options take precedence.

You can configure a CMP bean in GlassFish Server to automatically capture the database metadata and save it in a .dbschema file during deployment. If the sun-cmp-mappings.xml file contains an empty <schema/> entry, the cmp-resource entry in the glassfish-ejb-jar.xml file is used to get a connection to the database, and automatic generation of the schema is performed.

You can use the capture-schema command to manually generate the database metadata (.dbschema) file. For details, see the GlassFish Server Open Source Edition Reference Manual.

The capture-schema utility does not modify the schema in any way. Its only purpose is to provide the persistence engine with information about the structure of the database (the schema).

Keep the following in mind when using the capture-schema command:

The version consistency feature saves the bean state at first transactional access and caches it between transactions. The state is copied from the cache instead of being read from the database. The bean state is verified by primary key and version column values at flush for custom queries (for dirty instances only) and at commit (for clean and dirty instances).

In many cases when an entity bean’s state is fetched from the database, its relationship fields are always accessed in the same transaction. Relationship prefetching saves database round trips by fetching data for an entity bean and those beans referenced by its CMR fields in a single database round trip.

To enable relationship prefetching for a CMR field, use the default subelement of the fetched-with element in the sun-cmp-mappings.xml file. By default, these CMR fields are prefetched whenever findByPrimaryKey or a custom finder is executed for the entity, or when the entity is navigated to from a relationship. (Recursive prefetching is not supported, because it does not usually enhance performance.) See "fetched-with" in GlassFish Server Open Source Edition Application Deployment Guide.

To disable prefetching for specific custom finders, use the prefetch-disabled element in the glassfish-ejb-jar.xml file. See "prefetch-disabled" in GlassFish Server Open Source Edition Application Deployment Guide.

Multilevel relationship prefetching is supported for CMP 2.1 entity beans. To enable multilevel relationship prefetching, set the following property using the asadmin create-jvm-options command:

Another feature that the GlassFish Server provides is the read-only bean, an entity bean that is never modified by an EJB client. Read-only beans avoid database updates completely.

A read-only bean can be used to cache a database entry that is frequently accessed but rarely updated (externally by other beans). When the data that is cached by a read-only bean is updated by another bean, the read-only bean can be notified to refresh its cached data.

The GlassFish Server provides a number of ways by which a read-only bean’s state can be refreshed. By setting the refresh-period-in-seconds element in the glassfish-ejb-jar.xml file and the trans-attribute element (or @TransactionAttribute annotation) in the ejb-jar.xml file, it is easy to configure a read-only bean that is one of the following:

Access to CMR fields of read-only beans is not supported. Deployment will succeed, but an exception will be thrown at runtime if a get or set method is invoked.

Read-only beans are best suited for situations where the underlying data never changes, or changes infrequently. For further information and usage guidelines, see Using Read-Only Beans.

The Enterprise JavaBeans Specification, v1.1 does not specify the format of the finder method description. The GlassFish Server uses an extension of Java Data Objects Query Language (JDOQL) queries to implement finder and selector methods. You can specify the following elements of the underlying JDOQL query:

The GlassFish Server specific deployment descriptor (glassfish-ejb-jar.xml) provides the following elements to store the EJB 1.1 finder method settings:

The bean developer uses these elements to construct a query. When the finder method that uses these elements executes, the values of these elements are used to execute a query in the database. The objects from the JDOQL query result set are converted into primary key instances to be returned by the EJB 1.1 ejbFind method.

The JDO specification, JSR 12 (http://jcp.org/en/jsr/detail?id=12), provides a comprehensive description of JDOQL. The following information summarizes the elements used to define EJB 1.1 finders.

The filter expression is a String containing a Boolean expression evaluated for each instance of the candidate class. If the filter is not specified, it defaults to true. Rules for constructing valid expressions follow the Java language, with the following differences:

In addition, the GlassFish Server supports the following nonstandard JDOQL methods.

The following expressions are supported.

The rules for promotion follow the Java rules extended by BigDecimal, BigInteger, and numeric wrapper classes. See the numeric promotions of the Java language specification.

The parameter declaration is a String containing one or more parameter type declarations separated by commas. This follows the Java syntax for method signatures.

The type declarations follow the Java syntax for local variable declarations.

This section provides a few query examples.

EJB QL as defined in the EJB 2.1 Specification defines certain restrictions for the SELECT clause of an ORDER BY query (see section 11.2.8 ORDER BY Clause). This ensures that a query does not order by a field that is not returned by the query. By default, the EJB QL compiler checks the above restriction and throws an exception if the query does not conform.

However, some databases support SQL statements with an ORDER BY column that is not included in the SELECT clause. To disable the validation of the ORDER BY clause against the SELECT clause, set the DISABLE_ORDERBY_VALIDATION JVM option as follows:

The DISABLE_ORDERBY_VALIDATION option is set to false by default. Setting it to true results in a non-portable module or application.

On DB2, the database configuration parameter APPLHEAPSZ determines the heap size. If you are using the Oracle or DataDirect database driver, set this parameter to at least 2048 for CMP. For more information, see http://publib.boulder.ibm.com/infocenter/db2luw/v8/index.jsp?topic=/com.ibm.db2.udb.doc/opt/tsbp2024.html.

By default, the EJB container loads the state for all persistent fields (excluding relationship, BLOB, and CLOB fields) before invoking the ejbLoad method of the abstract bean. This approach might not be optimal for entity objects with large state if most business methods require access to only parts of the state.

Use the fetched-with element in sun-cmp-mappings.xml for fields that are used infrequently. See "fetched-with" in GlassFish Server Open Source Edition Application Deployment Guide.

The following restrictions apply to the remote interface of an EJB 2.1 bean that uses CMP:

Dependent value classes can be exposed in the remote interface or remote home interface, and can be included in the client EJB JAR file.

Case-sensitive behavior cannot be achieved for PostgreSQL databases. PostgreSQL databases internally convert all names to lower case, which makes the following workarounds necessary:

For EJB 2.1 beans, the lock-when-loaded consistency level is implemented by placing update locks on the data corresponding to a bean when the data is loaded from the database. There is no suitable mechanism available on Sybase databases to implement this feature. Therefore, the lock-when-loaded consistency level is not supported on Sybase databases. See "consistency" in GlassFish Server Open Source Edition Application Deployment Guide.

If a finder method with an input greater than 255 characters is executed and the primary key column is mapped to a VARCHAR column, Sybase attempts to convert type VARCHAR to type TEXT and generates the following error:

To avoid this error, make sure the finder method input is less than 255 characters.

If a field type is a Java date or time type (java.util.Date, java.sql.Date, java.sql.Time, java.sql.Timestamp), make sure that the field value exactly matches the value in the database.

For example, the following code uses a java.sql.Date type as a primary key field:

For some databases, this code results in only the year, month, and date portion of the field value being stored in the database. Later if the client tries to find this bean by primary key as follows, the bean is not found in the database because the value does not match the one that is stored in the database.

Similar problems can happen if the database truncates the timestamp value while storing it, or if a custom query has a date or time value comparison in its WHERE clause.

For automatic mapping to an Oracle database, fields of type java.util.Date, java.sql.Date, and java.sql.Time are mapped to Oracle’s DATE data type. Fields of type java.sql.Timestamp are mapped to Oracle’s TIMESTAMP(9) data type.

For version consistency triggers on MSSQL, the property RECURSIVE_TRIGGERS must be set to false, which is the default. If set to true, triggers throw a java.sql.SQLException.

Set this property as follows:

You can test this property as follows:

The following restrictions apply when you use a MySQL database with the GlassFish Server for persistence.

InnoDB provides MySQL with a transaction-safe (ACID compliant) storage engine having commit, rollback, and crash recovery capabilities. * For a FLOAT type field, the correct precision must be defined. By default, MySQL uses four bytes to store a FLOAT type that does not have an explicit precision definition. For example, this causes a number such as 12345.67890123 to be rounded off to 12345.7 during an INSERT. To prevent this, specify FLOAT(10,2) in the DDL file, which forces the database to use an eight-byte double-precision column. For more information, see http://dev.mysql.com/doc/mysql/en/numeric-types.html. * To use || as the string concatenation symbol, start the MySQL server with the --sql-mode="PIPES_AS_CONCAT" option. For more information, see http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html and http://dev.mysql.com/doc/mysql/en/ansi-mode.html. * MySQL always starts a new connection when autoCommit==true is set. This ensures that each SQL statement forms a single transaction on its own. If you try to rollback or commit an SQL statement, you get an error message.

To resolve this issue, add relaxAutoCommit=true to the JDBC URL. For more information, see http://forums.mysql.com/read.php?39,31326,31404. * Change the trigger create format from the following:

To the following:

For more information, see http://dev.mysql.com/doc/mysql/en/create-trigger.html. * MySQL does not allow a DELETE on a row that contains a reference to itself. Here is an example that illustrates the issue.

This example fails with the following error message.

To resolve this issue, change the table creation script to the following:

This can be done only if the foreign key field is allowed to be null. For more information, see http://dev.mysql.com/doc/mysql/en/innodb-foreign-key-constraints.html. * When an SQL script has foreign key constraints defined, capture-schema fails to capture the table information correctly. To work around the problem, remove the constraints and then run capture-schema. Here is an example that illustrates the issue.

To resolve this issue, change the table creation script to the following: