Configuring Jakarta EE ECI resource adapter on Liberty

The WebSphere® Liberty Profile provides an optional feature, which enables support for the Java™ Connector Architecture (JCA) part of the Java Enterprise Edition (Java Platform, Enterprise Edition) specification. Because WebSphere Application Server Liberty is one of the primary methods for connecting to CICS® with the CICS Transaction Gateway (CICS TG), it is good to check that it works in Liberty. Also, check how to use the CICS TG resource adapters from applications in a remote mode topology.

Configure the resource adapter

To configure the resource adapter, copy the cicseci.jakarta.rar file from CICS TG installation and store it in a directory on the local machine.

Add the following section to the server.xml file:

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

This section of server.xml makes the resource adapter available to the Liberty profile server and enables the addition of the rest of the Liberty profile configuration options. The value of the id property must be set to something meaningful as it is used 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. The ConnectionFactory is used in the application to connect to the Gateway daemon and start the backend CICS programs. The entry in server.xml looks as follows:

<connectionFactory id="ECI" jndiName="comp/env/ECI">
    <properties.eciResourceAdapter connectionUrl="tcp://eci-server.ibm.com" portNumber="2006" server="serverName" />
</connectionFactory>

Note: serverName - The name of the target CICS server for this connection.

The properties.eciResourceAdapter element is mandatory and enables setting the custom properties on the ConnectionFactory. In this case, it is connected to a Gateway daemon that is 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

Create a servlet application to connect to 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 running an Interaction against it. Rather than doing a JNDI lookup from an InitialContext to find the ConnectionFactory, you must use the new dependency injection framework to pass the ConnectionFactory object to it. This means that in the servlet, you must create an instance variable with an @Resource annotation.

@Resource(name = "ECI", lookup = "comp/env/ECI"
private ConnectionFactory cf = null;

The value of the lookup parameter needs to exactly match with 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();
eSpec.setCommareaLength(20); 
eSpec.setFunctionName("EC01");
eSpec.setInteractionVerb(ECIInteractionSpec.SYNC_SEND_RECEIVE);
eciInt.execute(eSpec, jsr, jsr);

Deploying the application

The application is deployed as a standard WAR file but some extra configuration is needed to avoid NoClassDefFound or ClassNotFound exceptions. It is necessary to avoid these exceptions because the application relies on classes that are supplied in the resource adapter file, ECIInteractionSpec being the main one. 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" />
</webApplication>

The value for classProviderRef matches the ID specified for the resourceAdapter and with that you can deploy the application. After the application runs, the date and time of the CICS server are retrieved and displayed in the browser.

Note: The package for connectors is changed from com.ibm.connector2.cics to com.ibm.jakarta.connector2.cics.

Sample file

The following is a sample of the server.xml file.

<server description="CICS TG server">

    <!-- Enable features -->
    <featureManager>
        <feature>jakartaee-10.0</feature>
    </featureManager>

    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint httpPort="9080" httpsPort="9443" id="defaultHttpEndpoint"/>

    <!-- Automatically expand WAR files and EAR files -->
    <applicationManager autoExpand="true"/>

    <resourceAdapter autoStart="true" id="eciResourceAdapter" location="{installation_dir}/deployable/cicseci.jakarta.rar">
    </resourceAdapter>

      <enterpriseApplication id="ECIIVT" location="{installation_dir}/deployable/ECIIVT.jakarta.ear" name="ECIIVT">
        <classloader classProviderRef="eciResourceAdapter"/>
        </enterpriseApplication>

    <connectionFactory id="ECI" jndiName="comp/env/ECI">
        <properties.eciResourceAdapter ConnectionUrl="tcp://eci-server.ibm.com" TraceLevel="3" portNumber="2000" serverName="IPCINTS" xaSupport="off"/>
    </connectionFactory>
    <!-- Default SSL configuration enables trust for default certificates from the Java runtime --> 
    <ssl id="defaultSSLConfig" trustDefaultCerts="true"/>

    <applicationMonitor updateTrigger="mbean"/>

</server>