EIS One-to-One Mapping

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

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

Table 56-6 EIS One-to-One Mapping by EIS Record Type

EIS Record Type	Mapping Behavior
Indexed	A new indexed record is created for the target object^Foot 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
Mapped	A new mapped record is created for the 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 the target object: 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

EIS Record Type

Mapping Behavior

Indexed

A new indexed record is created for the target object^Foot 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

Mapped

A new mapped record is created for the 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 the target object:

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

^Footnote 1See also "Reference EIS Mappings".

This section describes the following:

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

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

EIS One-to-One Mappings With Key on Source

Figure 56-8 illustrates a EIS one-to-one mapping between the Employee class attribute project and the Project class using XML records in a key on source design.

Figure 56-8 EIS One-to-One Mapping with Key on Source

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

When a read interaction is executed on the Employee object, TopLink puts the target Project object's primary key into the Employee record as a simple value. TopLink then uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instance of Project and creates a record for it 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-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:
- Source XML Field: @project-id
- 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-1, you can configure an EIS one-to-one mapping with key on source, as Example 56-2 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 a Project that is referenced using the project's id.

Example 56-1 XML Schema for EIS One-to-One 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="project">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="project-id" type="xsd:integer"/>
                    </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-2 EIS One-to-One Mapping with Key On Source

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

EISOneToOneMapping projectMapping = new EISOneToOneMapping();
projectMapping.setReferenceClass(Project.class);
projectMapping.setAttributeName("project");
projectMapping.dontUseIndirection();
projectMapping.addForeignKeyFieldName("project/project-id/text()", "id/text()");

EIS One-to-One Mappings With Key on Target

Figure 56-9 illustrates EIS one-to-one mapping between the Employee class attribute project and the Project class 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-9 EIS One-to-One Mapping with Key on Target

Description of "Figure 56-9 EIS One-to-One 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 instance of Project and creates a record for it 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 the value of Employee attribute firstName.

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:
- Source XML Field: firstName/text()
- Target XML Field: leader/text()
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-one 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, a Project references its leader using the employee's name.

Example 56-3 XML Schema for EIS One-to-One 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="project">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="project-id" type="xsd:integer"/>
                    </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-4 EIS One-to-One Mapping with Key on Target

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

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