Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Step 4: Mapping Attributes

In this step, you will create several direct and relationship mappings from the Java objects to the database tables. Review Table 16-10 for information on these mappings.

## Direct-to-Field Mappings

In the tutorial model, each attribute of the `Address` descriptor (such as `city`) maps directly to a column in a database table. TopLink represents this relationship as a direct-to-field mapping.

Use this procedure to create the direct-to-field mapping of the `city` attribibute of the `Address` class:

1. Expand the Address descriptor in the Navigator to display its attributes.

2. Select the city attribute and click Direct to Field Mapping. TopLink Workbench creates the direct-to-field mapping. Its properties appear in the Editor.

   You can also create the mapping by right-clicking the city attribute and selecting Map As > Direct to Field from the context menu.

   Notice that TopLink Workbench has added a warning icon to the city attribute, indicating that the mapping is incomplete.

   Figure 17-13 General Tab of Direct-to-Field Mapping

   Description of "Figure 17-13 General Tab of Direct-to-Field Mapping"

3. On the General tab, use the Database Field field to select the ADDRESS.CITY database field.

### Using Automap

Instead of mapping Java attributes manually, TopLink Workbench can attempt to automatically map attributes and database fields with similar names.

To automatically map each attribute of the `Address` class as a direct-to-field mapping, use this procedure:

1. Expand the Address descriptor in the Navigator to display its attributes.

2. Right-click the Address descriptor and select Automap from the context menu. TopLink Workbench automatically maps the unmapped descriptors and displays the Automap Status dialog box.

3. Click OK. TopLink Workbench mapped each attribute as a direct to field mapping.

4. Individually, select each attribute of the Address descriptor and confirm they are mapped to the following database fields:

   Attribute | Database Field
   --- | ---
   country | COUNTRY
   id | ADDRESS_ID
   postalCode | P_CODE
   province | PROVINCE
   street | STREET

   Note: It is not necessary to confirm the city attribute; the Automap function will not change attributes that are already mapped.

5. Click Save to save the project.

The Automap function relies on a logically named and ordered database structure. You should always review mappings created by the Automap function.

### Additional Direct-to-Field Mappings

Follow the procedure from "Direct-to-Field Mappings" to map the following attributes as direct-to-field mappings:

Descriptor | Attribute | Database Field
--- | --- | ---
Employee | firstName | F_NAME
id | EMP_ID (from EMPLOYEE table)
lastName | L_NAME
salary | SALARY (from SALARY table)
LargeProject | budget | BUDGET
milestoneVersion | MILESTONE
PhoneNumber | areaCode | AREA_CODE
number | P_NUMBER
type | TYPE
Project | description | DESCRIP
id | PROJ_ID
name | PROJ_NAME

Leave all other attributes unmapped.

## One-to-One Mappings

In the tutorial model, each employee has a single address. TopLink represents this relationship as a one-to-one mapping.

To create a one-to-one mapping of the `address` attribute of the `Employee` class, use this procedure:

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Select the address attribute and click One to One Mapping. TopLink Workbench creates the one-to-one mapping. Its properties appear in the Editor.

   You can also create the mapping by right-clicking the address attribute and selecting Map As > One to One from the context menu.

   Notice that TopLink Workbench has added a warning icon to the address attribute, indicating that the mapping is incomplete.

   Figure 17-14 General Tab of One-to-One Mapping

   Description of "Figure 17-14 General Tab of One-to-One Mapping"

3. Click the General tab. Use the following information to complete the fields on the General tab:

   Field | Description
   --- | ---
   Reference Descriptor | Select Address. The address attribute (of the Employee descriptor) references the Address descriptor.
   Private Owned | Select this option to automatically create, update, or delete the Address object, whenever its owner (Employee) is changed.
   Use Indirection | Select ValueHolder to allow TopLink to use a value holder when retrieving and storing information from the database. This reduces database accesses and improves performance. See "Configuring Indirection" for more information.

   Leave the other fields empty.

