Developing applications using Maven or Gradle

When writing your own build scripts, 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.

CICS provides a set of artifacts on Maven Central, an online repository, for you to resolve Java dependencies. Maven and Gradle are supported by most Java integrated development environments (IDEs) and compatible with popular automation tools such as Jenkins and Travis CI.

What artifacts are available

These artifacts are available 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.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 the development environment.

Note: Not all Eclipse packages support Maven or Gradle by default. For example, if you use a standalone CICS Explorer® for Aqua 3.11 or earlier, Maven or Gradle support is not included. To use Maven or Gradle, install the m2e (Maven integration for Eclipse) plug-in or the Buildship Gradle Integration plug-in through the Eclipse Marketplace.
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.
com.ibm.cics.ts.bom
All versions are available at com.ibm.cics.ts.bom.

Maven pom.xml

<dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.ibm.cics</groupId>
        <artifactId>com.ibm.cics.ts.bom</artifactId>
        <version>5.5-20200519131930-PH25409</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
</dependencyManagement>

In Maven, the BOM controls these configurations of the other dependencies:

Version:

The BOM version 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.5)
  • the time stamp when the BOM is built (20200519131930)
  • if relevant, the version of the CICS TS APAR (PH25409), which includes server-side updates to the libraries

Scope:

The BOM also 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.

Gradle build.gradle

repositories {
     mavenCentral()
}

dependencies {
    compileOnly enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.5-20200519131930-PH25409')
}

In Gradle, the BOM also controls these configurations of the other dependencies:

Version:

The BOM version 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.5)
  • the time stamp when the BOM is built (20200519131930)
  • if relevant, the version of the CICS TS APAR (PH25409), which includes server-side updates to the libraries
The enforcedPlatform keyword 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.

Scope:

Similar to the provided scope in Maven, Gradle has a compileOnly configuration to 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, declare dependency on the JCICS library (com.ibm.cics.server) with the BOM that has the compileOnly configuration as follows: 
dependencies {
    compileOnly enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.5-20200519131930-PH25409')
    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 also define a BOM with the annotationProcessor configuration. This is because the annotation processor dependency must use the annotationProcessor configuration.

Gradle build.gradle

dependencies {
    annotationProcessor enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.5-20200519131930-PH25409')
    annotationProcessor ("com.ibm.cics:com.ibm.cics.server.invocation")  //dependency on annotation processor
}
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.
com.ibm.cics.server
All versions are available at com.ibm.cics.server on Maven Central.

Maven 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 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.
<dependencies>
    <dependency>
        <groupId>com.ibm.cics</groupId>
        <artifactId>com.ibm.cics.server</artifactId>
        <version>1.700.1-5.5-PH25409</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle 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.700.1-5.5-PH25409'
}
com.ibm.cics.server.invocation.annotations
All versions are available at com.ibm.cics.server.invocation.annotations on Maven Central.

Maven 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.

Gradle 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.

Maven 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.5-PH25409</version>
                    </annotationProcessorPath>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
Note: Maven If 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.

Gradle 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 when writing the code. After you finish writing 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.

1 Aqua stands for z/OS Explorer for Aqua.