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.

• sun-ejb-jar.xml: The Application Server standard file for assembling enterprise beans. For a detailed description, see The sun-ejb-jar.xml File.

• sun-cmp-mappings.xml: The mapping deployment descriptor file, which describes the mapping of CMP beans to tables in a database. For a detailed description, see The sun-cmp-mappings.xml File.

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

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

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 Application Server or the deploytool creates the mappings in the sun-cmp-mappings.xml file automatically during deployment if the file is not present. For information on how to use the deploytool for mapping, see the “Create Database Mapping” topic in the deploytool’s online help.

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.