4. Click the Table Reference tab. The Table Reference tab appears.

   Figure 17-15 Table Reference Tab of One-to-One Mapping

   Description of "Figure 17-15 Table Reference Tab of One-to-One Mapping"

5. In the Table Reference field, select EMPLOYEE_ADDRESS. TopLink assigns the Source (ADDR_ID) and Target (ADDRESS_ID) fields, based on the database foreign key constraints imported when you imported the database tables (see "Importing Database Tables").

   Note: For more information on creating constraints using TopLink Workbench, see "Configuring Table and Field References (Foreign and Target Foreign Keys)".

6. Click Save to save the project.

### Additional One-to-One Mappings

Follow the procedure from "One-to-One Mappings" to map the following attributes as one-to-one mappings:

Descriptor | Attribute | Reference Descriptor | Table Reference
--- | --- | --- | ---
Employee | manager | EMPLOYEE | EMPLOYEE_EMPLOYEE
Project | teamLeader | EMPLOYEE | PROJECT_EMPLOYEE

Leave all other attributes unmapped.

## One-to-Many Mappings

In the tutorial model, each employee may have multiple telephone numbers. TopLink represents this relationship as a one-to-many mapping.

To create a one-to-many mapping of the attributes of the `Employee` class, use this procedure:

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Select the phoneNumbers attribute and click One to Many Mapping. TopLink Workbench creates the one-to-many mapping. Its properties appear in the Editor.

   You can also create the mapping by right-clicking the phoneNumbers attribute and selecting Map As > One to Many from the context menu.

   Notice that TopLink Workbench has added a warning icon to the phoneNumbers attribute, indicating that the mapping is incomplete.

   Figure 17-16 General Tab of One-to-Many Mapping

   Description of "Figure 17-16 General Tab of One-to-Many Mapping"

3. Click the General tab. Use the following information to complete the fields on the General tab:

   Field | Description
   --- | ---
   Reference Descriptor | Select PhoneNumber. The phoneNumbers attribute (of the Employee descriptor) references the PhoneNumber descriptor.
   Private Owned | Select this option to automatically create, update, or delete the PhoneNumber object, whenever its owner (Employee) is changed.
   Use Indirection | Select ValueHolder to allow TopLink to use a value holder when retrieving and storing information from the database. This reduces database accesses and improves performance. See "Configuring Indirection" for more information.

   Leave the other fields empty.

4. Click the Table Reference tab. The Table Reference tab appears.

   Figure 17-17 Table Reference Tab of One-to-Many Mapping

   Description of "Figure 17-17 Table Reference Tab of One-to-Many Mapping"

5. In the Table Reference field, select PHONE_EMPLOYEE. TopLink assigns the Source (EMP_ID) and Target (EMP_ID) fields, based on the database foreign key constraints.

6. To complete this one-to-many mapping, you must create a one-to-one mapping back from the referenced class. Follow the procedure from "One-to-One Mappings" to create a one-to-one mapping from the PhoneNumber descriptor's owner attribute to the Employee descriptor:

   Descriptor | Attribute | Reference Descriptor | Table Reference
   --- | --- | --- | ---
   PhoneNumber | owner | Employee | PHONE_EMPLOYEE

7. Click Save to save the project.

### Additional One-to-Many Mappings

Follow the procedure from "One-to-Many Mappings" to map the following attributes as one-to-many mappings:

Descriptor | Attribute | Reference Descriptor | Table Reference
--- | --- | --- | ---
Employee | managedEmployees | EMPLOYEE | EMPLOYEE_EMPLOYEE

This is an example of a one-to-many self-reference. The tutorial object model requires the `Employee` class to reference another instance of the same class. You have already created the one-to-one back-mapping from the Employee descriptor's manager attribute back to the Employee descriptor.

Leave all other attributes unmapped.

## Object Type Mappings

In the tutorial model, each employee's gender is stored as a single letter in the database (M or F), but the object value is the full word (Male or Female). TopLink represents this relationship as an object type mapping.

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Right-click the gender attribute and select Map As > Object Type from the context menu. TopLink Workbench creates the object type mapping. Its properties appear in the Editor.

