EJB Adapter

The Enterprise Java Bean (EJB) adapter consists of the EJB Listener service and the Sterling B2B Integrator Adapter EJB (a J2EE application) that work together to enable you to start a Sterling B2B Integrator business process from a remote J2EE application server.

For this document a remote application server means one that is not associated with Sterling B2B Integrator. The remote application server may reside on the same host as Sterling B2B Integrator or not.

The following table provides an overview of the EJB Adapter Listener service:

Category Description
System name GISEJBAdapter
Graphical Process Modeler (GPM) category This service is not used in business processes.
Description The EJB Adapter, using the EJB Adapter Listener service, defines a port on the Sterling B2B Integrator host and listens for incoming requests from a remote application server. Based on the request, the service can:
  • Initiate (bootstrap) a business process
  • Pass a document and other data from the application server into process data of the initiated business process
  • Return a status about the business process
  • Return the results of the business process
The Sterling B2B Integrator Adapter EJB is deployed on a remote application server and is used to send requests to Sterling B2B Integrator.
Business usage The EJB Adapter enables you to integrate programs on your existing application server with the business process transaction engine provided by Sterling B2B Integrator.
Usage example You create purchase orders on your legacy application server and you want to use Sterling B2B Integrator to route the order for approval, translate the order into EDI, transfer the order to the vendor and update the legacy application with the status of the purchase order throughout that process. Use the Sterling B2B Integrator Adapter EJB to write a client program on your application server that sends the purchase order to Sterling B2B Integrator, initiates a business process and requests status.
Preconfigured? No
Requires third party files? Yes. One of the following J2EE application servers:
  • BEA® WebLogic® 7.0 SP2 & SP3
  • JBoss™ 3.2
  • IBM® WebSphere® 5.0.2
Platform availability All supported Sterling B2B Integrator platforms
Related services None
Application requirements The following statements apply:
  • The Java Archive file GISInvokerEJB_appServProductName.JAR must be installed and configured on a WebLogic, WebSphere, or JBoss application server.

    See Deploying Sterling B2B Integrator Adapter EJB on a WebSphere Application Server, Deploying Sterling B2B Integrator Adapter EJB on a WebLogic Application Server, or Deploying Sterling B2B Integrator Adapter EJB on a JBoss Application Server.

  • You must create the client program on the application server. The client program is responsible for sending the requests to Sterling B2B Integrator.
Initiates business processes? Yes. This service initiates a business process on demand from a remote application server.
Invocation This service is inbound (bootstrapping) only, and will launch a business process on demand (non-polled).
Business process context considerations This service creates an initial business process context (WFC) with the documents and parameters provided by a client program at execution time.
Returned status values If the application server needs to obtain the status or the results of the Sterling B2B Integrator business process, you can use the following two methods in the client program: getStatus() and getResults().
  • Success – The EJB call to Sterling B2B Integrator was successful.
  • Error – The EJB call to Sterling B2B Integrator was not successful.
Restrictions These restrictions apply:
  • The communication from the application server to Sterling B2B Integrator is asynchronous only.
  • The Adapter Listener service cannot be used in a business process. It is only used for initiating a business process.
Persistence level Full Persistence
Testing considerations To test, do the following:Install and configure the EJB Adapter Listener serviceDeploy the Sterling B2B Integrator Adapter EJB in the remote application serverWrite a client program to send requests to Sterling B2B Integrator. See EJB Client Program Example.

How the EJB Adapter Works

The following steps illustrate a synchronous communication between the remote application server and Sterling B2B Integrator:
  1. A legacy system running on a remote J2EE application server has a document that requires processing by Sterling B2B Integrator.
  2. A client program on the remote application server uses the Sterling B2B Integrator Adapter EJB to transfer the document and request that a specific business process be started. The program can also send requests for status, and, when the status indicates complete, a request for the resulting processed document.
  3. The EJB Adapter Listener service receives the request, initiates the requested business process and passes the document into process data.
  4. When the service receives the status request, it passes the business process status back to the remote application server. When the service receives a result request it passes the primary document back to the remote application server.

Implementing Communications with a Remote Application Server

To implement synchronous communication from a remote application server to Sterling B2B Integrator two components must be set up:
  • The EJB Adapter Listener service that defines a port on the Sterling B2B Integrator host.
  • The J2EE application, GISInvokeEJB_appServProductName.jar, that you install on the remote application server.
