Mapping Classes and Tables in the Descriptor

When you create a new project and generate class definitions, OracleAS TopLink Mapping Workbench automatically creates descriptors. However, these descriptors do not contain any information about how the classes are associated with the tables. This section describes how to store associations in a descriptor, which can then be used by a Java application to make the classes persistent.

This section contains procedures to map the classes to tables for the ACME project. After mapping the descriptors, you can access the database from a Java application.

Mappings

The OracleAS TopLink mapping describes the way an attribute is stored in, and retrieved from, a database. For example, the name attribute of the Employee class maps to the NAME column of the EMPLOYEE table.

Descriptors

A descriptor stores the class-to-table mappings for a class.OracleAS TopLink Mapping Workbench stores the descriptors in XML files in the Descriptor directory. At run time, OracleAS TopLink creates instances of the Descriptor class for each of the descriptor files and stores them in a database session.

Mapping Classes to Tables

Use this procedure to associate the Java classes with database tables.

To map Java classes to a table:

Select the Address descriptor from the Navigator pane.
Click the Descriptor Info tab of the Editor pane.
In the Associated Table drop-down menu, choose the Address table.

Figure B-16 Descriptor Info Tab

Description of the illustration descinfo.gif

Note:
A warning message appears in the status bar, indicating that the primary key fields are unmapped. This is addressed later in the tutorial.
Repeat steps 0 – 3 to map:
- Employee class to the EMPLOYEE table
- PhoneNumber class to the PHONE table
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.

Although you have mapped the descriptors to specific database tables, the class attributes have not yet been mapped to the tables' columns. You will map the attributes later in this tutorial.

Preparing the Primary Keys

A table's primary key is the field (or fields) used to uniquely identify its records. The PHONE table has a compound primary key (EMP_ID and TYPE fields).

Database tables often use a sequence number as the primary key. Sequence numbers are sequential, artificially generated fields, outside of the problem domain, that uniquely identify a record. OracleAS TopLink supports sequence numbers through the database's native support, such as in Oracle and Sybase, or by maintaining a sequence table. If sequence numbers are enabled for a class, they are generated and incremented whenever an object of that class is inserted into a database.

To specify the primary key:

In the Navigator pane, select the ADDRESS database table.
On the Fields tab of the Editor pane, make sure the ADDRESS_ID column is selected as a Primary Key.

Figure B-17 Database Table Fields Tab

Description of the illustration fldaddr.gif
Repeat Step 1 – 2 for the other tables:
- EMPLOYEE table – Set the EMP_ID field as the primary key.
- PHONENUMBER table – Set both the EMP_ID and TYPE fields as primary keys.
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.

Setting the Sequence Table

The ACME system uses sequence numbers for the EMPLOYEE and ADDRESS tables. You must explicitly create a sequence table, then apply it to your project.

To create a sequence table:

Description of the illustration loginbtn.gif

Select the database in the Navigator pane, and log into the database by clicking the Login button or by right-clicking on the database in the Navigator and choosing Login from the pop-up menu.
Description of the illustration addtable.gif

Select Database in the Navigator pane and click the Add New Table button. The New Table dialog box appears.

Figure B-18 New Table

Description of the illustration newtable.gif
Create a table named SEQUENCE. Leave Catalog and Schema blank, unless required by your specific database.
Add the following fields to the table:
- SEQ_NAME (VARCHAR2 type, size 50)
- SEQ_COUNT (NUMBER type, size 50)
Figure B-19 Database Table Fields Tab

Description of the illustration seq_cnt.gif
Set the SEQ_NAME field as the primary key.
Log out of the database by right-clicking the Database in the Navigator pane and choosing Log Out from the pop-up menu.
Select the Project in the Navigator pane.
Select the project's Sequencing tab in the Editor pane.

Figure B-20 Sequencing Tab

Description of the illustration seqtut.gif
Select Use Custom Sequence Table and use the drop lists to choose the Name, Sequence Name Field, and Sequence Counter Field, as Figure B-20 illustrates.
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.

Note:
You will set the individual sequence names for each table later.

Implementing Direct-to-Field Mappings

The Address class does not reference any other classes. Its attributes map directly to database fields as a direct-to-field mapping.

To map the Address class attributes directly to the ADDRESS columns:

Expand the Address descriptor in the Navigator pane.
Click the city attribute.
Description of the illustration dtfmpbtn.gif

Click the Direct-to-Field mapping button on the mapping toolbar. The Direct-to-Field mapping tab appears in the Editor pane.
Use the Database Field drop-down list to choose the CITY field.

Figure B-21 Direct-to-Field Mapping General Tab

Description of the illustration dfcity.gif
Repeat steps 2 – 4 to map the remaining attributes in the ADDRESS table.
- Map the COUNTRY attribute to COUNTRY field.
- Map the ID attribute to ADDRESS_ID field.
  
  Note:
  When you map the ADDRESS_ID field (the primary key), the OracleAS TopLink Mapping Workbench removes the warning icon for the Address descriptor.
- Map the POSTALCODE attribute to P_CODE field.
- Map the PROVINCE attribute to PROVINCE field.
- Map the STREET attribute to STREET field.
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.

Setting the Sequence Name

The Address and Employee classes use nonnative sequencing for primary keys.

Note:

The sequence name is the value of a row stored in the sequence table. When you create tables for your own projects, you must insert this row into the table using the OracleAS TopLink SchemaManager.

To set the sequencing for the Address and Employee classes:

Select the Address descriptor in the Navigator pane.
Select the Descriptor Info in the Editor pane.
Select the Use Sequencing check box.
In the Name field, type ACME_ADDRESS and use the drop lists to choose the Table and Field, as in Figure B-22.