3. Click the General tab. The General tab appears.

4. On the General tab, use the Database Field field to select the EMPLOYEE.GENDER database field.

5. Click the Converter tab. The Converter tab appears. Ensure the Object Type converter is selected.

   Figure 17-18 Converter Tab, Object Type Mapping

   Description of "Figure 17-18 Converter Tab, Object Type Mapping"

6. Use the following information to complete the fields on the Converter tab:

   Field | Description
   --- | ---
   Data Type | Select Character. In the database, the GENDER column type is a single character.
   Attribute Type | Select String. In the object, the gender attribute is a text string.

7. In Conversion Values area of the Converter tab, click Add. The Enter Conversion Value Pair dialog box appears.

   Figure 17-19 Enter Conversion Value Pair Dialog Box

8. In the Data Value field, type `M`. In the Attribute Value field, type `Male`. Click OK.

   Repeat steps 7 and 8 to create a conversion from F to Female.

9. Click Save to save the project.

## Aggregate Object Mappings

In TopLink, two objects–a source (parent or owning) object and a target (child or owned) object–are related by aggregation if there is a strict one-to-one relationship between them, and all the attributes of the target object can be retrieved from the same data source representation as the source object. This means that if the source object exists, then the target object must also exist, and if the source object is destroyed, then the target object is also destroyed.

In the tutorial object model, the `Employee` descriptor's `period` attribute uses an aggregate mapping to the `EmploymentPeriod` descriptor (which is associated with the START and END date fields of the EMPLOYEE database table).

### Aggregate Descriptor

Before creating the mapping, you must create the aggregate descriptor by doing the following:

1. Select the EmploymentPeriod descriptor in the Navigator.

2. Click Aggregate Descriptor in the toolbar. TopLink Workbench changes the descriptor to an aggregate descriptor.

   Notice that the Descriptor Info and Queries tabs have been removed in the Editor.

3. Expand the EmploymentPeriod descriptor and map each attribute (StartDate and EndDate) as direct-to-field mappings.

   Notice that the Database Field field is not available on each mapping's General tab.

Next, you create the aggregate mappings.

### Aggregate Mapping

Now you will create an aggregate mapping for the `period` attribute, using the following procedure:

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Right-click the period attribute and select Map As > Aggregate from the context menu. TopLink Workbench creates the aggregate mapping. Its properties appear in the Editor.

3. On the General tab, use the Reference Descriptor field to select the EmploymentPeriod descriptor.

   Notice that the field lists only the aggregate descriptor.

4. Click the Fields tab. The Fields tab appears.

   Figure 17-20 Fields Tab of Aggregate Mapping

   Description of "Figure 17-20 Fields Tab of Aggregate Mapping"

   The Field Description column is populated automatically, based on the mapped attributes of the EmploymentPeriod aggregate descriptor.

5. Use the following information to select the database for each attribute:

   Fields | Database Field
   --- | ---
   EmploymentPeriod.endDate direct field | END_DATE
   EmploymentPeriod.startDate direct field | START_DATE

6. Click Save to save the project.

## Direct Collection Mappings

In the tutorial model, each employee has a list of responsibilities. TopLink represents this collection of objects relationship as a direct collection mapping.

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Right-click the responsibilitiesList attribute and select Map As > Direct Collection from the context menu. TopLink Workbench creates the mapping. Its properties appear in the Editor.

3. Click the General tab. The General tab appears.

   Figure 17-21 General Tab of Direct Collection Mapping

   Description of "Figure 17-21 General Tab of Direct Collection Mapping"

4. Use the following information to complete the fields on this tab:

   Field | Description
   --- | ---
   Target Table | Select the RESPONS table as the table in which to store the string value.
   Direct Value Field | Select the RESPONS.DESCRIP table.
   Use Indirection | Select ValueHolder indirection to allow TopLink to use a value holder when retrieving and storing information from the database. This reduces database accesses and improves performance. See "Configuring Indirection" for more information.

5. Click the Table Reference tab. The Table Reference tab appears.

