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