Setting up your development environment

Before you develop Java applications, you must set up your development environment to resolve dependencies and build your applications for deployment. CICS® provides a set of Java dependencies, including JCICS and JCICSX APIs, to access CICS resources. You can either use the IBM®-provided SDKs or bring your own IDE for development.

Before you begin

What IDE options are available?

You can develop applications either in an IDE with the IBM CICS SDK or in a Java IDE of your choice.

The IBM CICS SDK for Java™ provides support for Java applications, including JCICS and JCICSX APIs. It is preinstalled in CICS Explorer® and IBM Developer for z/OS (IDz), or can be installed as a plug-in into an existing Eclipse platform. The IBM CICS SDK for Enterprise Java (Liberty) provides Enterprise Java support and needs to be installed separately as an Eclipse plug-in. These SDKs provide necessary libraries and tools for you to resolve Java dependencies, build, and deploy applications into CICS.
If you use your own Java IDE, for example, Eclipse, IntelliJ, and VS Code, you can resolve dependencies by referencing CICS-provided Maven Central artifacts or manually importing the .jar files from USSHOME. You then package applications using CICS-provided Gradle or Maven plug-ins. For deployment, you can either use CICS-provided Gradle or Maven plug-ins, which require the CICS bundle deployment API to be configured in advance, or write your own build scripts to deploy the application.

Which IDE should I choose?

Differences between different Java IDEs are as follows. For comparison of JCICS and JCICSX, see Explore the Java APIs.

Table 1. Comparison of different IDEs. Capabilities are listed in Column c1. The IBM CICS SDKs and Bring your own IDE approaches are listed and compared in Columns c2 and c3.
Capability	IBM CICS SDKs	Bring your own IDE
Resolving CICS Java dependencies, including the JCICS and JCICSX API classes	Resolve dependencies automatically if you add the correct library to your build path or select the correct OSGi target platform. The IBM CICS SDK for Java includes the JCICS API in all releases and JCICSX API classes in CICS Explorer for Aqua 3.3 or later (Aqua refers to IBM Explorer for z/OS Aqua.) If you use CICS Explorer for Aqua 3.3 or later, the SDK no longer supports WDT; use an alternative solution, as suggested in Consideration for OSGi applications when installing CICS Explorer in the CICS Explorer product documentation. The IBM CICS SDK for Enterprise Java (Liberty) includes the Eclipse Web Tools Platform, which provides tools to develop Enterprise Java applications. The IBM CICS SDK for Enterprise Java (Liberty) provides the Enterprise Java and Liberty APIs in the form of a Java build path library or OSGi target platform.	Resolve the dependencies you need by referencing corresponding Gradle or Maven artifacts on Maven Central: the JCICS, JCICSX, CICS annotation, CICS annotation processor libraries and a bill of material (BOM). 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. Alternatively, you can copy .jar files manually from USSHOME for dependency management. However, copying .jar files manually makes them prone to get out of sync with updates. Missing dependencies won't be detected until the application gets built.
Building or packing applications	Need to check build results manually. If you are using CICS Explorer, the Explorer for z/OS it's based on can provide tools to work with files, data sets, and jobs on z/OS, including viewing JVM server log files.	Gradle or Maven can integrate easily into a CI pipeline.
Deploying applications into CICS	If you deploy applications in CICS bundle, you need system programmers to install, enable, or disable any existing BUNDLE resource in CICS for bundle deployment, unless you are granted with equivalent access.	If you use CICS-provided Gradle or Maven plug-ins for deployment (require the CICS bundle deployment API): After the CICS bundle is sent to the API, a functional ID automatically sends the package to zFS and manages the BUNDLE lifecycle for developers. As a result, Java developers can deploy bundles whilst the system programmer retains control. The system programmer must set up the API and its security in advance. The API is supported in CICSPlex® SM environments as of CICS TS 5.6 and in single CICS regions (SMSS) as of CICS TS 6.1. Support only the Liberty JVM server for deployment. If you do not use the CICS-provided plug-ins, you deploy applications in a similar way to using IBM CICS SDKs. That is, when deploying applications in CICS bundles, developers need to send CICS bundles to zFS over an FTP connection and ask system programmers to manage the BUNDLE resource's lifecycle in CICS.

Notes:

If you use the IBM CICS SDKs, to develop Enterprise Java applications for CICS, you must install the IBM CICS SDK for Enterprise Java (Liberty). If you want to create OSGi Application Projects (EBA) by using CICS Explorer downloaded from Eclipse Marketplace, you need to install the Liberty Developer Tools (LDT) from Eclipse Marketplace in addition to the IBM CICS SDK for Enterprise Java (Liberty).
The IBM CICS SDK for Enterprise Java (Liberty) depends on the IBM CICS SDK for Java. Therefore, when you install the IBM CICS SDK for Enterprise Java (Liberty), the IBM CICS SDK for Java is automatically installed.
If you need to leverage Gradle or Maven assets, such as the Maven Central artifacts and plug-ins, make sure your IDE supports Gradle or Maven accordingly. Example IDEs are Eclipse, IntelliJ, and VS Code.

Procedure

To use the SDKs, taking CICS Explorer as an example:
1. The IBM CICS SDK for Java is preinstalled in CICS Explorer. If you want to develop Enterprise Java applications, install the IBM CICS SDK for Enterprise Java (Liberty) into your CICS Explorer as a plug-in. For instructions, see Downloading and installing CICS Explorer in the CICS Explorer product documentation and Installing the CICS SDK for Enterprise Java and Liberty in the CICS Explorer product documentation.
  If you need to develop OSGi applications in CICS Explorer, see Consideration for OSGi applications when installing CICS Explorer 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 resolve 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 Gradle or Maven in your own IDE:
1. Ensure your environment fulfills either of the following prerequisites:
  
  If you want to use Gradle or Maven with the command line, you must install them on your machine. See Installing Gradle and Downloading and Installing Maven.
  
  Alternatively, use an IDE that supports Gradle or Maven. Such IDEs include Eclipse, IntelliJ IDEA, and Visual Studio Code.
2. Create your project using Gradle or Maven and import dependencies based on the API you want to use, as described in Managing Java dependencies using Gradle or Maven. You might need to add extra Gradle or Maven 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 import the JAR files from the USSHOME directory into your own IDE, see Manually importing Java libraries.

Results

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

What to do next

If you're using the IBM CICS SDKs, see Developing applications using IBM CICS SDKs.

If you are using Gradle or Maven, see Managing Java dependencies using Gradle or Maven.