Managing Java dependencies using Maven or Gradle

When writing your own build scripts for Java development, you can use build toolchains such as Maven or Gradle to resolve Java dependencies. As an alternative to the IBM® CICS® SDK for Java™, they can retrieve libraries from a remote repository or allow-listed local repositories. After finishing coding, you can use the CICS-provided Maven and Gradle plug-ins to build and deploy a CICS bundle including your Java application.

Maven and Gradle are supported by most Java integrated development environments (IDEs) and automation tools such as Jenkins and Travis CI; therefore, you can integrate the compilation, building, and deployment of applications into a pipeline more easily during development.

What artifacts are available

These artifacts are provided by CICS on Maven Central:

Table 1. CICS-provided artifacts on Maven Central
Group ID Artifact ID Description
com.ibm.cics com.ibm.cics.ts.bom

The bill of materials (BOM) that defines the versions of all the artifacts to ensure they are at the same CICS TS level.

Tip: You're recommended to use the BOM to control version numbers of the other dependencies and omit their version numbers from their own specifications.

Learn more ...

com.ibm.cics.server

The CICS Java class library (JCICS), a Java library that provides the EXEC CICS API support for Java applications in CICS TS.

Learn more ...

com.ibm.cics.jcicsx

The JCICSX API classes that support a subset of CICS functionality, available in CICS TS V5.6 or later.

The classes 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 those enhanced features.

Learn more ...

com.ibm.cics.server.invocation.annotations

CICS annotations, a Java library that provides the @CICSProgram annotation to enable CICS programs to invoke Java applications in a Liberty JVM server.

Learn more ...

com.ibm.cics.server.invocation

The CICS annotation processor, a Java library that is used during compilation to create metadata that enables CICS programs to invoke Java applications in a Liberty JVM server.

Learn more ...

How to declare dependencies

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

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

You declare dependencies in the Maven module's pom.xml file or the Gradle module's build.gradle file. The following instructions per artifact include snippets showing how to declare dependency on each artifact; you can modify the artifact coordinates according to the information on Maven Central. You can also use other build tools to leverage the Maven Central artifacts, but this topic focuses on Maven and Gradle only.
Note: Snippets on Maven Central are auto-generated and might be missing configurations such as <scope>import</scope> and compileOnly. Follow the syntax in this topic instead to ensure the dependencies are correctly declared.
To help you find instructions applicable to your case, the relevant steps for each tool are indicated using the following logos.
Apache Maven Gradle
Maven logo Gradle logo
com.ibm.cics.ts.bom
All versions are available at com.ibm.cics.ts.bom.
Note: You declare dependency on a BOM file for version control. The BOM itself does not import any library; you must also reference other libraries along with the BOM.

For Maven usersMaven: 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:
  • 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 the support for the other dependencies you need in your application, and that your target CICS system is at the same or newer CICS TS release and APAR maintenance level. In the 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.
  • Specifies that the other dependencies have a provided scope, so you don't need to add <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.

For Gradle usersGradle: build.gradle

repositories {
     mavenCentral()
}

dependencies {
    compileOnly enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.6-20200609123739')
}
In Gradle, the BOM also controls the configuration of the other dependencies as follows:
  • Controls the version of other dependencies in a way similar to Maven, except that the BOM version in Gradle is specified following the enforcedPlatform keyword, which ensures that the version specified in the BOM overrides any other versions found in the dependency graph.
    Note: enforcedPlatform is supported from Gradle 5.0.
  • Controls the scope of other dependencies using the compileOnly configuration. Similar to the provided scope in Maven, compileOnly ensure that the dependency is provided by the CICS TS runtime and not packaged with the module. However, you must specify consistent target configuration for both the BOM and the other dependencies. For example, if you reference a BOM with the compileOnly configuration and want to use it to control your JCICS library (com.ibm.cics.server), import dependencies as follows:
    dependencies {
        compileOnly enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.6-20200609123739')
        compileOnly("com.ibm.cics:com.ibm.cics.server")  //dependency on JCICS
    }
    Likewise, if you declare dependency on the annotation processor (com.ibm.cics.server.invocation), you should define a BOM with the annotationProcessor configuration. This is because the annotation processor dependency must use the annotationProcessor configuration.
    dependencies {
        annotationProcessor enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.6-20200609123739')
        annotationProcessor ("com.ibm.cics:com.ibm.cics.server.invocation")  //dependency on annotation processor
    }
com.ibm.cics.server
All versions are available at com.ibm.cics.server on Maven Central.

For Maven usersMaven: 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.
<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>

For Gradle usersGradle: build.gradle

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.ibm.cics:com.ibm.cics.server'
}
The version number is omitted as 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.
repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.ibm.cics:com.ibm.cics.server:1.800.0-5.6'
}
com.ibm.cics.jcicsx
All versions are available at com.ibm.cics.jcicsx on Maven Central.

For Maven usersMaven: 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. Note that the version number includes the OSGi Bundle-Version, the CICS release, and (if relevant) the APAR number.

For Gradle usersGradle: build.gradle

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.ibm.cics:com.ibm.cics.jcicsx'
}

The version number is omitted because it's inherited from the BOM. If you don't use a BOM, also specify a version number for this dependency.

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

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

For Maven usersMaven: 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. The version number includes the CICS release and (if relevant) the CICS TS APAR number.

For Gradle usersGradle: build.gradle

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.ibm.cics:com.ibm.cics.server.invocation.annotations'
}

The version number is omitted because it's inherited from the BOM. If you don't use a BOM, also specify a version number for this dependency.

The version number includes the CICS release and (if relevant) the CICS TS APAR number.
com.ibm.cics.server.invocation
All versions are available at com.ibm.cics.server.invocation on Maven Central.

You're recommended to use a 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.

For Maven usersMaven: 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: For Maven usersIf you're using Maven, you need to specify the version number of the artifact even if you use a BOM. The version number includes the CICS release and (if relevant) the CICS TS APAR number.

For Gradle usersGradle: build.gradle

repositories {
    mavenCentral()
}

dependencies {
    annotationProcessor 'com.ibm.cics:com.ibm.cics.server.invocation'
}
The version number is omitted because it's inherited from the BOM. Make sure that the BOM is defined with the same annotationProcessor configuration. If you don't use a BOM, specify a version number for this dependency. The version number includes the CICS release and (if relevant) the CICS TS APAR number.

What's next

You can reference the JCICS Javadoc information or the JCICSX Javadoc when writing the code, depending on which API you call. For more information about these APIs, see Java development using JCICS and Java development using JCICSX. After finishing the application code, you can build the applications and integrate them into your build toolchain in the same way as you build and deploy other Maven or Gradle modules. CICS provides a Maven and a Gradle plug-in for you to deploy your applications into CICS at development time.