Mapping CMP EJB Beans in Sun Java System Application Server 8 and J2EE 1.4 SDK

Print-friendly Version

With Deployment Tool, you can create database mappings in either of the following ways:

• Mapping mode — In this mode, you map EJB beans to an existing database schema. You provide the database schema in the form of a .dbschema file, which is an XML file that represents a snapshot of the structure of the database. You can manually generate this file by using the capture-schema utility in Application Server. Afterwards, you must package the file in the .ear or .jar file for use during the mapping process in Deployment Tool.
  
  If you are an experienced CMP user or a database administrator and already have a defined database structure, you should use the mapping mode. This mode is ideal for production systems and enables you to retain control over the database. You must define how the EJB beans map to the database. Deployment Tool creates a default mapping based on your database schema.
  
  
• Table generation mode — In this mode, Deployment Tool automatically generates the database schema and mapping information.
  
  If you are a novice user experimenting with EJB beans or building a prototype, use the table generation mode. This mode creates both a database schema and a mapping at the same time but is usually not appropriate for production systems, for which you would want to retain—not override—the existing database schema.

Both the mapping and table generation modes produce a sun-cmp-mappings.xml file, which describes the mapping between CMP fields and CMP relationships (CMR) to the database.

The sections that follow describe the procedures for creating mappings for the OrderApp example from The J2EE 1.4 Tutorial.

Recall that as a prerequisite, you must have a .ear or .jar file that contains a module with CMP beans and a database schema.

First, start Deployment Tool, which resides in the bin directory where you installed Application Server. From the tree hierarchy on the left, navigate to and select the module that contains your CMP beans. See Figure 1.

Figure 1 Application Opened in Deployment Tool

Do the following:

1. Click Sun-specific Settings.
   
   The Sun-specific Settings dialog box is displayed. Note that the Persistent Field Mappings section is blank.
   
   
2. Click Create Database Mappings.
   
   The Create Database Mappings dialog box is displayed. See Figure 2.
   
   

   Figure 2 Create Database Mappings Dialog Box

   
   
3. Select Map to Tables in Database Schema File.
   
   
4. Choose the .dbschema file from the Database Schema Files in Module drop-down list. Click OK.

The Persistent Field Mappings section now displays the default bean-to-table, field-to-column, and relationship field-to-column pair mappings that have been generated. The mapping is for the bean shown in the Enterprise Bean drop-down list. If multiple CMP beans are in the module, you can view the mapping for each of the beans, one at a time, by choosing their names from the drop-down list. See Figure 3.

Figure 3 Sun-specific Settings Dialog Box

The default mappings make the most logical selections and mappings. Be sure to browse each bean and verify that its mapping is correct. If any bean or field is unmapped or you would like to modify its mapping, you must do so manually.

Here is an explanation of the columns under Field Mappings:

• Field — This column, always read-only, displays the fields to be persisted.
  
  
• Mapped Column — You can change the mappings for the persistent field in this column by choosing the mapping from the drop-down list. If you choose the <map multiple columns> option from that list, the Map Field to Multiple Columns dialog box is displayed.
  
  
• Type — This column displays the data type of the selected Mapped Column. Since this is mapping mode, this column is read-only.
  
  
• Fetch — This column specifies the fetch group configuration for fields and mappings. A field can participate in a hierarchical or an independent fetch group.
  
  

Deployment Tool maps each of the CMP beans to a primary table with the most logical default selection. For example, if the schema contains a LINEITEM table, Deployment Tool maps LineItemBean to that table as its primary table. Otherwise, Deployment Tool leaves the bean as unmapped.

To manually map a selected bean to a primary table, choose the table from the Primary Table drop-down list. For example, to map the unmapped OrderBean, choose ORDERS from the drop-down list.

Deployment Tool maps each of the CMP fields to a column according to the most logical default match based on the field and column names. For example, Deployment Tool maps LineItemBean.quantity to LINEITEM.QUANTITY, assuming that the column exists in the table. Otherwise, Deployment Tool leaves the column as unmapped.

To manually map a field to a column:

1. Click the Mapped Column cell for the field.
   
   A drop-down list with the available columns is displayed.
   
   
2. Choose the corresponding column from the list.

