Declaring Java dependencies using Maven

When creating a Maven build script, you will need to refer to dependencies supplied by CICS®. Use this guide to understand how to reference each dependency.

For a complete list of all dependencies available, see Managing Java dependencies using Gradle or Maven.

Prerequisites: Before developing Java applications for CICS using Maven, you must make sure that:
  • You already have Maven installed in your workstation or IDE.
  • You have created a Maven module to include your application, or that you have converted an existing Java project to a Maven module. Most Java IDEs support this function.

For instructions, see the Maven related information in Setting up your development environment.

How to declare dependencies

You declare dependencies in the Maven module's pom.xml file. The following instructions include snippets showing how to declare a dependency on each artifact. More recent versions might be available, so check Maven Central for all available versions.
Note: The snippets shown on Maven Central are auto-generated and might not show the correct Maven directives such as <scope>import</scope>. Follow the syntax in this topic instead to ensure the dependencies are correctly declared.
You can declare dependencies on these CICS-supplied artifacts:
The CICS bill of materials (BOM): com.ibm.cics.ts.bom

All versions are available at com.ibm.cics.ts.bom on Maven Central.

Note: You declare a dependency on a BOM file to manage versions of other libraries. The BOM itself does not import any library. Therefore, you must also reference other libraries along with the BOM.

Refer to this library as follows:

Figure 1. pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.ibm.cics</groupId>
            <artifactId>com.ibm.cics.ts.bom</artifactId>
            <version>5.6-20200609123739</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
In Maven, the BOM controls the configurations of the other dependencies as follows:

  • The BOM controls the version of any other CICS dependency in the same module or its child modules if the version of that dependency is not otherwise specified.

    Make sure that you specify a BOM version that provides support for the other dependencies of your application, and that your target CICS system is at the same or later CICS TS release and APAR maintenance level. In the previous snippet, the version tag specifies the BOM version, consisting of:

    • The CICS version (5.6)
    • the time stamp when the BOM is built (20200609123739)
    • if relevant, the version of the CICS TS APAR that includes server-side updates to the libraries. For example, PH25409 in a version number 5.5-20200519131930-PH25409.

  • The BOM specifies that the other dependencies have a provided scope where relevant, so you don't need to specify <scope>provided</scope> in those Maven dependencies. When this scope is specified, the dependency will be provided by the eventual runtime and must not be packaged as part of the module. It not only reduces the application size, but also avoids hard-to-diagnose problems caused by inconsistent versions being used or classes being loaded from more than one class loader.

    If you do not use a BOM, you must specify <scope>provided</scope> when declaring those dependencies in Maven.

The CICS Java class library (JCICS): com.ibm.cics.server

All versions are available at com.ibm.cics.server on Maven Central.

Refer to this library as follows:

Figure 2. pom.xml
<dependencies>
    <dependency>
        <groupId>com.ibm.cics</groupId>
        <artifactId>com.ibm.cics.server</artifactId>
    </dependency>
</dependencies>

The version number and the scope configuration are omitted because they are inherited from the BOM. If you don't use a BOM, reference this library as follows, where the version number includes the OSGi Bundle-Version, the CICS release, and (if relevant) the APAR number.

Figure 3. pom.xml
<dependencies>
    <dependency>
        <groupId>com.ibm.cics</groupId>
        <artifactId>com.ibm.cics.server</artifactId>
        <version>1.800.0-5.6</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
The JCICSX API classes: com.ibm.cics.jcicsx

All versions are available at com.ibm.cics.jcicsx on Maven Central.

Refer to this library as follows:

Figure 4. pom.xml
<dependency>
    <groupId>com.ibm.cics</groupId>
    <artifactId>com.ibm.cics.jcicsx</artifactId>
</dependency>

The version number and scope configuration are omitted because they are inherited from the BOM. If you don't use a BOM, also specify the version number and <scope>provided</scope> for this dependency.

Its version number includes the OSGi Bundle-Version, the CICS release, and (if relevant) the APAR number.

The CICS annotations: com.ibm.cics.server.invocation.annotations

All versions are available at com.ibm.cics.server.invocation.annotations on Maven Central.

Refer to this library as follows:

Figure 5. pom.xml
<dependencies>
    <dependency>
        <groupId>com.ibm.cics</groupId>
        <artifactId>com.ibm.cics.server.invocation.annotations</artifactId>
    </dependency>
</dependencies>

The version number and scope configuration are omitted because they are inherited from the BOM. If you don't use a BOM, also specify the version number and <scope>provided</scope> for this dependency.

Its version number includes the CICS release and (if relevant) the CICS TS APAR number.

The CICS annotation processor: com.ibm.cics.server.invocation

All versions are available at com.ibm.cics.server.invocation on Maven Central.

You're recommended to use the separate processor path for annotation processors, rather than adding them directly to the class path. For this reason, the configuration for com.ibm.cics.server.invocation differs from the other artifacts.

Refer to this library as follows:

Figure 6. pom.xml
<build>
    <plugins>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <annotationProcessorPaths>
                    <annotationProcessorPath>
                        <groupId>com.ibm.cics</groupId>
                        <artifactId>com.ibm.cics.server.invocation</artifactId>
                        <version>5.6</version>
                    </annotationProcessorPath>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
Note:

You need to specify the version number of this artifact even if you use a BOM.

Its version number includes the CICS release and (if relevant) the CICS TS APAR number.

What's next

Write an application using the CICS Java API
CICS provides two versions of Java API: JCICS and JCICSX. For their differences, see Explore the Java APIs.

You can also find their API documentation at JCICS Javadoc information or JCICSX Javadoc.

Try some samples

CICS provides a series of samples for you to get started. See Try Java in your environment.

Build and deploy your application
After finishing the application code, you can build the application and integrate it into your build toolchain in the same way as you build and deploy other Maven modules. CICS provides a Maven plug-in for you to deploy your applications into CICS at development time.

This tutorial provides step-by-step instructions on how to build a CICS bundle from an existing Maven-built Java application. Use the sample provided therein to have a try.