cics-java-liberty-springboot-transactions

Overview

This sample project demonstrates how a Spring Boot application deployed to a Liberty JVM server can use different techniques to integrate with CICS transactions. The application uses a web browser front end and makes use of the Java™ Transaction API (JTA). The three techniques demonstrated are: Java EE User Transaction, Spring's @Transactional annotation, and the Spring Transaction Template.

Key Features:

• JTA Integration: Demonstrates Java Transaction API usage in CICS
• Multiple Transaction Techniques: Shows three different approaches to transaction management
• Spring Boot Integration: Uses Spring's @Transactional annotation and Transaction Template
• Java EE User Transaction: Demonstrates programmatic transaction control
• Recoverable TSQ Operations: Shows transaction commit and rollback with CICS temporary storage queues

Table of Contents

1. Overview
2. Prerequisites
3. Reference
4. Downloading
5. Check Dependencies
6. Building the Sample
7. Deploying to a CICS Liberty JVM server
8. Running the Sample
9. Troubleshooting
10. License
11. Additional Resources
12. Contributing

Prerequisites

• CICS TS V6.1 or later (required for Spring Boot 3.x and Jakarta EE 10 support)
• A configured Liberty JVM server in CICS
• Java SE 17 or later on the workstation
• An Eclipse development environment on the workstation (optional)
• Either Gradle or Apache Maven on the workstation (optional if using Wrappers)
• A CICS TSMODEL resource with the attribute Recovery(ON) for the TSQ called EXAMPLE

Reference

More information about the development of this sample can be found in the blog Spring Boot Java applications for CICS, Part 3: Transactions

Downloading

• Clone the repository using your IDEs support, such as the Eclipse Git plugin
• or, download the sample as a ZIP and unzip onto the workstation

Importing into Eclipse:

1. In the Git Repositories view, right-click the repository → Import as Project (imports the root project)
2. Switch to the Java EE perspective
3. In the Project Explorer, right-click the cics-java-liberty-springboot-transactions-app folder → Import as Project
4. Right-click the cics-java-liberty-springboot-transactions-cicsbundle folder → Import as Project
5. Right-click the cics-java-liberty-springboot-transactions-cicsbundle-eclipse folder → Import as Project
6. Right-click the root project → Gradle → Refresh Gradle Project or Maven → Update Project... to resolve dependencies

Check dependencies

Before building this sample, you should verify that the correct CICS TS bill of materials (BOM) is specified for your target release of CICS. The BOM specifies a consistent set of artifacts, and adds information about their scope. In the example below the version specified is compatible with CICS TS V6.1 with JCICS APAR PH63856, or newer. That is, the Java byte codes built by compiling against this version of JCICS will be compatible with later CICS TS versions and subsequent JCICS APARs. You can browse the published versions of the CICS BOM at Maven Central.

Gradle (build.gradle):

compileOnly enforcedPlatform("com.ibm.cics:com.ibm.cics.ts.bom:6.1-20250812133513-PH63856")

Maven (POM.xml):

<dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.ibm.cics</groupId>
        <artifactId>com.ibm.cics.ts.bom</artifactId>
        <version>6.1-20250812133513-PH63856</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

Building the Sample

You can build the sample using an IDE of your choice, or you can build it from the command line. For both approaches, using the supplied Gradle or Maven wrapper is the recommended way to get a consistent version of build tooling.

On the command line, you simply swap the Gradle or Maven command for the wrapper equivalent, gradlew or mvnw respectively.

For an IDE, taking Eclipse as an example, the plug-ins for Gradle buildship and Maven m2e will integrate with the "Run As..." capability, allowing you to specify whether you want to build the project with a Wrapper, or a specific version of your chosen build tool.

The required build-tasks are clean build for Gradle and clean verify for Maven. Once run, Gradle will generate a WAR file in the cics-java-liberty-springboot-transactions-app/build/libs directory, while Maven will generate it in the cics-java-liberty-springboot-transactions-app/target directory.

Note: When building a WAR file for deployment to Liberty it is good practice to exclude Tomcat from the final runtime artifact. We demonstrate this in the pom.xml with the provided scope, and in build.gradle with the providedRuntime() dependency.

Gradle Wrapper (command line)

Run the following in a local command prompt:

On Linux or Mac:

./gradlew clean build

On Windows:

gradlew.bat clean build

This creates a WAR file inside the cics-java-liberty-springboot-transactions-app/build/libs directory.

Note: In Eclipse, the build directory may be hidden by default. To view it: Package Explorer → ⋮ → Filters and Customization → uncheck "Gradle build folder". For Maven, the target directory is visible by default.

Maven Wrapper (command line)

Run the following in a local command prompt:

On Linux or Mac:

./mvnw clean verify

On Windows:

mvnw.cmd clean verify

This creates a WAR file inside the cics-java-liberty-springboot-transactions-app/target directory.

Deploying to a CICS Liberty JVM server

Ensure you have the following features defined in your Liberty server.xml:

• servlet-6.0 (required for Spring Boot 3.x and Jakarta EE 10)

Note: cicsts:security-1.0 is auto-injected when CICS region security is active — no manual configuration required.

A template server.xml is provided here.

CICS Bundle Plugin Deployment (Gradle/Maven)

This is the recommended deployment method as it uses the CICS bundle generated during the build process.

