77 Introduction to EIS Mappings

TopLink enterprise information system (EIS) mappings provide support for accessing legacy data sources and enterprise applications through Java EE Connector architecture (JCA) adapter. TopLink EIS mappings use the JCA Common Client Interface (CCI) to access the EIS through its resource adapter. This provides the ability to directly map from an existing Java object model to any transactional data source, such as mainframes with flat file/hierarchical data.

An EIS mapping transforms object data members to the EIS record format defined by the object's descriptor.

This chapter includes the following sections:

For information on mapping concepts and features common to more than one type of TopLink mappings, see Chapter 17, "Introduction to Mappings".

77.1 EIS Mapping Types

TopLink supports the EIS mappings listed in Table 77-1.

Table 77-1 TopLink Object EIS Mapping Types

EIS Mapping Type Description Oracle JDeveloper
 TopLink Workbench Java

Direct mapping (see Section 77.3, "EIS Direct Mapping")

Map a simple object attribute directly to an EIS record.

 Supported Supported Supported

Composite direct collection mapping (see Section 77.4, "EIS Composite Direct Collection Mapping")

Map a collection of Java attributes directly to an EIS record.

 Supported Supported Supported

Composite object mapping (see Section 77.5, "EIS Composite Object Mapping")

Map a Java object to an EIS record in a privately owned one-to-one relationship. Composite object mappings represent a relationship between two classes.

 Supported Supported Supported

Composite collection mapping (see Section 77.6, "EIS Composite Collection Mapping")

Map a Map or Collection of Java objects to an EIS record in a privately owned one-to-many relationship.

 Supported Supported Supported

One-to-one mapping (see Section 77.7, "EIS One-to-One Mapping")

Define a reference mapping that represents the relationship between a single source object and a single mapped persistent Java object.

 Supported Supported Supported

One-to-many mapping (see Section 77.8, "EIS One-to-Many Mapping")

Define a reference mapping that represents the relationship between a single source object and a collection of mapped persistent Java objects.

 Supported Supported Supported

Transformation mapping (see Section 77.9, "EIS Transformation Mapping")

Create custom mappings where one or more EIS record fields can be used to create the object to be stored in a Java class's attribute.

 Supported Supported Supported

77.2 EIS Mapping Concepts

This section describes concepts unique to TopLink EIS mappings, including the following:

77.2.1 EIS Record Type

TopLink supports the following JCA EIS record types:

You configure the record type at the EIS descriptor level (see Section 76.4, "Configuring Record Format"). EIS mappings use the record type of their EIS descriptor to determine how to map Java attributes. That is, you use the same EIS mapping regardless of the record type, with which you configure an EIS descriptor.

Note:

Not all JCA adapters support all record types. Consult your JCA adapter documentation for details.

77.2.1.1 Indexed Records

The javax.resource.cci.IndexedRecord represents an ordered collection of record elements based on the java.util.List interface.

The TopLink runtime maps Java objects to indexed record elements or subrecords of an indexed record depending on the type of EIS mapping you use (see Section 77.2.6, "Composite and Reference EIS Mappings").

77.2.1.2 Mapped Records

The javax.resource.cci.MappedRecord represents a key-value map-based collection of record elements based on the java.util.Map interface.

The TopLink runtime maps Java objects to mapped record elements or subrecords of a mapped record depending on the type of EIS mapping you use (see Section 77.2.6, "Composite and Reference EIS Mappings").

77.2.1.3 XML Records

An XML record represents a javax.resource.cci.Record as an XML schema (XSD)-based XML document. Not all JCA adapters support XML records.

The TopLink runtime maps Java objects to XML documents according to your XSD and the behavior defined for XML mappings.

For more information, see Chapter 53, "Introduction to XML Mappings".

77.2.2 XPath Support

When using XML records, TopLink EIS mappings use XPath statements to efficiently map the attributes of a Java object to locations in an XML record. For more information about using XPath with XML mappings, see Section 17.2.7, "Mappings and XPath".

