Merge pull request #1 from cicsdev/aj-main

5.5 branch

Author: AaronJhaj

.github/workflows/java.yaml

@@ -2,58 +2,25 @@ name: Build
 
 on:
   push:
-    branches: ["main"]
+    branches: ["cicsts/v5.5"]
   pull_request:
-    branches: ["main"]
+    branches: ["cicsts/v5.5"]
   schedule:
     - cron: '0 0 * * *'
 
 jobs:
   check-copyright:
-    name: Check Copyright
     runs-on: ubuntu-latest
+    name: Check Copyright
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          
-      - name: Check Copyright
-        env:
-          EXTENSIONS: "*.java"
-          BASE_COPYRIGHT: "Copyright IBM Corp. 2016"
-        run: |
-          for ext in "$EXTENSIONS"; do
-              for file in $(find . -type f -name "$ext" -path "./cics-java-liberty-link-app/*"); do
-                  echo "Processing file: $file"  
-                  
-                  LAST_MODIFIED_YEAR=$(git log --follow -1 --format="%ad" --date=format:"%Y" -- "$file")
-
-                  if ! grep -q "Copyright" "$file"; then
-                      echo -e "/**\n * $BASE_COPYRIGHT\n */\n$(cat "$file")" > "$file"
-                  else
-                      # Extract existing copyright line
-                      CURRENT_COPYRIGHT=$(grep -o "Copyright IBM Corp. [0-9]\{4\}\(, [0-9]\{4\}\)\?" "$file")
-                    
-                      # Check if LAST_MODIFIED_YEAR is anywhere in current copyright
-                      if [[ "$CURRENT_COPYRIGHT" != *"$LAST_MODIFIED_YEAR"* ]]; then
-                          # Check if copyright has two years
-                          if [[ "$CURRENT_COPYRIGHT" =~ ,\ [0-9]{4}$ ]]; then
-                              # If there is already a second year, replace it
-                              sed -i "s/$BASE_COPYRIGHT, [0-9]\{4\}/$BASE_COPYRIGHT, $LAST_MODIFIED_YEAR/" "$file"
-                          else
-                              # If there is no second year, add it
-                              sed -i "s/$BASE_COPYRIGHT/$BASE_COPYRIGHT, $LAST_MODIFIED_YEAR/" "$file"
-                          fi
-                      fi
-                  fi
-              done
-          done
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
+      - uses: actions/checkout@v4
+      - id: copyright-action
+        uses: cicsdev/.github/.github/actions/samples-copyright-checker@139edd8dc23af7f4f7dd9afe4d56a1053fe426a7
         with:
+          directory: './cics-java-liberty-tsq-app/'
+          file-extensions: '*.java *.html'
+          base-copyright: 'Copyright IBM Corp. 2025'
           token: ${{ secrets.GITHUB_TOKEN }}
-          base: ${{ github.head_ref }}
 
   build-mvnw:
     name: Build Maven Wrapper

.project

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>cics-java-liberty-link</name>
+	<name>cics-java-liberty-tsq</name>
 	<comment></comment>
 	<projects>
 	</projects>

.settings/org.eclipse.buildship.core.prefs

@@ -2,7 +2,7 @@ arguments=
 auto.sync=false
 build.scans.enabled=false
 connection.gradle.distribution=GRADLE_DISTRIBUTION(WRAPPER)
-connection.project.dir=cics-java-liberty-link-app
+connection.project.dir=cics-java-liberty-tsq-app
 eclipse.preferences.version=1
 gradle.user.home=
 java.home=

README.md

