Sending data to an ICS-managed EIS

WebSphere InterChange Server Access for EJB provides support for a client component to send data to an ICS-managed EIS application through either the executeCollaborationExtended() or executeCollaborationExtendedWithLocale() method. The client component prepares input data, which represents the triggering event of the collaboration. It then requests execution of the collaboration with either the executeCollaborationExtended() or executeCollaborationExtendedWithLocale() method of the enterprise bean's remote (EJBObject) interface. When a WebSphere Access EJB executes the method, it uses calls to the WebSphere InterChange Server Access Interface to communicate with InterChange Server (see Business method of the session bean). Therefore, the method initiates a call-triggered flow when it submits the triggering event to a collaboration.

The syntax of the executeCollaborationExtended() method in the remote interface is as follows:

public String executeCollaborationExtended(
       String ICSName,
       String collabName,
       String portName,
       String serializedData,
       String mimeType,
       String verb)
    throws CollaborationExecutionException, RemoteException;

The syntax of the executeCollaborationExtendedWithLocale() method in the remote interface is as follows:

public String executeCollaborationExtended(
       String ICSName,
       String collabName,
       String portName,
       String serializedData,
       String mimeType,
       String verb       String locale)
   throws CollaborationExecutionException, RemoteException;

Note:
These method signatures match the implementation of the corresponding methods in the Server Access for EJB's implementation of the SessionBean interface.

Table 11 provides a summary of the parameters in the executeCollaborationExtended() and executeCollaborationExtendedWithLocale() methods.

Table 11. Parameters of the remote interface methods

Parameter name Description For more information
ICSName
Name of the ICS instance that contains the collaboration "Connecting to the ICS instance"
collabName
Name of the collaboration to execute "Executing the collaboration"
portName
Name of the collaboration port that receives the serializedData data "Executing the collaboration"
serializedData
Input data, which is interpreted as the triggering event of the collaboration
"Converting the serialized input data"
mimeType
MIME type of the serializedData data
"Converting the serialized input data"
verb
WebSphere business integration system verb to send with the triggering event
"Executing the collaboration"
locale
The client locale with which to execute the collaboration. Processing locale-dependent data

Keep the following points in mind when requesting execution of a collaboration through a WebSphere Access EJB:

Execution of the executeCollaborationExtended() method involves the following steps:

Connecting to the ICS instance

The first step in initiating a call-triggered flow is to obtain a connection with an instance of InterChange Server. To identify the ICS instance that the WebSphere Access EJB is to use, the executeCollaborationExtended() method specifies the ICS name as its first argument. This ICS instance contains the collaboration that the client component needs to execute. This name must correspond to one of the ICS definitions in the Server Access for EJB environment, which is established when the WebSphere Access EJB was deployed. The deployment descriptor provides the valid ICS definitions. For more information, see Setting environment entries.

The following call to executeCollaborationExtended() establishes a connection to an ICS instance named dexter:

returnedData = cwObject.executeCollaboration("dexter", ....);

The deployment descriptor in Table 9 shows the ICS definition for an ICS instance named dexter.

Note:
A WebSphere Access EJB establishes connection pools that last for the lifetime of the application server. Therefore, the executeCollaborationExtended( ) method does not necessarily establish a new connection each time it executes. If a collaboration pool contains a connection to the requested ICS instance, executeCollaborationExtended( ) obtains this connection. For more information, see "Closing the connection".

Executing the collaboration

The second step in initiating a call-triggered flow is to execute the collaboration. To identify the collaboration to execute, use the executeCollaborationExtended() method. Its arguments provide the Access EJB with information it needs to identify the collaboration to execution. Several of this method's arguments specify the actual collaboration name and port, as follows:

Note:
The collaboration and port that you specify must be configured for a 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.

Once a connection to an ICS instance has been obtained, the executeCollaborationExtended() or executeCollaborationExtendedWithLocale() method initiates execution of the specified collaboration.

Consider the call to the executeCollaborationExtended() method in Figure 13. This call provides information about which collaboration to execute in its second, third, and last arguments (in bold). The call performs the following tasks:

Figure 13. A sample call to executeCollaborationExtended()

returnedData = cwObject.executeCollaborationExtended(
   "dexter", 
   "Customer",
   "NewCust",
   inputData,
   "text/xml"
   "Create");

Converting the serialized input data

The third step in initiating a call-triggered flow is to send serialized data to represent the triggering event for the collaboration. To identify the serialized data, the executeCollaborationExtended() method provides the serialized data and information on the format of this data as arguments, as follows:

As part of the call-triggered flow, InterChange Server converts the serialized input data into a WebSphere business integration system business object, which is the actual triggering event for the collaboration. To perform this data conversion, ICS uses a data handler, which converts between a business object and a particular serialized format (such as XML, name-value pairs, or EDI). Server Access within ICS uses the MIME type to determine which data handler to use. To obtain the triggering event, the data handler converts the serialized input data, which is in the format specified by its associated MIME type, into a business object.

Note:
For more information on MIME types and their role in the selection of a data handler, see the Data Handler Guide.

In the call to the executeCollaborationExtended() method in Figure 13, the fourth and fifth arguments provide the input data and its MIME type. These arguments provide the information that ICS needs to perform the following tasks:

Once the collaboration receives its triggering event, it begins execution.

Receiving the output data

The purpose of a client component requesting execution of a collaboration is to obtain information from an ICS-managed EIS. Execution of the collaboration results in the collaboration returning a business object, which contains data from an ICS-managed EIS. As the final step, InterChange Server converts this business object into serialized output data. To perform this data conversion, ICS uses the same data handler that it used to convert the serialized input data into the triggering event. It selects this data handler based on the MIME type that the executeCollaborationExtended() method provides as its fifth argument. This data handler converts the returned collaboration business object into the serialized output data, in the format specified by this MIME type.

The client component receives the output data as the return value of the executeCollaborationExtended() method. This return value is a serialized String value, in the same format as the serialized input data that the client component passed in to executeCollaborationExtended(). In the call to the executeCollaborationExtended() method in Figure 13, the client component receives its serialized output data in the returnedData variable. This variable contains the requested EIS information in XML format.

If any errors occur during collaboration execution, the WebSphere Access EJB sends them to the client component as appropriate. The types of errors that the session bean might encounter include:

For more information, see "Exceptions".

Closing the connection

A WebSphere Access EJB is responsible for managing the opening and closing of ICS connections. As a performance enhancement, the session bean does not automatically close an ICS connection when the collaboration completes. Instead, it keeps a pool of connections, one for each ICS instance defined in the session bean's environment. These ICS instances are listed in the ICServers environment entry of the bean's deployment descriptor. The Access EJB closes a connection only if a communications error occurs; otherwise, these connections are valid for the lifetime of the application server.

Copyright IBM Corp. 1997, 2004