EIS One-to-Many Mapping

An EIS one-to-many mapping is a reference mapping that represents the relationship between a single source object and a collection of target objects. The source object usually contains a foreign key (pointer) to the target objects (key on source); alternatively, the target objects may contain a foreign key to the source object (key on target). Because both the source and target objects use interactions, they must all be of a root object type (see "Configuring an EIS Descriptor as a Root or Composite Type").

Table 56-7 summarizes the behavior of this mapping depending on the EIS record type you are using.

Table 56-7 EIS One-to-Many Mapping by EIS Record Type

EIS Record Type	Mapping Behavior
Indexed	A new indexed record is created for each target object^Foot 1: With the Key on Source use case, the foreign key(s) is added to the record for the source object for each target object. With the Key on Target use case, the foreign key(s) is added to the record for the target object
Mapped	A new mapped record is created for each target object^Footref 1: With the Key on Source use case, the foreign key(s) is added to the record for the source object. With the Key on Target use case, the foreign key(s) is added to the record for the target object
XML	.A new XML record is created for each target object: With the Key on Source use case, the foreign key(s) is added to the record for the source object for each target object. With the Key on Target use case, the foreign key(s) is added to the record for the target object

EIS Record Type

Mapping Behavior

Indexed

A new indexed record is created for each target object^Foot 1:

With the Key on Source use case, the foreign key(s) is added to the record for the source object for each target object.
With the Key on Target use case, the foreign key(s) is added to the record for the target object

Mapped

A new mapped record is created for each target object^Footref 1:

With the Key on Source use case, the foreign key(s) is added to the record for the source object.
With the Key on Target use case, the foreign key(s) is added to the record for the target object

XML

.A new XML record is created for each target object:

With the Key on Source use case, the foreign key(s) is added to the record for the source object for each target object.
With the Key on Target use case, the foreign key(s) is added to the record for the target object

^Footnote 1See also "Reference EIS Mappings".

This section describes the following:

EIS One-to-Many Mappings With Key on Source
EIS One-to-Many Mappings With Key on Target

See Chapter 63, "Configuring an EIS One-to-Many Mapping" for more information.

EIS One-to-Many Mappings With Key on Source

Figure 56-10 illustrates an EIS one-to-many mapping between the Employee class attribute projects and multiple Project class instances using XML records in a key on source design.

Figure 56-10 EIS One-to-Many Mapping with Key on Source

Description of "Figure 56-10 EIS One-to-Many Mapping with Key on Source"

When a read interaction is executed on the Employee object, TopLink puts each target Project object's foreign key into the Employee record as a subelement. If you specify only one pair of source and target XML fields, by default, the foreign keys are not grouped in the Employee record. If you specify more than one pair of source and target XML fields, you must choose a grouping element (see "Configuring Reference Descriptors"). Figure 56-10 shows an Employee record with grouping element Project. TopLink then uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instances of Project and creates a record for each in the Employee object's transaction. In this example, you can designate the Project class's read interaction as the selection interaction.

The general procedure for creating and configuring this mapping is as follows:

Create a one-to-many EIS mapping on Employee attribute project.
Configure the reference descriptor as Project (see "Configuring Reference Descriptors").
Configure the source and target foreign keys (see "Configuring Foreign Key Pairs").

In this example:
- Source XML Field: PROJECT
- Target XML Field: @ID
Configure the selection interaction (see "Configuring Selection Interaction").

In this example, you can designate the Project class's read interaction as the selection interaction.

Given the XSD shown in Example 56-3, you can configure an EIS one-to-many mapping with key on source, as Example 56-4 shows. In this case, the source object contains a foreign key reference to the target object. In the following example, the source object is Employee, and the target object is Project. Here, the Employee object has one or more Project instances that are referenced by Project id.

Example 56-5 XML Schema for EIS One-to-Many Mapping with Key on Source

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:element name="project" type="project-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>
            <xsd:element name="name" type="xsd:string"/>
            <xsd:element name="projects">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="project-id"
                            type="xsd:integer" maxOccurs="unbounded"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:complexType name="project-type">
        <xsd:sequence>
            <xsd:element name="id" type="xsd:integer"/>
            <xsd:element name="leader" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

Example 56-6 EIS One-to-Many Mapping with Key on Source

// Employee descriptor
EISDescriptor descriptor = new EISDescriptor();
descriptor.setJavaClass(Employee.class);
descriptor.setDataTypeName("employee");
descriptor.setPrimaryKeyFieldName("name/text()");

EISOneToManyMapping projectMapping = new EISOneToManyMapping();
projectMapping.setReferenceClass(Project.class);
projectMapping.setAttributeName("projects");
projectMapping.setForeignKeyGroupingElement("projects"); projectMapping.setIsForeignKeyRelationship(true); projectMapping.dontUseIndirection();
projectMapping.addForeignKeyFieldName("project-id/text()", "id/text()");

EIS One-to-Many Mappings With Key on Target

Figure 56-9 illustrates an EIS one-to-many mapping between the Employee class attribute projects and multiple Project class instances using XML records in a key on target design. You still configure a one-to-one EIS mapping between Employee and Project but in this design, the Project attribute leader contains the foreign key of the Employee object.

Figure 56-11 EIS One-to-Many Mapping with Key on Target

Description of "Figure 56-11 EIS One-to-Many Mapping with Key on Target"

When a read interaction is executed on the Employee object, TopLink uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instances of Project and creates a record for each in the Employee object's transaction. In this example, the Project class's read interaction is unlikely to be sufficient: it is likely implemented to read based on Project attribute Id, not on leader. If this is the case, you must define a separate selection interaction on the Employee descriptor that does the following: finds the Project, whose leader equals X, where X is "Jane".

Note that in this configuration, Project attribute leader is not persisted. If you want this attribute persisted, you must configure a one-to-one EIS mapping from it to Employee attribute firstName.

The general procedure for creating and configuring this mapping is as follows:

Create a one-to-one EIS mapping on Employee attribute project.
Configure the reference descriptor as Project (see "Configuring Reference Descriptors").
Configure the source and target foreign keys (see "Configuring Foreign Key Pairs").

In this example, you select Foreign Keys Located On Source and specify one pair of source and target XML fields:
- Source XML Field:
- Target XML Field:
Configure the selection interaction (see "Configuring Selection Interaction").

In this example, you must define a separate selection interaction on the Employee descriptor.

Given the XSD shown in Example 56-3, you can configure an EIS one-to-many mapping with key on target as Example 56-4 shows. In this case, the target object contains a foreign key reference to the source object. In the following example, the source object is Employee, and the target object is Project. Here, each Project references its leader using the employee's name.

Example 56-7 XML Schema for EIS One-to-Many Mapping with Key on Target

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:element name="project" type="project-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>
            <xsd:element name="name" type="xsd:string"/>
            <xsd:element name="projects">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="project-id"
                            	type="xsd:integer" maxOccurs="unbounded"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:complexType name="project-type">
        <xsd:sequence>
            <xsd:element name="id" type="xsd:integer"/>
            <xsd:element name="leader" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

Example 56-8 EIS One-to-Many Mapping with Key on Target

// Project descriptor
EISDescriptor descriptor = new EISDescriptor();
descriptor.setJavaClass(Project.class);
descriptor.setDataTypeName("project");
descriptor.setPrimaryKeyFieldName("id/text()");

EISOneToManyMapping leaderMapping = new EISOneToOneMapping();
leaderMapping.setReferenceClass(Employee.class);
leaderMapping.setAttributeName("leader");
leaderMapping.dontUseIndirection();
leaderMapping.addForeignKeyFieldName("leader/text()", "name/text()");