Java development using JCICSX

The JCICSX API classes allow you to access CICS® services through a Java™ API. They support a subset of CICS functionality, can be run remotely, and are easier to mock and stub than the Java classes of JCICS. The JCICSX API classes can be used together with the JCICS API, but only the commands using JCICSX can benefit from these enhanced features.

Table of contents
Why use JCICSX? Restrictions of JCICSX Security model of JCICSX Configuring the environment for JCICSX JCICSX use cases and samples Best practices Troubleshooting Appendix 1. JCICSX API classes Appendix 2. Mapping between JCICSX and EXEC CICS commands

Why use JCICSX?

The JCICSX API classes extend parts of the JCICS API with the capability of remote development and mocking. They have the following benefits:

The classes allow easy mocking and stubbing. The JCICSX API classes make it easier to apply inversion of control and inject test doubles, so that you can mock the JCICSX method calls on your workstation during unit testing, using frameworks such as Mockito, EasyMock, and PowerMock.
The classes can be run remotely in development environments. You can link to programs or pass data through channels and containers in a remote CICS region by executing CICS Java applications on your local workstation, without having to repeatedly deploy the applications to CICS. In addition, no modification is required to the application code regardless of whether it runs in CICS or on your local workstation.
The syntax is simplified and natural for Java developers who are more familiar with more recent Java constructors.
You can leverage capabilities of modern Java IDEs, such as content assist, debugging, smart navigation, and hot-swapping. This is achieved through the support of mocking and remote development in a local IDE, including IntelliJ and Eclipse.
Code written using the JCICSX API classes can execute without change, both in remote development mode and when deployed to run in CICS.
It's compatible with the JCICS API. JCICSX API classes can be used alongside the JCICS API in the same program, but only pure JCICSX programs can benefit from the enhanced features such as remote development. For example, if you mix JCICS and JCICSX in the same program, you won't be able to run it remotely in your development environment.

Restrictions of JCICSX

The JCICSX API classes support only a subset of CICS functionality that addresses some of the most common scenarios for using Java in CICS, focused on linking to CICS programs using channels and containers. For more information, see Appendixes. If you need to use functions beyond that scope, consider using the JCICS API.

Client-side tooling is available initially to enable Liberty users to use JCICSX to access CICS from a servlet.

JCICSX API classes will not work correctly within worker threads that are dispatched as part of an asynchronous servlet.

Security model of JCICSX

For remote development, JCICSX requires a Liberty JVM server to be set up in CICS to receive the remote JCICSX requests. The JCICSX client-side tooling creates a new CICS Task with a call to the server. Subsequent JCICSX requests from that client will run under the same task, and must be issued by the same user. This is transparent when using the client-side tooling. The Liberty JVM server can be configured to use authentication and authorization for JCICSX calls, and the communication between the client and the remote server can be configured to use SSL. For more information, see Configuring security for remote JCICSX API development and Configuring SSL (TLS) for remote JCICSX API development.

In other cases, for example when the applications are deployed to run in CICS, JCICSX adopts an identical security model to that of JCICS.

Configuring the environment for JCICSX

Configure your environment for JCICSX as follows:

If you want to use JCICSX for remote development, extra configuration is needed to set up supporting infrastructure in CICS and on your local workstation. Note that the supporting infrastructure in CICS is required only in development regions. The JCICSX API is available in all CICS JVM servers by default.
Mandatory: Set up your compilation environment by importing the JCICSX dependency.

Required for remote development System programmers must configure a Liberty JVM server in CICS TS with the JCICSX server feature (cicsts:jcicsxServer-1.0) enabled

Note that JCICSX supports remote development for Liberty servlets.

Set up a Liberty JVM server in a development CICS region that the application will remotely execute against. You are advised to set up a JVM server solely for the purpose of remote development so that the remoting JVM server and the actual application JVM servers can have different configuration. Otherwise, the configuration might conflict. For more information, see Set up a Liberty JVM server.
Add the cicsts:jcicsxServer-1.0 Liberty feature to the Liberty JVM server's server.xml file:
```
<featureManager>
    <feature>cicsts:jcicsxServer-1.0</feature>
</featureManager>
```
Let the developer know the hostname and httpEndpoint port of this Liberty JVM server.
If needed, configure security for the remoting Liberty JVM server. See Configuring security for remote JCICSX API development.

Required for remote development Developers configure the local development environment to run Java code locally and to make remote calls for JCICSX

If you do not have a Liberty runtime on your local workstation, install one, for example, WebSphere Liberty Web Profile. It must be at Liberty 19.0.0.3 or later. For more information, see WebSphere Liberty for developers.
Install the jcicsxClient-1.0 Liberty feature into the general Liberty runtime on your local workstation. On a command line, navigate to the bin directory of your local Liberty server, and enter the following installUtility command:
```
installUtility install jcicsxClient-1.0 jsonp-1.0
```
Create a local Liberty JVM server that uses the Liberty runtime on your workstation to run the Java code.
Enable the jcicsxClient-1.0 feature in your local Liberty server by adding this to your server.xml:
```
<featureManager>
    <feature>usr:jcicsxClient-1.0</feature>
</featureManager>
```
Configure the server.xml file in your local Liberty server with the hostname and port of the remote Liberty JVM server that your system programmer created, which contains the cicsts:jcicsxServer-1.0 feature:
```
<usr_jcicsxClient serverUri="http://hostname:port"/>
```
If the remote Liberty JVM server is configured to use authentication, you can encrypt the user password by using the securityUtility command provided in the bin directory of the local Liberty server. So your snippet might look like this:
```
<usr_jcicsxClient serverUri="http://hostname:port">
    <basicAuthentication user="myUser" password="{aes}ADwac72WXpSCr2YDUv3hHgjfOa0moXZDj626MmM4DbtT"/>
</usr_jcicsxClient>
```
If the remote Liberty JVM server uses SSL connection for data encryption, your local Liberty server needs to trust the certificate of the remote server. See instructions for application developers in Configuring SSL (TLS) for remote JCICSX API development.

