Using JCA with the CICS TG in WebSphere Liberty Profile

The April betas of the WebSphere Liberty Profile provide an optional feature which enables support for the Java Connector Architecture (JCA) part of the Java Enterprise Edition (JEE) specification. As this has been one of the primary methods for connecting to CICS with the CICS TG, it made sense for me to check not only that it works in Liberty, but also how to make use of the CICS TG resource adapters from applications in a remote mode topology.

Getting the beta

Head over to and grab the latest Liberty profile beta of the runtime and extensions jar file, and follow the instructions for installing it. While there, it is worth getting the Eclipse tooling as this will help with developing the application and configuring the Liberty server.

An introduction to developing applications using Eclipse can be found here:

Configure the resource adapter

To configure the resource adapter I grabbed a copy of the cicseci.rar from my CICS TG install (or alternatively you can use the CC03 SupportPac) and stored it in a directory on my local machine. I then added the following section to my server.xml file:

<resourceAdapter autoStart="true" id="eciResourceAdapter" location="/Users/smithson/Documents/cicseci.rar"/>

This makes the resource adapter available to the Liberty profile server and allows us to add the rest of the Liberty profile configuration options. The value of the id property should be set to something meaningful as we'll be using it through the rest of the Liberty configuration.

Create a ConnectionFactory

Now that the resource adapter is available within the Liberty profile server, the next step is to create a ConnectionFactory which is used in our application to connect to the Gateway daemon and invoke the backend CICS programs. The entry in server.xml looks like:

<connectionFactory id="eciTest" jndiName="eis/ECI">
   <properties.eciResourceAdapter connectionUrl="tcp://localhost" portNumber="2006"/>

The properties.eciResourceAdapter element is mandatory and allows for the setting of the custom properties on the ConnectionFactory. In this case I'm connecting to a Gateway daemon running on the same system and listening on port 2006. The properties name, eciResourceAdapter, must match the id set in the resourceAdapter entry. The jndiName property is set to a meaningful value which is used in the application later to reference the ConnectionFactory.

Building the application

I created a servlet application to connect to the CICS TG, call the CICS application and display the results in the browser. The main function requires getting a reference to the ConnectionFactory, requesting a Connection from it and then executing an Interaction against it. Rather than doing a JNDI lookup from an InitialContext to find the ConnectionFactory we must use the new dependency injection framework to have the ConnectionFactory object passed to it. This means in my servlet I create an instance variable with a @Resource annotation.

private ConnectionFactory cf = null;

The value of the lookup parameter needs to exactly match the value of the jndiName parameter in the connectionFactory definition created earlier. The rest of the code then uses the standard JCA API calls:

Connection eciConn = cf.getConnection();
Interaction eciInt = eciConn.createInteraction();
JavaStringRecord jsr = new JavaStringRecord();

// Setup the interactionSpec.
ECIInteractionSpec eSpec = new ECIInteractionSpec();

eciInt.execute(eSpec, jsr, jsr);

Deploying the application

The application is deployed as a standard WAR file but some extra configuration is required in order to avoid NoClassDefFound or ClassNotFound exceptions. This is because the application relies on classes supplied in the resource adapter file, ECIInteractionSpec being the main one. In order for the application to use these classes a classloader definition is added to the webApplication definition in server.xml:

<webApplication id="libertyJCA" location="libertyJCA.war" name="libertyJCA">
   <classloader classProviderRef="eciResourceAdapter" />

The value for classProviderRef matches the id specified for the resourceAdapter and with that we can deploy the application and once it's run the date and time of the CICS server are retrieved and displayed in the browser.


Join The Discussion

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.