6. In the Table Reference field, select RESPONS_EMPLOYEE. TopLink assigns the Source (EMP_ID) and Target (EMP_ID) fields, based on the database foreign key constraints.

7. Click Save to save the project.

## Many-to-Many Mappings

In the tutorial model, many employees may have many projects. TopLink represents this relationship between collections as a many-to-many mapping.

To create a many-to-may mapping, use the following procedure:

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Right-click the projects attribute and select Map As > Many to Many from the context menu. TopLink Workbench creates the mapping. Its properties appear in the Editor.

3. Click the General tab. The General tab appears.

   Figure 17-22 General Tab of Many-to-Many Mapping

   Description of "Figure 17-22 General Tab of Many-to-Many Mapping"

4. Use the following information to complete the fields on this tab:

   Field | Description
   --- | ---
   Reference Descriptor | Select the Project descriptor.
   Use Indirection | Select ValueHolder indirection to allow TopLink to use a value holder when retrieving and storing information from the database. This reduces database accesses and improves performance. See "Configuring Indirection" for more information.

5. Click the Table Reference tab. The Table Reference tab appears.

   Figure 17-23 Table Reference Tab of Many-to-Many Mapping

   Description of "Figure 17-23 Table Reference Tab of Many-to-Many Mapping"

6. Use the following information to complete the fields on this tab:

   Field | Description
   --- | ---
   Relation Table | Select the PROJ_EMP table.
   Source Reference |
   Table Reference | Select the PROJEMP_EMP table. Select the EMP_ID field (from the PROJ_EMP table) as the Source Field, and the EMP_ID field (from the EMPLOYEE table) as the Target Field.
   Target Reference |
   Table Reference | Select the PROJEMP_PROJ table. Select the PROJ_ID field (from the PROJ_EMP table) as the Source Field, and the PROJ_ID field (from the PROJECT table) as the Target Field.

7. Click Save to save the project.

## Transformation Mappings

Typically, a TopLink mapping maps a single Java attribute to a single database field.

In the tutorial model, the `Employee` descriptor has a single attribute (`normalHours`) that extracts the values from two database columns (START_TIME and END_TIME).

You can use a TopLink transformation mapping for these situations when an existing TopLink mapping cannot address your application requirements.

A transformation mapping is made up of an attribute transformer for field-to-attribute transformation at read (unmarshall) time (see "Configuring Attribute Transformer") and one or more field transformers for attribute-to-field transformation at write (marshall) time (see "Configuring Field Transformer Associations").

To create a transformation mapping, use the following procedure:

1. Expand the Employee descriptor in the Navigator to display its attributes.

2. Right-click the normalHours attribute and select Map As > Transformation from the context menu. TopLink Workbench creates the transformation mapping. Its properties appear in the Editor.

   Notice that TopLink Workbench has added a warning icon to the transformation attribute, indicating that the mapping is incomplete.

   Figure 17-24 Transformation Mapping

   Description of "Figure 17-24 Transformation Mapping"

3. In the Attribute Transformer field, click Edit. The Specify Transformer dialog box appears.

   Figure 17-25 The Specify Transformer Dialog Box

   Description of "Figure 17-25 The Specify Transformer Dialog Box"

4. Select Use Transformation Method and select the buildNormalHours method. Click OK.

   You can specify the attribute transformer as a method of this domain object class (as done here) or as a separate class.

5. In the Field Transformer Associations area, click Add. The Specify Field-Transformer Association dialog box appears.

   Figure 17-26 The Specify Field-Transformer Association Dialog Box

   Description of "Figure 17-26 The Specify Field-Transformer Association Dialog Box"

6. Use the following information to complete the fields on the Specify Field-Transformer Association dialog box and click OK:

   Field | Description
   --- | ---
   Field | Select the `END_TIME` field from the `EMPLOYEE` table.
   Use Transformation Method | Select the `getEndTime()` method.

7. Click OK.

8. Repeat steps 5 and 6 to add the `START_TIME` transformation method.

9. Click Save to save the project.