Sending data to an ICS-managed EIS

Server Access for J2EE implements support for an application component to send data to an EIS application that InterChange Server manages. The application component prepares an input record and requests execution of a WebSphere Business Integration Collaboration. When a WebSphere Access Resource Adapter receives an input record from the application component, the resource adapter initiates a call-triggered flow by submitting an event to a collaboration. An application component requests this call-triggered flow through the interfaces that the CCI provides to drive an interaction (see Table 10).

Table 10. Server Access for J2EE CCI implementation for executing a collaboration

CCI Interface Description Supported methods
Interaction Allows an application component to request the initiation of a call-triggered flow. The createInteraction() method on a Connection instance returns an Interaction instance. execute(), close(), getConnection()
InteractionSpec , CwInteractionSpec Used to pass interaction-specific properties in the Interaction.execute() method. getFunctionName(), setFunctionName() getInteractionVerb(), setInteractionVerb(), getCollaborationName(), getCollaborationPort(), getCollaborationVerb()

In Table 10, the Supported Methods column lists those interface methods that Server Access for J2EE implements. Interface methods not listed there fall into one of the following categories:

Keep the following points in mind when requesting execution of a collaboration through an Access Resource Adapter:

Initiating a call-triggered flow in the application component involves the following steps:

Identifying the collaboration to execute

The InteractionSpec interface provides interaction-specific properties. The implementation of the InteractionSpec interface that Server Access for J2EE provides is called CwInteractionSpec. The application component defines how it wants to interact with InterChange Server through a CwInteractionSpec instance.

Table 11 shows the standard interaction properties of the InteractionSpec interface. As Table 11 shows, the CwInteractionSpec interface supports two of these standard properties.

Table 11.

CwInteractionSpec standard interaction properties
Standard interaction property Description WebSphere business integration system support
FunctionName The collaboration to send to InterChange Server for execution Server Access for J2EE expects the FunctionName to contain the following collaboration routing information:
  • the name of the collaboration to initiate
  • the port of the collaboration that receives the input record
  • the WebSphere business integration system verb for the collaboration (optional)

The application component can concatenate the name and port information into one delimited string and the resource adapter can parse it.

InteractionVerb An integer that represents the mode of interaction with InterChange Server. The InteractionSpec defines the following constants for these integers:
  • SYNC_SEND
  • SYNC_SEND_RECEIVE
  • SYNC_RECEIVE
Server Access for J2EE supports only the default interaction verb:
  • SYNC_SEND_RECEIVE: The execution of an Interaction instance requests execution of the collaboration and receives a response synchronously. Use of this verb indicates that the resource adapter both sends and receives data in a single, blocking call.

Because SYNC_SEND_RECEIVE is the default interaction verb, you do not need to explicitly set InteractionVerb to work with Server Access for J2EE. If you set the interaction verb to anything other than this default, the setInteractionVerb() method throws the exception PropertyVetoException.

ExecutionTimeout The number of milliseconds an Interaction instance waits for the EIS to execute the specified function Server Access for J2EE does not support this standard property.

Note:
Because InteractionSpec is implemented as a Java Bean, the CwInteractionSpec interface supports get and set methods to access the interaction properties (see Table 10).

The first step in requesting a call-triggered flow is to identify the collaboration that needs to execute. To identify the collaboration, specify the collaboration name, port, and verb in the CwInteractionSpec instance. Use the following syntax to set the FunctionName standard property to include the name and port of the collaboration, as well as the verb:

CollaborationName:Port:CollaborationVerb



As the syntax above indicates, a colon (:) separates each of these pieces of information.

Note:
The collaboration and port that you specify must be configured for call-triggered flow. In particular, the port must be bound as an external port. For more information on how to configure a collaboration for a call-triggered flow, see the Access Development Guide.

You can set the FunctionName standard property in either of the following ways:

Important:
To reference the CwInteractionSpec class within an application component, you must ensure that the InterChange Server specs.jar file gets loaded. This jar file contains the CwInteractionSpec class, which the application component needs to explicitly create instances of to pass parameters to an Access Resource Adapter. Some possible ways to provide the application component with access to the specs.jar file are: adding the specs.jar file to the application component's J2EE Enterprise Archive (EAR) file, or specifying this jar file in the CLASSPATH of your application server.

Creating the serialized input record

The application component stores the data to send to an EIS in an input record. The WebSphere Access Resource Adapter converts this input record into a business object, which is the triggering event for the collaboration. The Server Access for J2EE's implementation of the MappedRecord interface, CwMappedRecord, holds this serialized input record, which the application component then passes to the Interaction.execute() method.

Note:
The Server Access for J2EE's implementation of the Interaction interface accepts only CwMappedRecord instances for the execute() method. However, a CwMappedRecord instance can contain CwIndexedRecord instances and other CwMappedRecord instances.

If the verb for the collaboration is not specified in the InteractionSpec instance, the resource adapter extracts the verb from the top-level CwMappedRecord that is passed into the execute() method.

For more information on CwMappedRecord and CwIndexedRecord and how to create them, see "Using records".

Invoking the execute() method

The CCI method that actually sends the request to initiate the call-triggered flow is Interaction.execute(). The implementation of execute() that Server Access for J2EE provides takes the following steps:

  1. Convert the input record to a business object.
  2. Initiate a call-triggered flow by sending the triggering event to the specified collaboration.

To call the execute() method, the application component must take the following steps:

  1. Generate an Interaction instance with the Connection.createInteraction() method.
  2. Invoke the execute() method on the Interaction instance to initiate the call-triggered flow by requesting execution of a collaboration.

    Server Access for J2EE supports the following two forms of the Interaction.execute() method:

The following pseudo-code shows how an application component can request information about an employee named "Stan Smith":

// Obtain the input record (a CwMappedRecord instance) and populate it
inputRecord =
  connFactory.getRecordFactory().createMappedRecord("Employee");
inputRecord.put("FirstName", "Stan");
inputRecord.put("LastName", "Smith");
 
// Set the interaction-specific properties in the CwInteractionSpec
iSpec = new CwInteractionSpec("myCollab:fromObject:Retrieve");
 
// Generate the Interaction instance and then execute it
myInteraction = myConnection.createInteraction();
outputRecord = myInteraction.execute(iSpec, inputRecord);
 
// Obtain the data from the output record
employeeId = outputRecord.get("EmployeeId");
 
// Close the interaction
myInteraction.close();

Closing the interaction

When the application component is finished using an Interaction instance, it should explicitly close it. A call to the close() method releases all resources that the WebSphere Access Resource Adapter has maintained for the Interaction. The close of an Interaction instance does not close the associated connection handle. It is recommended that you close Interaction instances explicitly to free any held resources.

Copyright IBM Corp. 1997, 2004