EIS Mapping Concepts

This section describes concepts unique to TopLink 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

TopLink supports the following J2C EIS record types:

• Indexed Records

• Mapped Records

• XML 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.

Note: Not all J2C adapters support all record types. Consult your J2C adapter documentation for details.

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 "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 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 "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 J2C 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 "Understanding XML Mappings".

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 "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

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.

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.

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

Figure 56-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 56-1 EIS Composite Mappings

Description of "Figure 56-1 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).

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

Figure 56-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 56-2 EIS Reference Mappings

Description of "Figure 56-2 EIS Reference Mappings"

EIS Mapping Architecture

Figure 56-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)

• J2C

Figure 56-3 Possible EIS Mapping Architectures

Description of "Figure 56-3 Possible EIS Mapping Architectures"

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