QuickStart ESB adapter for a CICS program using Eclipse plugins.

QuickStart description

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

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

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

If you would rather use WebSphere MQ instead of HTTP as the wire protocol to reach the mainframe then the Mule configuration will be:

Installation

Follow instructions in:InstallationInstructions.

If you installed the z/OS CICS modules, then the target LSFILEAE COBOL program is ready. Otherwise, the source is in the samples/mule/quickstarts/legstar_adapter/cobol sub-folder and you need to upload, compile and install it in CICS.

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-mule and have the URL point to: http://dist.muleforge.org/legstar-transport//eclipse/update

With this new site selected, when you press the finish button, you are presented with all the plugins you need. Select the entire LegStar group, click next, accept the license terms and then click finish which should end the installation process.

Generate a Mule component adapter for a mainframe program

Start by creating a new Java project called MuleLsfileae 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/mule/quickstarts/legstar_adapter/cobol sub-folder, you will find the lsfileae.cbl 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 Binding classes:

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 Mule service adapter for LSFILEAE

The last step generates the lsfileaeBridgeUMO Mule component.

With your MuleLsfileae 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 a UMO 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 Mule adapter target:

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

You can select between HTTP or WebSphere MQ connectivity to the mainframe:

Once you have made your choice, click on Finish which will generate the Mule adapter:

Under src/com/legstar/test/cixs/mule/lsfileae you will find the generated transformer classes that turn java value objects or XML to mainframe byte arrays. These transformers can be used in any Mule configuration and are independant from the transport chosen.

Under conf, Mule configuration samples are generated:

mule-adapter-config-lsfileae-http-java-legstar.xml

Is the Mule configuration file. Notice that generated transformers are referenced. Access to mainframe uses the transport that you have chosen previously. The client is expected to send serialized java objects over an inbound TCP connection.

mule-adapter-config-lsfileae-http-xml-legstar.xml

Is an alternative where clients can send XML over TCP instead of serialized java objects.

The ant folder contains the build.xml generated ant script which bundles the mule-legstar-lsfileae.jar file and deploys the generated component to your Mule installation (Defined by the MULE_HOME environment variable).

Testing the Mule service adapter

The installation src/org/mule/transport/legstar/test/lsfileae folder contains the LsfileaeClientTest junit class that you can use to invoke the newly deployed component.

Alternatively, the src/org/mule/transport/legstar/test/lsfileae folder also contains LsfileaeHttpTest junit class that uses the Mule junit framework and will start a Mule instance as part of the test itself. You don't need to actually deploy the generated artifacts in order to run this test but you have to include the Mule libraries in your project classpath.

LsfileaeHttpXmlTest is an alternative to LsfileaeHttpTest where the client sends XML rather than serialized Java objects.