Declaring Java dependencies using Gradle

When creating a Gradle build script, you 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 with Gradle, you must make sure that:
  • You already have Gradle support installed in your workstation or IDE.
  • You have created a Gradle module to include your application, or that you have converted an existing Java project to a Gradle module. Most Java IDEs support this function.

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

How to declare dependencies

You declare dependencies in the Gradle module's build.gradle 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 Gradle configurations such as compileOnly. 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. build.gradle
repositories {
    mavenCentral()
}

dependencies {
    compileOnly enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.6-20200609123739')
}

In Gradle, the BOM controls the version of any other CICS-provided dependency in the same module or its child modules by using the enforcedPlatform keyword, which ensures that the versions specified in the BOM overrides any other versions found in the dependency graph.

Note: enforcedPlatform is supported from Gradle 5.0.

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 enforcedPlatform 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 only affects libraries that use the same Gradle scope configuration, such as compileOnly, which ensures that the dependency is provided by the CICS TS runtime and not packaged with the module. Therefore, you must specify the BOM for all the configurations that will use CICS dependencies, with the same scope configuration. For example, if you are referencing the JCICS library (com.ibm.cics.server) using the compileOnly configuration, you need to control its version with the BOM as follows:

Figure 2. build.gradle
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 a dependency on the annotation processor (com.ibm.cics.server.invocation), you need to define a BOM with the annotationProcessor configuration. This is because the annotation processor dependency must use the annotationProcessor configuration.

Figure 3. build.gradle
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
}
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 4. build.gradle
repositories {
    mavenCentral()
}

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

The version number is 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 5. build.gradle
repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.ibm.cics:com.ibm.cics.server:1.800.0-5.6'
}
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 6. 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.

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

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

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 Gradle modules. CICS provides a Gradle 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 Gradle-built Java application. Use the sample provided therein to have a try.