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;
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:
Server Access for EJB does not provide the ability to manipulate individual attributes of a business object or to create a specific business object. Actual manipulation and creation of a business object is delegated to InterChange Server.
If ICS unexpectedly terminates during execution of the call-triggered flow, the client component is not notified of the failure through an exception. However, the enterprise bean is informed whether the request was processed before the termination. To recover:
For more information on call-triggered flows, see the Access Development Guide.
Execution of the executeCollaborationExtended() method involves the following steps:
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.
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:
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");
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:
Pass this input data as a Java String.
The MIME type specifies the format of the serialized data. You can specify only MIME types that are supported by the ICS instance you request.
The MIME type specifies the format of the serialized data. You can specify only MIME types that are supported by the ICS instance you request.
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.
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.
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".
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.