Required Developers resolve the JCICSX dependency

The JCICSX API classes are available in CICS TS alongside the JCICS API in CICS TS 5.6 or later. You can import JCICSX API classes from any of the following places:

The build path library supplied with the IBM® CICS SDK for Java in IBM CICS Explorer® for Aqua 3.2¹ (Fix Pack 5.5.0.9) or later.
When using CICS Explorer to add a library to your project, JCICSX will automatically be available as an API in your client. See Step 1 in Creating a Dynamic Web Project to configure your Dynamic Web project to target CICS TS. If you haven't installed CICS Explorer, install it as described in Setting up your development environment.
The com.ibm.cics.jcicsx artifact on Maven Central. If you haven't installed Gradle or Maven, install either of them as described in Setting up your development environment.
If your enterprise uses locally hosted or allow-listed repositories, you can use tools such as JFrog Artifactory or Sonatype Nexus to configure the artifact to be obtained from such repositories.
The com.ibm.cics.jcicsx.jar file supplied with CICS in the USSHOME directory, which you can copy to your compilation environment. For more information, see Manually importing Java libraries.

JCICSX use cases and samples

After configuration is complete, you can start coding to the JCICSX API classes.

During unit testing, you can mock the JCICSX method calls on your workstation using familiar testing frameworks.

When the Liberty JVM server is enabled for remote development, you can run the application code in your local Liberty server to check how your code will behave when running in CICS or explore what information is returned on the API commands, by making remote calls into a CICS region. When you run your application within the local Liberty server, any JCICSX calls will automatically be redirected to your CICS region. When your application is deployed to a JVM server running in a real CICS region, the same JCICSX calls will be made directly against CICS.

Typical use cases of JCICSX are shown in JCICSX examples. For details of all JCICSX API classes, see JCICSX Javadoc.

Best practices

If you're developing using JCICSX, you are advised to run your code in a local Liberty server on your workstation. This can reduce issues around different applications conflicting with each other when running in a shared JVM server in a CICS development region.

If you're planning to deploy applications to a Liberty JVM server running in CICS TS, see Considerations for a shared JVM for best practices.

Troubleshooting

You can use your Java IDE's debugger, console message, and error handling information to debug your applications. JCICSX also allows multiple clients to debug at the same time. In addition, you can use the CEDX transaction to test your application program in CICS.

If an error that relates to CICS occurs, for example the remote JVM server or the CICS transaction, a response (RESP) code is returned. The system programmer can use the JVM server's traces and logs for debugging. For more information, see Troubleshooting Java applications.

Appendixes

Appendix 1. JCICSX API classes

The JCICSX API classes support a subset of the CICS functionality as follows. For details about each class, see JCICSX Javadoc.

Table 1. JCICSX API classes
Classes	Description
CICSContext	The environment that the API is executing in. Entry point to the JCICSX API.
Channel	Create or delete a channel, or retrieve information about the containers in it.
Container	Create a container, retrieve information about a container, get data from and put data into a container, or delete a container.
ProgramLinker	Link to a program.

Appendix 2. Mapping between JCICSX and EXEC CICS API commands

This table shows how JCICSX API methods map onto EXEC CICSAPI commands. Only methods that have mapping relationships are listed.

Table 2. Mapping between JCICSX and EXEC CICS API commands
Classes	Methods	EXEC CICS API commands
`BITContainer` `CHARContainer` `WritableBITContainer` `WritableCHARContainer` `WritableContainer`	`append`	`EXEC CICS PUT64 CONTAINER APPEND`
	`put`	`EXEC CICS PUT64 CONTAINER`
`Channel`	`exists` `getContainerCount`	`EXEC CICS QUERY CHANNEL`
	`delete`	`EXEC CICS DELETE CHANNEL`
	`iterator`	`EXEC CICS STARTBROWSE CONTAINER` `EXEC CICS GETNEXT CONTAINER` `EXEC CICS ENDBROWSE CONTAINER`
`ChannelProgramLinker`	`link`	`EXEC CICS LINK PROGRAM`
`Container`	`delete`	`EXEC CICS DELETE CONTAINER CHANNEL`
`Container`	`getLength`	`EXEC CICS GET CONTAINER CHANNEL NODATA`
`ProgramLinker`	`link`	`EXEC CICS LINK PROGRAM`
`ReadableBITContainer`	`get`	`EXEC CICS GET64 CONTAINER`
`ReadableBITContainer`	`read`	`EXEC CICS GET64 CONTAINER`
`ReadableCHARContainer` `ReadableContainer`	`get`	`EXEC CICS GET64 CONTAINER`

¹ Aqua refers to IBM Explorer for z/OS® Aqua.