Setting up the development environment

You can use the JCICS API to develop Java™ applications that can access CICS® resources. The API is available in the IBM® CICS SDK for Java, Maven Central, or in the USSHOME directory of your CICS installation.

About this task

The JCICS API provides you with the Java interface to access CICS services. This API is the Java equivalent of the EXEC CICS API that is provided for other CICS supported languages, such as COBOL.

The table shows where the API is provided and what tools you can use to consume it.

Table 1. JCICS API locations
Java code authoring tool	JCICS API
CICS Explorer®	Provided in the preinstalled IBM CICS SDK for Java, which resolves dependencies automatically.
Maven and Gradle (to access artifacts from Maven Central)	You can declare the dependency using any Java IDE that supports Maven or Gradle.
Any other tool, to import the API jars provided in USSHOME	You need to manually import the dependency.

Note: If you want to develop Java EE applications for CICS, you must install the IBM CICS SDK for Java EE, Jakarta EE and Liberty in CICS Explorer.

CICS Explorer provides the following tools for you to develop, package, and deploy Java applications that are hosted in the CICS JVM server:

The IBM CICS SDK for Java provides support for the JCICS API.
Eclipse and the Eclipse Web Tools Platform provide the tools to develop Java EE applications.
The IBM CICS SDK for Java EE, Jakarta EE and Liberty provides the Java EE, Jakarta EE, and Liberty APIs in the form of a Java build path library or OSGi target platform.
CICS Explorer provides the tools to package, deploy, and manage Java applications within CICS bundles.
Explorer for z/OS® provides the tools to work with files, data sets, and jobs on z/OS, including viewing JVM server log files.

The SDKs can resolve dependencies automatically as long as you add the correct library to your build path or select the correct OSGi target platform.

Consuming dependencies from Maven Central offers more flexibility in the choice of IDE and integrates easily into popular build toolchains such as Maven or Gradle. The Maven Central artifacts contain the JCICS, CICS annotation, CICS annotation processor libraries and a bill of material (BOM) for you to declare dependencies and develop applications for CICS in your IDE of choice. The artifacts can be obtained directly from Maven Central, or from locally hosted and allow-listed repositories using tools such as JFrog Artifactory or Sonatype Nexus.

Procedure

To use the SDKs in CICS Explorer:
1. The IBM CICS SDK for Java is preinstalled in CICS Explorer. If you want to develop Java EE applications, install the IBM CICS SDK for Java EE, Jakarta EE and Liberty into your CICS Explorer as a plug-in. For instructions, see Downloading and starting CICS Explorer in the CICS Explorer product documentation and Installing the CICS SDK for Java EE, Jakarta EE and Liberty in the CICS Explorer product documentation.
2. Restart your development environment.
3. Add libraries to your build path or select your target platform, for the SDK to revolve dependencies correctly for your projects. See Step 1 in Creating a Dynamic Web Project, Creating an OSGi Application Project, and Creating an Enterprise Application Project.
To use Maven or Gradle:
1. Ensure your environment fulfills either of the following prerequisites:
  - If you want to use Maven or Gradle with the command line, you must install them on your machine. See Downloading and Installing Maven and Installing Gradle.
  - Your IDE must support Maven or Gradle. Such IDEs include Eclipse, IntelliJ IDEA, and Visual Studio Code.
2. Create your project using Maven or Gradle and import dependencies based on the API you want to use, as described in Developing applications using Maven or Gradle. You might need to add extra Maven or Gradle configuration, depending on your project type. See Step 1 in Creating a Dynamic Web Project, Creating an OSGi Application Project, and Creating an Enterprise Application Project.
To use the JAR files in the USSHOME directory, see Manually importing Java libraries.

Results

Your development environment is ready to develop Java applications for CICS.

What to do next

You can start developing Java applications by referring to the JCICS Javadoc information. If you're using the IBM CICS SDK for Java, you can use the examples that are provided with the IBM CICS SDK for Java to get started. For more information, see Java samples: Servlet examples.