78 Configuring an EIS Mapping

This chapter describes how to configure an EIS mapping.

This chapter includes the following sections:

Introduction to EIS Mapping Configuration
Configuring Common EIS Mapping Options
Configuring Reference Descriptors
Configuring Selection Interaction

For information on how to configure TopLink mappings options common to two or more mapping types, see Chapter 121, "Configuring a Mapping".

For information on how to create TopLink mappings, see Chapter 120, "Creating a Mapping".

78.1 Introduction to EIS Mapping Configuration

Table 78-1 lists the types of EIS mappings that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.

Table 78-1 Configuring EIS Mappings

If you are creating...	See Also...
EIS direct mapping (see Section 77.3, "EIS Direct Mapping")	Chapter 79, "Configuring an EIS Direct Mapping"
EIS composite direct collection mapping (see Section 77.4, "EIS Composite Direct Collection Mapping")	Chapter 80, "Configuring an EIS Composite Direct Collection Mapping"
EIS composite object mapping (see Section 77.5, "EIS Composite Object Mapping")	Chapter 81, "Configuring an EIS Composite Object Mapping"
EIS composite collection mapping (see Section 77.6, "EIS Composite Collection Mapping")	Chapter 82, "Configuring an EIS Composite Collection Mapping"
EIS one-to-one mapping (see Section 77.7, "EIS One-to-One Mapping")	Chapter 83, "Configuring an EIS One-to-One Mapping"
EIS one-to-many mapping (see Section 77.8, "EIS One-to-Many Mapping")	Chapter 84, "Configuring an EIS One-to-Many Mapping"
EIS transformation mapping (see Section 77.9, "EIS Transformation Mapping")	Chapter 85, "Configuring an EIS Transformation Mapping"

Fore more information, see the following:

78.2 Configuring Common EIS Mapping Options

Table 78-2 lists the configurable options shared by two or more EIS mapping types. In addition to the configurable options described here, you must also configure the options described for the specific EIS mapping types (see Section 77.1, "EIS Mapping Types"), as shown in Table 78-1.

Table 78-2 Common Options for EIS Mapping

Option to Configure	Oracle JDeveloper	TopLink Workbench	Java
Read-only (see Section 121.2, "Configuring Read-Only Mappings")
Indirection (lazy loading) (see Section 121.3, "Configuring Indirection (Lazy Loading)")
XPath (see Section 121.4, "Configuring XPath")
Default null value (see Section 121.5, "Configuring a Default Null Value at the Mapping Level")
Reference descriptors (see Section 78.3, "Configuring Reference Descriptors")
Method or direct field access (see Section 121.6, "Configuring Method or Direct Field Accessing at the Mapping Level")
Private or independent relationships (see Section 121.7, "Configuring Private or Independent Relationships")
Comments (see Section 121.8, "Configuring Mapping Comments")
Serialized object converter (see Section 121.9, "Configuring a Serialized Object Converter")
Type conversion converter (see Section 121.10, "Configuring a Type Conversion Converter")
Object type converter (see Section 121.11, "Configuring an Object Type Converter")
Simple type translator (see Section 121.12, "Configuring a Simple Type Translator")
Container policy (see Section 121.14, "Configuring Container Policy")
Selection interaction (see Section 78.4, "Configuring Selection Interaction")
Use of a single node (see Section 121.19, "Configuring the Use of a Single Node")
JAXB typesafe enumeration converter (see Section 121.13, "Configuring a JAXB Typesafe Enumeration Converter")

78.3 Configuring Reference Descriptors

In EIS mappings that extend oracle.toplink.mappings.ForeignReferenceMapping or oracle.toplink.mappings.AggregateMapping class, attributes reference other TopLink descriptors–not the data source. You can select a descriptor in the current project, or a descriptor from some other project.

Table 78-3 summarizes which EIS mappings support this option.

Table 78-3 Mapping Support for Reference Descriptor

Mapping	How to Use Oracle JDeveloper	How to Configure Reference Descriptors Using TopLink Workbench	How to Use Java
Direct mapping (see Section 77.3, "EIS Direct Mapping")
Composite direct collection mapping (see Section 77.4, "EIS Composite Direct Collection Mapping")
Composite object mapping (see Section 77.5, "EIS Composite Object Mapping")
Composite collection mapping (see Section 77.6, "EIS Composite Collection Mapping")
One-to-one mapping (see Section 77.7, "EIS One-to-One Mapping")
One-to-many mapping (see Section 77.8, "EIS One-to-Many Mapping")
Transformation mapping (see Section 77.9, "EIS Transformation Mapping")