77.2.3 xsd:list and xsd:union Support

When using XML records, you can use EIS direct (see Section 77.3, "EIS Direct Mapping") and composite direct collection (see Section 77.4, "EIS Composite Direct Collection Mapping") mappings to map to xsd:list and xsd:union types in an XML record.

For more information, see Section 17.2.8, "Mappings and xsd:list and xsd:union Types".

77.2.4 jaxb:class Support

When using XML records, you can configure an EIS composite object mapping (see Section 77.5, "EIS Composite Object Mapping") to accommodate jaxb:class customizations with the following XSD structures:

  • all

  • sequence

  • choice

  • group

For more information, see Section 17.2.9, "Mappings and the jaxb:class Customization".

77.2.5 Typesafe Enumeration Support

You can map a Java attribute to a typesafe enumeration using the JAXBTypesafeEnumConverter with an EISDirectMapping or EISCompositeDirectCollectionMapping with XML records.

For more information, see Section 17.2.10, "Mappings and JAXB Typesafe Enumerations".

77.2.6 Composite and Reference EIS Mappings

TopLink supports composite and reference EIS mappings. Although there is a source and target object in both mapping types, the TopLink runtime handles interactions with each differently. This section explains how.

77.2.6.1 Composite EIS Mappings

In a composite EIS mapping (Section 77.4, "EIS Composite Direct Collection Mapping", Section 77.5, "EIS Composite Object Mapping", and Section 77.6, "EIS Composite Collection Mapping"), the source object contains (owns) the target object.

TopLink puts the attributes of the target (owned) object (or the owned collection of objects) into the source (owning) object's record as a subrecord. The target object needs not be a root object type (see Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type"): it needs not have interactions defined for it.

Figure 77-1 illustrates a read interaction on an instance of the Customer class using indexed records. For the composite object EIS mapping defined for the address attribute, TopLink creates an Address subrecord in the Customer record.

Figure 77-1 EIS Composite Mappings

Description of Figure 77-1 follows
Description of "Figure 77-1 EIS Composite Mappings"

77.2.6.2 Reference EIS Mappings

In a reference EIS mapping (Section 77.7, "EIS One-to-One Mapping" and Section 77.8, "EIS One-to-Many Mapping"), the source object contains only a foreign key (pointer) to the target object or, alternatively, the target object contains a foreign key to the source object (key on target).

TopLink puts the foreign key of the target object into the source object's record as a simple value. When an interaction is executed on the source object, TopLink uses the selection interaction that you define on its descriptor to retrieve the appropriate target object instance and creates a record for it in the source object's transaction. By default, the selection interaction is the target object's read interaction. If the read interaction is not sufficient, you can define a separate selection interaction (see Section 78.4, "Configuring Selection Interaction"). Because both the source and target object use interactions, they must both be of a root object type (see Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type").

Figure 77-2 illustrates a read interaction on an instance of the Order class using indexed records. For the one-to-one EIS mapping defined for the customer attribute, TopLink puts the target Customer object's foreign key into the Order record as a simple value. TopLink then uses the selection interaction you configure on the Order descriptor to retrieve the appropriate instance of Customer and creates a record for it in the Order object's transaction.

Figure 77-2 EIS Reference Mappings

Description of Figure 77-2 follows
Description of "Figure 77-2 EIS Reference Mappings"

77.2.7 EIS Mapping Architecture

Figure 77-3 illustrates the following possible TopLink EIS mapping architectures:

  • JDBC database gateway (such as Oracle Database 10g)

  • JDBC adapter

  • Proprietary adapter (such as Oracle Interconnect)

  • JCA

Figure 77-3 Possible EIS Mapping Architectures

Description of Figure 77-3 follows
Description of "Figure 77-3 Possible EIS Mapping Architectures"

The best solution may vary, depending on your specific EIS and infrastructure.

77.3 EIS Direct Mapping