@@ -1,15 +1,13 @@
-# Sample: cics-java-liberty-link
-[![Build](https://github.com/cicsdev/cics-java-liberty-link/actions/workflows/java.yaml/badge.svg)](https://github.com/cicsdev/cics-java-liberty-link/actions/workflows/java.yaml)
+# Sample: cics-java-liberty-tsq
 
-A sample CICS Java application showing use of the `com.ibm.cics.server.invocation.CICSProgram` annotation to link to an Enterprise Java program running in a Liberty JVM server.
+This sample demonstrates a Java EE web application running on a Liberty JVM server in CICS. It provides a web interface to interact with Temporary Storage Queues (TSQs) using the JCICS API.
 
 ## Contents
-A set of sample components that demonstrate how to annotate a POJO packaged in a WAR (Web application), deploy it to a Liberty JVM server, and then LINK to (or call) that POJO from a CICS program or CICS transaction.
 
-- [cics-java-liberty-link](./cics-java-liberty-link) - Top-level project.
-- [cics-java-liberty-link-app](./cics-java-liberty-link-app) - Web application project.
-- [cics-java-liberty-link-bundle](./cics-java-liberty-link-bundle) - CICS bundle plug-in based project, contains Web application and WLPH transaction bundle-parts. Use with Gradle and Maven builds.
-- [etc/eclipse_projects/com.ibm.cics.server.examples.wlp.link.bundle](./etc/eclipse_projects/com.ibm.cics.server.examples.wlp.link.bundle) - CICS Explorer based CICS bundle project, contains Web application and WLPH transaction bundle-parts. Use with CICS Explorer 'Export to zFS' deployment capability.
+- [cics-java-liberty-tsq](./cics-java-liberty-tsq) - Top-level project.
+- [cics-java-liberty-tsq-app](./cics-java-liberty-tsq-app) - Web application project.
+- [cics-java-liberty-tsq-bundle](./cics-java-liberty-tsq-bundle) - CICS bundle plug-in based project, contains Web application. Use with Gradle and Maven builds.
+- [etc/eclipse_projects/com.ibm.cics.server.examples.wlp.tsq.bundle](./etc/eclipse_projects/com.ibm.cics.server.examples.wlp.tsq.bundle) - CICS Explorer based CICS bundle project, contains Web application. Use with CICS Explorer 'Export to zFS' deployment capability.
 - [etc/config/liberty/server.xml](./etc/config/liberty/server.xml) - A template `server.xml` demonstrating the minimum configuration required to run the sample.
 
 ## Prerequisites
@@ -23,7 +21,7 @@ A set of sample components that demonstrate how to annotate a POJO packaged in a
 ## Downloading
 
 - Clone the repository using your IDEs support, such as the Eclipse Git plugin
-- **or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-liberty-link/archive/main.zip) and unzip onto the workstation
+- **or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-liberty-tsq/archive/main.zip) and unzip onto the workstation
 
 > [!TIP]
 > Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository.
@@ -63,8 +61,8 @@ You can build the sample in a variety of ways:
 
 
 > [!IMPORTANT]
-> The sample comes pre-configured for use with a JDK 1.8 and CICS TS V5.5 Libraries for Java EE 6/7. When you initially import the project to your IDE, if your IDE is not configured for a JDK 1.8, or does not have CICS Explorer SDK installed, you might experience local project compile errors. To resolve issues you should configure the Project's build-path to add/remove your preferred combination of CICS TS, JDK, and Liberty's Enterprise Java libraries (Java EE or Jakarta EE). Resolving errors might also depend on how you wish to build and deploy the sample. If you are building and deploying through CICS Explorer SDK and 'Export to zFS' you should edit the link-app's Project properties. 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.
-If you are building and deploying with Gradle or Maven then you don't necessarily need to fix the local errors, but to do so, you can do as above, or you can run a tooling refresh on the link-app project. For example, in Eclipse: right-click on "Project", select "Gradle -> Refresh Gradle Project", **or** right-click on "Project", select "Maven -> Update Project...".
+> The sample comes pre-configured for use with a JDK 1.8 and CICS TS V5.5 Libraries for Java EE 8. When you initially import the project to your IDE, if your IDE is not configured for a JDK 1.8, or does not have CICS Explorer SDK installed, you might experience local project compile errors. To resolve issues you should configure the Project's build-path to add/remove your preferred combination of CICS TS, JDK, and Liberty's Enterprise Java libraries (Java EE or Jakarta EE). Resolving errors might also depend on how you wish to build and deploy the sample. If you are building and deploying through CICS Explorer SDK and 'Export to zFS' you should edit the tsq-app's Project properties. 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.
+If you are building and deploying with Gradle or Maven then you don't necessarily need to fix the local errors, but to do so, you can do as above, or you can run a tooling refresh on the tsq-app 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.
@@ -76,14 +74,14 @@ If you are using the Egit client to clone the repo, remember to tick the button
 
 ### Option 2: Building with Gradle
 
