76 Configuring an EIS Descriptor

This chapter describes the various components that you must configure in order to use an EIS descriptor.

This chapter includes the following sections:

For information on how to configure descriptor options common to two or more descriptor types, see Chapter 119, "Configuring a Descriptor".

Table 76-1 lists the default configurable options for an EIS descriptor.

76.1 Introduction to EIS Descriptor Configuration

Table 76-1 lists the default configurable options for an EIS descriptor.

Table 76-1 Configurable Options for EIS Descriptor

Option to Configure Oracle JDeveloper
TopLink Workbench Java

XML schema namespace (see Section 5.6.5, "How to Configure XML Schema Namespace")

Supported Supported Supported

XML schema reference (see Section 5.6.4, "How to Configure an XML Schema Reference")

Supported Supported Supported

Shema context (see Section 76.2, "Configuring Schema Context for an EIS Descriptor")

Supported Supported Supported

Default root element (see Section 76.3, "Configuring Default Root Element")

Supported Supported

Unsupported.

Primary keys (see Section 119.2, "Configuring Primary Keys")Foot 1 

Supported Supported Supported

Read-only (see Section 119.3, "Configuring Read-Only Descriptors")Footref 1

Supported Supported Supported

Unit of work conforming (see Section 119.4, "Configuring Unit of Work Conforming at the Descriptor Level")Footref 1

Supported Supported Supported

Alias (see Section 119.5, "Configuring Descriptor Alias")

Supported Supported Unsupported.

Comments (see Section 119.6, "Configuring Descriptor Comments")

Supported Supported Unsupported.

Record format (see Section 76.4, "Configuring Record Format")

Unsupported.

Unsupported.

Supported

Creating classes (see Section 5.7.1, "How to Create Classes")

Supported Supported Unsupported.

Named queries (see Section 119.7, "Configuring Named Queries at the Descriptor Level")Footref 1

Supported.

Supported.

Supported.

Custom EIS interactions for basic persistence operations (see Section 76.5, "Configuring Custom EIS Interactions for Basic Persistence Operations")Footref 1

Unsupported.

Supported.

Supported.

Cache refreshing (see Section 119.9, "Configuring Cache Refreshing")Footref 1

Supported Supported Supported

Cache type and size (see Section 119.12, "Configuring Cache Type and Size at the Descriptor Level")Footref 1

Supported Supported Supported

Cache isolation (see Section 119.13, "Configuring Cache Isolation at the Descriptor Level")

Supported

Supported.

Supported.

Cache coordination change propagation (see Section 119.15, "Configuring Cache Coordination Change Propagation at the Descriptor Level")

Supported

Supported.

Supported.

Cache expiration (see Section 119.16, "Configuring Cache Expiration at the Descriptor Level")

Supported

Supported.

Supported.

Cache existence checking (see Section 119.17, "Configuring Cache Existence Checking at the Descriptor Level")

Supported

Supported.

Supported.