Complete the following process:
  1. Create an EJB Adapter Listener service configuration.
  2. Configure the EJB Adapter Listener service.
  3. Create and enable a business process that you want to have initiated by the remote application server. For example, create a business process that translates documents from a legacy system on the remote application server.
  4. Deploy the Sterling B2B Integrator Adapter EJB on the remote application server. See one of the following:
    • Deploying Sterling B2B Integrator Adapter EJB on a WebSphere Application Server
    • Deploying Sterling B2B Integrator Adapter EJB on a WebLogic Application Server
    • Deploying Sterling B2B Integrator Adapter EJB on a JBoss Application Server
  5. Test the client program on the remote application server with the business process.

Configuring the EJB Adapter Listener Service

To configure the EJB Adapter Listener service, you must specify field settings in Sterling B2B Integrator. There are no fields that must be defined in the Graphical Process Modeler (GPM).

Sterling B2B Integrator Configuration

The following table describes the fields used to configure the EJB Adapter Listener service in Sterling B2B Integrator:

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 adapter 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 to which the remote application server sends requests. Be certain to select an available port for this parameter. Required.
Listen Hostname(ListenHostname) Name or IP address of the host to which the remote application server sends requests. Optional.
Document Storage Type(docStorageType) Defines how the document will be stored in the system. Required. Valid values are:
  • System Default
  • Database
  • File System
Note: For more information about document storage types, see Managing Services and Adapters.

Deploying Sterling B2B Integrator Adapter EJB on a WebSphere Application Server

If your legacy tools reside in a WebSphere application server, follow these steps to install the J2EE application Sterling B2B Integrator Adapter EJB and deploy it in that server:
  1. Copy the install_directory/client/ejb/GISInvokerEJB.jar file from the Sterling B2B Integrator installation onto the machine that hosts your WebSphere application server.
  2. Start the WebSphere server and go to the Administrative Console page.
  3. Select Install New Application and enter the absolute path of the GISInvokerEJB.jar file.
  4. Complete the installation procedure using the following guidelines:
    • Enter GISAdapterEJB for the Application Name
    • Enter GISAdapterEJB for the JNDI Name.
    • Update the access control list with the proper user information and be certain to disable the parameter Deny All.
  5. Save the successful installation to the Master Configuration.
  6. Navigate to Environment > Naming > Name Space binding and select New.
  7. Configure the WebSphere environment using the following guidelines:
    • Obtain the name of the host that Sterling B2B Integrator is installed on
    • Obtain the listenPort value used in the EJB Adapter Listener service configuration. This is the Listen Port parameter you used when configuring the service.
    • Create a new Name Space binding using the Binding Type String for the Sterling B2B Integrator host and port.

      Enter host for the Name in Name Space and your Sterling B2B Integrator host name for the String Value.

      Enter port for the Name in Name Space and your service configuration listenPort value for the String Value.

  8. Save the environment to the Master Configuration.
  9. You can now create a client program on your Websphere server that can initiate a Sterling B2B Integrator business process.

    See EJB Client Program Example for a sample Context Holder Object and a list of methods you can use in a client program and the properties they correspond to in Sterling B2B Integrator.

Deploying Sterling B2B Integrator Adapter EJB on a WebLogic Application Server

Note: This section is not needed if you chose to integrate with WebLogic during the Sterling B2B Integrator installation process.
If your legacy tools reside in a WebLogic application server, follow these steps to install the J2EE application Sterling B2B Integrator Adapter EJB and deploy it in that server:
  1. Copy the install_directory/client/ejb/GISInvokerEJB.jar file from the Sterling B2B Integrator installation onto the machine that hosts your WebLogic application server.
  2. Start the WebLogic server and go to the Administrative Console page. The console page can be found at http://host:weblogic_port/console.
  3. Select Deployments > EJB under mydomain from the left toolbar menu.
  4. Select the directory into which you want to upload the EJB adapter.
  5. Click upload it through your browser.
  6. Select the absolute path of the GISInvokerEJB.jar file and upload the file. The file GISInvokerEJB.jar should now be listed in the directory list.
  7. Click the Select link for GISInvokerEJB.jar.
  8. Highlight your server and move it from Available Servers to Target Servers.
  9. Select the servers onto which you want to deploy GIS Invoker EJB.
  10. Complete the installation procedure using GISAdapterEJB for the Application Name. There should be a Completed message in the Status column and GISAdapterEJB should appear under EJB in the left toolbar menu.
  11. You can now create a client program on your WebLogic server that can initiate a Sterling B2B Integrator business process.

See EJB Client Program Example for a sample Context Holder Object and a list of methods you can use in a client program and the properties they correspond to in Sterling B2B Integrator.

Note: You can bind the host and port to JNDI in the java program by the following method:
InitialContext env = (InitialContext) ctx.lookup("java:comp/env"); 
ctx.rebind("host","hostname"); 
ctx.rebind("port","listenerPort");

Deploying Sterling B2B Integrator Adapter EJB on a JBoss Application Server

Note: This section is not needed if you chose to integrate with JBoss during the Sterling B2B Integrator installation process.
If your legacy tools reside in a JBoss application server, follow these steps to install the J2EE application Sterling B2B Integrator Adapter EJB and deploy it in that server:
  1. Copy the install_directory/client/ejb/GISInvokerEJB.jar file from the Sterling B2B Integrator installation into the deploy directory on the machine that hosts your JBoss application server.
  2. Start the JBoss server and go to the Administrative Console page. The console page can be found at http://host:jboss_port/web-console.
  3. Select J2EE Domains > Manager > JBoss (http://www.jboss.org/) - 3.2.5 > GISInvokerEJB.jar > GISInvoker from the JBoss Management Console menu. You can see the state of the GISInvoker Bean and confirm that the bean was successfully deployed to the JBoss application server.
  4. You can now create a client program on your JBoss server that can initiate a Sterling B2B Integrator business process.
    Note: You can safely redeploy the application if it is already deployed. To undeploy it, just remove the archive from the deploy directory. You do not need to restart the server in either case.

See EJB Client Program Example for a sample Context Holder Object and a list of methods you can use in a client program and the properties they correspond to in Sterling B2B Integrator.

Note: You can bind the host and port to JNDI in the java program by the following method:
InitialContext env = (InitialContext) ctx.lookup("java:comp/env"); 
ctx.rebind("host","hostname"); 
ctx.rebind("port","listenerPort");

EJB Client Program Example

Before you can create a client program that will initiate a Sterling B2B Integrator business process you must:
  • Configure the EJB Adapter Listener service in Sterling B2B Integrator.
  • Create and check in the business process you want to initiate.
  • Install and configure the Sterling B2B Integrator Adapter EJB on your remote J2EE application server.

The following lists Sterling B2B Integrator-specific methods you can use in the client program:

Purpose Method
//Execute business process
ContextHolder rch = ejb.submitContext(ch,"login","password");
//Obtain business process status
int wf_status = ejb.getState(rch,"admin","password");
//Obtain process data
ContextHolder con = ejb.retrieveContext(rch,"login","password");

The following is an example of a program you could create on your application server that would work with Sterling B2B Integrator.

{\rtf1\ansi\ansicpg1252\deff0\deflang1033{\fonttbl{\f0\fswiss\fcharset0 Arial;}} 
\viewkind4\uc1\pard\f0\fs20\par 
import javax.ejb.*;\par 
import javax.naming.*;\par 
import java.rmi.*;\par 
import java.util.*;\par 
import java.io.*;\par 
\par 
public class TestEJBAdapter \{\par 
\par 
public static void main(String arg[]) \{\par 
\par 
if(arg[0] == null || arg[1] == null || arg[2] ==null || arg[3] == null)\par 
\{\par
       System.out.println("Missing arguemnts : testwl BPName , JNDI , GIS Host , 
       GIS Port");\par
       System.exit(0);\par 
\}\par 
\par 
\par 
try\{\par 
\par 
FileInputStream jndicfg = new FileInputStream(arg[1]);\par 
\par 
Properties p = new Properties();\par 
p.load(jndicfg);\par 
\par 
// Obtain the Initial Context from Application Server\par 
InitialContext ctx = new InitialContext(p);\par 
\par 
// doing lookup for GIS EJB adapter\par 
Object obj = ctx.lookup("com.sterlingcommerce.GISInvoker");\par 
\par 
// Create  EJB home\par 
\par 
GISInvokerHome home = (GISInvokerHome)javax.rmi.PortableRemoteObject.narrow(obj, 
    Class.forName("com.sterlingcommerce.woodstock.services.ejb.client.GISInvokerHome"));\par 
\par 
GISInvoker ejb = home.create();\par 
\par
// Creating Context Holder object to launch Work flow in EJB\par 
\par
         ContextHolder ch = new ContextHolder();\par
         ch.setName(arg[0]);\par
         ch.setMaxBPWaitTime(30000);\par
         ch.setWorkFlowDataOnError(true);\par
         ch.setBody("My body".getBytes("UTF-8"));\par
         ch.setBPName(arg[0]);\par
          System.out.println(ch.toString());\par 
\par 
// Executing Business Process\par
 ContextHolder rch = ejb.submitContext(ch,"admin","password");\par
  System.out.println("Executed BP "+rch);\par 
\par 
// Obtaining the Businss Process status  \par
  \par
  ejb.getState(rch,"admin","password");\par
  \par
 // Obtain the Context \par 
ContextHolder con=  ejb.retrieveContext(rch,"admin","password");\par 
\par 
\}catch(Exception e) \{\par
    e.printStackTrace();\par
  \}\par 
\par 
\}\par 
\par 
\par 
}