Restructure to multi-module project (app + cicsbundle)

.github/workflows/build.yaml

@@ -15,6 +15,9 @@ jobs:
   check-copyright:
     runs-on: ubuntu-latest
     name: Check Copyright
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:

README.md

@@ -9,11 +9,11 @@ For further details about the development of this sample refer to the IBM develo
 
 ## Prerequisites
 
-- CICS TS V5.3 or later
-- A configured Liberty JVM server 
-- Java SE 1.8 or later on the workstation
+- CICS TS V5.5 or later
+- A configured Liberty JVM server
+- Java SE 17 or later on the workstation
 - An Eclipse development environment on the workstation (optional)
-- Either Gradle or Apache Maven on the workstation
+- Either Gradle or Apache Maven on the workstation (optional if using Wrappers)
 - IBM MQ V8.0 or later on z/OS
 - IBM MQ Resource Adapter for the WebSphere Application Server Liberty available from https://www.ibm.com/support/pages/node/489235
 
@@ -26,23 +26,23 @@ For further details about the development of this sample refer to the IBM develo
 
 ### 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 V5.5 with JCICS APAR PH25409, 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. 
+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](https://mvnrepository.com/artifact/com.ibm.cics/com.ibm.cics.ts.bom).
+You can browse the published versions of the CICS BOM at [Maven Central.](https://mvnrepository.com/artifact/com.ibm.cics/com.ibm.cics.ts.bom)
 
-Gradle (build.gradle): 
+Gradle (cics-java-liberty-springboot-jms-app/build.gradle):
 
-`compileOnly enforcedPlatform("com.ibm.cics:com.ibm.cics.ts.bom:5.5-20200519131930-PH25409")`
+`compileOnly enforcedPlatform("com.ibm.cics:com.ibm.cics.ts.bom:6.1-20250812133513-PH63856")`
 
-Maven (POM.xml):
+Maven (cics-java-liberty-springboot-jms-app/pom.xml):
 
-``` xml	
+``` xml
 <dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.ibm.cics</groupId>
       <artifactId>com.ibm.cics.ts.bom</artifactId>
-      <version>5.5-20200519131930-PH25409</version>
+      <version>6.1-20250812133513-PH63856</version>
       <type>pom</type>
       <scope>import</scope>
     </dependency>
@@ -54,21 +54,21 @@ Maven (POM.xml):
 
 The JMSMessageReceiver.java class assumes an MQ destination of `SPRING.QUEUE`. If that value does not meet your enterprise naming standards, this can be updated by modifying the static variable `MDP_QUEUE`.
 
-## Building 
+## Building
 
-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. 
+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 typically `clean bootWar` for Gradle and `clean package` for Maven. Once run, Gradle will generate a WAR file in the `build/libs` directory, while Maven will generate it in the `target` directory.
+The required build-tasks are typically `clean build` for Gradle and `clean verify` for Maven. Once run, Gradle will generate a WAR file in the `cics-java-liberty-springboot-jms-app/build/libs` directory, while Maven will generate it in the `cics-java-liberty-springboot-jms-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.
 
 **Note:** If you import the project to your IDE, you might experience local project compile errors. To resolve these errors you should run a tooling refresh on that project. For example, in Eclipse: right-click on "Project", select "Gradle -> Refresh Gradle Project", **or** right-click on "Project", select "Maven -> Update Project...".
 
->Tip: *In Eclipse, Gradle (buildship) is able to fully refresh and resolve the local classpath even if the project was previously updated by Maven. However, Maven (m2e) does not currently reciprocate that capability. If you previously refreshed the project with Gradle, you'll need to manually remove the 'Project Dependencies' entry on the Java build-path of your Project Properties to avoid duplication errors when performing a Maven Project Update.* 
+>Tip: *In Eclipse, Gradle (buildship) is able to fully refresh and resolve the local classpath even if the project was previously updated by Maven. However, Maven (m2e) does not currently reciprocate that capability. If you previously refreshed the project with Gradle, you'll need to manually remove the 'Project Dependencies' entry on the Java build-path of your Project Properties to avoid duplication errors when performing a Maven Project Update.*
 
 #### Gradle Wrapper (command line)
 
@@ -77,15 +77,15 @@ Run the following in a local command prompt:
 On Linux or Mac:
 
 ```shell
-./gradlew clean bootWar
+./gradlew clean build
 ```
 On Windows:
 
 ```shell
-gradlew.bat clean bootWar
+gradlew.bat clean build
 ```
 
-This creates a WAR file inside the `build/libs` directory.
+This creates a WAR file inside the `cics-java-liberty-springboot-jms-app/build/libs` directory.
 
 #### Maven Wrapper (command line)
 
@@ -94,16 +94,16 @@ Run the following in a local command prompt:
 On Linux or Mac:
 
 ```shell
-./mvnw clean package
+./mvnw clean verify
 ```
 
 On Windows:
 
 ```shell
-mvnw.cmd clean package
+mvnw.cmd clean verify
 ```
 
-This creates a WAR file inside the `target` directory.
+This creates a WAR file inside the `cics-java-liberty-springboot-jms-app/target` directory.
 
 ## Deploying
 
@@ -118,15 +118,15 @@ In addition it is advisable to set the `BackoutThreshold` attribute on the queue
 
 ### CICS Liberty
 
-- Ensure you have the following features in `server.xml`: 
-    - `servlet-3.1` or `servlet-4.0` depending on the version of Java EE in use.
-    - `concurrent-1.0`.
-    - `jms-2.0`.
+- Ensure you have the following features in `server.xml`:
+    - `servlet-6.0` for Jakarta EE 10.
+    - `concurrent-3.0`.
+    - `messaging-3.1`.
     - `wmqJmsClient-2.0`.
     - `jndi-1.0`.
-    - `cicsts:security-1.0` if CICS security is enabled. 
+    - `cicsts:security-1.0` if CICS security is enabled.
 
->**Note:** `servlet-4.0` will only work for CICS TS V5.5 or later
+>**Note:** This sample uses Spring Boot 3.x which requires Jakarta EE 10 and Java 17 or later
 
 - Add the JMS MQ Connection Factory configuration to `server.xml`
 
@@ -145,15 +145,15 @@ In addition it is advisable to set the `BackoutThreshold` attribute on the queue
 The value of 10 on `maxPoolSize` is used as an example only. Set `maxPoolSize` to the maximum number of concurrent users of the connection factory.
 
 - Deployment option 1:
-    - Copy and paste the built WAR from your *target* or *build/libs* directory into a Eclipse CICS bundle project and create a new WAR bundlepart that references the WAR file. Then deploy the CICS bundle project from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard.
+    - Copy and paste the built WAR from your *cics-java-liberty-springboot-jms-app/target* or *cics-java-liberty-springboot-jms-app/build/libs* directory into a Eclipse CICS bundle project and create a new WAR bundlepart that references the WAR file. Then deploy the CICS bundle project from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard.
 
 - Deployment option 2:
     - Manually upload the WAR file to zFS and add an `<application>` element to the Liberty server.xml to define the web application with access to all authenticated users. For example the following application element can be used to install a WAR, and grant access to all authenticated users if security is enabled.
 
     ``` XML
-    <application id="cics-java-liberty-springboot-jms-0.1.0"
-        location="${server.config.dir}/springapps/cics-java-liberty-springboot-jms-0.1.0.war"
-        name="cics-java-liberty-springboot-jms-0.1.0" type="war">
+    <application id="cics-java-liberty-springboot-jms-app-1.0.0"
+        location="${server.config.dir}/springapps/cics-java-liberty-springboot-jms-app-1.0.0.war"
+        name="cics-java-liberty-springboot-jms-app-1.0.0" type="war">
         <application-bnd>
             <security-role name="cicsAllAuthenticated">
                 <special-subject type="ALL_AUTHENTICATED_USERS"/>
@@ -166,10 +166,10 @@ The value of 10 on `maxPoolSize` is used as an example only. Set `maxPoolSize` t
 
 1. Ensure the web application started successfully in Liberty by checking for msg `CWWKT0016I` in the Liberty messages.log:
 
-    - `A CWWKT0016I: Web application available (default_host): http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jms-0.1.0`
-    - `I SRVE0292I: Servlet Message - [com.ibm.cicsdev.springboot.jms-0.1.0]:.Initializing Spring embedded WebApplicationContext`
+    - `A CWWKT0016I: Web application available (default_host): http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jms-app-1.0.0`
+    - `I SRVE0292I: Servlet Message - [cics-java-liberty-springboot-jms-app-1.0.0]:.Initializing Spring embedded WebApplicationContext`
 
-2. Copy the context root from message CWWKT0016I along with the REST service suffix `send/SPRING.QUEUE?data=I LOVE CICS` into you web browser. e.g. `http://myzos.mycompany.com:httpPort/com.ibm.cicsdev.springboot.jms-0.1.0/send/SPRING.QUEUE?data=I LOVE CICS`.
+2. Copy the context root from message CWWKT0016I along with the REST service suffix `send/SPRING.QUEUE?data=I LOVE CICS` into you web browser. e.g. `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jms-app-1.0.0/send/SPRING.QUEUE?data=I LOVE CICS`.
 
 3. Check if the specified TSQ has the information you expected by executing the CICS 3270 command `CEBR SPRINGQ`. For this example, you should just see one `I LOVE CICS` in TSQ SPRINGQ. 
 

cics-java-liberty-springboot-jms-app/build.gradle

@@ -0,0 +1,76 @@
+plugins
+{
+	id 'org.springframework.boot' version '3.5.9'
+	id 'io.spring.dependency-management' version '1.1.7'
+	id 'java'
+	id 'eclipse'
+	id 'idea'
+	id 'war'
+}
+
+group = 'com.ibm.cicsdev.springboot'
+version = '1.0.0'
+
+// ============================================================================
+// Java Configuration
+// ============================================================================
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(java_version)
+    }
+}
+
+// ============================================================================
+// WAR Configuration
+// ============================================================================
+war
+{
+    archiveFileName = "cics-java-liberty-springboot-jms-app-${version}.war"
+}
+
+// Two versions of the WAR would be built, one for embedding into servers like Liberty (plain)
+// and a bootWAR which can run standalone and contains all the Tomcat and Spring Boot stuff
+// we don't need bootWAR, so disable it.
+bootWar { enabled = false }
+
+// If in Eclipse, add Javadoc to the local project classpath
+eclipse
+{
+    classpath
+    {
+        downloadJavadoc = true
+    }
+}
+
+repositories 
+{
+    mavenCentral()
+}
+
+dependencies
+{
+    // Spring Boot web starter dependency
+    implementation("org.springframework.boot:spring-boot-starter-web")
+
+    // Don't include TomCat in the runtime build, but put it in lib-provided so it can run standalone as well as embedded
+    providedRuntime("org.springframework.boot:spring-boot-starter-tomcat")
+
+	// CICS TS V6.1 Maven BOM (as of Sept 2024)
+	def bom = "com.ibm.cics:com.ibm.cics.ts.bom:6.1-20250812133513-PH63856"
+
+    compileOnly enforcedPlatform(bom)
+
+    // Don't include JCICS components in the final build (no need for version because we have BOM)  
+    compileOnly("com.ibm.cics:com.ibm.cics.server")
+
+    // Jakarta EE JTA transaction management
+    compileOnly("jakarta.transaction:jakarta.transaction-api")
+
+    // Jakarta EE JMS API
+    compileOnly("jakarta.jms:jakarta.jms-api")
+
+    // Spring Integration JMS Support
+    implementation("org.springframework.integration:spring-integration-jms")
+}
+
+