An EIS direct mapping maps a simple object attribute directly to an EIS record according to its descriptor's record type, as shown in Table 77-2.

Table 77-2 EIS Direct Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed

Maps directly to a field in the indexed record.

Mapped

Maps directly to a field in the mapped record.

XML

Maps directly to an attribute or text node in the XML recordFoot 1 .

Footnote 1 See also Section 53.3, "XML Direct Mapping".

Figure 77-4 illustrates a direct EIS mapping between Order class attribute orderedBy and XML record attribute ordered_by within the order element.

Figure 77-4 EIS Direct Mappings

Description of Figure 77-4 follows
Description of "Figure 77-4 EIS Direct Mappings"

See Chapter 79, "Configuring an EIS Direct Mapping" for more information.

77.4 EIS Composite Direct Collection Mapping

An EIS composite direct collection mapping maps a collection of Java attributes directly to an EIS record according to its descriptor's record type, as shown in Table 77-3.

Table 77-3 EIS Composite Direct Collection Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed

Maps directly to a subrecord in the indexed recordFoot 1 .

Mapped

Maps directly to a subrecord in the mapped recordFootref 1.

XML

Maps directly to an attribute or text node in the XML recordFoot 2 .

Footnote 1 See also Section 77.2.6.1, "Composite EIS Mappings".

Footnote 2 See also Section 53.4, "XML Composite Direct Collection Mapping".

Figure 77-5 illustrates a composite direct collection mapping between Order class attribute items and an XML record. The Order attribute items is a collection type (such as Vector). It is mapped to an XML record composed of an order element that contains a sequence of item elements.

Figure 77-5 EIS Composite Direct Collection Mapping

Description of Figure 77-5 follows
Description of "Figure 77-5 EIS Composite Direct Collection Mapping"

See Chapter 80, "Configuring an EIS Composite Direct Collection Mapping" for more information.

77.5 EIS Composite Object Mapping

An EIS composite object mapping maps a Java object to a privately owned one-to-one relationship in an EIS record according to its descriptor's record type, as shown in Table 77-4.

Table 77-4 EIS Composite Object Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed

Maps directly to a subrecord in the indexed recordFoot 1 .

Mapped

Maps directly to a subrecord in the mapped recordFootref 1.

XML

Maps directly to an attribute or text node in the XML recordFoot 2 .

Footnote 1 See also Section 77.2.6.1, "Composite EIS Mappings".

Footnote 2 See also Section 53.5, "XML Composite Object Mapping".

Figure 77-6 illustrates a composite object EIS mapping between Order class attribute address and an XML record. Order attribute address is mapped to an XML record composed of an order element that contains an address element.

Figure 77-6 EIS Composite Object Mappings

Description of Figure 77-6 follows
Description of "Figure 77-6 EIS Composite Object Mappings"

