Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
TopLink enterprise information system (EIS) mappings provide support for accessing legacy data sources and enterprise applications through J2EE Connector architecture (J2C) adapter. TopLink EIS mappings use the J2C 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 describes the following:
TopLink supports the EIS mappings listed in Table 53-1.
Table 53-1 TopLink Object EIS Mapping Types
Mapping Type | Description | Type | TopLink Workbench | Java |
---|---|---|---|---|
|
Map a simple object attribute directly to an EIS record. |
Basic |
||
"EIS Composite Direct Collection Mapping" |
Map a collection of Java attributes directly to an EIS record. |
Basic |
||
"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. |
Advanced |
||
"EIS Composite Collection Mapping" |
Map a |
Advanced |
||
|
Define a reference mapping that represents the relationship between a single source object and a single mapped persistent Java object. |
Basic |
||
|
Define a reference mapping that represents the relationship between a single source object and a collection of mapped persistent Java objects. |
Basic |
||
|
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. |
Advanced |
This section describes concepts unique to TopLink EIS mappings, including the following:
TopLink supports the following J2C EIS record types:
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. |
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").
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").
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".
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".
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".
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".
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".
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.
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 53-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.
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 53-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 53-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 53-3 Possible EIS Mapping Architectures
The best solution may vary, depending on your specific EIS and infrastructure.
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 53-2.
Table 53-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 "XML Direct Mapping".
Figure 53-4 illustrates a direct EIS mapping between Order
class attribute orderedBy
and XML record attribute ordered_by
within the order
element.
See Chapter 55, "Configuring an EIS Direct Mapping" for more information.
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 53-3.
Table 53-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 "Composite EIS Mappings".
Footnote 2 See also "XML Composite Direct Collection Mapping".
Figure 53-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 53-5 EIS Composite Direct Collection Mapping
See Chapter 56, "Configuring an EIS Composite Direct Collection Mapping" for more information.
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 53-4.
Table 53-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 "Composite EIS Mappings".
Footnote 2 See also "XML Composite Object Mapping".
Figure 53-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 53-6 EIS Composite Object Mappings
You can use an EIS composite object mapping with a change policy (see "Configuring Change Policy".
See Chapter 57, "Configuring an EIS Composite Object Mapping" for more information.
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 53-5. Composite collection mappings can reference any class that has a TopLink descriptor.
Table 53-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 "Composite EIS Mappings".
Footnote 2 See also "XML Composite Collection Mapping".
Figure 53-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 53-7 EIS Composite Collection Mappings
See Chapter 58, "Configuring an EIS Composite Collection Mapping" for more information.
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 53-6 summarizes the behavior of this mapping depending on the EIS record type you are using.
Table 53-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 :
|
Mapped |
A new mapped record is created for the target objectFootref 1:
|
XML |
.A new XML record is created for the target object:
|
Footnote 1 See also "Reference EIS Mappings".
This section describes the following:
See Chapter 59, "Configuring an EIS One-to-One Mapping" for more information.
Figure 53-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 53-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 53-1, you can configure an EIS one-to-one mapping with key on source, as Example 53-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 53-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 53-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()");
Figure 53-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 53-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 53-3, you can configure an EIS one-to-one mapping with key on target, as Example 53-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 53-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 53-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()");
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").
Table 53-7 summarizes the behavior of this mapping depending on the EIS record type you are using.
Table 53-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 :
|
Mapped |
A new mapped record is created for each target objectFootref 1:
|
XML |
.A new XML record is created for each target object:
|
Footnote 1 See also "Reference EIS Mappings".
This section describes the following:
See Chapter 60, "Configuring an EIS One-to-Many Mapping" for more information.
Figure 53-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 53-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 "Configuring Reference Descriptors"). Figure 53-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:
Create a one-to-many 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
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 53-3, you can configure an EIS one-to-many mapping with key on source, as Example 53-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 53-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 53-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()");
Figure 53-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 53-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:
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, you select Foreign Keys Located On Source and specify one pair of source and target XML fields:
Source XML Field:
Target XML Field:
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 53-3, you can configure an EIS one-to-many mapping with key on target as Example 53-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 53-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 53-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()");
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 53-8 summarizes the behavior of this mapping depending on the EIS record type you are using.
Table 53-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 53-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.
See Chapter 61, "Configuring an EIS Transformation Mapping" for more information.