Map the Java Classes

Associate the Class with a Database Table

Each TopLink descriptor must be associated with a database table. This association defines information such as the primary key for the class.

For more information, see "Configuring an Object-Relational Descriptor" in Oracle Toplink Developer's Guide.

Show me...

1. Right-click the tlMap TopLink map in the Applications Navigator and select Open. The TopLink map properties page appears in the Mapping editor.

2. In the Structure window, expand the tlMap node and select the Employee descriptor. The Employee properties page appears in the Mapping editor.

3. Select the Descriptor Info tab. In the Associated Table field, select the EMPLOYEE table.

4. We will also enable sequencing for this descriptor. This tells TopLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created.

   In the Sequencing area, select Use Sequencing. Use this table to complete the remaining fields.

   Field	Description
   Name	EMP_SEQ
   Table	EMPLOYEE
   Field	EMP_ID

   
   

Employee Descriptor Info Tab

Associating with Multiple Tables

TopLink descriptors can use multiple tables in mappings. For example, you may need to use multiple tables when:

• A subclass is involved in inheritance, and its superclass is mapped to one table, while the subclass has additional attributes that are mapped to a second table, or

• The data associated with a class (not involved in inheritance) is spread out across multiple tables

In this tutorial, although most of the data for the Employee class is in the EMPLOYEE table, the salary information is in the SALARY table.

For more information, see "Configuring Multitable Information" in Oracle Toplink Developer's Guide.

Show me...

1. Right-click the Employee descriptor in the Structure window and select Advanced Properties > Multitable Info. The Employee properties page appears in the Editor.

2. Select the Multitable Info tab.

3. In the Additional Tables area click Add. The Select Table dialog appears.

4. Select the SALARY table and click OK.

5. On the Multitable Info tab, in the Association to Primary Table area, select the Primary Keys Have the Same Names option.

   Later in this tutorial, we will map one of the attributes in the Employee descriptor to the SALARY table.

Employee Multitable Info Tab

 

Associate the Other Classes

Repeat the "Associate the Class with a Database Table" procedure to associate the following classes with their database table:

• Address class: ADDRESS table

  Select the Use Sequencing option for the Address descriptor with the following options:

  • Name: ADDRESS_SEQ

  • Table: ADDRESS

  • Field: ADDRESS_ID

• LargeProject class: LPROJECT table

• PhoneNumber class: PHONE table

• Project class: PROJECT table

• SmallProject class: PROJECT table.

Create Direct Mappings

A direct mapping maps primitive object attributes, or non persistent regular objects, such as the JDK classes, directly to a database column.

In this step, we will map each attribute of the Address descriptor directly to a specific database column.

For more information, see "Direct-to-Field Mappings" in Oracle Toplink Developer's Guide.

Show me...

1. Expand the Address descriptor in the Structure window.

2. Right-click the city attribute and select Map As > Direct to Field.

3. In the Database Field field, select ADDRESS.CITY.

   
   

   Note: Be sure that the Use Method Access option is not selected. Selecting this option will cause the mapping to use specific accessor methods instead directly accessing public attributes. By default, TopLink does not use this option – the mapping instead uses direct access.

   
   

Direct to Field Mapping

Use the Automap Feature

The TopLink Automap feature can automatically map Java classes and attributes to similarly named database tables and columns.

Right-click the Address descriptor in the Navigator and select Automap.

Complete each page of the wizard to map each attribute of the Address descriptor as a direct mapping to the appropriate database field. The wizard will identify the suggested database field for each attribute.

For more information, see "Creating Mappings Automatically During Development" in Oracle Toplink Developer's Guide.

Create One-to-One Mappings

One-to-one mappings represent simple pointer references between two Java objects.

In this step, we will create a mapping from the Employee's address attribute to the Address descriptor (each employee has one address).

For more information, see "One-to-One Mappings" in Oracle Toplink Developer's Guide.

Show me...

1. Expand the Employee descriptor in the Structure window.

