JCA Listener Service and Sterling B2B Integration Resource Adapter

The JCA Listener service and Sterling B2B Integration Resource adapter works together to integrate Sterling B2B Integration with your legacy systems.

The following table provides an overview of the JCA Listener service:

System name SI_JCA_ADAPTER
Graphical Process Modeler (GPM) category None
Description Listens for incoming requests from Java Connector Architecture™ (JCA) requests. Runs business processes and returns resultant documents. A JCA Resource adapter (for Sterling B2B Integration, called the Sterling B2B Integration Resource adapter) is a standard mechanism in J2EE™ for supplying connectivity to remote enterprise integration systems from an application server. The JCA Listener service receives information from the Sterling B2B Integration Resource adapter and starts a business process.
Business usage The Sterling B2B Integration Resource adapter is deployed in two parts: one in a remote application server, the other in Sterling B2B Integration. This enables you to use an Enterprise Java Bean (EJB) that you write to start Sterling B2B Integration business processes directly from your application server. You can also pass documents to Sterling B2B Integration for processing and retrieve documents from Sterling B2B Integration. This enables you to integrate Sterling B2B Integration into your existing systems.
Usage example A legacy system running on an application server (for example, JBoss™ or WebLogic®) contains data such as a purchase order or bill of materials. The legacy system can run a business process in Sterling B2B Integration and pass documents into Sterling B2B Integration for processing. The legacy system can also retrieve the results of the processing from Sterling B2B Integration.
Preconfigured? No
Requires third-party files? Application server must have j2ee.jar (v1.3.1) in its classpath.
Platform availability All supported Sterling B2B Integration platforms
Related services The JCA Listener service is designed to work with the Sterling B2B Integration Resource adapter for Sterling B2B Integration, which is deployed in an application server.
Application requirements The Resource adapter (v 1.0) for Sterling B2B Integration must be deployed in an application server before using the JCA Listener service.
Initiates business processes? This adapter starts business processes requested through the JCA Listener service on the remote application server. You integrate the remote application with an EJB written to access Sterling B2B Integration through the JCA Listener service.
Invocation Does not run by a business process.
Business process context considerations Any text nodes placed under the message_to_child node at the top of ProcessData will be returned to the calling EJB.
Returned status values If this adapter starts from a business process, it will return an error. The completed business process returns the process ID to the Listener, which then allows for using the PID to query for the status, and to retrieve process data or documents.
Restrictions There may be multiple configurations of this adapter, but each must listen on a unique port.

Requirements

To use the Sterling B2B Integration Resource adapter, you should have knowledge of:
  • JCA specification
  • Enterprise Java Beans
  • XML concepts
  • How process data and documents are handled in Sterling B2B Integration
For the Sterling B2B Integration Resource adapter to work correctly, verify that:
  • You have deployed the Sterling B2B Integration Resource adapter in an external application server.
  • You have installed and configured the JCA Listener service in Sterling B2B Integration.
  • The files j2ee.jar (version 1.3.1 or higher) is in the application server classpath.

How the Sterling B2B Integration Resource Adapter Works

The Sterling B2B Integration Resource adapter is deployed in a remote application server. This enables you to use a custom-written Enterprise Java Bean (EJB) to run a business process inside Sterling B2B Integration. You can also pass documents to Sterling B2B Integration for processing and retrieve documents from Sterling B2B Integration. This enables you to integrate Sterling B2B Integration into your existing systems.

The Sterling B2B Integration Resource adapter and the JCA Listener service can be configured to run in synchronous or asynchronous mode.

The following steps summarize how the Sterling B2B Integration Resource adapter and the JCA Listener service work in synchronous mode. In this mode, you can run a predefined Sterling B2B Integration business process and receive the resulting document when the business process completes.
  1. A legacy system running on an external application server has a document that requires processing by Sterling B2B Integration.
  2. The legacy system uses an EJB you write to specify the Sterling B2B Integration business process to run and to pass the document to the Sterling B2B Integration Resource adapter.
  3. The Sterling B2B Integration Resource adapter transfers the document and the name of the business process to run to the JCA Listener service running in Sterling B2B Integration.
  4. The JCA Listener service starts the specified business process and passes it the input document.
  5. When the business process is completed, the resultant document is returned to the Sterling B2B Integration Resource adapter and back to the EJB.

Using the asynchronous mode of communication, you can run a predefined Sterling B2B Integration business process without waiting for the business process to complete. In this case, you can go back at some later time to retrieve resulting documents and status.

Note: The JCA Listener service cannot run as part of a business process.

The following figure shows how the Sterling B2B Integration Resource adapter, running on an external application server, interacts with the JCA Listener service running on Sterling B2B Integration.

Limitations to Full JCA Specification Support

