diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 8acc24e..3d5d708 100644 --- a/.github/workflows/build.yaml +++ b/.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: diff --git a/README.md b/README.md index 0cd36c3..872e90a 100644 --- a/README.md +++ b/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 com.ibm.cics com.ibm.cics.ts.bom - 5.5-20200519131930-PH25409 + 6.1-20250812133513-PH63856 pom import @@ -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 `` 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 - + @@ -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. diff --git a/build.gradle b/build.gradle deleted file mode 100644 index 873f57f..0000000 --- a/build.gradle +++ /dev/null @@ -1,66 +0,0 @@ -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' -archivesBaseName='cics-java-liberty-springboot-jms' -version = '0.1.0' - -// If in Eclipse, add Javadoc to the local project classpath -eclipse -{ - classpath - { - downloadJavadoc = true - } -} - - -repositories -{ - mavenCentral() -} - - -java -{ - toolchain - { - languageVersion = JavaLanguageVersion.of(java_version) - } -} - - -dependencies -{ - implementation("org.springframework.boot:spring-boot-starter-web") - - // Don't include TomCat in the runtime build, but do put it in WEB-INF so it can be run standalone a well as embedded - providedRuntime("org.springframework.boot:spring-boot-starter-tomcat") - - // CICS BOM (as of Sept 2024) - compileOnly enforcedPlatform("com.ibm.cics:com.ibm.cics.ts.bom:6.1-20250812133513-PH63856") - - // Don't include JCICS 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") - -} - - - - diff --git a/cics-java-liberty-springboot-jms-app/build.gradle b/cics-java-liberty-springboot-jms-app/build.gradle new file mode 100644 index 0000000..b6c8684 --- /dev/null +++ b/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") +} + + diff --git a/cics-java-liberty-springboot-jms-app/pom.xml b/cics-java-liberty-springboot-jms-app/pom.xml new file mode 100644 index 0000000..16c907b --- /dev/null +++ b/cics-java-liberty-springboot-jms-app/pom.xml @@ -0,0 +1,92 @@ + + + 4.0.0 + + + + com.ibm.cicsdev + cics-java-liberty-springboot-jms + 1.0.0 + ../pom.xml + + + + cics-java-liberty-springboot-jms-app + com.ibm.cicsdev.springboot.jms.app + Demo project for Spring Boot with CICS JMS - Application + war + + + 17 + UTF-8 + ${java.version} + true + + + + + + + com.ibm.cics + com.ibm.cics.ts.bom + 6.1-20250812133513-PH63856 + pom + import + + + + + + + + com.ibm.cics + com.ibm.cics.server + + + + + org.springframework.boot + spring-boot-starter-web + + + + + org.springframework.boot + spring-boot-starter-tomcat + provided + + + + + jakarta.transaction + jakarta.transaction-api + provided + + + + + org.springframework.integration + spring-integration-jms + + + + + jakarta.jms + jakarta.jms-api + provided + + + + + cics-java-liberty-springboot-jms-app-${project.version} + + + org.springframework.boot + spring-boot-maven-plugin + + + + + + diff --git a/src/main/java/com/ibm/cicsdev/springboot/jms/Application.java b/cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/Application.java similarity index 100% rename from src/main/java/com/ibm/cicsdev/springboot/jms/Application.java rename to cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/Application.java diff --git a/src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageReceiver.java b/cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageReceiver.java similarity index 100% rename from src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageReceiver.java rename to cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageReceiver.java diff --git a/src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageSendController.java b/cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageSendController.java similarity index 100% rename from src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageSendController.java rename to cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/JMSMessageSendController.java diff --git a/src/main/java/com/ibm/cicsdev/springboot/jms/ServletInitializer.java b/cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/ServletInitializer.java similarity index 100% rename from src/main/java/com/ibm/cicsdev/springboot/jms/ServletInitializer.java rename to cics-java-liberty-springboot-jms-app/src/main/java/com/ibm/cicsdev/springboot/jms/ServletInitializer.java diff --git a/src/main/webapp/WEB-INF/web.xml b/cics-java-liberty-springboot-jms-app/src/main/webapp/WEB-INF/web.xml similarity index 100% rename from src/main/webapp/WEB-INF/web.xml rename to cics-java-liberty-springboot-jms-app/src/main/webapp/WEB-INF/web.xml diff --git a/cics-java-liberty-springboot-jms-cicsbundle/build.gradle b/cics-java-liberty-springboot-jms-cicsbundle/build.gradle new file mode 100644 index 0000000..e044f20 --- /dev/null +++ b/cics-java-liberty-springboot-jms-cicsbundle/build.gradle @@ -0,0 +1,34 @@ +// ============================================================================ +// Plugins +// ============================================================================ +plugins +{ + id 'com.ibm.cics.bundle' version '1.0.8' +} + +// ============================================================================ +// Project Information +// ============================================================================ +description = 'CICS Spring Boot JMS Application - CICS Bundle' +version = '1.0.0' + +// ============================================================================ +// Dependencies +// ============================================================================ +dependencies +{ + // Application WAR from sibling project + cicsBundlePart project(path: ':cics-java-liberty-springboot-jms-app', configuration: 'archives') +} + +// ============================================================================ +// CICS Bundle Configuration +// ============================================================================ +cicsBundle +{ + build + { + defaultJVMServer = project.findProperty('cics.jvmserver') ?: 'DFHWLP' + } +} + diff --git a/cics-java-liberty-springboot-jms-cicsbundle/pom.xml b/cics-java-liberty-springboot-jms-cicsbundle/pom.xml new file mode 100644 index 0000000..650c06e --- /dev/null +++ b/cics-java-liberty-springboot-jms-cicsbundle/pom.xml @@ -0,0 +1,56 @@ + + + 4.0.0 + + + + + + com.ibm.cicsdev + cics-java-liberty-springboot-jms + 1.0.0 + ../pom.xml + + + + + + cics-java-liberty-springboot-jms-cicsbundle + cics-bundle + CICS Spring Boot JMS - CICS Bundle + + + + + + + + ${project.groupId} + cics-java-liberty-springboot-jms-app + ${project.version} + war + + + + + + + + + + + com.ibm.cics + cics-bundle-maven-plugin + 1.0.8 + true + + ${cics.jvmserver} + + + + + + + diff --git a/pom.xml b/pom.xml index 4b62c6b..b8f811a 100644 --- a/pom.xml +++ b/pom.xml @@ -1,96 +1,53 @@ - - 4.0.0 - - - - org.springframework.boot - spring-boot-starter-parent - 3.5.9 - - - - com.ibm.cicsdev.springboot - cics-java-liberty-springboot-jms - 0.1.0 - cics-java-liberty-springboot-jms - Demo project for Spring Boot - - 17 - - UTF-8 - ${java.version} - - - - - - - com.ibm.cics - com.ibm.cics.ts.bom - 6.1-20250812133513-PH63856 - pom - import - - - - + + + 4.0.0 + + + + org.springframework.boot + spring-boot-starter-parent + 3.5.9 + + + + + + + com.ibm.cicsdev + cics-java-liberty-springboot-jms + 1.0.0 + Demo project for Spring Boot with CICS JMS + pom + + + 17 + UTF-8 + ${java.version} + DFHWLP + + + + - - - - org.springframework.boot - spring-boot-starter-web - - - - - org.springframework.boot - spring-boot-starter-tomcat - provided - - - - - com.ibm.cics - com.ibm.cics.server - - - - - jakarta.transaction - jakarta.transaction-api - provided - - - - - org.springframework.integration - spring-integration-jms - - - - - jakarta.jms - jakarta.jms-api - provided - - + + + com.ibm.cics + com.ibm.cics.ts.bom + 6.1-20250812133513-PH63856 + pom + import + - - - war - - - - org.springframework.boot - spring-boot-maven-plugin - - - - + + + + + + + cics-java-liberty-springboot-jms-app + cics-java-liberty-springboot-jms-cicsbundle + + diff --git a/settings.gradle b/settings.gradle index 3310199..42accd8 100644 --- a/settings.gradle +++ b/settings.gradle @@ -1 +1,11 @@ +// ============================================================================ +// Root Project Configuration +// ============================================================================ rootProject.name = 'cics-java-liberty-springboot-jms' + +// ============================================================================ +// Subprojects +// ============================================================================ +include(':cics-java-liberty-springboot-jms-app') +include(':cics-java-liberty-springboot-jms-cicsbundle') +