Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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 objectFoot 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 objectFootref 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 1 See 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:

1. Create a one-to-one EIS mapping on `Employee` attribute `project`.

2. Configure the reference descriptor as `Project` (see "Configuring Reference Descriptors").

3. Configure the source and target foreign keys (see "Configuring Foreign Key Pairs").

   In this example:

   - Source XML Field: `@project-id`

   - Target XML Field: `@id`

4. 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:

1. Create a one-to-one EIS mapping on `Employee` attribute `project`.

2. Configure the reference descriptor as `Project` (see "Configuring Reference Descriptors").

3. 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()`

4. 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()");