78.3.1 How to Configure Reference Descriptors Using TopLink Workbench

To specify a reference descriptor for an EIS mapping, use this procedure.

Select the mapped attribute in the Navigator. Its properties appear in the Editor.
Click the General tab. The General tab appears.

Figure 78-1 General Tab, Reference Descriptor Field

Description of "Figure 78-1 General Tab, Reference Descriptor Field"

Use the Reference Descriptor field to select the descriptor referenced by this relationship mapping.

Note:

For one-to-one and one-to-many EIS mappings, the reference descriptor must be a root descriptor. See Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type".

You can specify a reference descriptor that is not in the current TopLink Workbench project. For example, to create a mapping to an Employee class that does not exist in the current project, do the following:

Add the Employee class to your current project. See Section 116.2, "Working with Projects".
Create the relationship mapping to the Employee descriptor.
Deactivate the Employee descriptor. See Active and Inactive Descriptors.

When you generate the deployment XML for your project, the mapping to the Employee class will be included, but not the Employee class itself.

78.4 Configuring Selection Interaction

In EIS mappings that extend oracle.toplink.mappings.ForeignReferenceMapping class, TopLink uses a selection interaction to acquire the instance of the target object to which the mapping refers.

By default, TopLink uses the read interaction you define for the mapping's reference descriptor (see Section 78.3, "Configuring Reference Descriptors"). In most cases, this interaction is sufficient. If the reference descriptor's read interaction is not sufficient, you can define a separate interaction.

Table 78-4 summarizes which EIS mappings support this option.

Table 78-4 Mapping Support for Selection Interaction

Mapping	How to Use Oracle JDeveloper	How to Configure Selection Interaction Using TopLink Workbench	How to Use Java
Direct mapping (see Section 77.3, "EIS Direct Mapping")
Composite direct collection mapping (see Section 77.4, "EIS Composite Direct Collection Mapping")
One-to-one mapping (see Section 77.7, "EIS One-to-One Mapping")
One-to-many mapping (see Section 77.8, "EIS One-to-Many Mapping")
Composite object mapping (see Section 77.5, "EIS Composite Object Mapping")
Composite collection mapping (see Section 77.6, "EIS Composite Collection Mapping")
Transformation mapping (see Section 77.9, "EIS Transformation Mapping")

For more information about how TopLink uses the selection criteria, see Section 77.2.6.2, "Reference EIS Mappings".

78.4.1 How to Configure Selection Interaction Using TopLink Workbench

To specify the selection interaction (such as Read Object) for the EIS mapping, use this procedure:

Select the one-to-many EIS mapping in the Navigator. Its properties appear in the Editor.
Click the Selection Interaction tab. The Selection Interaction tab appears.

Figure 78-2 Selection Interaction Tab

Description of "Figure 78-2 Selection Interaction Tab"

Use the following information to enter data in each field on the tab:

Field	Description
Function Name	The name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.
Input Record Name	The name passed to the JCA adapter when creating the input record.
Input Root Element Name	The root element name to use for the input DOM.
Input Arguments	The query argument name to map to the interaction field or XPath nodes in the argument record. For example, if you are using XML records, use this option to map input argument `name` to the XPath `name/first-name`.
Output Arguments	The result record field or XPath nodes to map to the correct nodes in the record used by the descriptor's mappings. For example, if you are using XML records, use this option to map the output `fname` to `name/first-name`. Output arguments are not required if the interaction returns an XML result that matches the descriptor's mappings.
Input Result Path	Use this option if the EIS interaction expects the interaction arguments to be nested in the XML record. For example, specify `arguments`, if the arguments were to be nested under the root element `exec-find-order`, then under an `arguments` element.
Output Result Path	The name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.
Properties	Any properties required by your EIS platform. For example, property name `operation` (from `AQPlatform.QUEUE_OPERATION`) and property value `enqueue` (from `AQPlatform.ENQUEUE`).