-For a complete build you should run the settings.gradle file in the top-level 'cics-java-liberty-link' directory which is designed to invoke the individual build.gradle files for each project. 
+For a complete build you should run the settings.gradle file in the top-level 'cics-java-liberty-tsq' directory which is designed to invoke the individual build.gradle files for each project. 
 
-If successful, a WAR file is created inside the `cics-java-liberty-link-app/build/libs` directory and a CICS bundle ZIP file inside the `cics-java-liberty-link-bundle/build/distribution` directory. 
+If successful, a WAR file is created inside the `cics-java-liberty-tsq-app/build/libs` directory and a CICS bundle ZIP file inside the `cics-java-liberty-tsq-bundle/build/distribution` directory. 
 
 [!NOTE]
 In Eclipse, the output 'build' directory is often hidden by default. From the Package Explorer pane, select the three dot menu, choose filters and un-check the Gradle build folder to view its contents.
 
-The JVM server the CICS bundle is targeted at is controlled through the `cics.jvmserver` property, defined in the [`cics-java-liberty-link-bundle/build.gradle`](cics-java-liberty-link-bundle/build.gradle) file, or alternatively can be set on the command line:
+The JVM server the CICS bundle is targeted at is controlled through the `cics.jvmserver` property, defined in the [`cics-java-liberty-tsq-bundle/build.gradle`](cics-java-liberty-tsq-bundle/build.gradle) file, or alternatively can be set on the command line:
 
 **Gradle Wrapper (Linux/Mac):**
 ```shell
@@ -104,10 +102,10 @@ gradle clean build -Pcics.jvmserver=MYJVM
 
 ### Option 3: Building with Apache Maven
 
-For a complete build you should run the pom.xml file in the top-level 'cics-java-liberty-link' directory. A WAR file is created inside the `cics-java-liberty-link-app/target` directory and a CICS bundle ZIP file inside the `cics-java-liberty-link-bundle/target` directory.
+For a complete build you should run the pom.xml file in the top-level 'cics-java-liberty-tsq' directory. A WAR file is created inside the `cics-java-liberty-tsq-app/target` directory and a CICS bundle ZIP file inside the `cics-java-liberty-tsq-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-link-bundle/pom.xml`](cics-java-liberty-link-bundle/pom.xml) file under the `defaultjvmserver` configuration property, or alternatively can be set on the command line.
+ `cics.jvmserver` property, defined in [`cics-java-liberty-tsq-bundle/pom.xml`](cics-java-liberty-tsq-bundle/pom.xml) file under the `defaultjvmserver` configuration property, or alternatively can be set on the command line.
 
 **Maven Wrapper (Linux/Mac):**
 ```shell
@@ -129,53 +127,51 @@ mvn clean verify -Dcics.jvmserver=MYJVM
 ## Deploying to a Liberty JVM server
 
 Ensure you have the following features defined in your Liberty server.xml:
-* `cicsts:link-1.0`
+* `<feature>servlet-4.0</feature>`
 
 A template server.xml is provided [here](./etc/config/liberty/server.xml).
 
-### Deploying CICS Bundles with CICS Explorer
-1. Optionally, change the name of the JVMSERVER in the .warbundle file of the CICS bundle project from DFHWLP to the name of your JVMSERVER resource defined in CICS. 
-2. Export the bundle project to zFS by selecting 'Export Bundle project to z/OS Unix File System' from the context menu.
-3. In CICS, create a bundle definition, setting the bundle directory attribute to the zFS location you just exported to, and install it. 
-4. Check the CICS region for the dynamically created PROGRAM resource HELLOWLP using the Programs view in CICS Explorer, or the CEMT INQUIRE PROGRAM command.
+## Deploying to CICS
 
-### Deploying CICS Bundles from Gradle or Maven
-1. Manually upload the ZIP file from the _cics-java-liberty-link-bundle/target_ or _cics-java-liberty-link-bundle/build/distributions_ directory to zFS.
-2. Unzip this ZIP file on zFS (e.g. `${JAVA_HOME}/bin/jar xf /path/to/bundle.zip`).
-3. Create a CICS BUNDLE resource definition, setting the bundle directory attribute to the zFS location you just extracted to, and install it into the CICS region. 
-4. Check the CICS region for the dynamically created PROGRAM resource HELLOWLP using the Programs view in CICS Explorer, or the CEMT INQUIRE PROGRAM command.
+### Option 1 - Deploying using CICS Explorer SDK and the provided CICS bundle project
+1. Deploy the CICS bundle project 'com.ibm.cics.server.examples.wlp.tsq.bundle' from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard. This CICS bundle includes the WAR bundlepart to run the sample.
 
