From a0656c43f5460b54a5c8cb939ecd0a90776c1faf Mon Sep 17 00:00:00 2001 From: Ivan Hargreaves Date: Thu, 25 Jun 2026 17:04:22 +0100 Subject: [PATCH 1/6] Improve Eclipse import and build experience - Move CICS bundle project to root level for automatic nested project import - Add Gradle toolchain auto-provisioning for Java 8 - Pre-configure CICS TS V5.5 library in Eclipse classpath - Update README with comprehensive Eclipse import instructions - Add toolchain resolver plugin to settings.gradle for JDK auto-download These changes ensure the project compiles immediately after import in Eclipse while maintaining full compatibility with Gradle and Maven builds. --- .project | 2 +- .settings/org.eclipse.core.resources.prefs | 2 + README.md | 50 +++++++++++++++---- cics-java-liberty-restapp-app/.classpath | 5 ++ .../.project | 2 +- .../org.eclipse.core.resources.prefs | 1 + .../META-INF/cics.xml | 2 +- .../cics-java-liberty-restapp-app.warbundle | 0 gradle.properties | 5 ++ settings.gradle | 8 +++ 10 files changed, 64 insertions(+), 13 deletions(-) create mode 100644 .settings/org.eclipse.core.resources.prefs rename {etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle => com.ibm.cicsdev.wlp.restapp.cicsbundle}/.project (91%) rename {etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle => com.ibm.cicsdev.wlp.restapp.cicsbundle}/.settings/org.eclipse.core.resources.prefs (53%) rename {etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle => com.ibm.cicsdev.wlp.restapp.cicsbundle}/META-INF/cics.xml (74%) rename {etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle => com.ibm.cicsdev.wlp.restapp.cicsbundle}/cics-java-liberty-restapp-app.warbundle (100%) diff --git a/.project b/.project index 29e3d33..1182948 100644 --- a/.project +++ b/.project @@ -27,7 +27,7 @@ - org.eclipse.m2e.core.maven2Nature + org.eclipse.m2e.core.maven2Nature org.eclipse.wst.common.project.facet.core.nature org.eclipse.wst.common.modulecore.ModuleCoreNature org.eclipse.jem.workbench.JavaEMFNature diff --git a/.settings/org.eclipse.core.resources.prefs b/.settings/org.eclipse.core.resources.prefs new file mode 100644 index 0000000..99f26c0 --- /dev/null +++ b/.settings/org.eclipse.core.resources.prefs @@ -0,0 +1,2 @@ +eclipse.preferences.version=1 +encoding/=UTF-8 diff --git a/README.md b/README.md index ff26dc8..0a1844f 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The following Java source components are supplied in the [`cics-java-liberty-res - [cics-java-liberty-restapp-app](./cics-java-liberty-restapp-app) - Application source code. - [cics-java-liberty-restapp-bundle](./cics-java-liberty-restapp-bundle) - CICS bundle plug-in based project. Use with Gradle and Maven builds. -- [etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle](./etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle) - CICS Explorer based CICS bundle project, contains Web application bundle-part. Use with Eclipse and CICS Explorer. +- [com.ibm.cicsdev.wlp.restapp.cicsbundle](./com.ibm.cicsdev.wlp.restapp.cicsbundle) - CICS Explorer based CICS bundle project, contains Web application bundle-part. Use with Eclipse and CICS Explorer. ## Prerequisites @@ -107,19 +107,49 @@ mvnw.cmd clean verify ### Option 2: Building with Eclipse +#### Importing the Project +To import the sample into Eclipse: +1. Clone the repository using your IDE's support, such as the Eclipse Git plugin, **or** +2. Download the zip archive and use the **File > Import > Existing Projects into Workspace** wizard and select the expanded zip archive directory as the root directory -To import the sample into Eclipse either -1. Clone the repository using your IDEs support, such as the Eclipse Git plugin,**or** -2. Download the zip archive and use the **File > Import > Existing Projects into Workspace** wizard and select the expanded zip archive directory as the root directory. -Ensure you check "Search for nested projects", and do not select **Copy projects into workspace** +**Important:** Ensure you check "Search for nested projects", and do not select **Copy projects into workspace** -The sample comes pre-configured for use with a JDK 1.8 and CICS TS V5.5 Libraries for Java EE & Jakarta EE 8. When you initially import the project into your IDE, if your IDE is not configured for Java 17, or does not have CICS Explorer SDK installed with the correct Target Platform set, you might experience local project compile errors. +#### Resolving Dependencies -To resolve build issues: +The sample comes pre-configured with the CICS TS V5.5 with Java EE and Liberty 8 library in the Eclipse classpath. This means the project should compile immediately after import if you have the CICS Explorer SDK installed. -- Ensure you have the latest CICS Explorer SDK plug-in installed -- Configure the cics-java-liberty-restapp-app project's build-path, and Application Project settings to use your preferred combination of CICS TS, JDK, and Liberty's Enterprise Java libraries (Java EE or Jakarta EE). Select **Java Build Path**, on the **Libraries** tab select **Classpath**, click **Add Library**, select **CICS with Enterprise Java and Liberty** Library, and choose the appropriate CICS and Enterprise Java versions. +However, if you see compilation errors, or if you want to use Gradle or Maven for dependency management instead of the pre-configured CICS library, you have several options: + +**Option 2a: Using Build Tool Integration** + +If you have Gradle (Buildship) or Maven (m2e) integration installed in Eclipse, you can use the build tool to automatically resolve dependencies: + +**For Gradle:** +1. Right-click on `cics-java-liberty-restapp` → **Run As** → **Gradle Build...** +2. In the dialog, enter `clean build` in the "Gradle Tasks" field +3. Click **Run** - this will download Java 8 (if needed via toolchain auto-provisioning) and resolve all dependencies +4. Once the build succeeds, right-click on `cics-java-liberty-restapp` → **Gradle** → **Refresh Gradle Project** +5. Clean and rebuild: **Project** → **Clean** → Select all projects → **Clean** + +**For Maven:** +1. Right-click on `cics-java-liberty-restapp` → **Maven** → **Update Project** → Check "Force Update of Snapshots/Releases" +2. Clean and rebuild: **Project** → **Clean** → Select all projects → **Clean** + +The build tool will automatically download and configure all required dependencies (CICS libraries, JAX-RS, JAXB, etc.) and update Eclipse's classpath. + +**Note:** For Gradle projects, the initial "Run As → Gradle Build" step is required to trigger toolchain auto-provisioning if Java 8 is not installed. After a successful build, "Gradle → Refresh Gradle Project" will synchronize the Eclipse classpath with the resolved dependencies. + +**Option 2b: Verifying Pre-Configured CICS Library (Default)** + +The project is already configured with the CICS library. If you see errors: + +1. Ensure you have the latest CICS Explorer SDK plug-in installed +2. Verify the CICS library is present: Right-click on `cics-java-liberty-restapp-app` → **Build Path** → **Configure Build Path** → **Libraries** tab +3. If the CICS library shows an error or is missing, remove it and re-add: Click **Add Library** → **CICS with Enterprise Java and Liberty** → Select **CICS TS V5.5 with Java EE and Liberty 8** +4. Clean and rebuild: **Project** → **Clean** → Select all projects → **Clean** + +**Note:** The pre-configured CICS library (Option 2b) provides the fastest setup for Eclipse users. Gradle/Maven integration (Option 2a) is useful if you want to use the same dependency management approach across different IDEs or build environments. @@ -148,7 +178,7 @@ The sample Java classes are designed to be built into a an WAR file and deployed #### Option 2 - Deploying using CICS Explorer SDK and the CICS bundle projects -1. Deploy the CICS bundle project `com.ibm.cicsdev.wlp.restapp.cicsbundle` from CICS Explorer to zFS using the **Export Bundle Project to z/OS UNIX File System** wizard. The samples use the sub-directory `com.ibm.cicsdev.restapp.cicsbundle_1.0.0`. +1. Deploy the CICS bundle project `com.ibm.cicsdev.wlp.restapp.cicsbundle` from CICS Explorer to zFS using the **Export Bundle Project to z/OS UNIX File System** wizard. The samples use the sub-directory `com.ibm.cicsdev.restapp.cicsbundle_1.0.0`. ### Installing into CICS diff --git a/cics-java-liberty-restapp-app/.classpath b/cics-java-liberty-restapp-app/.classpath index 82220ad..136e74a 100644 --- a/cics-java-liberty-restapp-app/.classpath +++ b/cics-java-liberty-restapp-app/.classpath @@ -8,6 +8,11 @@ + + + + + diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project b/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project similarity index 91% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project rename to com.ibm.cicsdev.wlp.restapp.cicsbundle/.project index 04b3722..55dff9f 100644 --- a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project +++ b/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project @@ -10,7 +10,7 @@ bundleID - com.ibm.cics.server.examples.wlp.link.bundle + com.ibm.cicsdev.wlp.restapp.cicsbundle majorVersion diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs b/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs similarity index 53% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs rename to com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs index 8ddaf77..a0137e2 100644 --- a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs +++ b/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs @@ -1,2 +1,3 @@ eclipse.preferences.version=1 encoding//META-INF/cics.xml=UTF-8 +encoding/cics-java-liberty-restapp-app.warbundle=UTF-8 diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml b/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml similarity index 74% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml rename to com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml index 0983976..1c1654b 100644 --- a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml +++ b/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml @@ -1,5 +1,5 @@ - + 2025-09-02T15:13:21.573Z diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle b/com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle similarity index 100% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle rename to com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle diff --git a/gradle.properties b/gradle.properties index 458c344..f0cb1ff 100644 --- a/gradle.properties +++ b/gradle.properties @@ -6,5 +6,10 @@ org.gradle.daemon=true # Enable parallel builds for faster compilation org.gradle.parallel=true +# Enable toolchain auto-provisioning to download JDKs if not found locally +# This allows builds to work even if Java 8 isn't installed on the system +org.gradle.java.installations.auto-detect=true +org.gradle.java.installations.auto-download=true + # Configuration cache disabled - CICS Bundle Plugin 1.0.8 not compatible # org.gradle.configuration-cache=true diff --git a/settings.gradle b/settings.gradle index 48bf055..b032d5a 100644 --- a/settings.gradle +++ b/settings.gradle @@ -1,3 +1,11 @@ +// ============================================================================ +// Toolchain Configuration +// ============================================================================ +// Configure toolchain resolver for auto-provisioning of JDKs +plugins { + id 'org.gradle.toolchains.foojay-resolver-convention' version '0.8.0' +} + // ============================================================================ // Root Project Configuration // ============================================================================ From 9c5a6f83f7d53e983c06284bfdaa26af80bacbb4 Mon Sep 17 00:00:00 2001 From: Ivan Hargreaves Date: Thu, 25 Jun 2026 17:26:40 +0100 Subject: [PATCH 2/6] Standardize project naming conventions - Rename cics-java-liberty-restapp-bundle to cics-java-liberty-restapp-cicsbundle (Gradle/Maven) - Rename com.ibm.cicsdev.wlp.restapp.cicsbundle to cics-java-liberty-restapp-cicsbundle-eclipse (Eclipse) - Update all references in pom.xml, settings.gradle, and README.md - Aligns with standard naming pattern used in Spring Boot samples This ensures consistent naming across all CICS samples where: - -cicsbundle = CICS bundle plugin project (Gradle/Maven) - -cicsbundle-eclipse = Eclipse CICS bundle project --- README.md | 6 +++--- cics-java-liberty-restapp-app/.classpath | 5 ----- .../.project | 4 ++-- .../.settings/org.eclipse.core.resources.prefs | 0 .../META-INF/cics.xml | 0 .../cics-java-liberty-restapp-app.warbundle | 0 .../.project | 2 +- .../.settings/org.eclipse.buildship.core.prefs | 0 .../build.gradle | 0 .../pom.xml | 2 +- pom.xml | 2 +- settings.gradle | 2 +- 12 files changed, 9 insertions(+), 14 deletions(-) rename {com.ibm.cicsdev.wlp.restapp.cicsbundle => cics-java-liberty-restapp-cicsbundle-eclipse}/.project (84%) rename {com.ibm.cicsdev.wlp.restapp.cicsbundle => cics-java-liberty-restapp-cicsbundle-eclipse}/.settings/org.eclipse.core.resources.prefs (100%) rename {com.ibm.cicsdev.wlp.restapp.cicsbundle => cics-java-liberty-restapp-cicsbundle-eclipse}/META-INF/cics.xml (100%) rename {com.ibm.cicsdev.wlp.restapp.cicsbundle => cics-java-liberty-restapp-cicsbundle-eclipse}/cics-java-liberty-restapp-app.warbundle (100%) rename {cics-java-liberty-restapp-bundle => cics-java-liberty-restapp-cicsbundle}/.project (91%) rename {cics-java-liberty-restapp-bundle => cics-java-liberty-restapp-cicsbundle}/.settings/org.eclipse.buildship.core.prefs (100%) rename {cics-java-liberty-restapp-bundle => cics-java-liberty-restapp-cicsbundle}/build.gradle (100%) rename {cics-java-liberty-restapp-bundle => cics-java-liberty-restapp-cicsbundle}/pom.xml (95%) diff --git a/README.md b/README.md index 0a1844f..aed2901 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,8 @@ The following Java source components are supplied in the [`cics-java-liberty-res ## Contents - [cics-java-liberty-restapp-app](./cics-java-liberty-restapp-app) - Application source code. -- [cics-java-liberty-restapp-bundle](./cics-java-liberty-restapp-bundle) - CICS bundle plug-in based project. Use with Gradle and Maven builds. -- [com.ibm.cicsdev.wlp.restapp.cicsbundle](./com.ibm.cicsdev.wlp.restapp.cicsbundle) - CICS Explorer based CICS bundle project, contains Web application bundle-part. Use with Eclipse and CICS Explorer. +- [cics-java-liberty-restapp-cicsbundle](./cics-java-liberty-restapp-cicsbundle) - CICS bundle plug-in based project. Use with Gradle and Maven builds. +- [cics-java-liberty-restapp-cicsbundle-eclipse](./cics-java-liberty-restapp-cicsbundle-eclipse) - CICS Explorer based CICS bundle project, contains Web application bundle-part. Use with Eclipse and CICS Explorer. ## Prerequisites @@ -178,7 +178,7 @@ The sample Java classes are designed to be built into a an WAR file and deployed #### Option 2 - Deploying using CICS Explorer SDK and the CICS bundle projects -1. Deploy the CICS bundle project `com.ibm.cicsdev.wlp.restapp.cicsbundle` from CICS Explorer to zFS using the **Export Bundle Project to z/OS UNIX File System** wizard. The samples use the sub-directory `com.ibm.cicsdev.restapp.cicsbundle_1.0.0`. +1. Deploy the CICS bundle project `cics-java-liberty-restapp-cicsbundle-eclipse` from CICS Explorer to zFS using the **Export Bundle Project to z/OS UNIX File System** wizard. The samples use the sub-directory `cics-java-liberty-restapp-cicsbundle-eclipse_1.0.0`. ### Installing into CICS diff --git a/cics-java-liberty-restapp-app/.classpath b/cics-java-liberty-restapp-app/.classpath index 136e74a..82220ad 100644 --- a/cics-java-liberty-restapp-app/.classpath +++ b/cics-java-liberty-restapp-app/.classpath @@ -8,11 +8,6 @@ - - - - - diff --git a/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project b/cics-java-liberty-restapp-cicsbundle-eclipse/.project similarity index 84% rename from com.ibm.cicsdev.wlp.restapp.cicsbundle/.project rename to cics-java-liberty-restapp-cicsbundle-eclipse/.project index 55dff9f..ae3bd9d 100644 --- a/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project +++ b/cics-java-liberty-restapp-cicsbundle-eclipse/.project @@ -1,6 +1,6 @@ - com.ibm.cicsdev.wlp.restapp.cicsbundle + cics-java-liberty-restapp-cicsbundle-eclipse @@ -10,7 +10,7 @@ bundleID - com.ibm.cicsdev.wlp.restapp.cicsbundle + cics-java-liberty-restapp-cicsbundle-eclipse majorVersion diff --git a/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs b/cics-java-liberty-restapp-cicsbundle-eclipse/.settings/org.eclipse.core.resources.prefs similarity index 100% rename from com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs rename to cics-java-liberty-restapp-cicsbundle-eclipse/.settings/org.eclipse.core.resources.prefs diff --git a/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml b/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml similarity index 100% rename from com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml rename to cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml diff --git a/com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle b/cics-java-liberty-restapp-cicsbundle-eclipse/cics-java-liberty-restapp-app.warbundle similarity index 100% rename from com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle rename to cics-java-liberty-restapp-cicsbundle-eclipse/cics-java-liberty-restapp-app.warbundle diff --git a/cics-java-liberty-restapp-bundle/.project b/cics-java-liberty-restapp-cicsbundle/.project similarity index 91% rename from cics-java-liberty-restapp-bundle/.project rename to cics-java-liberty-restapp-cicsbundle/.project index 8580d80..e140315 100644 --- a/cics-java-liberty-restapp-bundle/.project +++ b/cics-java-liberty-restapp-cicsbundle/.project @@ -1,6 +1,6 @@ - cics-java-liberty-restapp-bundle + cics-java-liberty-restapp-cicsbundle diff --git a/cics-java-liberty-restapp-bundle/.settings/org.eclipse.buildship.core.prefs b/cics-java-liberty-restapp-cicsbundle/.settings/org.eclipse.buildship.core.prefs similarity index 100% rename from cics-java-liberty-restapp-bundle/.settings/org.eclipse.buildship.core.prefs rename to cics-java-liberty-restapp-cicsbundle/.settings/org.eclipse.buildship.core.prefs diff --git a/cics-java-liberty-restapp-bundle/build.gradle b/cics-java-liberty-restapp-cicsbundle/build.gradle similarity index 100% rename from cics-java-liberty-restapp-bundle/build.gradle rename to cics-java-liberty-restapp-cicsbundle/build.gradle diff --git a/cics-java-liberty-restapp-bundle/pom.xml b/cics-java-liberty-restapp-cicsbundle/pom.xml similarity index 95% rename from cics-java-liberty-restapp-bundle/pom.xml rename to cics-java-liberty-restapp-cicsbundle/pom.xml index 2b5095e..a934188 100644 --- a/cics-java-liberty-restapp-bundle/pom.xml +++ b/cics-java-liberty-restapp-cicsbundle/pom.xml @@ -9,7 +9,7 @@ 1.0.0 - cics-java-liberty-restapp-bundle + cics-java-liberty-restapp-cicsbundle CICS Enterprise Java Program - CICS Bundle cics-bundle diff --git a/pom.xml b/pom.xml index 87474ed..9c62eda 100644 --- a/pom.xml +++ b/pom.xml @@ -42,7 +42,7 @@ cics-java-liberty-restapp-app - cics-java-liberty-restapp-bundle + cics-java-liberty-restapp-cicsbundle diff --git a/settings.gradle b/settings.gradle index b032d5a..b0ab577 100644 --- a/settings.gradle +++ b/settings.gradle @@ -15,4 +15,4 @@ rootProject.name = 'cics-java-liberty-restapp' // Subprojects // ============================================================================ include(':cics-java-liberty-restapp-app') -include(':cics-java-liberty-restapp-bundle') \ No newline at end of file +include(':cics-java-liberty-restapp-cicsbundle') \ No newline at end of file From 04553f2d77f733e688776a80be26f0e507e5a6b7 Mon Sep 17 00:00:00 2001 From: Ivan Hargreaves Date: Thu, 25 Jun 2026 20:07:55 +0100 Subject: [PATCH 3/6] Update Eclipse CICS bundle ID to match renamed project - Changed bundle ID from com.ibm.cicsdev.wlp.restapp.cicsbundle to cics-java-liberty-restapp-cicsbundle-eclipse - Aligns with project naming standardization --- cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml b/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml index 1c1654b..45b339f 100644 --- a/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml +++ b/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml @@ -1,5 +1,5 @@ - + 2025-09-02T15:13:21.573Z From a4fb7d9468ae41e65fec0a3f597e71bbb7a2d497 Mon Sep 17 00:00:00 2001 From: Ivan Hargreaves Date: Tue, 7 Jul 2026 12:43:08 +0100 Subject: [PATCH 4/6] Apply Agents.md validation fixes - C-2: Maven compiler plugin uses parameter, remove deprecated source/target - C-3: Upgrade CICS Bundle Plugin to 1.0.8 in all build files - C-4: Add job-level permissions to check-copyright CI job - C-5: Fix Eclipse bundle ID and cics.xml id to cics-java-liberty-restapp-bundle - H-1: Add root .classpath - H-2: Add root .settings/org.eclipse.jdt.core.prefs - H-3: Add CICS Liberty Libraries and Maven container to -app/.classpath - H-4: Rewrite README to follow standard template - H-6: Add -cicsbundle/.settings/org.eclipse.core.resources.prefs - M-1: Update MAINTAINERS.md review date to July 2026 - M-2: Update cleanup workflow keep_minimum_runs to 6 - M-3: Remove non-standard bundle-war goal from -app/pom.xml - M-4: Replace deprecated archivesBaseName with war { archiveFileName } - M-5: Fix Gradle group to com.ibm.cicsdev - Remove noise from root .project --- .classpath | 9 + .github/workflows/build.yaml | 3 + .github/workflows/cleanup-old-runs.yml | 2 +- .project | 11 - .settings/org.eclipse.jdt.core.prefs | 8 + README.md | 243 ++++++++---------- cics-java-liberty-restapp-app/.classpath | 11 + cics-java-liberty-restapp-app/build.gradle | 12 +- cics-java-liberty-restapp-app/pom.xml | 49 +--- .../.project | 2 +- .../META-INF/cics.xml | 2 +- .../org.eclipse.core.resources.prefs | 2 + .../build.gradle | 2 +- cics-java-liberty-restapp-cicsbundle/pom.xml | 2 +- pom.xml | 7 +- 15 files changed, 172 insertions(+), 193 deletions(-) create mode 100644 .classpath create mode 100644 .settings/org.eclipse.jdt.core.prefs create mode 100644 cics-java-liberty-restapp-cicsbundle/.settings/org.eclipse.core.resources.prefs diff --git a/.classpath b/.classpath new file mode 100644 index 0000000..1fc8451 --- /dev/null +++ b/.classpath @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index a3a587d..4eab723 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/.github/workflows/cleanup-old-runs.yml b/.github/workflows/cleanup-old-runs.yml index 0fb2cd5..8847b2c 100644 --- a/.github/workflows/cleanup-old-runs.yml +++ b/.github/workflows/cleanup-old-runs.yml @@ -19,6 +19,6 @@ jobs: token: ${{ github.token }} repository: ${{ github.repository }} retain_days: 30 - keep_minimum_runs: 3 # Keep at least 3 recent runs of each workflow + keep_minimum_runs: 6 # Keep at least 6 recent runs of each workflow # Made with Bob diff --git a/.project b/.project index 1182948..0fe233f 100644 --- a/.project +++ b/.project @@ -33,15 +33,4 @@ org.eclipse.jem.workbench.JavaEMFNature org.eclipse.buildship.core.gradleprojectnature - - - 1756823436255 - - 30 - - org.eclipse.core.resources.regexFilterMatcher - node_modules|\.git|__CREATED_BY_JAVA_LANGUAGE_SERVER__ - - - diff --git a/.settings/org.eclipse.jdt.core.prefs b/.settings/org.eclipse.jdt.core.prefs new file mode 100644 index 0000000..1d3fc37 --- /dev/null +++ b/.settings/org.eclipse.jdt.core.prefs @@ -0,0 +1,8 @@ +eclipse.preferences.version=1 +org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8 +org.eclipse.jdt.core.compiler.compliance=1.8 +org.eclipse.jdt.core.compiler.problem.assertIdentifier=error +org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures=disabled +org.eclipse.jdt.core.compiler.problem.enumIdentifier=error +org.eclipse.jdt.core.compiler.problem.reportPreviewFeatures=warning +org.eclipse.jdt.core.compiler.source=1.8 diff --git a/README.md b/README.md index aed2901..f0a7636 100644 --- a/README.md +++ b/README.md @@ -5,69 +5,64 @@ ## Overview -Sample RESTful web application for deployment to a Liberty JVM server in CICS. The application is supplied with two resources: +Sample RESTful web application for deployment to a Liberty JVM server in CICS. The application is supplied with two REST resources: -1. `InfoResource` - This queries the JVM server environment using system properties and uses JAXB beans to return a JSON response detailing the CICS environment. -1. `ReverseResource` - This is similar to `InfoResource`, but uses the JCICS API to link to the COBOL program `EDUCHAN` using channels and containers. An input string is passed to `EDUCHAN`, which is then reversed and returned, along with the time from CICS. +**Key Features:** +- `InfoResource` — queries the JVM server environment using system properties and uses JAXB beans to return a JSON response detailing the CICS environment +- `ReverseResource` — uses the JCICS API to link to the COBOL program `EDUCHAN` using channels and containers; an input string is passed to `EDUCHAN`, which is reversed and returned along with the time from CICS -Further extensions to this application are available in the repository [cics-java-liberty-restappext](https://github.com/cicsdev/cics-java-liberty-restappext) which provides several code examples for accessing CICS resources from Java using the JCICS API. +Further extensions to this application are available in [cics-java-liberty-restappext](https://github.com/cicsdev/cics-java-liberty-restappext), which provides additional code examples for accessing CICS resources from Java using the JCICS API. -The following Java source components are supplied in the [`cics-java-liberty-restapp-app/src/main/java`](cics-java-liberty-restapp-app/src/main/java) directory in this repository. - -## Java package com.ibm.cicsdev.restapp -* [`CICSApplication`](src/main/java/com/ibm/cicsdev/restapp/CICSApplication.java) - Sets the `ApplicationPath` for resources in this application -* [`InfoResource`](src/main/java/com/ibm/cicsdev/restapp/InfoResource.java) - Returns JSON structure using `CICSInformation` bean -* [`ReverseResource`](src/main/java/com/ibm/cicsdev/restapp/ReverseResource.java) - Returns JSON structure using `ReverseResult` bean - - -## Java package com.ibm.cicsdev.restapp.bean -* [`CICSEnvironment`](src/main/java/com/ibm/cicsdev/restapp/bean/CICSEnvironment.java) - JAXB bean returning JSON structure containing information about CICS product and version -* [`CICSInformation`](src/main/java/com/ibm/cicsdev/restapp/bean/CICSInformation.java) - JAXB bean returning JSON structure containing CICS applid, time and JVM server name and instance of `CICSEnvironment` -* [`ReverseResult`](src/main/java/com/ibm/cicsdev/restapp/bean/ReverseResult.java) - JAXB bean returning JSON structure containg input and output containers sent to `EDUCHAN` COBOL program - -## Contents - -- [cics-java-liberty-restapp-app](./cics-java-liberty-restapp-app) - Application source code. -- [cics-java-liberty-restapp-cicsbundle](./cics-java-liberty-restapp-cicsbundle) - CICS bundle plug-in based project. Use with Gradle and Maven builds. -- [cics-java-liberty-restapp-cicsbundle-eclipse](./cics-java-liberty-restapp-cicsbundle-eclipse) - CICS Explorer based CICS bundle project, contains Web application bundle-part. Use with Eclipse and CICS Explorer. +## Table of Contents +- [Prerequisites](#prerequisites) +- [Downloading](#downloading) +- [Check dependencies](#check-dependencies) +- [Building the Sample](#building-the-sample) +- [Deploying to a CICS Liberty JVM server](#deploying-to-a-cics-liberty-jvm-server) +- [Running the Sample](#running-the-sample) +- [License](#license) ## Prerequisites -- CICS TS V5.5 or later -- Java SE 1.8 or later on the workstation -- One of the following on your workstation: - - Eclipse with the IBM CICS SDK for Java EE, Jakarta EE and Liberty - - An IDE of your choice that supports Gradle or Maven (or can run the wrappers) - -## Supporting files -* [`DFHCSD.txt`](etc/DFHCSD.txt) - DFHCSDUP sample input stream for the CICS BUNDLE resource definition. -* [`EDUCHAN.cbl`](etc/src/cobol/EDUCHAN.cbl) - A sample CICS COBOL that returns the date and time and reversed input using channels and containers - +- CICS TS V5.5 or later with a configured Liberty JVM server +- Java SE 8 or later on the workstation +- One of the following on your workstation: + - Eclipse with the IBM CICS SDK for Java EE, Jakarta EE and Liberty + - An IDE of your choice that supports Gradle or Maven (or can run the wrappers) ## Downloading -- Clone the repository using your IDEs support, such as the Eclipse Git plugin +- Clone the repository using your IDE's support, such as the Eclipse Git plugin - **or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-liberty-restapp/archive/main.zip) and unzip onto the workstation +### Check dependencies -## Building +The following source components are supplied in [`cics-java-liberty-restapp-app/src/main/java`](cics-java-liberty-restapp-app/src/main/java): -The sample includes Eclipse project configurations, Gradle and Maven build files and Gradle/Maven Wrappers offering a wide range of build options with the tooling and IDE of your choice. +**Package `com.ibm.cicsdev.restapp`** +- [`CICSApplication`](cics-java-liberty-restapp-app/src/main/java/com/ibm/cicsdev/restapp/CICSApplication.java) — sets the `ApplicationPath` for resources in this application +- [`InfoResource`](cics-java-liberty-restapp-app/src/main/java/com/ibm/cicsdev/restapp/InfoResource.java) — returns JSON structure using the `CICSInformation` bean +- [`ReverseResource`](cics-java-liberty-restapp-app/src/main/java/com/ibm/cicsdev/restapp/ReverseResource.java) — returns JSON structure using the `ReverseResult` bean -We document the following 2 approaches: +**Package `com.ibm.cicsdev.restapp.bean`** +- [`CICSEnvironment`](cics-java-liberty-restapp-app/src/main/java/com/ibm/cicsdev/restapp/bean/CICSEnvironment.java) — JAXB bean returning JSON structure containing CICS product and version information +- [`CICSInformation`](cics-java-liberty-restapp-app/src/main/java/com/ibm/cicsdev/restapp/bean/CICSInformation.java) — JAXB bean returning JSON structure containing CICS applid, time, JVM server name, and an instance of `CICSEnvironment` +- [`ReverseResult`](cics-java-liberty-restapp-app/src/main/java/com/ibm/cicsdev/restapp/bean/ReverseResult.java) — JAXB bean returning JSON structure containing the input and output containers sent to the `EDUCHAN` COBOL program -1. Use the command line to drive the supplied Gradle or Apache Maven wrappers, this means there is no requirement for Gradle, Maven, Eclipse, or CICS Explorer SDK to be installed. Alternatively the build files can also be used with locally installed Gradle or Maven runtimes. -1. Use the built-in Eclipse and CICS Explorer SDK capability +**Supporting files:** +- [`DFHCSD.txt`](etc/DFHCSD.txt) — DFHCSDUP sample input stream for the CICS BUNDLE resource definition +- [`EDUCHAN.cbl`](etc/src/cobol/EDUCHAN.cbl) — sample CICS COBOL program that returns the date, time, and reversed input using channels and containers +## Building the Sample -### Option 1a: Building with Gradle +The sample includes Eclipse project configurations, Gradle and Maven build files, and Gradle/Maven wrappers — offering a wide range of build options with any tooling or IDE. -For a complete build you should run the gradle build in the top-level `cics-java-liberty-restapp` directory which is designed to invoke the individual build.gradle files for each sub-project. +### Option 1a: Building with Gradle -If successful, a WAR file is created inside the `cics-java-liberty-restapp-app/build/libs` directory and a CICS bundle ZIP file inside the `cics-java-liberty-restapp-bundle/build/distribution` directory. +Run the Gradle build from the top-level `cics-java-liberty-restapp` directory. A WAR file is created in `cics-java-liberty-restapp-app/build/libs` and a CICS bundle ZIP in `cics-java-liberty-restapp-cicsbundle/build/distributions`. -The JVM server the CICS bundle is targeted at is controlled through the `cics.jvmserver` property, defined in the [`cics-java-liberty-restapp-bundle/build.gradle`](cics-java-liberty-restapp-bundle/build.gradle) file, or alternatively can be set on the command line as follows: +The target JVM server is controlled by the `cics.jvmserver` property (default `DFHWLP`): **Gradle wrapper (Linux/Mac):** ```shell @@ -75,20 +70,16 @@ The JVM server the CICS bundle is targeted at is controlled through the `cics.jv ``` **Gradle wrapper (Windows):** ```shell -gradle.bat clean build +gradlew.bat clean build ``` -**Gradle wrapper (command-line & setting jvmserver):** +**Setting the JVM server name:** ```shell ./gradlew clean build "-Pcics.jvmserver=MYJVM" ``` - ### Option 1b: Building with Apache Maven -For a complete build you should run the Maven pom.xml file in the top-level `cics-java-liberty-restapp` directory. A WAR file is created inside the `cics-java-liberty-restapp-app/target` directory and a CICS bundle ZIP file inside the `cics-java-liberty-restapp-bundle/target` directory. - -If building a CICS bundle ZIP the CICS JVM server name for the WAR bundle part should be modified in the - `cics.jvmserver` property, defined in [`cics-java-liberty-restapp-bundle/pom.xml`](cics-java-liberty-restapp-bundle/pom.xml) file under the `defaultjvmserver` configuration property, or alternatively can be set on the command line as follows: +Run the Maven build from the top-level `cics-java-liberty-restapp` directory. A WAR file is created in `cics-java-liberty-restapp-app/target` and a CICS bundle ZIP in `cics-java-liberty-restapp-cicsbundle/target`. **Maven wrapper (Linux/Mac):** ```shell @@ -98,126 +89,112 @@ If building a CICS bundle ZIP the CICS JVM server name for the WAR bundle part s ```shell mvnw.cmd clean verify ``` -**Maven wrapoper (command-line & setting jvmserver):** +**Setting the JVM server name:** ```shell ./mvnw clean verify "-Dcics.jvmserver=MYJVM" ``` - - ### Option 2: Building with Eclipse #### Importing the Project To import the sample into Eclipse: -1. Clone the repository using your IDE's support, such as the Eclipse Git plugin, **or** -2. Download the zip archive and use the **File > Import > Existing Projects into Workspace** wizard and select the expanded zip archive directory as the root directory - -**Important:** Ensure you check "Search for nested projects", and do not select **Copy projects into workspace** +1. Clone the repository using your IDE's support, such as the Eclipse Git plugin, **or** download the ZIP archive and unzip it +2. **File → Import → General → Existing Projects into Workspace** → select the repository root directory → **Finish** + - This imports the root project only; subprojects are discovered in the next step +3. Right-click `cics-java-liberty-restapp` → **Gradle** → **Refresh Gradle Project** (or **Maven** → **Update Project**) to import `-app` and `-cicsbundle` +4. To import the Eclipse CICS bundle project, right-click the `cics-java-liberty-restapp-cicsbundle-eclipse` folder in Project Explorer → **Import as Project** + - This project is excluded from the Gradle/Maven build so it is never auto-discovered #### Resolving Dependencies -The sample comes pre-configured with the CICS TS V5.5 with Java EE and Liberty 8 library in the Eclipse classpath. This means the project should compile immediately after import if you have the CICS Explorer SDK installed. - -However, if you see compilation errors, or if you want to use Gradle or Maven for dependency management instead of the pre-configured CICS library, you have several options: - -**Option 2a: Using Build Tool Integration** - -If you have Gradle (Buildship) or Maven (m2e) integration installed in Eclipse, you can use the build tool to automatically resolve dependencies: - -**For Gradle:** -1. Right-click on `cics-java-liberty-restapp` → **Run As** → **Gradle Build...** -2. In the dialog, enter `clean build` in the "Gradle Tasks" field -3. Click **Run** - this will download Java 8 (if needed via toolchain auto-provisioning) and resolve all dependencies -4. Once the build succeeds, right-click on `cics-java-liberty-restapp` → **Gradle** → **Refresh Gradle Project** -5. Clean and rebuild: **Project** → **Clean** → Select all projects → **Clean** - -**For Maven:** -1. Right-click on `cics-java-liberty-restapp` → **Maven** → **Update Project** → Check "Force Update of Snapshots/Releases" -2. Clean and rebuild: **Project** → **Clean** → Select all projects → **Clean** - -The build tool will automatically download and configure all required dependencies (CICS libraries, JAX-RS, JAXB, etc.) and update Eclipse's classpath. - -**Note:** For Gradle projects, the initial "Run As → Gradle Build" step is required to trigger toolchain auto-provisioning if Java 8 is not installed. After a successful build, "Gradle → Refresh Gradle Project" will synchronize the Eclipse classpath with the resolved dependencies. - -**Option 2b: Verifying Pre-Configured CICS Library (Default)** - -The project is already configured with the CICS library. If you see errors: +The project is pre-configured with the CICS TS V5.5 with Java EE and Liberty 8 library in the Eclipse classpath. The project should compile immediately after import if you have the CICS Explorer SDK installed. -1. Ensure you have the latest CICS Explorer SDK plug-in installed -2. Verify the CICS library is present: Right-click on `cics-java-liberty-restapp-app` → **Build Path** → **Configure Build Path** → **Libraries** tab -3. If the CICS library shows an error or is missing, remove it and re-add: Click **Add Library** → **CICS with Enterprise Java and Liberty** → Select **CICS TS V5.5 with Java EE and Liberty 8** -4. Clean and rebuild: **Project** → **Clean** → Select all projects → **Clean** +If you see compilation errors, or want to use Gradle or Maven for dependency management, use one of the options below. -**Note:** The pre-configured CICS library (Option 2b) provides the fastest setup for Eclipse users. Gradle/Maven integration (Option 2a) is useful if you want to use the same dependency management approach across different IDEs or build environments. +**For Gradle (Buildship):** +1. Right-click `cics-java-liberty-restapp` → **Run As** → **Gradle Build...** +2. Enter `clean build` in the Gradle Tasks field and click **Run** +3. Once the build succeeds, right-click `cics-java-liberty-restapp` → **Gradle** → **Refresh Gradle Project** +4. Clean and rebuild: **Project** → **Clean** → select all → **Clean** +**For Maven (m2e):** +1. Right-click `cics-java-liberty-restapp` → **Maven** → **Update Project** → check **Force Update of Snapshots/Releases** +2. Clean and rebuild: **Project** → **Clean** → select all → **Clean** +## Deploying to a CICS Liberty JVM server -## Deploying +The application must be built into a WAR file and deployed to Liberty using a CICS bundle. You will need a Liberty JVM server configured in your CICS region, and you must add the `jaxrs-1.1` (or later) Liberty feature to `server.xml`. -The sample Java classes are designed to be built into a an WAR file and deployed into a Liberty JVM server using a CICS bundle resource. To do this you will need to configure a Liberty JVM server in your CICS region, deploy the WAR archive to zFS, and then install this into CICS using a CICS BUNDLE resource. In addition the EDUCHAN COBOL can be deployed to support the function to call into CICS. +Download and compile the supplied COBOL program `EDUCHAN` and deploy it into CICS to support the reverse function. -### Configuring the Liberty JVM server -1. Create a Liberty JVM server in your target CICS region -2. Install the JVM server. -3. Add the `jaxrs-1.1` (or later version) Liberty feature to `server.xml` depending on your version of Java EE. +### CICS Bundle Plugin Deployment (Gradle/Maven) - -### Deploying to zFS - - -#### Option 1 - Deploying CICS Bundle Maven/Gradle plugin builds -1. Upload the built CICS bundle ZIP file in binary to zFS from your *target* or */build/distributions* directory in the cics-java-liberty-restapp-bundle project. -1. Connect to USS on the host system (e.g. SSH). -2. Create a bundle directory in zFS for the project -1. Copy the CICS bundle ZIP file into the bundle directory. -1. Extract the CICS bundle ZIP file. This can be done using the `jar` command. For example: +1. Build the project using Gradle or Maven as described above — the CICS bundle ZIP is produced automatically +2. Upload the CICS bundle ZIP in binary to zFS (from `cics-java-liberty-restapp-cicsbundle/build/distributions` for Gradle, or `cics-java-liberty-restapp-cicsbundle/target` for Maven) +3. Connect to USS (e.g. via SSH) and extract the ZIP: ```shell - jar -xvf bundle.zip + jar -xvf cics-java-liberty-restapp-cicsbundle-1.0.0.zip ``` +4. In CICS, create a BUNDLE resource definition pointing to the extracted directory and install it -#### Option 2 - Deploying using CICS Explorer SDK and the CICS bundle projects +A sample DFHCSDUP input file is provided in [`etc/DFHCSD.txt`](etc/DFHCSD.txt). -1. Deploy the CICS bundle project `cics-java-liberty-restapp-cicsbundle-eclipse` from CICS Explorer to zFS using the **Export Bundle Project to z/OS UNIX File System** wizard. The samples use the sub-directory `cics-java-liberty-restapp-cicsbundle-eclipse_1.0.0`. - -### Installing into CICS - -1. In CICS, create a BUNDLE resource definition, setting the bundle directory attribute to the zFS location you just exported to, and install it. -**Note:** A sample DFHCSDUP input file for the required CICS BUNDLE resource definition is supplied in the supporting file [DFHCSD.txt](etc/DFHCSD.txt) file. -1. Download and compile the supplied COBOL program `EDUCHAN` and deploy into CICS. +### CICS Explorer SDK Deployment +1. Import the `cics-java-liberty-restapp-cicsbundle-eclipse` project into Eclipse: right-click the folder in Project Explorer → **Import as Project** +2. Build the application WAR in Eclipse using Gradle or Maven (see Option 2 above) +3. Right-click `cics-java-liberty-restapp-cicsbundle-eclipse` → **Export Bundle Project to z/OS UNIX File System** +4. The bundle is exported to the `cics-java-liberty-restapp-bundle_1.0.0` directory on zFS +5. In CICS, create and install a BUNDLE resource definition pointing to that zFS directory +### Direct Liberty Application Deployment +1. Build the WAR using Gradle or Maven +2. Upload the WAR file to zFS +3. Add a `` element to your Liberty `server.xml` pointing to the WAR location +4. Restart or update the JVM server ## Running the Sample -### Using a web browser you can issue the following HTTP GET requests - -* http://host:port/com.ibm.cicsdev.restapp/rest/cicsinfo - -This will invoke the `InfoResource` class and return the following JSON response with information about the target CICS system: - -`{"applid":"IYK2Z32E","jvmServer":"DFHWLP","time":"2016-09-09T16:19:55.384Z","cicsEnvironment":{"cicsProduct":"CICS Transaction Server for z/OS","cicsVersion":"5.3.0"}}` - - -* http://host:port/com.ibm.cicsdev.restapp/rest/reverse - -This will invoke the `ReverseResource` class which links to the CICS COBOL program and reverses the default string "Hello from Java" returning the following JSON response: +Once deployed, use the context root `com.ibm.cicsdev.restapp`. Issue the following HTTP GET requests: -`{"time":"2016-09-09T16:15:52.756Z","original":"Hello from Java","reverse":"avaJ morf olleH","truncated":false}` +**Get CICS environment information:** +``` +http://host:port/com.ibm.cicsdev.restapp/rest/cicsinfo +``` +Example response: +```json +{"applid":"IYK2Z32E","jvmServer":"DFHWLP","time":"2016-09-09T16:19:55.384Z","cicsEnvironment":{"cicsProduct":"CICS Transaction Server for z/OS","cicsVersion":"5.3.0"}} +``` +**Reverse the default string "Hello from Java":** +``` +http://host:port/com.ibm.cicsdev.restapp/rest/reverse +``` +Example response: +```json +{"time":"2016-09-09T16:15:52.756Z","original":"Hello from Java","reverse":"avaJ morf olleH","truncated":false} +``` -* http://host:port/com.ibm.cicsdev.restapp/rest/reverse/ilovecics +**Reverse a custom string:** +``` +http://host:port/com.ibm.cicsdev.restapp/rest/reverse/ilovecics +``` +Example response: +```json +{"time":"2016-09-09T16:15:32.466Z","original":"ilovecics","reverse":"scicevoli","truncated":false} +``` -This will invoke the `ReverseResource` class which links to the CICS COBOL program reversing the input string "ilovecics" as follows: +## License -`{"time":"2016-09-09T16:15:32.466Z","original":"ilovecics","reverse":"scicevoli","truncated":false}` +This project is licensed under the [Eclipse Public License Version 2.0](LICENSE). -## License -This project is licensed under [Apache License Version 2.0](LICENSE). +## Additional Resources -## Usage terms -By downloading, installing, and/or using this sample, you acknowledge that separate license terms may apply to any dependencies that might be required as part of the installation and/or execution and/or automated build of the sample, including the following IBM license terms for relevant IBM components: +- [cics-java-liberty-restappext](https://github.com/cicsdev/cics-java-liberty-restappext) — extended code examples for accessing CICS resources from Java +- [IBM CICS documentation](https://www.ibm.com/docs/en/cics-ts) -• IBM CICS development components terms: https://www.ibm.com/support/customer/csol/terms/?id=L-ACRR-BBZLGX +## Contributing +We welcome contributions. Please raise issues and pull requests in the [GitHub repository](https://github.com/cicsdev/cics-java-liberty-restapp). diff --git a/cics-java-liberty-restapp-app/.classpath b/cics-java-liberty-restapp-app/.classpath index 82220ad..7430eb8 100644 --- a/cics-java-liberty-restapp-app/.classpath +++ b/cics-java-liberty-restapp-app/.classpath @@ -8,10 +8,21 @@ + + + + + + + + + + + diff --git a/cics-java-liberty-restapp-app/build.gradle b/cics-java-liberty-restapp-app/build.gradle index 9c09e8b..2ae49d1 100644 --- a/cics-java-liberty-restapp-app/build.gradle +++ b/cics-java-liberty-restapp-app/build.gradle @@ -7,8 +7,7 @@ plugins } -group = 'com.ibm.cicsdev.restapp' -archivesBaseName='cics-java-liberty-restapp' +group = 'com.ibm.cicsdev' version = '0.1.0' java { @@ -17,10 +16,15 @@ java { } } +war +{ + archiveFileName = 'cics-java-liberty-restapp.war' +} + // If in Eclipse, add Javadoc to the local project classpath -eclipse +eclipse { - classpath + classpath { downloadJavadoc = true } diff --git a/cics-java-liberty-restapp-app/pom.xml b/cics-java-liberty-restapp-app/pom.xml index 2784faa..1020b55 100644 --- a/cics-java-liberty-restapp-app/pom.xml +++ b/cics-java-liberty-restapp-app/pom.xml @@ -44,43 +44,18 @@ - - - org.apache.maven.plugins - maven-compiler-plugin - 3.13.0 - - - - - org.apache.maven.plugins - maven-war-plugin - 3.4.0 - - false - - false - - - - - - - com.ibm.cics - cics-bundle-maven-plugin - 1.0.6 - - - - bundle-war - - - ${cics.jvmserver} - - - - - + + + org.apache.maven.plugins + maven-war-plugin + 3.4.0 + + false + + false + + + \ No newline at end of file diff --git a/cics-java-liberty-restapp-cicsbundle-eclipse/.project b/cics-java-liberty-restapp-cicsbundle-eclipse/.project index ae3bd9d..beb74cb 100644 --- a/cics-java-liberty-restapp-cicsbundle-eclipse/.project +++ b/cics-java-liberty-restapp-cicsbundle-eclipse/.project @@ -10,7 +10,7 @@ bundleID - cics-java-liberty-restapp-cicsbundle-eclipse + cics-java-liberty-restapp-bundle majorVersion diff --git a/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml b/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml index 45b339f..0983976 100644 --- a/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml +++ b/cics-java-liberty-restapp-cicsbundle-eclipse/META-INF/cics.xml @@ -1,5 +1,5 @@ - + 2025-09-02T15:13:21.573Z diff --git a/cics-java-liberty-restapp-cicsbundle/.settings/org.eclipse.core.resources.prefs b/cics-java-liberty-restapp-cicsbundle/.settings/org.eclipse.core.resources.prefs new file mode 100644 index 0000000..99f26c0 --- /dev/null +++ b/cics-java-liberty-restapp-cicsbundle/.settings/org.eclipse.core.resources.prefs @@ -0,0 +1,2 @@ +eclipse.preferences.version=1 +encoding/=UTF-8 diff --git a/cics-java-liberty-restapp-cicsbundle/build.gradle b/cics-java-liberty-restapp-cicsbundle/build.gradle index e060c64..06dc9fe 100644 --- a/cics-java-liberty-restapp-cicsbundle/build.gradle +++ b/cics-java-liberty-restapp-cicsbundle/build.gradle @@ -1,5 +1,5 @@ plugins { - id 'com.ibm.cics.bundle' version "1.0.6" + id 'com.ibm.cics.bundle' version "1.0.8" } dependencies { diff --git a/cics-java-liberty-restapp-cicsbundle/pom.xml b/cics-java-liberty-restapp-cicsbundle/pom.xml index a934188..10156ce 100644 --- a/cics-java-liberty-restapp-cicsbundle/pom.xml +++ b/cics-java-liberty-restapp-cicsbundle/pom.xml @@ -28,7 +28,7 @@ com.ibm.cics cics-bundle-maven-plugin - 1.0.7 + 1.0.8 true diff --git a/pom.xml b/pom.xml index 9c62eda..06bb267 100644 --- a/pom.xml +++ b/pom.xml @@ -20,10 +20,8 @@ 8 UTF-8 - ${java.version} - ${java.version} DFHWLP - + @@ -55,6 +53,9 @@ org.apache.maven.plugins maven-compiler-plugin 3.13.0 + + ${java.version} + From 27d26f2d0f9b9f1c6cc5f962ed7c0734564ebc38 Mon Sep 17 00:00:00 2001 From: Ivan Hargreaves Date: Tue, 7 Jul 2026 14:53:54 +0100 Subject: [PATCH 5/6] Fix context root and document Liberty features - ibm-web-ext.xml: update context-root from com.ibm.cicsdev.restapp to cics-java-liberty-restapp to match agreed cicsdev naming convention and align with wst.common.component - README.md: specify exact Liberty features (jaxrs-2.1, servlet-4.0) required for this Java EE 8 / javax.* sample; add warning against Jakarta EE 10 features; update all sample URLs to use cics-java-liberty-restapp context root - etc/config/server.xml: add sample server.xml with correct features --- README.md | 23 +++++++++++++++---- .../src/main/webapp/WEB-INF/ibm-web-ext.xml | 2 +- etc/config/server.xml | 18 +++++++++++++++ 3 files changed, 37 insertions(+), 6 deletions(-) create mode 100644 etc/config/server.xml diff --git a/README.md b/README.md index f0a7636..30e30a3 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,20 @@ If you see compilation errors, or want to use Gradle or Maven for dependency man ## Deploying to a CICS Liberty JVM server -The application must be built into a WAR file and deployed to Liberty using a CICS bundle. You will need a Liberty JVM server configured in your CICS region, and you must add the `jaxrs-1.1` (or later) Liberty feature to `server.xml`. +The application must be built into a WAR file and deployed to Liberty using a CICS bundle. You will need a Liberty JVM server configured in your CICS region. + +**Required Liberty features** — this sample uses the `javax.*` namespace (Java EE 8). Add the following to your `server.xml`: + +```xml + + jaxrs-2.1 + servlet-4.0 + +``` + +> **Note:** Do not use Jakarta EE 10 features (`restfulWS-3.1`, `servlet-6.0`) with this sample — those features use the `jakarta.*` namespace and are incompatible with the `javax.*` API used here. Liberty will fail to dispatch requests and return `SRVE0190E: File not found`. + +A sample `server.xml` is provided in [`etc/config/server.xml`](etc/config/server.xml). Download and compile the supplied COBOL program `EDUCHAN` and deploy it into CICS to support the reverse function. @@ -157,11 +170,11 @@ A sample DFHCSDUP input file is provided in [`etc/DFHCSD.txt`](etc/DFHCSD.txt). ## Running the Sample -Once deployed, use the context root `com.ibm.cicsdev.restapp`. Issue the following HTTP GET requests: +Once deployed, use the context root `cics-java-liberty-restapp`. Issue the following HTTP GET requests: **Get CICS environment information:** ``` -http://host:port/com.ibm.cicsdev.restapp/rest/cicsinfo +http://host:port/cics-java-liberty-restapp/rest/cicsinfo ``` Example response: ```json @@ -170,7 +183,7 @@ Example response: **Reverse the default string "Hello from Java":** ``` -http://host:port/com.ibm.cicsdev.restapp/rest/reverse +http://host:port/cics-java-liberty-restapp/rest/reverse ``` Example response: ```json @@ -179,7 +192,7 @@ Example response: **Reverse a custom string:** ``` -http://host:port/com.ibm.cicsdev.restapp/rest/reverse/ilovecics +http://host:port/cics-java-liberty-restapp/rest/reverse/ilovecics ``` Example response: ```json diff --git a/cics-java-liberty-restapp-app/src/main/webapp/WEB-INF/ibm-web-ext.xml b/cics-java-liberty-restapp-app/src/main/webapp/WEB-INF/ibm-web-ext.xml index 4706719..a735606 100644 --- a/cics-java-liberty-restapp-app/src/main/webapp/WEB-INF/ibm-web-ext.xml +++ b/cics-java-liberty-restapp-app/src/main/webapp/WEB-INF/ibm-web-ext.xml @@ -5,7 +5,7 @@ xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd" version="1.0"> - + diff --git a/etc/config/server.xml b/etc/config/server.xml new file mode 100644 index 0000000..c773a25 --- /dev/null +++ b/etc/config/server.xml @@ -0,0 +1,18 @@ + + + + + + + jaxrs-2.1 + + servlet-4.0 + + + From 037e3182562c1e9600b355d40cf1121e7d9a123d Mon Sep 17 00:00:00 2001 From: Ivan Hargreaves Date: Tue, 7 Jul 2026 15:40:43 +0100 Subject: [PATCH 6/6] Fix Maven CI: remove JDK 8 from matrix, pin java.version=8 maven-compiler-plugin parameter requires JDK 9+ - running the build on JDK 8 itself fails with 'invalid flag: --release'. Remove JDK 8 from the Maven matrix; use JDK 11+ with -Djava.version=8 to validate Java 8 source compatibility via cross-compilation instead. --- .github/workflows/build.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 4eab723..6cd9dfc 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -36,7 +36,9 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - jdk: [8, 11, 17, 21, 25] + # JDK 8 excluded: maven-compiler-plugin requires JDK 9+ + # Use JDK 11+ with -Djava.version=8 to validate Java 8 source compatibility + jdk: [11, 17, 21, 25] steps: - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.jdk }} @@ -46,7 +48,7 @@ jobs: distribution: "semeru" cache: maven - name: Build with Maven - run: mvn --batch-mode --update-snapshots --file pom.xml -Djava.version=${{ matrix.jdk }} verify + run: mvn --batch-mode --update-snapshots --file pom.xml -Djava.version=8 verify build-mvnw: name: Build Maven Wrapper @@ -54,7 +56,9 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - jdk: [8, 11, 17, 21, 25] + # JDK 8 excluded: maven-compiler-plugin requires JDK 9+ + # Use JDK 11+ with -Djava.version=8 to validate Java 8 source compatibility + jdk: [11, 17, 21, 25] steps: - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.jdk }} @@ -64,7 +68,7 @@ jobs: distribution: "semeru" cache: maven - name: Build with Maven Wrapper - run: ./mvnw --batch-mode --update-snapshots --file pom.xml -Djava.version=${{ matrix.jdk }} verify + run: ./mvnw --batch-mode --update-snapshots --file pom.xml -Djava.version=8 verify build-gradle: name: Build Gradle