You can use an EIS composite object mapping with a change policy (see Section 119.30, "Configuring Change Policy".

See Chapter 81, "Configuring an EIS Composite Object Mapping" for more information.

77.6 EIS Composite Collection Mapping

An EIS composite collection mapping maps a collection of Java objects to a privately owned one-to-many relationship in an EIS record according to its descriptor's record type, as shown in Table 77-5. Composite collection mappings can reference any class that has a TopLink descriptor.

Table 77-5 EIS Composite Collection Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed

Maps directly to a subrecord in the indexed recordFoot 1 .

Mapped

Maps directly to a subrecord in the mapped recordFootref 1.

XML

Maps directly to an attribute or text node in the XML recordFoot 2 .

Footnote 1 See also Section 77.2.6.1, "Composite EIS Mappings".

Footnote 2 See also Section 53.6, "XML Composite Collection Mapping".

Figure 77-7 illustrates a composite collection EIS mapping between Phone class attribute phoneNumbers and an XML record. Employee attribute phoneNumbers is mapped to an XML record composed of an EMPLOYEE element that contains a sequence of PHONE_NUMBER elements.

Figure 77-7 EIS Composite Collection Mappings

Description of Figure 77-7 follows
Description of "Figure 77-7 EIS Composite Collection Mappings"

See Chapter 82, "Configuring an EIS Composite Collection Mapping" for more information.

77.7 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 Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type")

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

Table 77-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 Section 77.2.6.2, "Reference EIS Mappings".

This section describes the following:

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

77.7.1 EIS One-to-One Mappings with Key on Source

Figure 77-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 77-8 EIS One-to-One Mapping with Key on Source

Description of Figure 77-8 follows
Description of "Figure 77-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 Section 78.3, "Configuring Reference Descriptors").

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

    In this example:

    • Source XML Field: @project-id

    • Target XML Field: @id

  4. Configure the selection interaction (see Section 78.4, "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 77-1, you can configure an EIS one-to-one mapping with key on source, as Example 77-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 77-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 77-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()");

77.7.2 EIS One-to-One Mappings with Key on Target

Figure 77-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 77-9 EIS One-to-One Mapping with Key on Target

Description of Figure 77-9 follows
Description of "Figure 77-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 Section 78.3, "Configuring Reference Descriptors").

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

    In this example:

    • Source XML Field: firstName/text()

    • Target XML Field: leader/text()

  4. Configure the selection interaction (see Section 78.4, "Configuring Selection Interaction").

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

Given the XSD shown in Example 77-3, you can configure an EIS one-to-one mapping with key on target, as Example 77-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 77-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 77-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()");

77.8 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 Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type").

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

Table 77-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 objectFoot 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 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 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 1 See also Section 77.2.6.2, "Reference EIS Mappings".

This section describes the following:

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

77.8.1 EIS One-to-Many Mappings with Key on Source

Figure 77-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 77-10 EIS One-to-Many Mapping with Key on Source

Description of Figure 77-10 follows
Description of "Figure 77-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 Section 78.3, "Configuring Reference Descriptors"). Figure 77-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:

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

  2. Configure the reference descriptor as Project (see Section 78.3, "Configuring Reference Descriptors").

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

    In this example:

    • Source XML Field: PROJECT

    • Target XML Field: @ID

  4. Configure the selection interaction (see Section 78.4, "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 77-3, you can configure an EIS one-to-many mapping with key on source, as Example 77-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 77-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 77-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()");

77.8.2 EIS One-to-Many Mappings with Key on Target

Figure 77-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 77-11 EIS One-to-Many Mapping with Key on Target

Description of Figure 77-11 follows
Description of "Figure 77-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:

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

  2. Configure the reference descriptor as Project (see Section 78.3, "Configuring Reference Descriptors").

  3. Configure the source and target foreign keys (see Section 83.2, "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:

  4. Configure the selection interaction (see Section 78.4, "Configuring Selection Interaction").

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

Given the XSD shown in Example 77-3, you can configure an EIS one-to-many mapping with key on target, as Example 77-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 77-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 77-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()");

77.9 EIS Transformation Mapping

A transformation EIS mapping lets you create a custom mapping, where one or more fields in an EIS record can be used to create the object to be stored in a Java class's attribute.

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

Table 77-8 EIS Transformation Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed

.The field transformer adds data to the indexed record (you have access to the indexed record in the attribute transformer).

Mapped

.The field transformer adds data to the mapped record (you have access to the mapped record in the attribute transformer).

XML

.The field transformer adds data to the XML record (you have access to the XML record in the attribute transformer).

As Figure 77-12 illustrates, you configure the transformation mapping with an oracle.toplink.mappings.transformers.AttributeTransformer instance to perform the XML instance-to-Java attribute transformation at unmarshall time. In this example, the AttributeTransformer combines two XML text nodes into a single Java object.

Figure 77-12 EIS Transformation Mappings

Description of Figure 77-12 follows
Description of "Figure 77-12 EIS Transformation Mappings "

See Chapter 85, "Configuring an EIS Transformation Mapping" for more information.