2. Right-click the address attribute and select Map As > One to One.

3. Select the General tab. In the Reference Descriptor field, select Address.

4. Select the Private Owned option. This indicates that Employee's address attribute is a private component of the source object (the Address class).

   The target object cannot exist without the source and is accessible only through the source object. Destroying the source object will also destroy the target object.

5. Select the Use Indirection option.

   Using indirection (also known as lazy reading, lazy loading, and just-in-time reading) allows TopLink to create "stand-ins" for related objects. These indirection objects take the place of an application object so the application object is not read from the database until it is needed. This results in significant performance improvements, especially when the application requires the contents of only the retrieved object rather than all related objects.

   For more information, see "Indirection" in Oracle Toplink Developer's Guide.

6. Select the Table Reference tab. In the Table Reference field, select EMPLOYEE_ADDRESS.

   TopLink identifies the Source Field (EMPLOYEE.ADDR_ID) and Target Field (ADDRESS.ADDRESS) key references automatically, based on the database constraints.

One-to-One Mapping

Create One-to-Many Mappings

One-to-many mappings represent the relationship between a single source object and a collection of target objects.

In this step, we will create a mapping from the Employee's phoneNumbers attribute to the PhoneNumber descriptor (each employee has multiple phone numbers).

For more information, see "One-to-Many Mappings" in Oracle Toplink Developer's Guide.

Show me...

1. Expand the Employee descriptor in the Structure window.

2. Right-click the phoneNumbers attribute and select Map As > One to Many.

3. Select the General tab. In the Reference Descriptor field, select PhoneNumber.

4. Select the Private Owned option. This indicates that Employee's phoneNumbers attribute is a private component of the source object (the Phone class).

5. Select the Table Reference tab. In the Table Reference field, select PHONE_EMPLOYEE.

   TopLink identifies the Source Field (PHONE.EMP_ID) and Target Field (EMPLOYEE_EMP.ID) key references automatically, based on the database constraints.

One-to-Many Mapping

Create a Back Reference

The purpose of creating this one-to-one mapping in the target is so that the foreign key information can be written when the target object is saved.

Create a one-to-one mapping from the owner attribute of the PhoneNumber descriptor back to the Employee descriptor.

1. Expand the PhoneNumber descriptor in the Structure window.

2. Right-click the owner attribute and select Map As > One to One.

3. Select the General tab. In the Reference Descriptor field, select Employee.

4. Select the Private Owned option. This indicates that PhoneNumber's owner attribute is a private component of the source object (the Employee class).

5. Select the Use Indirection option.

6. Select the Table Reference tab. In the Table Reference field, select PHONE_EMPLOYEE. The Source Field and Target Fields should be identical to the fields selected for the one-to-many mapping.

Create Many-to-Many Mappings

Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. They require the creation of a relation table that manages the associations between the source and target records.

In this step, we will create a mapping from the Employee's projects attribute to the Project descriptor (each employee has multiple projects; each project has multiple employees). The PROJ_EMP database table manages this association.

For more information, see "Many-to-Many Mappings" in Oracle Toplink Developer's Guide.

Show me...

1. Expand the Employee descriptor in the Structure window.

2. Right-click the projects attribute and select Map As > Many to Many.

3. Select the General tab. In the Reference Descriptor field, select Project.

4. Select the Private Owned option. This indicates that Employee's project attribute is a private component of the source object (the Project class).

5. In the Relation Table field, select PROJ_EMP.

6. Select the Source Reference tab.

7. In the Table Reference field, select PROJEMP_EMP.

   TopLink identifies the Source Field (PROJ_EMP.EMP_ID) and Target Field (EMPLOYEE_EMP.ID) key references automatically, based on the database constraints.

8. Select the Target Reference tab.

9. In the Table Reference field, select PROJEMP_PROJ.

   TopLink identifies the Source Field (PROJ_EMP.PROJ_ID) and Target Field (PROJECT.PROJ_ID) key references automatically, based on the database constraints.

Many-to-Many Mapping