If foreign-key relationships between database tables exist, you would usually preserve those relationships in the CMP beans mapped to those tables. From the Map Relationship Field dialog box, you can determine how relationships between mapped CMP beans are stored in the database. Relationships enable navigation from one bean to another in the same way that a foreign key enables navigation from one table to another.

The Map Relationship Field dialog box chooses the most logical default mappings for you. To view or edit the mappings, do the following:

1. Click the Mapped Column cell for the CMR field.
   
   A drop-down list is displayed.
   
   
2. Select <map relationship field>.
   
   The Map Relationship Field dialog box is displayed. See Figure 4.
   
   

   Figure 4 Initial Setup Page in Map Relationship Field Dialog Box

   
   
3. On the Initial Setup page, verify that the values under Related Bean, Related Field, and Primary Table for the related bean are correct.

Typically, if a relationship between two beans is one-to-one or one-to-many, you would map it directly to a foreign key. Do the following:

1. On the Initial Setup page, select the Link the Mapped Tables Directly radio button and then click Next. See Figure 5.
   
   On the Map to Key page, the foreign key mapping is displayed as the default.
   
   

   Figure 5 Map to Key Page in Map Relationship Field Dialog Box

   
   
2. Optional. To change the default, click Add Pair to add a key column pair or Remove to delete a key column pair.
   
   
3. Optional. In a selected row, choose a column from this bean's primary table for the Local Column and a column from the related bean's primary table for the Foreign Column.
   
   If the table contains a composite foreign key, you must add multiple key column pairs.
   
   
4. Click Finish.
   
   

Typically, if a relationship between two beans is many-to-many, you would map it with a join table. Do the following:

1. On the Initial Setup page, select the Link the Mapped Tables Using a Join Table radio button and then click Next. See Figure 6.
   
   

   Figure 6 Map to Key: Local to Join Page in Map Relationship Field Dialog Box

   
   If you have defined foreign keys, the join table and the mapping between this bean and the join table are displayed as the default.
   
   
2. Optional. To change the default, choose a join table from the Join Table drop-down list.
   
   The default mapping based on the join table you chose is then displayed.
   
   
3. Optional. To change the default, click Add Pair to add a key column pair or Remove to delete a key column pair.
   
   
4. Optional. In a selected row, choose a column from this bean's primary table for the Local Column and a column from the join table for the Join Table Column.
   
   If the table contains a composite foreign key, you must add multiple key column pairs.
   
   
5. Click Next to proceed to the Map to Key: Join to Foreign page.
   
   See Figure 7. The foreign key mapping between the join table and the related bean's primary table are displayed as the default.
   
   

   Figure 7 Map to Key: Join to Foreign Page in Map Relationship Field Dialog Box

   
   
6. Repeat step 3.
   
   
7. Optional. In a selected row, choose a column from the join table for the Join Table Column and a column from the related bean's primary table for the Foreign Column.
   
   If the table contains a composite foreign key, you must add multiple key column pairs.
   
   
8. Click Finish.
   
   

A secondary table enables you to map fields in your EJB bean to columns that are not part of your primary table. When you define secondary tables for an EJB bean, you can map the fields in that bean to columns in different tables.

A secondary table must be related to the primary table by one or more columns whose associated rows have the same values in both tables. Normally, you have a foreign key defined between the tables. When you select a secondary table from the list, if a foreign key between the two tables exists, Deployment Tool uses it as the default association.

For example, to map fields PartBean.drawing and PartBean.specification in bean PartBean to the columns in a table called PART_DETAIL, you must first define PART_DETAIL as a secondary table for PartBean.

To map CMP beans to multiple tables, do the following:

1. Click Advanced Settings in the Persistent Field Mappings section for PartBean.
   
   The Advanced Settings dialog box is displayed. See Figure 8.
   
   

   Figure 8 Advanced Settings Dialog Box

   
   
2. Click Add to add a secondary table.
   
   The Mapped Secondary Table Setup dialog box is displayed. See Figure 9.
   
   

   Figure 9 Mapped Secondary Table Setup Dialog Box

   
   
3. Select a table to be linked to the primary table.
   
   The foreign key mapping is displayed as the default.
   
   
4. Optional. To change the default, click Add Pair. Afterwards, click <Choose Column> to choose a key column under Primary Table Column and then click <Choose Column> under Secondary Table Column to choose the corresponding key column. Alternatively, click Remove to delete a key column pair.
   
   
5. Click OK.
   
   The dialog box closes. The selected table is then displayed in the list of secondary tables in the Advanced Settings dialog box.
   

