Mapping Capabilities

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:

Mapping a CMP bean to one or more tables

Mapping CMP fields to one or more columns

Mapping CMP fields to different column types

Mapping tables with compound primary keys

Mapping tables with unknown primary keys

Mapping CMP relationships to foreign keys

Mapping tables with overlapping primary and foreign
keys

The Mapping Deployment Descriptor File

Each module with CMP beans must have the following files:

ejb-jar.xml – The J2EE
standard file for assembling enterprise beans. For a detailed description,
see the Enterprise JavaBeans Specification, v2.1.

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

Note –

Table names in databases can be case-sensitive. Make sure
that the table names in the sun-cmp-mappings.xml file
match the names in the database.

Relationships should
always be mapped to the primary key field(s) of the related table.

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.

Mapping Considerations

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.

Join Tables and Relationships

Use of join tables in the database schema is supported for all
types of relationships, not just many-to-many relationships. For general
information about relationships, see section 10.3.7 of the Enterprise
JavaBeans Specification, v2.1.

If the database schema is created during deployment, the GlassFish Server creates
the schema with the primary key column, then generates unique values
for the primary key column at runtime.

If the database schema is not created during deployment, the
primary key column in the mapped table must be of type NUMERIC with
a precision of 19 or more, and must not be mapped to any CMP field.
The GlassFish Server generates unique values for the primary key column
at runtime.

Fixed Length CHAR Primary Keys

If an existing database table has a primary key column in which
the values vary in length, but the type is CHAR instead
of VARCHAR, the GlassFish Server automatically trims
any extra spaces when retrieving primary key values. It is not a good
practice to use a fixed length CHAR column as a
primary key. Use this feature with schemas that cannot be changed,
such as a schema inherited from a legacy application.

Managed Fields

A managed field is a CMP or CMR field that is mapped to the
same database column as another CMP or CMR field. CMP fields mapped
to the same column and CMR fields mapped to exactly the same column
lists always have the same value in memory. For CMR fields that share
only a subset of their mapped columns, changes to the columns affect
the relationship fields in memory differently. Basically, the GlassFish Server always
tries to keep the state of the objects in memory synchronized with
the database.

BLOB Support

Binary Large Object (BLOB) is a data type used to store values
that do not correspond to other types such as numbers, strings, or
dates. Java fields whose types implement java.io.Serializable or
are represented as byte[] can be stored as BLOBs.

If a CMP field is defined as Serializable,
it is serialized into a byte[] before being stored
in the database. Similarly, the value fetched from the database is
deserialized. However, if a CMP field is defined as byte[],
it is stored directly instead of being serialized and deserialized
when stored and fetched, respectively.

To enable BLOB support in the GlassFish Server environment, define
a CMP field of type byte[] or a user-defined type
that implements the java.io.Serializable interface.
If you map the CMP bean to an existing database schema, map the field
to a column of type BLOB.

To use BLOB
or CLOB data types larger than 4 KB for CMP using the Inet Oraxo JDBC
Driver for Oracle Databases, you must set the streamstolob property
value to true.

For automatic mapping, you might need to change the default
BLOB column length for the generated schema using the schema-generator-properties element in sun-ejb-jar.xml. See your
database vendor documentation to determine whether you need to specify
the length. For example:

For automatic mapping, you might need to change the default
CLOB column length for the generated schema using the schema-generator-properties element in sun-ejb-jar.xml. See your
database vendor documentation to determine whether you need to specify
the length. For example: