QuickStart description

This is an alternative to JBossESBLegStarAdapterQuickStartAnt using Eclipse plugins rather than ant scripts.

Using Eclipse plugins, we will walk you through the process of integrating JBoss ESB with a backend IBM CICS system

Once deployed, the generated ESB component will act as an adapter for the sample CICS COBOL program LSFILEAE. ESB clients can then consume the ESB component without any knowledge of the actual legacy backend system:

Installation

Follow instructions in:InstallInstructions.

The installed z/OS CICS modules include the LSFILEAE COBOL sample program that we will be using for this quickstart.

We will be using HTTP connectivity to CICS for this quickstart (Alternatively, you can use Sockets or Websphere MQ).

Start Eclipse and select menu option:

Help-->Software Updates-->Find and Install...

From there check the Search for new features to install option and click next.

Create a New Remote Site named legstar-jbossesb and have the URL point to:

http://www.legsem.com/legstar/jbossesb/eclipse/update

With this new site selected, when you press the finish button, you are presented with all the features you need. Select both LegStar and LegStar for JBoss ESB groups, click next, accept the license terms and then click finish which should end the installation process.

Generate a JBoss ESB service adapter for a mainframe program

Start by creating a new Java project called JbesbLsfileae and select the project.

Map the LSFILEAE Structures to XML Schema

First step is to generate an XML schema from the source of the target COBOL program LSFILEAE.

Select the Structures Mapping plugin:

Then type the name of the target XML Schema, lsfileae.xsd, in the XSD file name field. This should pre-fill the other fields:

Click next and click on the Select Cobol fragments from file system link. This will pop up a standard file selection dialog. Look for your LegStar installation folder. Under the samples/jbossesb/quickstarts/legstar_adapter/cobol sub-folder, you will find the lsfileae sample. When you select that file, the content is displayed for your review:

Although the entire COBOL program is displayed, only the data description will be processed.

Click on the Finish button, this starts the mapping process and the generated XML Schema is opened. You will notice that each COBOL data structure in the LSFILEAE COBOL source has been mapped to an XML Schema type.

Bind the XML Schema to Java annotated classes

Next step turns the XML schema types into Java annotated classes.

From the package explorer view, expand your Java project. The generated lsfileae.xsd file should appear. Select the file, right click to show the context menu and then select LegStar-->Generate Transformers:

Lsfileae.xsd contains 2 complex types: Dfhcommarea and ComPersonal which is a sub-type of Dfhcommarea. Binding a type will automatically bind all sub-types so all we have to do is to select Dfhcommarea and click Finish:

Your package explorer should now display 2 new packages. A library containing the LegStar dependencies should have been added to the project Build path.

If you open Dfhcommarea.java, you will notice that classes exhibit annotations that bind java types both to XML and COBOL:

Generate an ESB service adapter for LSFILEAE

The last step generates the legstar-lsfileae.esb JBoss ESB service.

With your JbesbLsfileae project selected, select the Operations mapping plugin:

Enter name lsfileae.cixs for the operations mapping file.

After you click finish, use the Add... button to create a new operation. Ultimately, this operation will become an action in the ESB pipeline. Type in operation name lsfileae:

An operation maps to a mainframe program in a request/response exchange pattern. What you need to do at this stage is specify the input and output structures. You select these structures from the set that was bound during the previous step. These are displayed when you click on the Add button, successively for Input and for Output:

In our case, we select Dfhcommarea both for Input and for Output, because the LSFILEAE program uses a single structure both for input and output:

After you click on ok, the Generate button is now enabled. If you click on it, you should be able to select the JBoss ESB adapter target:

Clicking on ok again will get you to a multi-tab dialog showing pre-filled generation options:

You have the choice between 2 transports for the adapter sample configurations. With the JBoss Messaging option you can test the adapter using a JMS client and with the HTTP option, you can use an HTTP client.

When you have selected the right option for you, click on Finish which will generate the JBoss ESB adapter:

Under the com.legstar.test.cixs.lsfileae package you will find the generated LsfileaeAction.java source of the actual JBoss ESB action.

Under conf, JBoss ESB configuration samples are generated:

• META-INF/jboss-esb.xml

Is the JBoss ESB service descriptor. This sample service implements a sequence of 2 actions (not counting debug trace actions). The first action performs the actual call to the mainframe program, the second one drops the result into a JMS queue.

• jbm-queue-service.xml and META-INF/deployment.xml

Describe the JMS queues used by the generated ESB service.

Deploy the ESB service adapter for LSFILEAE

The ant folder contains the generated build-esb.xml ant script which bundles the legstar-lsfileae.esb file and the deploy.xml ant script which deploys the generated service to your JBoss ESB installation (Defined by the JBOSS_HOME environment variable).

Go ahead and run deploy.xml from Eclipse.

If JBoss ESB is running, you should get messages like these:

11:39:57,359 INFO  [JBoss4ESBDeployer] create esb service, legstar-lsfileae.esb
11:39:57,406 INFO  [QueueService] Queue[/queue/lsfileae_Request_gw_reply] started, fullSize=200000, pageSize=2000, downCacheSize=2000
11:39:57,421 INFO  [QueueService] Queue[/queue/lsfileae_Request_gw] started, fullSize=200000, pageSize=2000, downCacheSize=2000}}}

Test the ESB service adapter

Once the esb is deployed, any JMS client can use it.

The legstar-jbossesb installation folder samples/jbossesb/quickstarts/legstar_adapter/src contains a SendJMSMessage java program that you can use to invoke the newly deployed service. This program expects a parameter value. Passing a string with a value such as "100" should return the content of the CICS file FILEA for customer 100.

You can use JBoss Messaging as the JMS provider for this test in which case, you will need the following jars on your classpath:

• $JBOSS_HOME/client/jbossall-client.jar
• $JBOSS_HOME/client/jboss-messaging-client.jar
• $JBOSS_HOME/server/default/deploy/jboss-aop-jdk50.deployer/jboss-aop-jdk50.jar