You can now use the columns in the PART_DETAIL table to map the PartBean.drawing and PartBean.specification fields in the Persistent Field Mappings section.

Occasionally, you may want to map some beans to one schema and other beans to another schema. In those cases, chances are that no matches exist for the beans in the second schema, so you must perform a manual mapping. Bear in mind this rule for using multiple schemas: Beans mapped to one schema cannot be related to those mapped to another schema.

To change the schema of a particular bean, do so in the Advanced Settings dialog box:

1. Select a bean from the Persistent Field Mappings section.
   
   
2. Click Advanced Settings and select a schema file from the Database Schema drop-down list.
   
   
3. Click OK.
   

You can now examine and update the mapping in the Persistent Field Mappings section.

At times, you may want to remap all the beans to a newer snapshot of the same database schema in a different .dbschema file that is also packaged in the same .ear or .jar file. To do so, select a different schema in the Advanced Settings dialog box after performing the preceding three steps. Be sure to remap each bean. Generally, all the table and column names are the same as the old ones and you can retain the majority of the data. However, as a precaution, verify that each bean's fields are still mapped.

At other times, you may want to reset the mappings to the default. To do so, click Automap All in the Persistent Field Mappings section. Automap All makes the most logical selections and updates all the mappings, including relationship fields. Be aware that Automap All overrides all the current mappings.

When you save an application or module from within Deployment Tool, you save it in an .ear or .jar file, which you can then deploy from Deployment Tool or from the asadmin command line.

Before you can generate a database schema and mappings with Deployment Tool, you must have an .ear or .jar file that contains a module with CMP beans but without .dbschema or sun-cmp-mappings.xml files.

First, start Deployment Tool, which resides in the bin directory where you installed Application Server. From the tree hierarchy on the left, navigate to and select the module that contains your CMP beans. Then do the following:

1. Click Sun-specific Settings.
   
   The Sun-specific Settings dialog box is displayed. Note that the Persistent Field Mappings section contains no data.
   
   
2. Click Create Database Mappings.
   
   The Create Database Mappings dialog box is then displayed. See Figure 10.
   
   

   Figure 10 Create Database Mappings Dialog Box

   
   
3. Optional. To create tables that do not contain unique names within all the applications' modules, deselect the default of Generate Unique Table Names.
   
   For details, see the next section, "Generating Unique Names."
   
   
4. Optional. If you are using a database from a vendor other than the default (PointBase), choose that vendor name from the list. If your vendor is not listed but is SQL92-compliant, choose SQL92.
   
   
5. Click OK.
   
   

The Persistent Field Mappings section now displays the default bean-to-table, field-to-column, and relationship field-to-column pair mappings that have been generated. The mapping is for the bean shown in the Enterprise Bean drop-down list. If multiple CMP beans are in the module, you can view the mapping for each of the beans, one at a time, by choosing their names from the drop-down list. See Figure 11.

Figure 11 Sun-specific Settings Dialog Box

Here is an explanation of the columns under Field Mappings:

• Field — This column, always read-only, displays the fields to be persisted.
  
  
• Mapped Column — This is the column that is mapped to the field. Since this is generation mode, this column is read-only.
  
  
• Type — This column displays the data type of the selected Mapped Column.
  
  
• Fetch — This column specifies the fetch group configuration for fields and mappings. A field can participate in a hierarchical or an independent fetch group.
  

In the Create Database Mappings dialog box, you can choose whether or not to generate unique table names. If you want names of the table and the foreign key constraint to be unique across applications, leave that option selected; that's the default.

However, if you plan to work with the SQL and are not concerned with uniqueness across applications, deselect that option. Non-unique names are easier to reconcile with the ejb-name elements of your beans.

The schema as shown in the Persistent Field Mappings table is based on a set of default mappings. You can override the column type of a non-relationship field.

To override the column's default JDBC type on a field-by-field basis, do the following:

1. Click the Type cell for a field.
   
   The Edit Column Type dialog box is displayed. See Figure 12.
   
   

   Figure 12 Edit Column Type Dialog Box

   
   
