Aggregate Object Mapping

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 table(s) 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.

An aggregate mapping allows you to associate data members in the target object with fields in the source object's underlying database tables.

You configure the aggregate mapping in the source object's descriptor. However, before doing so, you must designate the target object's descriptor as an aggregate (see "Configuring a Relational Descriptor as a Class or Aggregate Type").

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

You cannot configure one-to-one, one-to-many, or many-to-many mappings from a nonaggregate object to an aggregate target object.

You can configure such mappings from an aggregate target object to another nonaggregate object. If you configure a one-to-many mapping from an aggregate target object to another nonaggregate object, you must configure a one-to-one mapping from the other object back to the source object that owns the aggregate (instead of to the aggregate target object itself). This is because the source object contains the table and primary key information of the aggregate target.

You can configure inheritance for a descriptor designated as an aggregate (see "Descriptors and Inheritance"), however, in this case, all the descriptors in the inheritance tree must be aggregates. Aggregate and class descriptors cannot exist in the same inheritance tree.

This section describes the following:

• Aggregate Object Mappings with a Single Source Object

• Aggregate Object Mappings With Multiple Source Objects

• Implementing an Aggregate Object Relationship Mapping

You can use an aggregate object mapping with a change policy (see "Configuring Change Policy".

For more information on configuring an aggregate object relationship mapping, see "Configuring a Relational Aggregate Object Mapping".

Aggregate Object Mappings with a Single Source Object

Figure 36-8 shows an example aggregate object mapping between source object Employee and target object Period. In this example, the target object is not shared by other types of source object.

Figure 36-8 Aggregate Object Mapping with a Single Source Object

Description of "Figure 36-8 Aggregate Object Mapping with a Single Source Object"

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

Aggregate Object Mappings With Multiple Source Objects

Figure 36-9 shows an example aggregate object mapping in which different source objects–Employee and Project–map instances of the same type of target object, Period.

Figure 36-9 Aggregate Object Mapping with Multiple Source Objects

Description of "Figure 36-9 Aggregate Object Mapping with Multiple Source Objects "

When you configure the aggregate object mapping in the source object, you choose the source object table for that particular mapping. This allows different source types to store the same target information within their tables. Each source object's table may use different field names. TopLink automatically manages the case where multiple source object tables use different field names.

For example, in Figure 36-9, The Employee attribute employPeriod is mapped by an aggregate object mapping to target object Period. This mapping associates Period attribute startDate with EMPLOYEE table field START_DATE. The Project attribute projectPeriod is also mapped by an aggregate object mapping to target object Period. This mapping associates Period attribute startDate with PROJECT table field S_DATE.

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

Implementing an Aggregate Object Relationship Mapping

You must ensure that the following takes place:

• The descriptor of the target class declares 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 adds 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, TopLink writes NULLs to the aggregate database fields (see "Configuring Allowing Null Values"). 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.)