View source for Introduction to EIS Mappings (ELUG)

[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''

----

<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Introduction to EIS Mappings (ELUG)|Related Topics]]</div>
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%20to%20Mappings%20(ELUG)|Introduction to Mappings]].



==EIS Mapping Types==
EclipseLink supports the EIS mappings listed in this table.


<span id="Table 73-1"></span>

{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink Object EIS Mapping Types" summary="This table describes the object EIS mapping types." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
|- align="left" valign="top"
! id="r1c1-t2" align="left" valign="bottom" | '''EIS Mapping Type'''
! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
! id="r1c3-t2" align="left" valign="bottom" | '''EclipseLink Workbench'''
! id="r1c4-t2" align="left" valign="bottom" | '''Java'''
|- align="left" valign="top"
| id="r2c1-t2" headers="r1c1-t2" align="left" |
[[#EIS Direct Mapping|EIS Direct Mapping]]
| headers="r2c1-t2 r1c2-t2" align="left" |
Map a simple object attribute directly to an EIS record.
| headers="r2c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r2c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r3c1-t2" headers="r1c1-t2" align="left" |
[[#EIS Composite Direct Collection Mapping|EIS Composite Direct Collection Mapping]]
| headers="r3c1-t2 r1c2-t2" align="left" |
Map a collection of Java attributes directly to an EIS record.
| headers="r3c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r3c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r4c1-t2" headers="r1c1-t2" align="left" |
[[#EIS Composite Object Mapping|EIS Composite Object Mapping]]
| headers="r4c1-t2 r1c2-t2" align="left" |
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.
| headers="r4c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r4c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r5c1-t2" headers="r1c1-t2" align="left" |
[[#EIS Composite Collection Mapping|EIS Composite Collection Mapping]]
| headers="r5c1-t2 r1c2-t2" align="left" |
Map a <tt>Map</tt> or <tt>Collection</tt> of Java objects to an EIS record in a privately owned one-to-many relationship.
| headers="r5c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r5c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r6c1-t2" headers="r1c1-t2" align="left" |
[[#EIS One-to-One Mapping|EIS One-to-One Mapping]]
| headers="r6c1-t2 r1c2-t2" align="left" |
Define a reference mapping that represents the relationship between a single source object and a single mapped persistent Java object.
| headers="r6c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r6c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r7c1-t2" headers="r1c1-t2" align="left" |
[[#EIS One-to-Many Mapping|EIS One-to-Many Mapping]]
| headers="r7c1-t2 r1c2-t2" align="left" |
Define a reference mapping that represents the relationship between a single source object and a collection of mapped persistent Java objects.
| headers="r7c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r7c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r8c1-t2" headers="r1c1-t2" align="left" |
[[#EIS Transformation Mapping|EIS Transformation Mapping]]
| headers="r8c1-t2 r1c2-t2" align="left" |
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.
| headers="r8c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r8c1-t2 r1c4-t2" align="left" |
[[Image:support.gif|Supported]]<br>
|}



==EIS Mapping Concepts==
This section describes concepts unique to EclipseLink EIS mappings, including the following:
* [[#EIS Record Type|EIS Record Type]]
* [[#XPath Support|XPath Support]]
* [[#xsd:list and xsd:union Support|xsd:list and xsd:union Support]]
* [[#jaxb:class Support|jaxb:class Support]]
* [[#Typesafe Enumeration Support|Typesafe Enumeration Support]]
* [[#Composite and Reference EIS Mappings|Composite and Reference EIS Mappings]]
* [[#EIS Mapping Architecture|EIS Mapping Architecture]]


===EIS Record Type===
EclipseLink supports the following JCA EIS record types:
* [[#Indexed Records|Indexed Records]]
* [[#Mapped Records|Mapped Records]]
* [[#|XML RecordsXML Records]]

You configure the record type at the EIS descriptor level (see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring Record Format|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.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note:''' Not all JCA adapters support all record types. Consult your JCA adapter documentation for details.
|}


====Indexed Records====
The <tt>javax.resource.cci.IndexedRecord</tt> represents an ordered collection of record elements based on the <tt>java.util.List</tt> 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|Composite and Reference EIS Mappings]]).


====Mapped Records====
The <tt>javax.resource.cci.MappedRecord</tt> represents a key-value map-based collection of record elements based on the <tt>java.util.Map</tt> 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|Composite and Reference EIS Mappings]]).


====XML Records====
An XML record represents a <tt>javax.resource.cci.Record</tt> 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%20to%20XML%20Mappings%20(ELUG)|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 [[Introduction%20to%20Mappings%20(ELUG)#Mappings and XPath|Mappings and XPath]].


===xsd:list and xsd:union Support===
When using XML records, you can use EIS direct (see [[#EIS Direct Mapping|EIS Direct Mapping]]) and composite direct collection (see [[#EIS Composite Direct Collection Mapping|EIS Composite Direct Collection Mapping]]) mappings to map to <tt>xsd:list</tt> and <tt>xsd:union</tt> types in an XML record.

For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Mappings and xsd:list and xsd:union Types|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|EIS Composite Object Mapping]]) to accommodate <tt>jaxb:class</tt> customizations with the following XSD structures:
* <tt>all</tt>
* <tt>sequence</tt>
* <tt>choice</tt>
* <tt>group</tt>

For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Mappings and the jaxb:class Customization|Mappings and the jaxb:class Customization]].


===Typesafe Enumeration Support===
You can map a Java attribute to a <tt>typesafe</tt> enumeration using the <tt>JAXBTypesafeEnumConverter</tt> with an <tt>EISDirectMapping</tt> or <tt>EISCompositeDirectCollectionMapping</tt> with XML records.

For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Mappings and JAXB Typesafe Enumerations|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 Direct Collection Mapping]], [[#EIS Composite Object Mapping|EIS Composite Object Mapping]], and [[#EIS Composite Collection Mapping|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%20an%20EIS%20Descriptor%20(ELUG)#Configuring an EIS Descriptor as a Root or Composite Type|Configuring an EIS Descriptor as a Root or Composite Type]]): it needs not have interactions defined for it.

The [[#Figure 73-1|EIS Composite Mappings]] figure illustrates a read interaction on an instance of the <tt>Customer</tt> class using indexed records. For the composite object EIS mapping defined for the <tt>address</tt> attribute, EclipseLink creates an <tt>Address</tt> subrecord in the <tt>Customer</tt> record.

<br>
<span id="Figure 73-1"></span>
''''' EIS Composite Mappings'''''

[[Image:eiscomp.gif|EIS Composite Mappings]]<br><br>


====Reference EIS Mappings====
In a reference EIS mapping ( [[#EIS One-to-One Mapping|EIS One-to-One Mapping]] and [[#EIS One-to-Many Mapping|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%20an%20EIS%20Mapping%20(ELUG)#Configuring Selection Interaction|Configuring Selection Interaction]]). Because both the source and target object use interactions, they must both be of a root object type (see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring an EIS Descriptor as a Root or Composite Type|Configuring an EIS Descriptor as a Root or Composite Type]]).

The [[#Figure 73-2|EIS Reference Mappings]] figure illustrates a read interaction on an instance of the <tt>Order</tt> class using indexed records. For the one-to-one EIS mapping defined for the <tt>customer</tt> attribute, EclipseLink puts the target <tt>Customer</tt> object's foreign key into the <tt>Order</tt> record as a simple value. EclipseLink then uses the selection interaction you configure on the <tt>Order</tt> descriptor to retrieve the appropriate instance of <tt>Customer</tt> and creates a record for it in the <tt>Order</tt> object's transaction.

<br>
<span id="Figure 73-2"></span>
''''' EIS Reference Mappings'''''

[[Image:eisref.gif|EIS Reference Mappings]]<br><br>


===EIS Mapping Architecture===
The [[#Figure 73-3|Possible EIS Mapping Architectures]] figure illustrates the following possible EclipseLink EIS mapping architectures:
* JDBC database gateway (such as Oracle Database 10''g'')
* JDBC adapter
* Proprietary adapter (such as Oracle Interconnect)
* JCA

<br>
<span id="Figure 73-3"></span>
''''' Possible EIS Mapping Architectures'''''

[[Image:eisarch.gif|Possible EIS Mapping Architectures]]<br><br>

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.


<span id="Table 73-2"></span>
''''' EIS Direct Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS Direct Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t4" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t4" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t4" headers="r1c1-t4" align="left" |
Indexed
| headers="r2c1-t4 r1c2-t4" align="left" |
Maps directly to a field in the indexed record.
|- align="left" valign="top"
| id="r3c1-t4" headers="r1c1-t4" align="left" |
Mapped
| headers="r3c1-t4 r1c2-t4" align="left" |
Maps directly to a field in the mapped record.
|- align="left" valign="top"
| id="r4c1-t4" headers="r1c1-t4" align="left" |
XML
| headers="r4c1-t4 r1c2-t4" align="left" |
Maps directly to an attribute or text node in the XML record <sup> 1 </sup>.
|}

<br><sup>1 </sup>See also [[Introduction%20to%20XML%20Mappings%20(ELUG)#XML Direct Mapping|XML Direct Mapping]].<br>

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

<br>
<span id="Figure 73-4"></span>
''''' EIS Direct Mappings'''''

[[Image:onetoone_eis_fig.gif|EIS Direct Mappings]]<br><br>

See [[Configuring%20an%20EIS%20Direct%20Mapping%20(ELUG)#Configuring an EIS Direct Mapping|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.


<span id="Table 73-3"></span>
''''' EIS Composite Direct Collection Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS Composite Direct Collection Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t5" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t5" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t5" headers="r1c1-t5" align="left" |
Indexed
| headers="r2c1-t5 r1c2-t5" align="left" |
Maps directly to a subrecord in the indexed record <sup> 1 </sup>.
|- align="left" valign="top"
| id="r3c1-t5" headers="r1c1-t5" align="left" |
Mapped
| headers="r3c1-t5 r1c2-t5" align="left" |
Maps directly to a subrecord in the mapped record <sup> 1</sup>.
|- align="left" valign="top"
| id="r4c1-t5" headers="r1c1-t5" align="left" |
XML
| headers="r4c1-t5 r1c2-t5" align="left" |
Maps directly to an attribute or text node in the XML record <sup> 2 </sup>.
|}

<br><sup>1 </sup>See also [[#Composite EIS Mappings|Composite EIS Mappings]].<br><sup>2 </sup>See also [[Introduction%20to%20XML%20Mappings%20(ELUG)#XML Composite Direct Collection Mapping|XML Composite Direct Collection Mapping]].<br>

The [[#Figure 73-5|EIS Composite Direct Collection Mapping]] figure illustrates a composite direct collection mapping between <tt>Order</tt> class attribute <tt>items</tt> and an XML record. The <tt>Order</tt> attribute <tt>items</tt> is a collection type (such as <tt>Vector</tt>). It is mapped to an XML record composed of an <tt>order</tt> element that contains a sequence of <tt>item</tt> elements.

<br>
<span id="Figure 73-5"></span>
''''' EIS Composite Direct Collection Mapping'''''

[[Image:eiscdc.gif|EIS Composite Direct Collection Mapping]]<br><br>

See [[Configuring%20an%20EIS%20Composite%20Direct%20Collection%20Mapping%20(ELUG)|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.


<span id="Table 73-4"></span>
''''' EIS Composite Object Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS Composite Object Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t6" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t6" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t6" headers="r1c1-t6" align="left" |
Indexed
| headers="r2c1-t6 r1c2-t6" align="left" |
Maps directly to a subrecord in the indexed record<sup> 1 </sup>.
|- align="left" valign="top"
| id="r3c1-t6" headers="r1c1-t6" align="left" |
Mapped
| headers="r3c1-t6 r1c2-t6" align="left" |
Maps directly to a subrecord in the mapped record <sup> 1</sup>.
|- align="left" valign="top"
| id="r4c1-t6" headers="r1c1-t6" align="left" |
XML
| headers="r4c1-t6 r1c2-t6" align="left" |
Maps directly to an attribute or text node in the XML record<sup> 2 </sup>.
|}

<br><sup>1 </sup>See also [[#Composite EIS Mappings|Composite EIS Mappings]].<br><sup>2 </sup>See also [[Introduction%20to%20XML%20Mappings%20(ELUG)#XML Composite Object Mapping|XML Composite Object Mapping]].<br>

The [[#Figure 73-6|EIS Composite Object Mappings]] figure illustrates a composite object EIS mapping between <tt>Order</tt> class attribute <tt>address</tt> and an XML record. <tt>Order</tt> attribute <tt>address</tt> is mapped to an XML record composed of an <tt>order</tt> element that contains an <tt>address</tt> element.

<br>
<span id="Figure 73-6"></span>
''''' EIS Composite Object Mappings'''''

[[Image:coeisfig.gif|EIS Composite Object Mappings]]<br><br>

You can use an EIS composite object mapping with a change policy (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Change Policy|Configuring Change Policy]].

See [[Configuring%20an%20EIS%20Composite%20Object%20Mapping%20(ELUG)|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.


<span id="Table 73-5"></span>
''''' EIS Composite Collection Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS Composite Collection Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t7" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t7" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t7" headers="r1c1-t7" align="left" |
Indexed
| headers="r2c1-t7 r1c2-t7" align="left" |
Maps directly to a subrecord in the indexed record <sup> 1 </sup>.
|- align="left" valign="top"
| id="r3c1-t7" headers="r1c1-t7" align="left" |
Mapped
| headers="r3c1-t7 r1c2-t7" align="left" |
Maps directly to a subrecord in the mapped record <sup> 1</sup>.
|- align="left" valign="top"
| id="r4c1-t7" headers="r1c1-t7" align="left" |
XML
| headers="r4c1-t7 r1c2-t7" align="left" |
Maps directly to an attribute or text node in the XML record<sup> 2 </sup>.
|}

<br><sup>1 </sup>See also [[#Composite EIS Mappings|Composite EIS Mappings]].<br><sup>2 </sup>See also [[Introduction%20to%20XML%20Mappings%20(ELUG)#XML Composite Collection Mapping|XML Composite Collection Mapping]].<br>

This figure illustrates a composite collection EIS mapping between <tt>Phone</tt> class attribute <tt>phoneNumbers</tt> and an XML record. <tt>Employee</tt> attribute <tt>phoneNumbers</tt> is mapped to an XML record composed of an <tt>EMPLOYEE</tt> element that contains a sequence of <tt>PHONE_NUMBER</tt> elements.

<br>
<span id="Figure 73-7"></span>
''''' EIS Composite Collection Mappings'''''

[[Image:comclfig.gif|EIS Composite Collection Mappings]]<br><br>

See [[Configuring%20an%20EIS%20Composite%20Collection%20Mapping (ELUG)|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%20an%20EIS%20Descriptor%20(ELUG)#Configuring an EIS Descriptor as a Root or Composite Type|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.


<span id="Table 73-6"></span>
''''' EIS One-to-One Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS One-to-One Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t8" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t8" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t8" headers="r1c1-t8" align="left" |
Indexed
| headers="r2c1-t8 r1c2-t8" align="left" |
A new indexed record is created for the target object<sup> 1 </sup><nowiki>:</nowiki>
* 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
|- align="left" valign="top"
| id="r3c1-t8" headers="r1c1-t8" align="left" |
Mapped
| headers="r3c1-t8 r1c2-t8" align="left" |
A new mapped record is created for the target object <sup> 1</sup><nowiki>:</nowiki>
* 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
|- align="left" valign="top"
| id="r4c1-t8" headers="r1c1-t8" align="left" |
XML
| headers="r4c1-t8 r1c2-t8" align="left" |
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
|}

<br><sup>1 </sup>See also [[#Reference EIS Mappings|Reference EIS Mappings]].<br>

This section describes the following:
* [[#EIS One-to-One Mappings with Key on Source|EIS One-to-One Mappings with Key on Source]]
* [[#EIS One-to-One Mappings with Key on Target|EIS One-to-One Mappings with Key on Target]]

See [[Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)|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 <tt>Employee</tt> class attribute <tt>project</tt> and the <tt>Project</tt> class using XML records in a '''key on source''' design.

<br>
<span id="Figure 73-8"></span>
''''' EIS One-to-One Mapping with Key on Source'''''

[[Image:eisoto.gif|EIS One-to-One Mapping with Key on Source]]<br><br>

When a read interaction is executed on the <tt>Employee</tt> object, EclipseLink puts the target <tt>Project</tt> object's primary key into the <tt>Employee</tt> record as a simple value. EclipseLink then uses the selection interaction you configure on the <tt>Employee</tt> descriptor to retrieve the appropriate instance of <tt>Project</tt> and creates a record for it in the <tt>Employee</tt> object's transaction. In this example, you can designate the <tt>Project</tt> 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 <tt>Employee</tt> attribute <tt>project</tt>.
# Configure the reference descriptor as <tt>Project</tt> (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Reference Descriptors|Configuring Reference Descriptors]]).
# Configure the source and target foreign keys (see [[Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)#Configuring Foreign Key Pairs|Configuring Foreign Key Pairs]]).In this example:
#* Source XML Field: <tt>@project-id</tt>
#* Target XML Field: <tt>@id</tt>
# Configure the selection interaction (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Selection Interaction|Configuring Selection Interaction]]).In this example, you can designate the <tt>Project</tt> class's read interaction as the selection interaction.

Given the XSD shown in the [[#Example 73-1|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 [[#Example 73-2|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 <tt>Employee</tt> and the target object is <tt>Project</tt>. Here, the <tt>Employee</tt> object has a <tt>Project</tt> that is referenced using the project's id.


<span id="Example 73-1"></span>
''''' 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>
 


<span id="Example 73-2"></span>
''''' 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 [[#Figure 73-9|EIS One-to-One Mapping with Key on Target]] figure illustrates EIS one-to-one mapping between the <tt>Employee</tt> class attribute <tt>project</tt> and the <tt>Project</tt> class using XML records in a '''key on target''' design. You still configure a one-to-one EIS mapping between <tt>Employee</tt> and <tt>Project</tt>, but in this design, the <tt>Project</tt> attribute <tt>leader</tt> contains the foreign key of the <tt>Employee</tt> object.

<br>
<span id="Figure 73-9"></span>
''''' EIS One-to-One Mapping with Key on Target'''''

[[Image:eisotok.gif|EIS One-to-One Mapping with Key on Target]]<br><br>

When a read interaction is executed on the <tt>Employee</tt> object, EclipseLink uses the selection interaction you configure on the <tt>Employee</tt> descriptor to retrieve the appropriate instance of <tt>Project</tt> and creates a record for it in the <tt>Employee</tt> object's transaction. In this example, the <tt>Project</tt> class's read interaction is unlikely to be sufficient: it is likely implemented to read based on <tt>Project</tt> attribute <tt>Id</tt>, not on <tt>leader</tt>. If this is the case, you must define a separate selection interaction on the <tt>Employee</tt> descriptor that does the following: finds the <tt>Project</tt>, whose <tt>leader</tt> equals X, where X is the value of <tt>Employee</tt> attribute <tt>firstName</tt>.

Note that in this configuration, <tt>Project</tt> attribute <tt>leader</tt> is not persisted. If you want this attribute persisted, you must configure a one-to-one EIS mapping from it to <tt>Employee</tt> attribute <tt>firstName</tt>.

The general procedure for creating and configuring this mapping is as follows:

# Create a one-to-one EIS mapping on <tt>Employee</tt> attribute <tt>project</tt>.
# Configure the reference descriptor as <tt>Project</tt> (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Reference Descriptors|Configuring Reference Descriptors]]).
# Configure the source and target foreign keys (see [[Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)#Configuring Foreign Key Pairs|Configuring Foreign Key Pairs]]).<br>In this example:
#* Source XML Field: <tt>firstName/text()</tt>
#* Target XML Field: <tt>leader/text()</tt>
# Configure the selection interaction (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Selection Interaction|Configuring Selection Interaction]]).<br>In this example, you must define a separate selection interaction on the <tt>Employee</tt> descriptor.

Given the XSD shown in the [[#Example 73-3|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 [[#Example 73-4|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 <tt>Employee</tt>, and the target object is <tt>Project</tt>. Here, a <tt>Project</tt> references its <tt>leader</tt> using the employee's name.


<span id="Example 73-3"></span>
''''' 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>
 


<span id="Example 73-4"></span>
''''' 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%20an%20EIS%20Descriptor%20(ELUG)#Configuring an EIS Descriptor as a Root or Composite Type|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.


<span id="Table 73-7"></span>
''''' EIS One-to-Many Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS One-to-Many Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t9" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t9" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t9" headers="r1c1-t9" align="left" |
Indexed
| headers="r2c1-t9 r1c2-t9" align="left" |
A new indexed record is created for each target object<sup> 1 </sup><nowiki>:</nowiki>
* 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
|- align="left" valign="top"
| id="r3c1-t9" headers="r1c1-t9" align="left" |
Mapped
| headers="r3c1-t9 r1c2-t9" align="left" |
A new mapped record is created for each target object<sup> 1</sup><nowiki>:</nowiki>
* 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
|- align="left" valign="top"
| id="r4c1-t9" headers="r1c1-t9" align="left" |
XML
| headers="r4c1-t9 r1c2-t9" align="left" |
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
|}

<br><sup>1 </sup>See also [[#Reference EIS Mappings|Reference EIS Mappings]].<br>

This section describes the following:
* [[#EIS One-to-Many Mappings with Key on Source|EIS One-to-Many Mappings with Key on Source]]
* [[#EIS One-to-Many Mappings with Key on Target|EIS One-to-Many Mappings with Key on Target]]

See [[Configuring%20an%20EIS%20One-to-Many%20Mapping%20(ELUG)|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 <tt>Employee</tt> class attribute <tt>projects</tt> and multiple <tt>Project</tt> class instances using XML records in a key on source design.

<br>
<span id="'Figure 73-10"></span>
''''' EIS One-to-Many Mapping with Key on Source'''''

[[Image:eisotm.gif|EIS One-to-Many Mapping with Key on Source]]<br><br>

When a read interaction is executed on the <tt>Employee</tt> object, EclipseLink puts each target <tt>Project</tt> object's foreign key into the <tt>Employee</tt> 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 <tt>Employee</tt> record. If you specify more than one pair of source and target XML fields, you must choose a grouping element (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Reference Descriptors|Configuring Reference Descriptors]]). The [[#Figure 73-10|EIS One-to-Many Mapping with Key on Source]] figure shows an <tt>Employee</tt> record with grouping element <tt>Project</tt>. EclipseLink then uses the selection interaction you configure on the <tt>Employee</tt> descriptor to retrieve the appropriate instances of <tt>Project</tt> and creates a record for each in the <tt>Employee</tt> object's transaction. In this example, you can designate the <tt>Project</tt> 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 <tt>Employee</tt> attribute <tt>project</tt>.
# Configure the reference descriptor as <tt>Project</tt> (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Reference Descriptors|Configuring Reference Descriptors]]).
# Configure the source and target foreign keys (see [[Configuring%20an%20EIS%20One-to-Many%20Mapping%20(ELUG)#Configuring Foreign Key Pairs|Configuring Foreign Key Pairs]]).<br>In this example:
#* Source XML Field: <tt>PROJECT</tt>
#* Target XML Field: <tt>@ID</tt>
# Configure the selection interaction (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Selection Interaction|Configuring Selection Interaction]]).<br>In this example, you can designate the <tt>Project</tt> class's read interaction as the selection interaction.

Given the XSD shown in [[#Example 73-3| 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 [[#Example 73-4| 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 <tt>Employee</tt>, and the target object is <tt>Project</tt>. Here, the <tt>Employee</tt> object has one or more <tt>Project</tt> instances that are referenced by <tt>Project</tt> id.


<span id="Example 73-5"></span>
''''' 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>
 


<span id="Example 73-6"></span>
''''' 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 [[#Figure 73-9|EIS One-to-Many Mapping with Key on Target]] figure illustrates an EIS one-to-many mapping between the <tt>Employee</tt> class attribute <tt>projects</tt> and multiple <tt>Project</tt> class instances using XML records in a key on target design. You still configure a one-to-one EIS mapping between <tt>Employee</tt> and <tt>Project</tt> but in this design, the <tt>Project</tt> attribute <tt>leader</tt> contains the foreign key of the <tt>Employee</tt> object.

<br>
<span id="'Figure 73-11"></span>
''''' EIS One-to-Many Mapping with Key on Target'''''

[[Image:eisotmk.gif|EIS One-to-Many Mapping with Key on Target]]<br><br>

When a read interaction is executed on the <tt>Employee</tt> object, EclipseLink uses the selection interaction you configure on the <tt>Employee</tt> descriptor to retrieve the appropriate instances of <tt>Project</tt> and creates a record for each in the <tt>Employee</tt> object's transaction. In this example, the <tt>Project</tt> class's read interaction is unlikely to be sufficient: it is likely implemented to read based on <tt>Project</tt> attribute <tt>Id</tt>, not on <tt>leader</tt>. If this is the case, you must define a separate selection interaction on the <tt>Employee</tt> descriptor that does the following: finds the <tt>Project</tt>, whose <tt>leader</tt> equals X, where X is "Jane".

Note that in this configuration, <tt>Project</tt> attribute <tt>leader</tt> is not persisted. If you want this attribute persisted, you must configure a one-to-one EIS mapping from it to <tt>Employee</tt> attribute <tt>firstName</tt>.

The general procedure for creating and configuring this mapping is as follows:
# Create a one-to-one EIS mapping on <tt>Employee</tt> attribute <tt>project</tt>.
# Configure the reference descriptor as <tt>Project</tt> (see [[Configuring%20an%20EIS%20Mapping%20(ELUG)#Configuring Reference Descriptors|Configuring Reference Descriptors]]).
# Configure the source and target foreign keys (see [[Configuring%20an%20EIS%20One-to-One%20Mapping%20(ELUG)#Configuring Foreign Key Pairs|Configuring Foreign Key Pairs]]).<br>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%20an%20EIS%20Mapping%20(ELUG)#Configuring Selection Interaction|Configuring Selection Interaction]]).<br>In this example, you must define a separate selection interaction on the <tt>Employee</tt> descriptor.

Given the XSD shown in the [[#Example 73-3| 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 [[#Example 73-4|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 <tt>Employee</tt>, and the target object is <tt>Project</tt>. Here, each <tt>Project</tt> references its <tt>leader</tt> using the employee's name.


<span id="Example 73-7"></span><span id="Example 73-3"></span>
''''' 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>
 


<span id="Example 73-8"></span><span id="Example 73-4"></span>
''''' 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.


<span id="Table 73-8 EIS"></span>
''''' Transformation Mapping by EIS Record Type'''''

{| class="HRuleFormal" dir="ltr" title="EIS Transformation Mapping by EIS Record Type" summary="This table lists the mapping behaviour for each EIS record type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t10" align="left" valign="bottom" | '''EIS Record Type'''
! id="r1c2-t10" align="left" valign="bottom" | '''Mapping Behavior'''
|- align="left" valign="top"
| id="r2c1-t10" headers="r1c1-t10" align="left" |
Indexed
| headers="r2c1-t10 r1c2-t10" align="left" |
The field transformer adds data to the indexed record (you have access to the indexed record in the attribute transformer).
|- align="left" valign="top"
| id="r3c1-t10" headers="r1c1-t10" align="left" |
Mapped
| headers="r3c1-t10 r1c2-t10" align="left" |
The field transformer adds data to the mapped record (you have access to the mapped record in the attribute transformer).
|- align="left" valign="top"
| id="r4c1-t10" headers="r1c1-t10" align="left" |
XML
| headers="r4c1-t10 r1c2-t10" align="left" |
The field transformer adds data to the XML record (you have access to the XML record in the attribute transformer).
|}

<br>

As the [[#Figure 73-12|EIS Transformation Mappings]] figure illustrates, you configure the transformation mapping with an <tt>org.eclipse.persistence.mappings.transformers.AttributeTransformer</tt> instance to perform the XML instance-to-Java attribute transformation at unmarshall time. In this example, the <tt>AttributeTransformer</tt> combines two XML text nodes into a single Java object.

<br>
<span id="Figure 73-12"></span>
''''' EIS Transformation Mappings'''''

[[Image:transfig.gif|EIS Transformation Mappings ]]<br><br>

See [[Configuring%20an%20EIS%20Transformation%20Mapping%20(ELUG)|Configuring an EIS Transformation Mapping]] for more information.



----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Concept]]
[[Category: EIS]]