Working with Aggregate Object Mappings

Two objects are related by aggregation if there is a strict one-to-one relationship between the objects, and all the attributes of the second object can be retrieved from the same table(s) as the owning object. This means that if the source (parent) object exists, then the target (child or owned) object must also exist, as illustrated in Figure 6-7.

Aggregate objects are privately owned and should not be shared or referenced by other objects.

Note: When using an aggregate descriptor in an inheritance, all the descriptors in the inheritance tree must be aggregates. Aggregate and Class descriptors cannot exist in the same inheritance tree.

Figure 6-7 Aggregate Object Mapping

Description of the illustration agmapfig.gif

To implement an aggregate object mapping:

• The descriptor of the target class must declare itself to be an aggregate object. Because all its information comes from its parent's table(s), the target descriptor does not have a specific table associated with it. You must, however, choose one or more candidate table(s) from which you can use fields in mapping the target. In the example above, you could choose the EMPLOYEE table so that the START_DATE and END_DATE fields are available during mapping.

• The descriptor of the source class must add an aggregate object mapping that specifies the target class. In the example above, the Employee class has an attribute called employPeriod that would be mapped as an aggregate object mapping with Period as the reference class. The source class must ensure that its table has fields that correspond to the field names registered with the target class.

• If a source object has a null target reference, OracleAS TopLink writes NULLs to the aggregate database fields. When the source is read from the database, it can handle this null target in one of two ways:

  • Create an instance of the object with all its attributes equal to null.

  • Put a null reference in the source object without instantiating a target. (This is the default method of handling null targets.)

Target objects can also have multiple sources, hence the need to choose a candidate table during its mapping. This allows different source types to store the same target information within their tables. Each source class must have table fields that correspond to the field names registered with the target class. If one of the source tables has different field names than the names registered with the target class, the source class must translate the field names.

In Figure 6-8:

• The Period class has a direct-to-field mapping between startDate and START_DATE.

• The Employee class can use the Period class as a normal aggregate to write to its START_DATE column.

• The PROJECT table does not have a field called START_DATE, so the Project descriptor must provide a field translation on its aggregate object mapping from START_DATE to S_DATE. (If the PROJECT table had a START_DATE column, this field translation would be unnecessary.)

Figure 6-8 Aggregation with Multiple Source Classes

Description of the illustration agmultiple.gif

Aggregate target classes not shared among multiple source classes can have any type of mapping, including other aggregate object mappings.

Aggregate target classes shared with multiple source classes cannot have one-to-many or many-to-many mappings.

Other classes cannot reference the aggregate target with one-to-one, one-to-many, or many-to-many mappings. If the aggregate target has a one-to-many relationship with another class, the other class must provide a one-to-one relationship back to the aggregate's parent class, instead of the aggregate child. This is because the source class contains the table and primary key information of the aggregate.

Aggregate descriptors can make use of inheritance. The subclasses must also be declared as aggregate and be contained in the source's table. See "Working with Inheritance" on page 4-39 for more information.

Creating a Target Descriptor

Use this procedure to create a target descriptor to employ with an aggregate mapping. You must configure the target before specifying field translations in the parent descriptor.

To create the target descriptor:

1. 
   Description of the illustration agdesicn.gif
   
   In the Navigator pane, right-click the target descriptor and choose Aggregate from the pop-up menu. The descriptor's icon in the Navigator pane changes to an Aggregate Descriptor.

   
   Description of the illustration agdesbtn.gif
   
   You can also choose Selected > Aggregate from the menu or by clicking the Aggregate Descriptor button.

2. Map the attributes, specifying all but field information.

   • For a one-to-one mapping, pick a reference between a table in the target descriptor and a table in a descriptor that will have a mapping to this aggregate target. If this aggregate target will be mapped to multiple source descriptors, pick a reference whose foreign key field(s) will be in the tables of one of the source descriptors.

   • For a one-to-many mapping or a many-to-many mapping, pick a reference whose foreign key field(s) will be in the referenced descriptor's tables and whose primary key field will be in the source descriptor's tables.

3. Continue with "Creating an Aggregate Object Mapping" to create the aggregate mapping.

Creating an Aggregate Object Mapping

Use this procedure to create an aggregate object mapping. You must also create a target descriptor to use with the aggregate mapping.

To create an aggregate object mapping:

1. 
   Description of the illustration agmapbtn.gif
   
   In the Navigator pane, select the mapping to be mapped and click the Aggregate Mapping button on the mapping toolbar.

   The Aggregate mapping tab appears in the Editor pane.

Figure 6-9 Aggregate Mapping General Tab

Description of the illustration agmapgen.gif

1. Use the Reference Descriptor drop-down list on the General tab to choose a reference descriptor.

   
   

   Note: You can select only aggregate descriptors. See "Creating a Target Descriptor" for details.

   
   

2. You can also specify:

   • Read-only attributes – See "Specifying Read-Only Settings" on page 4-72.

   • Access methods – See "Specifying Direct Access and Method Access" on page 4-71.

   • Null values – See "Defaulting Null Values" on page 4-73.

3. Click the Fields tab to specify field information for the target descriptor's mapping.

Figure 6-10 Aggregate Mapping Fields Tab

Description of the illustration agmapfld.gif

1. Use this table to enter data in each field:

Field	Description
Field Description	Available fields from the reference descriptor. These fields are for display only and cannot be changed on this tab.
Field	Use the drop-down list to choose a field to use for the mapping for each field description.