-### Deploying directly with Liberty's application configuration
-1. Manually upload the WAR file from the _cics-java-liberty-link-app/target_ or _cics-java-liberty-link-app/build/libs_ directory to zFS.
-2. Add an `<application>` element to the Liberty server.xml to define the web application.
-3. Check the CICS region for the dynamically created PROGRAM resource HELLOWLP using the Programs view in CICS Explorer, or the CEMT INQUIRE PROGRAM command.
 
+### Option 2 - Deploying using CICS Explorer SDK with own CICS bundle project
+1. Copy and paste the built WAR from your *projects/cics-java-liberty-tsq-app/target* or *projects/cics-java-liberty-tsq-app/build/libs* directory into a new Eclipse CICS bundle project.
+2. Create a new bundlepart that references the WAR file. 
+3. Right click using the ** Export Bundle Project to z/OS UNIX File System ** wizard.
 
-## Running
 
-If you deployed the sample through CICS Explorer (Export to zFS), or through the CICS bundle plug-in as a ZIP and manually FTP'd the resource to zFS, the sample can be run using the `WLPH` transaction that is provided as a bundlepart within the CICS bundle definition.
+### Option 3 - Deploying using CICS Explorer (Remote System Explorer) and CICS Bundle ZIP
+1. Connect to USS on the host system
+2. Create the bundle directory for the project.
+3. Copy & paste the built CICS bundle ZIP file from your *projects/cics-java-liberty-tsq-bundle/target* or *projects/cics-java-liberty-tsq-bundle/build/distributions* directory to z/FS on the host system into the bundle directory.
+4. Extract the ZIP by right-clicking on the ZIP file > User Action > unjar...
+5. Refresh the bundle directory
 
-Alternatively, you can define your own CICS transaction to invoke the program 'HELLOWLP', or you can use the CECI transaction to invoke the sample program:
 
-```text
-CECI LINK PROGRAM(HELLOWLP)
-```
+### Option 4 - Deploying using command line tools
+1. Upload the built CICS bundle ZIP file from your *projects/cics-java-liberty-tsq-bundle/target* or *projects/cics-java-liberty-tsq-bundle/build/distributions* directory to z/FS on the host system (e.g. FTP).
+2. Connect to USS on the host system (e.g. SSH).
+3. Create the bundle directory for the project.
+4. Move the CICS bundle ZIP file into the bundle directory.
+5. Change directory into the bundle directoy.
+6. Extract the CICS bundle ZIP file. This can be done using the `jar` command. For example:
+   ```shell
+   jar xf file.zip
+   ```
 
-The program prints a message to the STDOUT output stream of the JVM server it runs on.
+---
 
-You can pass a channel with a container:
 
-```text
-CECI PUT CONTAINER(NAME) CHAR FROM(MATTHEW) CHANNEL(CHAN)
-CECI LINK PROG(HELLOWLP) CHANNEL(CHAN)
-```
-
-(ensure both commands are entered in the same CECI session).
+## Running
 
+The servlet is accessed with the following URL: [http://zos.example.com:9080/cics-java-liberty-tsq-app/](http://zos.example.com:9080/cics-java-liberty-tsq-app/).
 
+If using Maven/Gradle build and deployment, The servlet is accessed with the following URL: [http://zos.example.com:9080/cics-java-liberty-tsq-app-1.0.0/](http://zos.example.com:9080/cics-java-liberty-tsq-app-1.0,0/).
 
-## Find out more
-For more information about invoking Java EE applications in a Liberty JVM server from CICS programs, see [Linking to Java applications in a Liberty JVM server by using the @CICSProgram annotation](https://www.ibm.com/docs/en/cics-ts/latest?topic=djariljs-linking-java-applications-in-liberty-jvm-server-by-using-cicsprogram-annotation).
+You will see a TSQ interface rendered.
 
 
 ## License