EJB information (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information")

Supported Supported Supported

EIS descriptor as a root or composite type (see Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type")

Unsupported.

Supported

Supported

Inheritance for a child class descriptor (see Section 119.20, "Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor")

Supported.

Supported.

Supported.

Inheritance for a parent class descriptor (see Section 119.21, "Configuring Inheritance for a Parent (Root) Descriptor"

Supported.

Supported Supported

Inherited attribute mapping in a subclass (see Section 119.23, "Configuring Inherited Attribute Mapping in a Subclass")

Supported.

Supported.

Supported.

Domain object method as an event handler (see Section 119.24, "Configuring a Domain Object Method as an Event Handler")

Supported.

Supported.

Supported.

Descriptor event listener as an event handler (see Section 119.25, "Configuring a Descriptor Event Listener as an Event Handler")

Unsupported. Unsupported.

Supported.

Locking policy (see Section 119.26, "Configuring Locking Policy"Footref 1)

Supported.

Supported Supported

Returning policy (see Section 119.27, "Configuring Returning Policy")

Supported.

Supported Supported

Instantiation policy (see Section 119.28, "Configuring Instantiation Policy")

Supported.

Supported Supported

Copy policy (see Section 119.29, "Configuring Copy Policy")

Supported.

Supported Supported

Change policy (see Section 119.30, "Configuring Change Policy")

Unsupported.

Unsupported.

Supported.

Wrapper policy (see Section 119.32, "Configuring Wrapper Policy")

Unsupported.

Unsupported. Supported

Amendment methods (see Section 119.35, "Configuring Amendment Methods")

Supported Supported Supported

Mapping (see Section 121, "Configuring a Mapping")

Supported Supported Supported

Footnote 1 EIS root descriptors only (see Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type").

For more information, see Chapter 74, "Introduction to EIS Descriptors".

76.2 Configuring Schema Context for an EIS Descriptor

TopLink Workbench uses the schema context to associate the class that the EIS descriptor describes with a simple or complex type in one of the schemas associated with the EIS project (see Section 5.6.4, "How to Configure an XML Schema Reference"). This allows TopLink Workbench to display the appropriate attributes available for mapping in that context.

You must configure the schema context for an EIS root descriptor (see Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type") only if you are using TopLink Workbench or Oracle JDeveloper TopLink Editor.

76.2.1 How to Configure Schema Context for an EIS Descriptor Using TopLink Workbench

To associate an EIS descriptor with a simple or complex type in this project's schema, use this procedure:

  1. Select an EIS descriptor in the Navigator. Its properties appear in the Editor.

  2. Click the Descriptor Info tab. The Descriptor Info tab appears.

    Figure 76-1 Descriptor Info Tab, Schema Context Option

    Description of Figure 76-1 follows
    Description of "Figure 76-1 Descriptor Info Tab, Schema Context Option"

Click Browse to select the schema element to associate with this descriptor. For more information, see Section 76.2.1.1, "Choosing a Schema Context".

76.2.1.1 Choosing a Schema Context

Use the Choose Schema Context dialog box to select a specific schema element (such as when mapping an element).

Figure 76-2 Choose Schema Context Dialog Box

Description of Figure 76-2 follows
Description of "Figure 76-2 Choose Schema Context Dialog Box"

Select the schema element and click OK.

76.2.2 How to Configure Schema Context for an EIS Descriptor Using Java

For an EIS descriptor, the TopLink runtime does not need the schema context: the runtime can determine the schema context based on the mappings you configure on the descriptor. No further configuration is required.

76.3 Configuring Default Root Element

You must configure the default root element for an EIS root descriptor (see Section 75.2.1.1, "EIS Root Descriptors") so that the TopLink runtime knows the data source data type associated with the class the descriptor describes. Descriptors used only in composite relationship mappings do not require a default root element.

Note:

Although you select an element from your project's schema to configure this attribute, you are choosing the element's simple or complex type.

For more information, see Section 16.2.12, "Default Root Element".

76.3.1 How to Configure Default Root Element Using TopLink Workbench

When you create an EIS project using TopLink Workbench, you must use XML records. Consequently, you must configure a default root element so that TopLink Workbench knows what element to start with when persisting an instance of the class that the EIS descriptor describes.

To specify a schema element as the default root element for the descriptor, use this procedure:

  1. Select a descriptor in the Navigator. Its properties appear in the Editor.

  2. Click the Descriptor Info tab. The Descriptor Info tab appears.

    Figure 76-3 Descriptor Info Tab, Default Root Element Option

    Description of Figure 76-3 follows
    Description of "Figure 76-3 Descriptor Info Tab, Default Root Element Option"

Use the Default Root Element option to select the root element for this descriptor.

Click Browse to select the schema element to identify as the root element. See Section 76.3.1.1, "Choosing a Root Element" for more information.

76.3.1.1 Choosing a Root Element

Use the Choose Root Element dialog box to select a specific root element.

Figure 76-4 Choose Root Element Dialog Box

Description of Figure 76-4 follows
Description of "Figure 76-4 Choose Root Element Dialog Box"

Select the root element and click OK.

76.3.2 How to Configure Default Root Element Using Java

When you create an EIS project using Java code, use the EISDescriptor method setDataTypeName to specify the XML schema complex type name (if you are using XML records) or the JCA record name (if you are using indexed or mapped records) corresponding to the class that the EIS descriptor describes. For more information, see Oracle Fusion Middleware Java API Reference for Oracle TopLink.

76.4 Configuring Record Format

The EIS descriptor record format determines the EIS record type to which the descriptor's EIS mappings map.

When you create an EIS project using TopLink Workbench, TopLink configures all EIS descriptors with a record format of XML.

When you create an EIS project in Java, you can configure the EIS descriptor record type to any of the supported types, as Table 76-2 shows.

Table 76-2 EIS Record Formats

EISDescriptor Method EIS Record Type

useMappedRecordFormat

All EIS mappings owned by this descriptor map to EIS mapped records.

useIndexedRecordFormat

All EIS mappings owned by this descriptor map to EIS indexed records.

useXMLRecordFormat

All EIS mappings owned by this descriptor map to EIS XML records.

If you use the XML record format, you must specify one or more XML schemas in your EIS project (see Section 5.6.3, "How to Import an XML Schema"). The TopLink runtime performs XML data conversion based on one or more XML schemas. In an EIS XML project, TopLink Workbench does not directly reference schemas in the deployment XML, but instead

exports mappings configured with respect to the schemas you specify.

For information on TopLink support for XML namespaces, see Section 15.2.7, "XML Namespaces".


For more information, see Section 77.2.1, "EIS Record Type".

76.4.1 How to Configure Record Format Using Java

To configure the EIS record format for an EIS descriptor, use one of the EISDescriptor methods listed in Table 76-2, as shown in Example 76-1.

Example 76-1 Configuring EISDescriptor Record Format

EISDescriptor descriptor = new EISDescriptor();
descriptor.useIndexedRecordFormat();

76.5 Configuring Custom EIS Interactions for Basic Persistence Operations

You can use TopLink to define an interaction for each basic persistence operation (insert, update, delete, read object, read all, or does exist) so that when you query and modify your EIS-mapped objects, the TopLink runtime will use the appropriate EIS interaction instead of the default EIS interaction.

You can configure custom EIS interactions for basic persistence operations only for EIS descriptors designated as root descriptors (Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type").

For CMP projects, the ejb-jar.xml file stores query lists. You can define the queries in the file and then read them into TopLink Workbench, or define them on the Queries tab and write them to the file. For more information, see Section 19.7.1, "How to Write to the ejb-jar.xml File Using TopLink Workbench" and Section 19.7.2, "How to Read from the ejb-jar.xml File Using TopLink Workbench".

Using TopLink Workbench, you can create XMLInteraction objects, in which there is a single query per interaction (see Section 76.5.1, "How to Configure Custom EIS Interactions for Basic Persistence Operations Using TopLink Workbench").

Using Java, you can create any EISInteraction type. For some EIS projects, it is common for multiple interactions to be used in a single query. For example, one interaction–to enqueue a request, and another–to dequeue the response. Because TopLink Workbench does not support setting multiple interactions on a single query, you must use an amendment method to create and configure the interaction in Java (see Section 76.5.2, "How to Configure Custom EIS Interactions for Basic Persistence Operations Using Java").

Note:

In a one-to-one or one-to-many EIS mapping, you must also specify a selection interaction that TopLink uses to acquire target objects. You can use either the target object's read interaction (the default) or specify a separate selection interaction, if necessary. For more information, see Section 78.4, "Configuring Selection Interaction").

76.5.1 How to Configure Custom EIS Interactions for Basic Persistence Operations Using TopLink Workbench

To configure custom EIS interactions for basic persistence operations, use the following procedure:

  1. In the Navigator, select an EIS root descriptor in a EIS project.

  2. Click the Queries tab in the Editor. The Queries tab appears.

  3. Click the Custom Calls tab. The Custom Calls tab appears.

    Figure 76-5 Queries, Custom Calls Tab for EIS Calls

    Description of Figure 76-5 follows
    Description of "Figure 76-5 Queries, Custom Calls Tab for EIS Calls"

Click the appropriate interaction type from the list (Insert, Update, Delete, Read Object, Read All, or Does Exist) and use the following table to enter data in each field

Field Description
Interaction Type Using TopLink Workbench, you can only use XML Interactions. You cannot change this field.
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 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 Use this option if the EIS interaction result record contains the XML data that maps to the objects in a nested structure.

For example, specify order, if the results were return under a root element results, then under an order element.

Properties Any properties required by your EIS platform. For example, property name operation (from AQPlatform.QUEUE_OPERATION) and property value enqueue (from AQPlatform.ENQUEUE).

76.5.2 How to Configure Custom EIS Interactions for Basic Persistence Operations Using Java

Using Java, you can create any type of EIS interaction that TopLink supports (see Section 109.8, "Using EIS Interactions").

For some EIS projects, it is common for multiple interactions to be used in a single query: for example, one interaction to enqueue a request and another to dequeue the response. Because TopLink Workbench does not support setting multiple interactions on a single query, you must use an amendment method to create and configure the interaction in Java, as Example 76-2 shows.

Example 76-2 Creating an XML Interaction for an AQ Platform

public static void addXMLInteractions(ClassDescriptor descriptor) {
    // find order interaction
    XMLInteraction request = new XMLInteraction();
    request.setProperty(AQPlatform.QUEUE_OPERATION, AQPlatform.ENQUEUE);
    request.setProperty(AQPlatform.QUEUE, "ORDER_INBOUND_QUEUE");
    request.setProperty(AQPlatform.SCHEMA, "AQUSER");
    request.setInputRootElementName("READ_ORDER");
    request.addArgument("@id");
 
    XMLInteraction response = new XMLInteraction();
    response.setProperty(AQPlatform.QUEUE_OPERATION, AQPlatform.DEQUEUE);
    response.setProperty(AQPlatform.QUEUE, "ORDER_OUTBOUND_QUEUE");
    response.setProperty(AQPlatform.SCHEMA, "AQUSER");
 
    ReadObjectQuery query = new ReadObjectQuery();
    query.addCall(request);
    query.addCall(response);
    descriptor.getQueryManager().setReadObjectQuery(query);
 
    // place order interaction
    XMLInteraction insert = new XMLInteraction();
    insert.setProperty(AQPlatform.QUEUE_OPERATION, AQPlatform.ENQUEUE);
    insert.setProperty(AQPlatform.QUEUE, "ORDER_INBOUND_QUEUE");
    insert.setProperty(AQPlatform.SCHEMA, "AQUSER");
    insert.setInputRootElementName("INSERT_ORDER");
                
    descriptor.getQueryManager().setInsertCall(insert);
}

76.6 Configuring an EIS Descriptor as a Root or Composite Type

You can designate an EIS descriptor as root (see Section 75.2.1.1, "EIS Root Descriptors") or composite (see Section 75.2.1.2, "EIS Composite Descriptors").

When you designate an EIS descriptor as a root, you tell the TopLink runtime that the EIS descriptor's reference class is a parent classš–no other class will reference it by way of a composite object mapping or composite collection mapping. Using an EIS root descriptor, you can configure all supported mappings and you can configure the descriptor with EIS interactions (see Section 109.8, "Using EIS Interactions"). However, if you configure the EIS root descriptor with a composite object mapping or composite collection mapping, the reference descriptor you define must be an EIS composite descriptor; it cannot be another EIS root descriptor.

When you designate an EIS descriptor as a composite (the default), you tell the TopLink runtime that the EIS descriptor's reference class may be referenced by a composite object or composite collection mapping (see Chapter 81, "Configuring an EIS Composite Object Mapping" and Chapter 82, "Configuring an EIS Composite Collection Mapping"). Using an EIS composite descriptor, you can configure all supported mappings, but you cannot configure it with EIS interactions.

You can configure inheritance for a descriptor designated as a composite (see Section 119.20, "Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor"), however, in this case, all the descriptors in the inheritance tree must be aggregates. Aggregate and class descriptors cannot exist in the same inheritance tree. For more information, see Section 16.3.4, "Aggregate and Composite Descriptors and Inheritance".

If you configure a descriptor as a composite using TopLink Workbench, you cannot configure the descriptor with EJB information (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information").

For more information, see the following:

76.6.1 How to Configure an EIS Descriptor as a Root or Composite Type Using TopLink Workbench

To configure an EIS descriptor as a root or composite EIS descriptor, use this procedure:

  1. In the Navigator, select an EIS composite descriptor.

  2. Click the Root or Composite descriptor button on the mapping toolbar.

    You can also select the descriptor and choose Selected > Descriptor Type > Root or Composite from the menu or by right-clicking on the descriptor in the Navigator and selecting Descriptor Type > Root or Composite from the context menu.

76.6.2 How to Configure an EIS Descriptor as a Root or Composite Type Using Java

To configure an EIS descriptor as root or composite using Java, create a descriptor amendment method (see Section 119.35, "Configuring Amendment Methods") and use the following EISDescriptor methods:

  • To designate an EIS descriptor as a root descriptor, use EISDescriptor method descriptorIsNormal.

  • To designate an EIS descriptor as a composite (nonroot) descriptor, use EISDescriptor method descriptorIsAggregate.