It’s important to us that you are able to develop your CICS applications as easily as possible. That’s why we’ve now released the libraries you need to develop CICS Java applications to Maven Central.

As a result, you can refer to JCICS and other related libraries from Maven and Gradle builds. No more manually importing your dependencies into your artifact repository!

What libraries are available?

We’ve delivered the following libraries to Maven Central:

  • JCICS is the main library to call into CICS. It allows you to use containers, queues, files, and many other aspects of the CICS API.
  • The annotation processor for Link-to-Liberty scans your source during compilation to enable calling from the rest of CICS into a Liberty program.
  • The annotation for Link-to-Liberty marks the methods that you can call from the rest of CICS.

We’ve also delivered a bill-of-materials (BOM) for all these libraries, so that you can easily use consistent versions of them all.

How do I use the libraries from Maven Central?

To use the libraries, just make a small dependency declaration in your project’s metadata. If you use Maven, change the pom.xml file. Alternatively, if you use Gradle, change the build.gradle file.

For example, here’s how to add JCICS to your Maven project’s pom.xml:

<dependencies>
  <dependency>
    <groupId>com.ibm.cics</groupId>
    <artifactId>com.ibm.cics.server</artifactId>
    <version>1.700.0-5.5-PH10453</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

If you’re using Gradle, add this to your build.gradle:

repositories {
  mavenCentral()
}

dependencies {
  compileOnly 'com.ibm.cics:com.ibm.cics.server:1.700.0-5.5-PH10453'
}

Note that we’ve specified the provided scope in Maven, and the compileOnly configuration in Gradle. This is because JCICS is provided on the classpath of applications that run in CICS. By specifying this Maven scope or Gradle configuration, we’re making sure that JCICS is never packaged into the application, because we want to rely on the JCICS inside CICS itself. Packaging JCICS into your applications is likely to result in strange inconsistencies.

Can I simplify this configuration?

Because you never want to package JCICS into your application, it would be great if you could specify that it was always provided. In addition, it would be useful to know that you are using consistent versions of JCICS and other libraries. These challenges are solved by the Bill of Materials (BOM). The BOM specifies a consistent set of artifacts, and adds information about their scope too.

In Maven, the BOM is configured by importing it into the dependency management section of your project. Configure the CICS BOM like so:

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

In Gradle, you configure the BOM using the enforcedPlatform keyword for each configuration you need, like this:

dependencies {
  compileOnly         enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.5-20190701171918-PH10453')
  annotationProcessor enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.5-20190701171918-PH10453')
}
Having done this, you you can now really simplify your dependencies. For example, where you previously specified the version of a dependency, you can remove the declaration. In addition, where a dependency specified a provided scope, you can remove the declaration too. You’ll see how the examples below don’t need to refer to a version or scope.

How do I set up Link-to-Liberty with the Maven Central libraries?

When you link from other CICS programs to Liberty programs, you must run an annotation processor on your code at compilation time. The annotation processor creates metadata that tells CICS about the programs. There are multiple ways to do this in Maven, one of which involves configuring your compiler plugin as follows:

<dependencies>
  <dependency>
    <groupId>com.ibm.cics</groupId>
    <artifactId>com.ibm.cics.server.invocation.annotations</artifactId>
  </dependency>
</dependencies>
<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-PH10453</version>
          </annotationProcessorPath>
        </annotationProcessorPaths>
      </configuration>
    </plugin>
  </plugins>
</build>

By comparison, for Gradle projects, the same instruction is less verbose:

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

Find out more

To find out all the detail about how to use the libraries from Maven Central, see our Knowledge Center. It takes you through each of the artifacts, with advice for how to use them.

Plus, if you’re using Maven, you’ll want to know about our plugin for building CICS bundles.

We’d love to hear your feedback, so feel free to leave us a comment. If you’re interested in the future of development with CICS, consider joining the IBM Z design forum.

Join The Discussion

Your email address will not be published. Required fields are marked *