2. Choose the correct JDBC type from the Column Type drop-down list.
   
   The items in the list are always appropriate for the database type of the column you specified.
   
   
3. Optional. Enter the value for Precision, Scale, or Length, as appropriate, for your JDBC type.
   
   Here are the possibilities:
   
   

   JDBC Column Type	Attribute
   BIGINT	none
   BIT	none
   DECIMAL	precision and scale
   DOUBLE	none
   INTEGER	none
   REAL	none
   SMALLINT	none
   TINYINT	none
   CHAR	length
   CLOB	length
   VARCHAR	length
   DATE	none
   TIME	none
   TIMESTAMP	none
   BLOB	length

   
   
4. Click OK.
   

To regenerate a schema for use on a database from a different vendor, click Create Database Mappings and go through the process of generating a new schema. Beware! You will lose all the modifications you have made to the beans.

By default, deploying from Deployment Tool causes tables to be created in the database when you deploy and to be dropped from the database when you undeploy. You can modify this behavior, however, for example, have Deployment Tool not drop the tables when you undeploy, thus preserving data across deployments.

Here is what to do:

1. Click Table Generation Settings in the Sun-specific Settings dialog box.
   
   The Table Generation Settings dialog box is displayed. See Figure 13.
   
   

   Figure 13 Table Generation Settings Dialog Box

   
   
2. Optional. Deselect the option Create Tables on Deploy.
   
   
3. Optional. Deselect the option Delete Tables on Undeploy.
   
   
4. Click OK.
   

When you save your work, Deployment Tool saves these settings in the sun-ejb-jar.xml file.

To deploy an EJB module that contains CMP beans, you must specify the Java Naming and Directory Interface (JNDI) resource name in the module's sun-ejb-jar.xml file. Also, that name must match the one specified by the jdbc-resource tag in the domain.xml file. At runtime, Application Server uses the JNDI name to locate persistent resources.

If you mapped your CMP beans in table generation mode, ensure that the JNDI name refers to a database with the same vendor as the one specified in the Create Database Mappings dialog box.

For example, if your domain.xml file contains the following entry, set the CMP Resource to jdbc/oracle in the Sun-specific Settings dialog box.

<jdbc-resource
    jndi-name="jdbc/oracle"
    pool-name="jdbc/oracle_pool"/>

Q: If I opened an application with a sun-cmp-mappings.xml file but forgot to package the .dbschema file, can I add the latter afterwards with Deployment Tool?

A: Yes, you can. From the tree hierarchy to the left of the main dialog box, navigate to the module that contains your CMP beans. Click Edit Contents to display the Edit Contents dialog box and then choose the .dbschema file in the Available Files tree; click Add. Click OK to go back to the main dialog box and choose Save from the main menu to save your work.

Q: What happens if I open an application in Deployment Tool with a sun-cmp-mappings.xml file that contains a blank schema element?

A: In that case, Deployment Tool does not show the mapping in the Persistent Field Mappings table. However, the mapping file remains valid and deployable. At deployment time, Deployment Tool automatically generates the .dbschema file and, assuming that the mapping file matches the schema, all the data are valid.

Q: What happens if I open an application in Deployment Tool with a sun-cmp-mappings.xml file but point to a schema that does not exist?

A: In that case, Deployment Tool displays a warning message: "Database Schema File Missing." To correct the error, click OK to display the Sun-specific Settings dialog box. Then either add the .dbschema file to Deployment Tool (see the answer to the first question for the procedure) or click Create Database Mappings to regenerate new mappings with a different .dbschema file.

• Sun Java System Application Server
  • Main page
  • Developer home


• J2EE Platform
  • Main page
  • J2EE 1.4 SDK


• Sun Java Enterprise System and Sun Java System Suites

Jie Leng, who joined Sun six years ago, is a member of technical staff for Sun Java System Application Server and the J2EE SDK. She has been focusing on development projects that relate to EJB beans and e-commerce B2B.

Rochelle Raccah, a staff engineer at Sun since 1997, currently works on the CMP implementation of Sun Java System Application Server and the J2EE SDK. Before her current assignment, she contributed to easing the development and deployment of applications with development tools, such as NetBeans, Deployment Tool, and Sun Java Studio Enterprise.

Marina Sum is a staff writer for Sun Developer Network. She has been writing for Sun for 15 years, mostly in the technical arena.