Use Advanced Mappings

This section includes information on several of the advanced mappings available with TopLink:

Object type mappings
Transformation mappings
Aggregate mappings
Direct collection mappings

Create Object Type Mappings

Use object type mappings to match a fixed number of database primitives to Java objects. In this tutorial we will create a hastable of keys and values to map the gender attribute of the Employee descriptor: M = male, F = female.

For more information, see "Object Type Converter" in Oracle Toplink Developer's Guide.

Show me...

Expand the Employee descriptor in the Structure window.
Right-click the gender attribute and select Map As > Object Type.
Select the General tab. In the Database Field field, select Gender.
For the Database Type, select Character; for the Object Type select String.

The employee's gender is stored as a single character in the database; a string in the class.
In the Conversion Values area, click Add. The Conversion Value dialog appears.
For the Database Value, type M; for the Object Value type Male. Click OK.

Repeat this procedure to add a second conversion value pair: F and Female.

Object Type Mapping

Create Transformation Mappings

Use transformation mappings to extend TopLink when no other mappings are appropriate, such as when a single Java attribute value is defined by a sum of database fields or an array of fields.

To create a transformation mapping, you must provide the methods to define the transformation:

Given raw database row, return a value to populate the attribute.
Add a separate method for every database field to be populated. Each method returns a value to populate the field, given the object to be written.

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

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

Show me...

Expand the Employee descriptor in the Structure window.
Right-click the normalHours attribute and select Map As > Transformation.
In the Database Row -> Object Method field, select buildNormalHours method.
In the Object -> Field Methods area, click Add. Enter the following information.
- For the Database Field, select EMPLOYEE.END_TIME.
- For the Method, select the getEndTime( ) method.

Repeat step 4 to add an association for the EMPLOYEE.START_TIME field and getStartTime( ) method.

Transformation Mapping

Create Aggregate Mappings

An aggregate is an object that lives in the same row as its owner. Aggregate objects do not have identify because they are really part of the parent – deleting the parent also deletes the aggregate (because they live in the same row).

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). The target object is not shared by other types of the source object

For more information, see "Aggregate Object Mapping" in Oracle Toplink Developer's Guide.

Map the Aggregate Class

First, we will define the EmploymentPeriod descriptor as an aggregate descriptor.

Right-click the EmploymentPeriod descriptor in the Structure window and select Descriptor Type > Aggregate.
Map the endDate and startDate attributes as direct mappings (see "Create Direct Mappings").

Notice that the Database Field field is not available for either mapping. The actual column name. The aggregate descriptor describes only the logical mapping (in this example, the direct mapping for both attributes). The physical mapping (the column named) will be determined by the columns of the database table to which the parent object is mapped, and is specified later.

Map the Aggregate Relationships

Now we will define the aggregate mappings.

Expand the Employee descriptor in the Structure window.
Right-click the period attribute and select Map As > Aggregate.
Select the General tab. In the Reference Descriptor field select EmploymentPeriod.
Select the Fields tab.
- For the EmploymentPeriod.endDate, select the EMPLOYEE.END_DATE field.
- For the EmploymentPeriod.startDate, select the EMPLOYEE.START_DATE field.

Fields Tab for Aggregate Mapping

Create Direct Collection Mappings

Use direct collection to map a single Java attribute to a collection of simple Java types. In this tutorial, the Employee descriptor's responsibilityList attribute contains a list of responsibilities.

For more information, see "Direct Collection Mapping" in Oracle Toplink Developer's Guide.

Show me...

Expand the Employee descriptor in the Structure window.
Right-click the responsibilitiesList attribute and select Map As > Direct Collection.
Select the General tab.
- In the Target Table field, select RESPONS.
- In the Direct Value Field field, select RESPONS.DESCRIP.
Confirm that the Use Indirection and ValueHolder options are selected.

A value holder is an instance of a class that implements the ValueHolderInterface interface. This object stores the information necessary to retrieve the object it is replacing from the database. If the application does not access the value holder, the replaced object is never read from the database. This can result in a significant performance improvement.

For more information, see "Value Holder Indirection" in Oracle Toplink Developer's Guide.
Select the Table Reference tab.
- In the Target Table field, select RESPONS.
- In the Direct Value Field field, select RESPONS.DESCRIP.
Select the Table Reference tab. In the Table Reference field, select RESPONS_EMPLOYEE.

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

Direct Collection

Map the Remaining Attributes

Now that you have successfully created direct, one-to-one, one-to-many, many-to-many, object type, direct collection, and aggregate mappings for the Employee descriptor, use this table to map the remaining attributes in the project:

Descriptor	Attribute	Mapping
Employee	firstName	Direct mapping to EMPLOYEE.FNAME
	id	Direct mapping to EMPLOYEE.EMP_ID
	lastName	Direct mapping to EMPLOYEE.LNAME
	managedEmployees	One to many mapping to the Employee descriptor. On the Table Reference tab, select EMPLOYEE_EMPLOYEE as the Table Reference.
	manager	One to one mapping to the Employee descriptor. On the Table Reference tab, select EMPLOYEE_EMPLOYEE as the Table Reference.
	salary	Direct mapping to SALARY.SALARY Notice that this attribute from the Employee class is mapped to the secondary table that we configured in "Associating with Multiple Tables".
	version	Direct mapping to EMPLOEE.VERSION On the General tab, select the Read Only option.
LargeProject	budget	Direct mapping to LPROJECT.BUDGET
LargeProject	milestoneVersion	Direct mapping to LPROJECT.MILESTONE
PhoneNumber	areaCode	Direct mapping to PHONE.AREA_CODE
	number	Direct mapping to PHONE.P_NUMBER
	type	Direct mapping to PHONE.TYPE
Project	description	Direct mapping to PROJECT.DESCRIP
	id	Direct mapping to PROJECT.PROJ_ID
	name	Direct mapping to PROJECT.PROJ_NAME
	teamLeader	One to one mapping to the Employee descriptor. On the Table Reference tab, select PROJECT_EMPLOYEE as the Table Reference.

Because the SmallProject does not add any attribute to Project, there are no additional mappings to complete for the SmallProject descriptor.