The Sterling B2B Integration Resource adapter does not support the following portions of the JCA specification:
  • Non-managed two-tier application scenarios, that is, applications that are not managed by an application server
  • Transactions
  • Connection pooling, in the traditional sense, as the adapter does not persist any live connections

Sample Business Scenario

This section describes a sample business scenario involving the JCA adapter.

You have a legacy billing system, and need to pass invoices to Sterling B2B Integration for processing, then receive back the results of that process.
  1. Write the necessary business process in Sterling B2B Integration.
  2. Configure the Sterling B2B Integration Resource adapter to work with your legacy billing system server.
  3. Write an EJB that passes the file from the legacy billing system to the Sterling B2B Integration Resource adapter, and specifies the business process to run in Sterling B2B Integration.
  4. Identify a free port on the server for the JCA Listener service to listen on.
  5. Create a JCA Listener service configuration. For information, see Managing Services and Adapters.
  6. Configure the JCA Listener service. For information, see Configuring the JCA Listener Service.
  7. Enable the JCA Listener service and Sterling B2B Integration Resource adapter.
  8. When your billing system produces a file to be sent to Sterling B2B Integration, the EJB picks up the file from the legacy system and passes it and the business process name to the Sterling B2B Integration Resource adapter.
  9. The Sterling B2B Integration Resource adapter passes the file and business process name to the JCA Listener service.
  10. The business process starts, runs successfully, and puts the results in the business process context.
  11. The response is passed back from the JCA Listener service to the Sterling B2B Integration Resource adapter, then to the legacy system.

Implementing the Sterling B2B Integration Resource Adapter

To implement the Sterling B2B Integration Resource adapter, complete the following tasks:
  1. Deploy the Sterling B2B Integration Resource adapter on your application server.
  2. Configure the Sterling B2B Integration Resource adapter using your application server administrator console or by editing the application server deployment descriptors.
  3. Make classpath changes to support compiling external J2EE components.
  4. Create a JCA Listener service configuration. For information, see Managing Services and Adapters.
  5. Configure the JCA Listener service. For information, see Configuring the JCA Listener Service.

    You can configure multiple instances of this adapter, each one on a unique port.

  6. Use the JCA Listener service in a business process.

Installed Location

The resource adapter (RAR) file containing the resource adapter implementation and the deployment descriptors is available under the client/jca subdirectory. The RAR files for deploying in JBoss and in WebLogic application servers are under the JBoss and WebLogic subdirectories, respectively.

JBoss Deployment

To deploy the Sterling B2B Integration Resource adapter on a JBoss application server, copy the following files to the application server deployment directory:
  • sijca-service.xml – JBoss deployment descriptor for the resource adapter.
  • sijca_<version>_jboss.rar – Contains the resource adapter implementation classes and the standard deployment descriptor, ra.xml.

The Resource adapter can then be accessed through the JBoss JMX console.

WebLogic Deployment

To deploy the Sterling B2B Integration Resource adapter in a WebLogic application server, the resource adapter (RAR file) must be packaged in an Enterprise Archive (EAR) file along with the J2EE component that will access it. It must be deployed as an EAR application to establish that the CCI classes are loaded and accessible to the J2EE component.

The sijca_<version>_wl.rar contains:
  • ra.xml – The standard deployment descriptor for the Resource adapter
  • weblogic-ra.xml – The WebLogic deployment descriptor for the Resource adapter
  • Resource adapter implementation classes

Alternatively, si_jca_<version>_client.jar can be added to the WebLogic system classpath. In that case, deployment of new versions of the resource adapter will require an application server restart. To leverage the hot-deploy capability of the WebLogic server, it is recommended that the Resource adapter be deployed as part of an EAR application.

The Resource adapter can be accessed and configured through the WebLogic server administrator console.

Configuration

Before you can use the Sterling B2B Integration Resource adapter, you must configure the following parameters:
  • HostName – The host machine where the targeted Sterling B2B Integration instance is running
  • PortNumber – The port number where the JCA Listener service configuration is running

These parameters can be configured through the application server administrator consoles, or by editing the Resource adapter deployment descriptors (sijca-service.xml for JBoss, and weblogic-ra.xml for WebLogic).

The user name and password for authenticating the user must be provided through the ConnectionSpec when starting getConnection() on the ConnectionFactory.

Classpath Changes

To compile the external J2EE components that will access the Sterling B2B Integration Resource adapter, si_jca_<version>_client.jar (under client/jca) has to be added to the classpath. The javadoc for these CCI (Common Client Interface) classes is available under the client/jca/javadoc subdirectory.

Configuring the JCA Listener Service

To configure the JCA Listener service, you must specify settings for the following fields in Sterling B2B Integration:

Note: The field names in parentheses represent the corresponding field names in the GPM. This information is provided for your reference.
Field Description
Name Unique and meaningful name for the service configuration. Required.
Description Meaningful description for the service configuration, for reference purposes. Required.
Select a Group Select one of the options:
  • None – You do not want to include this configuration in a group at this time.
  • Create New Group – You can enter a name for a new group in this field, which will then be created along with this configuration.
  • Select Group – If you have already created one or more groups for this service type, they are displayed in the list. Select a group from the list.
