CMP Mapping in NetBeans IDE 4.1

Primary table

A primary table is the table that most closely matches the bean you are mapping. A primary table must be selected for each CMP bean. The available primary tables are listed in the combo box. If no primary table is available in the combo box, you need to specify the database schema by clicking Advanced Settings. In the Advanced Settings dialog box, choose the schema from the Database Schema combo box, which lists the database schema files (.dbschema) in the project. If a schema is already specified, choosing a new schema removes all of the current field mappings that refer to this schema.

Secondary tables

A secondary table enables you to map columns that are not part of your primary table directly to fields in your bean. You might want to do this if, for example, the data that represents a logical object is split across two or more tables.

A secondary table differs from relationships. You use secondary tables when you want columns from another table to be fields in the same bean. You use relationship fields when there is a logical relationship between tables. For example, if you want the entire row of another table to be an object in a single bean, you would map that with a relationship.

Setting secondary tables:
You can set secondary tables by clicking Advanced Settings in the CMP Mapping tab and clicking Add to open the Mapped Secondary Table Setup dialog box.

If you want to map to columns from tables other than the primary table, you must specify one or more secondary 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. This link is called a reference key. Normally, this key is a foreign key in the primary table.

1. Select the secondary table from the combo box. The combo box lists the secondary tables available in the schema. When you select a secondary table, the IDE checks for a foreign key between the primary and secondary tables. If a foreign key between the tables exists, it is displayed as the reference key by default in the table. If the database schema has not defined a foreign key, you need to specify a reference key between the two tables.
2. In the reference key table, select the column from the primary table you wish to use as the reference key.
3. Select a column from the secondary table which you wish to link to the reference key and click OK.

Mapping Fields to Multiple Columns

Choosing <map multiple columns> in the Mapped Column combo box opens the Map Field to Multiple Columns dialog box.

Mapping a field to more than one column:

1. Add columns you want to map.
   In the left pane, select the columns you want mapped to the field and click Add. The selected columns appear in the right pane. The left pane lists the available columns from the tables mapped to the bean.
   • If you do not see the column you want to map, you might need to add a secondary table to your mapping, or change the primary table you have selected.
   • If no columns are listed, you have not yet mapped a primary table, or you have mapped a table that has no columns.
2. Set column order.
   Use Move Up/Move Down to change the order of the columns in the right pane.
   If you map a field to more than one column, all columns will be updated with the value of the first column listed. Therefore, if the value of one of the columns is changed outside of an EJB application, the value will only be read if the change was made to that first column. Writing a value to the database overwrites any conflicting changes made to any other columns.

   When you map more than one field to any of these columns, the mappings can either completely overlap or not overlap at all. They cannot partially overlap. Consider the following three examples:

   • Field A mapped to Columns A and B, Field B mapped to Column B. Since the mappings only partially overlap, this example will get a validation error at compilation.
   • Field A mapped to Column A, and Field B mapped to Column B. Since there is no overlap, this mapping is allowed.
   • Field A mapped to Columns A and B, Field B mapped to Columns A and B. Since the mappings completely overlap, this mapping is allowed.
3. Click OK.

Mapping Relationship Fields

An entity bean may be related to other entity beans, and with container-managed persistence, the EJB container takes care of these relationships for you. For example, the cmporder container-managed persistence example in the J2EE 1.4 Tutorial for NetBeans IDE 4.1 contains entity beans that have self-referential relationships, one-to-one relationships, unidirectional relationships, unknown primary keys, primitive primary key types, and composite primary keys. It has entity beans that represent orders, parts, vendors, and line items, and each order may have one or more elements.

For the cmporder example to work correctly, the relationships between the entity beans representing these database tables must be configured correctly. When you generate CMP entity beans from an existing database, the IDE automatically configures the module's CMP relationships and CMP fields and creates a default mapping used by the Sun Java System Application Server. However, you can also modify the mappings manually in the Field Mappings table.

Mapping a relationship:
When you have foreign-key relationships between database tables, you will usually want to preserve those relationships in the CMP beans mapped to those tables. The Map Relationship Field wizard lets you 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 wizard takes you through the following steps:

1. In the first panel, you perform the intial setup for preparing to map the related beans, fields and primary table.
   • Verify that the Related Bean and Related Field are set. If not, then you need to cancel out of the editor and set them in the standard relationship setup for the bean before proceeding.
   • Verify that the Primary Table is set for the related bean.
   • Select between linking the tables directly, or through a join table.
2. If you are linking the mapped tables directly in a 1:1 or 1:n relationship, you use the following wizard panel.

   • Map to Key
     This panel shows the following mapping information:

     • An existing mapping if there is one and there were no changes on the initial setup page.
     • A default mapping if there is no existing mapping or the mapping is no longer valid.

     The editor will attempt to determine the most logical key column pairs between the two related beans based on existing foreign keys. If there are no foreign keys, you need to create the key column pairs by selecting local and foreign columns.

     • To create a compound key, use the Add Pair button.
     • If you want to map a relationship using a join table, go back to the previous panel and select Link the Mapped Tables with a Join Table.

   If you are linking the mapped tables using a join table, you map the relationship field first to a key in the join table in the Local to Join panel, and then to the foreign key in the Join to Foreign panel. All the tables, including the join table, must be contained in the same schema.

   • Local to Join
     In this panel, you choose a join table, then map the relationship field to a key. This is the relationship between the join table and the table the bean (MyBean) is mapped to. If you do not have a join table, go back to the previous panel and select Link the Mapped Tables Directly.

     Choose a join table that sits between the two tables that your beans are mapped to. The IDE will attempt to determine the most logical key column pairs between the join table and the table that MyBean is mapped to.

     If the tables have a foreign key between them, the IDE will use the foreign key as the default key column pair. If there is no foreign key, then you must create a key by choosing a pair of columns that will allow navigation from the join table to the table to which MyBean is mapped. The columns in each pair are expected to have the same value.

     You can create a compound key by clicking Add Pair to add additional Key Column Pairs. If the Next button is disabled, you need to pick a join table and a key column pair.

   • Join to Foreign Key
     In this panel, you relate a second bean to the join table you chose in the previous panel.

     The IDE will attempt to determine the most logical key column pairs between the join table and the table that the related bean is mapped to.

     If the tables have a foreign key between them, the IDE will use the foreign key as the default key column pair. If there is no foreign key, then you must create a key by choosing a pair of columns that will allow navigation from the join table to the table to which the Related Bean is mapped. The columns in each pair are expected to have the same value.

     You can create a compound key by clicking Add Pair to add additional Key Column Pairs. If the Finish button is disabled, you need to choose a join table and a key column pair.

3. Click OK to exit the Map Relationship Field wizard.

After you have mapped your relationships, the Field Mappings field in the CMP Mapping tab displays <mapped relationship> in the Mapped Column field for the persistent field.