Figure B-22 Descriptor Info Tab

Description of the illustration seqname.gif
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.
Repeat steps 0 – 4 to set the sequencing for the Employee class. Use ACME_EMPLOYEE as the Name, and choose EMPLOYEE and EMP_ID from the Table and Field drop-down lists, respectively.
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu

When the descriptors are registered with a database session, this information is entered into the SEQUENCE table. The session tracks the sequencing information.

Creating One-to-One Mappings Between Objects

In the Employee class, the name and id attributes map directly to the EMPLOYEE table columns. The phoneNumbers and address attributes refer to other Java classes, rather than referring directly to columns in the database.

Map the firstName and lastName attributes as a direct-to-field mapping to the F_NAME and L_NAME fields, respectively.
Map the id attribute as a direct-to-field mapping to the EMP_ID field (the primary key).

Only one home address is associated with each employee, so the address attribute requires a one-to-one mapping with the Address class. Figure B-23 illustrates a sample one-to-one mapping.

Figure B-23 One-to-One Mappings

Description of the illustration 11mapfig.gif

To create a one-to-one mapping

Description of the illustration 11mapbtn.gif

Select the Employee's address attribute in the Navigator pane, then click the One-to-one Mapping button on the mapping toolbar.

The Editor pane displays the appropriate information for a one-to-one relationship to be specified.

Figure B-24 One-to-One Mapping General Tab

Description of the illustration chseref.gif
Use the Reference Descriptor drop-down list in the to select Address as the reference descriptor.
Select the Use Indirection check box.
Ensure that the Private Owned check box is enabled.

This allows the Address object to be created, updated, or deleted automatically when the Employee owning it is changed.

Foreign Key References

One-to-one mappings use the relational database concept of foreign keys to access other classes stored in the database. You must specify the foreign key information in the descriptor so that OracleAS TopLink knows how to search for a referenced object, as Figure B-23 shows.

Click the Table Reference tab.
Create a new table reference by clicking the New button.
In the New Reference dialog box, create a reference whose:
- Name is EMPLOYEE_ADDRESS
- Source table is EMPLOYEE
- Target table is ADDRESS
  
  Note:
  If you leave the Name field blank, OracleAS TopLink automatically builds the name as <SourceTable>_<TargetTable>.
Select the On Database option if you want to create the reference on the database when you create the tables. OracleAS TopLink does not require that you actually have the constraint on the database, but you may wish to do this for other reasons. Consult your database administrator for more information.

Note:
The mapping is from the EMPLOYEE table, ADDRESS_ID attribute to the ADDRESS table.
Choose EMPLOYEE_ADDRESS from the Table Reference drop-down list.
Click the Add button to define the foreign key fields.
- In the Source Field column, choose ADDRESS_ID (foreign key).
- In the Target Field column, choose ADDRESS_ID (primary key).
- Leave the Target Foreign Key option unchecked.
Figure B-25 One-to-One Mapping Table Reference Tab

Description of the illustration addrref.gif
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.

Creating One-to-Many Mappings

To map an attribute to a Java collection such as a Vector, the application must make a one-to-many mapping for the class owning the collection, and a one-to-one mapping back from the class being referenced. The one-to-one mapping in the referenced class is implemented as a foreign key to the source class.

Figure B-26 One-to-Many Mappings

Description of the illustration 1mmapfig.gif

In this tutorial, the Employee project requires:

A one-to-many mapping from the phoneNumbers attribute of the Employee class to the PhoneNumber class
A one-to-one mapping from the owner attribute of the PhoneNumber class back to the Employee class

To map the phoneNumbers attribute:

Expand the Employee class in the Navigator pane.
Select the phoneNumbers attribute.
Description of the illustration 1mmapbtn.gif

Click the One-to-many Mapping button on the mapping toolbar. The Editor pane changes to allow you to specify the appropriate information for a one-to-many relationship.
Use the Reference Descriptor drop-down list to choose PhoneNumber.

Figure B-27 One-to-Many Mapping General Tab

Description of the illustration chsephon.gif
Click the Table Reference tab, and add a new reference by clicking New.
- Create a new reference named PHONE_EMPLOYEE with a source table of PHONE and a target table of EMPLOYEE and click OK.
- In the Table Reference drop-down list, choose the PHONE_EMPLOYEE.
- Click the Add button on the Table Reference tab to add a foreign key relationship. Set the Source (foreign key) field to EMP_ID and the Target (primary key) field to EMP_ID.
Figure B-28 One-to-Many Mapping Table Reference Tab

Description of the illustration phtabref.gif
Description of the illustration savebtn.gif

Save your changes. Click the Save Project button or choose File > Save from the menu.

Note:
Leave the remaining attributes of the Employee descriptor as unmapped. You will use them in the Advanced tutorial.

To map the PhoneNumber class to the Employee class:

After mapping the Employee descriptor, use this procedure to map the one-to-one back reference:

Map the owner attribute of the PhoneNumber descriptor as a one-to-one mapping to the Employee class (refer to "Creating One-to-One Mappings Between Objects").
Select EMPLOYEE as the Reference Descriptor.

Note:
You do not need to create a new table reference. Select the same PHONE_EMPLOYEE reference you created when you mapped the one-to-many from Employee to PhoneNumber.
Map the remaining attributes in the Phone descriptor as direct-to-field mappings (refer to "Implementing Direct-to-Field Mappings").
Remove all unmapped attributes in the Employee descriptor. Right-click the attribute and choose Remove from the pop-up menu.

You can also remove attributes by choosing Selected > Remove from the menu.