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