Note: For more information about groups, see Managing Services and Adapters.
Listen Port(listenPort) Port number that this instance of the adapter will listen on. This port must be a free port. Numeric. Valid values are 1025 - 65535. Required.

Functions Supported for Sterling B2B Integration

The Sterling B2B Integration Resource adapter enables you to use Sterling B2B Integration functionality, such as:
  • Running a business process with or without an input document, and with or without input process data

    To run a business process in Sterling B2B Integration:

  1. Set the operationName in the SIInteractionSpec to InvokeBusinessProcess.
  2. To specify synchronous or asynchronous invocation, set the operationMode in the InteractionSpec as follows:

    To run the business process synchronously, set the operationMode to InteractionSpec.SYNC_SEND_RECEIVE

    To run the business process asynchronously, set the operationMode to InteractionSpec.SYNC_SEND

  • Retrieving documents and output process data from completed business processes

    Any process data parameters that are included inside a message_to_child xml tag in process data of the business process that is running are returned as output process data. In the following example, param1 and param2 are returned as output process data, but not param3.

    <process_data> 
<message_to_child>
<param1>ValueOfParam1</param1>
<param2>ValueOfParam2</param2>
</message_to_child>
…
<param3>ValueOfParam3</param3>
…
</process_data>

    To retrieve a document and/or output process data from a completed business process, set the operationName to GetBusinessProcessContext; operationMode is disregarded for this operation.

  • Retrieving the state of a business process.

    To retrieve the state of a business process, set the operationName to GetBusinessProcessState; operationMode is disregarded for this operation.

Code Example

A sample EJB illustrating the use of the Sterling B2B Integration Resource adapter is available under the samples/jca directory.
  1. Look up the Resource Adapter Connection Factory:
    InitialContext iniCtx = new InitialContext();         
/*
/ For JBoss Object ref = iniCtx.lookup("java:/SI");
*/
          // For WebLogic Object ref = iniCtx.lookup("eis/SI");
System.out.println("Found ConnectionFactory - " +      
     ref.getClass().getName());
cf = (SIConnectionFactory) ref;
System.out.println("Found ConnectionFactory");
  2. Make a connection. At this point, the Sterling B2B Integration Resource adapter connects to the JCA Listener service on Sterling B2B Integration, authenticates the user, and disconnects. The user name and password come from the Sterling B2B Integration Accounts area:
    SIConnectionSpec info = new SIConnectionSpec("admin","password");
Connection conn = cf.getConnection(info);
        System.out.println("Created Connection #1");
Interaction interaction = conn.createInteraction();
  3. Create an InteractionSpec defining the operation to be run and the mode of operation.
    InteractionSpec interSpec = new SIInteractionSpec(
                  SIInteractionSpec.OP_INVOKE_BP,
                InteractionSpec.SYNC_SEND_RECEIVE);
  4. Create a MappedRecord and set the required input data.
    
MappedRecord inRec = new SIMappedRecord();
          inRec.setRecordName("InputRecord");
inRec.setRecordShortDescription("Input record");
  5. Set the following for passing an input document:
    
inRec.put(SIMappedRecordKeys.DOC_NAME, "DocName");
inRec.put(SIMappedRecordKeys.DOC_SUBJECT, "DocSubject");
inRec.put(SIMappedRecordKeys.DOC_TYPE, "text");
inRec.put(SIMappedRecordKeys.DOC_SUBTYPE, "plain");
          inRec.put(SIMappedRecordKeys.DOC_ENCODING, "UTF-8");
          String docBody = new
String("This is the body of the test document");
inRec.put(SIMappedRecordKeys.DOC_BODY, docBody.getBytes());
  6. Pass any input process data as follows:
    Hashtable
processData = new Hashtable();
processData.put("processData1", "process data value 1");
        processData.put("processData2", "process data value 2");
inRec.put(SIMappedRecordKeys.PROCESS_DATA, processData);
  7. Set the name of the business process to run.
    inRec.put(SIMappedRecordKeys.INVOKE_BP_NAME, "BoomerangJCA");
  8. Execute the operation.
    MappedRecord outRec = (MappedRecord)interaction.execute(interSpec,inRec);

  9. Retrieve the output process data. Only parameters that are inside a message_to_child node in process data will be returned.
    
Hashtable pd = (Hashtable) outRec.get(SIMappedRecordKeys.PROCESS_DATA);
Enumeration pdKeys = pd.keys(); 
        while (pdKeys.hasMoreElements()) {
System.out.println("Process Data key = " + pdKeys.nextElement());
};
  10. Release the connection.
    interaction.close();
conn.close();