Difference between revisions of "Introduction to EIS Mappings (ELUG)"

Latest revision as of 11:12, 23 July 2012

For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/

EclipseLink enterprise information system (EIS) mappings provide support for accessing legacy data sources and enterprise applications through Java EE Connector architecture (JCA) adapter. EclipseLink 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.

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

EIS Mapping Types

EclipseLink supports the EIS mappings listed in this table.

EIS Mapping Concepts

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

• EIS Record Type
• XPath Support
• xsd:list and xsd:union Support
• jaxb:class Support
• Typesafe Enumeration Support
• Composite and Reference EIS Mappings
• EIS Mapping Architecture

EIS Record Type

EclipseLink supports the following JCA EIS record types:

• Indexed Records
• Mapped Records
• XML RecordsXML Records

You configure the record type at the EIS descriptor level (see 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.

Indexed Records

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

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

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 EclipseLink runtime maps Java objects to mapped record elements or subrecords of a mapped record depending on the type of EIS mapping you use (see Composite and Reference EIS Mappings).

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 EclipseLink runtime maps Java objects to XML documents according to your XSD and the behavior defined for XML mappings.

For more information, see Introduction to XML Mappings.

XPath Support

When using XML records, EclipseLink 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 Mappings and XPath.

xsd:list and xsd:union Support

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

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

jaxb:class Support

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

• all
• sequence
• choice
• group

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

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 Mappings and JAXB Typesafe Enumerations.

Composite and Reference EIS Mappings

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

Composite EIS Mappings

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

EclipseLink 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 Configuring an EIS Descriptor as a Root or Composite Type): it needs not have interactions defined for it.

The EIS Composite Mappings figure 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, EclipseLink creates an Address subrecord in the Customer record.

EIS Composite Mappings

Reference EIS Mappings

In a reference EIS mapping ( EIS One-to-One Mapping and 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).

EclipseLink 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, EclipseLink 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 Configuring Selection Interaction). 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).

The EIS Reference Mappings figure 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, EclipseLink puts the target Customer object's foreign key into the Order record as a simple value. EclipseLink 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.

EIS Reference Mappings

EIS Mapping Architecture

The Possible EIS Mapping Architectures figure illustrates the following possible EclipseLink EIS mapping architectures:

• JDBC database gateway (such as Oracle Database 10g)
• JDBC adapter
• Proprietary adapter (such as Oracle Interconnect)
• JCA

Possible EIS Mapping Architectures

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

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 this table.

EIS Direct Mapping by EIS Record Type

¹ See also XML Direct Mapping.

This figure illustrates a direct EIS mapping between Order class attribute orderedBy and XML record attribute ordered_by within the order element.

EIS Direct Mappings

See Configuring an EIS Direct Mapping for more information.

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 this table.

EIS Composite Direct Collection Mapping by EIS Record Type

¹ See also Composite EIS Mappings.
² See also XML Composite Direct Collection Mapping.

The EIS Composite Direct Collection Mapping figure 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.

EIS Composite Direct Collection Mapping

See Configuring an EIS Composite Direct Collection Mapping for more information.

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 this table.

EIS Composite Object Mapping by EIS Record Type

¹ See also Composite EIS Mappings.
² See also XML Composite Object Mapping.

The EIS Composite Object Mappings figure 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.

EIS Composite Object Mappings

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

See Configuring an EIS Composite Object Mapping for more information.

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 the following table. Composite collection mappings can reference any class that has an EclipseLink descriptor.

EIS Composite Collection Mapping by EIS Record Type

¹ See also Composite EIS Mappings.
² See also XML Composite Collection Mapping.

This figure 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.

EIS Composite Collection Mappings

See Configuring an EIS Composite Collection Mapping for more information.

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)

This table summarizes the behavior of this mapping depending on the EIS record type you are using.

EIS One-to-One Mapping by EIS Record Type

¹ 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 Configuring an EIS One-to-One Mapping for more information.

EIS One-to-One Mappings with Key on Source

This figure 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.

EIS One-to-One Mapping with Key on Source

When a read interaction is executed on the Employee object, EclipseLink puts the target Project object's primary key into the Employee record as a simple value. EclipseLink 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 the XML Schema for EIS One-to-One Mapping with Key on Source example, you can configure an EIS one-to-one mapping with key on source, as the EIS One-to-One Mapping with Key On Source example 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.

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>

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

The EIS One-to-One Mapping with Key on Target figure 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.

EIS One-to-One Mapping with Key on Target

When a read interaction is executed on the Employee object, EclipseLink 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 the XML Schema for EIS One-to-One Mapping with Key on Target example, you can configure an EIS one-to-one mapping with key on target, as the EIS One-to-One Mapping with Key on Target example 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.

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>

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

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).

This table summarizes the behavior of this mapping depending on the EIS record type you are using.

EIS One-to-Many Mapping by EIS Record Type

¹ See 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 Configuring an EIS One-to-Many Mapping for more information.

EIS One-to-Many Mappings with Key on Source

This figure 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.

EIS One-to-Many Mapping with Key on Source

When a read interaction is executed on the Employee object, EclipseLink 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). The EIS One-to-Many Mapping with Key on Source figure shows an Employee record with grouping element Project. EclipseLink 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 Configuring Reference Descriptors).
3. Configure the source and target foreign keys (see Configuring Foreign Key Pairs).
   In this example:
   • Source XML Field: PROJECT
   • 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 XML Schema for EIS One-to-One Mapping with Key on Target, you can configure an EIS one-to-many mapping with key on source, as the EIS One-to-One Mapping with Key on Target example 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.

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>

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

The EIS One-to-Many Mapping with Key on Target figure 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.

EIS One-to-Many Mapping with Key on Target

When a read interaction is executed on the Employee object, EclipseLink 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 Configuring Reference Descriptors).
3. 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:
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 the XML Schema for EIS One-to-Many Mapping with Key on Target example, you can configure an EIS one-to-many mapping with key on target, as the EIS One-to-Many Mapping with Key on Target example 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.

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>

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

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.

This table summarizes the behavior of this mapping depending on the EIS record type you are using.

Transformation Mapping by EIS Record Type

As the EIS Transformation Mappings figure illustrates, you configure the transformation mapping with an org.eclipse.persistence.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.

EIS Transformation Mappings

See Configuring an EIS Transformation Mapping for more information.

Copyright Statement