Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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 ("Configuring an EIS Descriptor as a Root or Composite Type").

For 2.0 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 "Writing to the ejb-jar.xml File" and "Reading From the ejb-jar.xml File".

Using TopLink Workbench, you can create `XMLInteraction` objects, in which there is a single query per interaction (see "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 "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 "Configuring Selection Interaction").

## Using TopLink Workbench

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

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 J2C 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`).

## Using Java

Using Java, you can create any type of EIS interaction that TopLink supports (see "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 Example 31-2 shows.

Example 31-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);
    }