This method uses the cics-bundle-gradle-plugin or cics-bundle-maven-plugin to automatically generate a CICS bundle.

Configure your JVM server name:

Gradle (cics-java-liberty-springboot-transactions-cicsbundle/build.gradle):

cics.jvmserver = 'YOUR_JVMSERVER_NAME'  // e.g., 'DFHWLP'

Maven (cics-java-liberty-springboot-transactions-cicsbundle/pom.xml):

<cics.jvmserver>YOUR_JVMSERVER_NAME</cics.jvmserver>  <!-- e.g., DFHWLP -->

Deploy the bundle:

1. Upload the CICS bundle ZIP file to zFS:

   • Gradle: cics-java-liberty-springboot-transactions-cicsbundle/build/distributions/cics-java-liberty-springboot-transactions-cicsbundle-1.0.0.zip
   • Maven: cics-java-liberty-springboot-transactions-cicsbundle/target/cics-java-liberty-springboot-transactions-cicsbundle-1.0.0.zip

2. Unzip the bundle on zFS

3. Create a CICS BUNDLE resource definition:

   CEDA DEFINE BUNDLE(TXNS) GROUP(MYGROUP) BUNDLEDIR(/path/to/bundle)
   

4. Install the bundle:

   CEDA INSTALL BUNDLE(TXNS) GROUP(MYGROUP)
   

Alternative: Use the CICS deployment API via CMCI to deploy the bundle remotely.

---

CICS Explorer SDK Deployment

This repository includes a pre-configured Eclipse CICS bundle project cics-java-liberty-springboot-transactions-cicsbundle-eclipse that can be used directly with CICS Explorer SDK.

1. Right-click the cics-java-liberty-springboot-transactions-cicsbundle-eclipse project → Export Bundle Project to z/OS UNIX File System and follow the wizard

Note: The bundle project is pre-configured so that the Eclipse WTP export automatically packages the application WAR with all dependencies. This relies on the -app project being open in the same Eclipse workspace. If you have not yet imported the project, follow step 5 of the Importing into Eclipse instructions first.

---

Direct Liberty Application Deployment

1. Manually upload the WAR file to zFS
2. Add an <application> element to the Liberty server.xml to define the web application with access to all authenticated users. For example:

<application id="cics-java-liberty-springboot-transactions"
    location="${server.config.dir}/springapps/cics-java-liberty-springboot-transactions.war"
    name="cics-java-liberty-springboot-transactions" type="war">
    <application-bnd>
        <security-role name="cicsAllAuthenticated">
            <special-subject type="ALL_AUTHENTICATED_USERS"/>
        </security-role>
    </application-bnd>
</application>

---

Running the Sample

1. Ensure the web application started successfully in Liberty by checking for msg CWWKT0016I in the Liberty messages.log:

   CWWKT0016I: Web application available (default_host): http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-transactions
   

2. Visit the root URL from a browser to review the usage guide:

   http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-transactions/
   

   Note: The trailing / is required to display the Usage Guide.

3. To demonstrate the @Transactional container managed transaction, drive the /transactionalCommit end-point. You should see hello CICS from transactionalCommit() at the browser and a corresponding entry in the TSQ 'EXAMPLE'. You can browse the contents of the TSQ using the CEBR transaction in CICS.

4. Now try the same TSQ write operation /transactionalRollback. This time the application is designed to write to the TSQ then throw an exception causing Spring Boot to rollback the transaction. If you have not installed a TSMODEL resource to make the EXAMPLE TSQ recoverable, you will see a second entry in the TSQ! If you have already made the TSQ recoverable then there should be no such entry due to rollback of the CICS UOW.

5. Next, try the Spring Transaction Template and Java EE User Transaction demos at /STcommit and /JEEcommit respectively. Along with their rollback counterparts /STrollback and /JEErollback.

6. For confirmation of the behaviour, you can run the sample before your TSQ is designated as recoverable (through a TSMODEL) and again afterwards. Observe how the entries to the TSQ are either committed, or written - then rolled back.

Troubleshooting

Rollback does not remove the TSQ entry

• The EXAMPLE TSQ must be defined as recoverable via a CICS TSMODEL resource with Recovery(ON). Without this, CICS cannot roll back writes to the TSQ and the entry persists even after a transaction rollback.
• Define the TSMODEL and reinstall it, then retry the rollback endpoints.

Application fails to start — CWWKZ0013E or SRVE0190E

• Verify servlet-6.0 is enabled in your Liberty server.xml.
• Confirm CICS TS V6.1 or later is installed — earlier releases do not support Jakarta EE 10.

Spring Boot context fails to initialise — ClassNotFoundException for jakarta.*

• This sample uses jakarta.* namespace (Spring Boot 3.x / Jakarta EE 10). Ensure you are not using a CICS TS release older than V6.1 which uses javax.*.

License

This project is licensed under Eclipse Public License - v 2.0.

Additional Resources

• CICS TS Documentation
• WebSphere Liberty Documentation
• Spring Boot Documentation
• Spring Boot Java applications for CICS, Part 3: Transactions
• Spring Transaction Management

Contributing

This sample is maintained by IBM CICS development. We welcome bug reports and feature requests via GitHub Issues. Contributions are welcome and reviewed on a case-by-case basis — please read the contributing guidelines before opening a pull request. For CICS product questions, contact IBM Support.