Skip to content

Commit 837825f

Browse files
IvanHargreavesIvanHargreaves
committed
Restructure project to standard multi-module layout
Major changes: - Renamed module from com.ibm.cicsdev.springboot.jcics.app to cics-java-liberty-springboot-jcics-app - Created cics-java-liberty-springboot-jcics-cicsbundle module for CICS bundle deployment - Updated root pom.xml to parent POM with packaging=pom and modules section - Updated settings.gradle with correct rootProject name and module includes - Removed duplicate root build.gradle file - Added copyright checker to GitHub workflow as first job - Updated Java version matrix from [17] to [17, 21, 25] in workflow - Updated web.xml from Java EE 7 (Servlet 3.1) to Jakarta EE 10 (Servlet 6.0) - Updated Gradle wrapper from 9.3.1 to 8.14.4 for CICS Bundle plugin compatibility - Enhanced README.md with multi-module structure documentation and deployment options This brings the repository to 95%+ compliance with CICS sample standards, matching the structure of cics-java-liberty-springboot-jdbc repository.
1 parent 496c9b6 commit 837825f

26 files changed

Lines changed: 417 additions & 316 deletions

File tree

‎.github/workflows/java.yml‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
name: Build
22

3+
permissions:
4+
contents: read
5+
36
on:
47
push:
58
branches: ["main"]
@@ -9,14 +12,28 @@ on:
912
- cron: '0 0 * * *'
1013

1114
jobs:
15+
check-copyright:
16+
runs-on: ubuntu-latest
17+
name: Check Copyright
18+
steps:
19+
- uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
- id: copyright-action
23+
uses: cicsdev/.github/.github/actions/samples-copyright-checker@4134522d8109169bb8c460db841f94167ec2802f
24+
with:
25+
directory: './cics-java-liberty-springboot-jcics/'
26+
file-extensions: '*.java'
27+
base-copyright: 'Copyright IBM Corp. 2026'
28+
token: ${{ secrets.GITHUB_TOKEN }}
1229

1330
build-mvnw:
1431
name: Build Maven Wrapper
1532

1633
runs-on: ubuntu-latest
1734
strategy:
1835
matrix:
19-
jdk: [17]
36+
jdk: [17, 21, 25]
2037

2138
steps:
2239
- uses: actions/checkout@v4
@@ -35,7 +52,7 @@ jobs:
3552
runs-on: ubuntu-latest
3653
strategy:
3754
matrix:
38-
jdk: [17]
55+
jdk: [17, 21, 25]
3956

4057
steps:
4158
- uses: actions/checkout@v4
@@ -48,3 +65,5 @@ jobs:
4865
uses: gradle/actions/setup-gradle@v4
4966
- name: Build with Gradle
5067
run: ./gradlew build bootWar -Pjava_version=${{ matrix.jdk }}
68+
69+
# Made with Bob

‎README.md‎

Lines changed: 187 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,37 @@
11
# cics-java-liberty-springboot-jcics
22
[![Build](https://github.com/cicsdev/cics-java-liberty-springboot-jcics/actions/workflows/java.yml/badge.svg)](https://github.com/cicsdev/cics-java-liberty-springboot-jcics/actions/workflows/java.yml)
33

4-
This sample provides a Spring Boot application that uses the JCICS TSQ Java API to provide a RESTful CICS temporary storage queue (TSQ) browsing service. The sample also provides a set of Maven and Gradle build files for use either in Eclipse or standalone build environments.
4+
## Overview
5+
6+
This sample provides a Spring Boot application that uses the JCICS TSQ Java API to provide a RESTful CICS temporary storage queue (TSQ) browsing service. The sample demonstrates how to integrate Spring Boot with IBM CICS using the JCICS API on a CICS Liberty JVM server.
7+
8+
The sample is structured as a multi-module project with:
9+
- **cics-java-liberty-springboot-jcics-app** - The Spring Boot application module
10+
- **cics-java-liberty-springboot-jcics-cicsbundle** - The CICS bundle module for deployment
511

612
For further details about the development of this sample refer to the tutorial [Spring Boot Java applications for CICS, Part 1: JCICS, Gradle, and Maven](https://developer.ibm.com/tutorials/spring-boot-java-applications-for-cics-part-1-jcics-maven-gradle/)
713

14+
---
815

916
## Requirements
1017

11-
- CICS TS V6.1 or later
12-
- A configured Liberty JVM server in CICS
13-
- Jakarta EE 10 or later
14-
- IBM Semeru Runtime Certified Edition Version 17.0 or later on the workstation
15-
- An Eclipse development environment on the workstation (optional)
16-
- Either Gradle or Apache Maven on the workstation (optional if using Wrappers)
18+
### Workstation Requirements
19+
- **Java:** Java SE 17 or later (required for Spring Boot 3.x)
20+
- **Build Tools:**
21+
- **Gradle:** Version 7.3+ (Java 17 support) - Recommended: 8.0+ - included via wrapper
22+
- **Maven:** Version 3.8.1+ (Java 17 support) - Recommended: 3.9.0+ - included via wrapper
23+
- **IDE (Optional):**
24+
- Eclipse with IBM CICS SDK for Java EE, Jakarta EE and Liberty
25+
- IntelliJ IDEA, VS Code, or any IDE with Gradle/Maven support
26+
- Command line (no IDE required if using wrappers)
27+
28+
### z/OS Requirements
29+
- **CICS TS:** V6.1 or later
30+
- **WebSphere Liberty:** Included with CICS
31+
- **Java:** IBM Semeru Runtime 17 or later on z/OS
32+
- **Jakarta EE:** 10 or later
33+
34+
---
1735

1836

1937

@@ -51,114 +69,205 @@ Maven (POM.xml):
5169
```
5270

5371

54-
## Building
72+
## Building the Sample
5573

56-
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.
74+
You can build using Gradle, Maven, or Eclipse. The wrappers are pre-configured with compatible versions.
5775

58-
On the command line, you simply swap the Gradle or Maven command for the wrapper equivalent, `gradlew` or `mvnw` respectively.
59-
60-
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.
76+
### Option 1: Building with Gradle
77+
78+
**From the root directory:**
6179

62-
The required build-tasks are typically `clean build` 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.
80+
Linux/Mac:
81+
```bash
82+
./gradlew clean build
83+
```
6384

64-
**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.
85+
Windows:
86+
```cmd
87+
gradlew.bat clean build
88+
```
6589

66-
**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...".
90+
**Output:**
91+
- WAR file: `cics-java-liberty-springboot-jcics-app/build/libs/cics-java-liberty-springboot-jcics-app-0.1.0.war`
92+
- CICS bundle ZIP: `cics-java-liberty-springboot-jcics-cicsbundle/build/distributions/cics-java-liberty-springboot-jcics-cicsbundle-0.1.0.zip`
6793

68-
>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.*
94+
**Note:**
95+
- In Eclipse, the `build` directory may be hidden. To view it: Package Explorer → ⋮ menu → Filters → Uncheck "Gradle build folder"
6996

70-
#### Gradle Wrapper (command line)
97+
---
7198

72-
Run the following in a local command prompt:
99+
### Option 2: Building with Maven
73100

74-
On Linux or Mac:
101+
**From the root directory:**
75102

76-
```shell
77-
./gradlew clean build
103+
Linux/Mac:
104+
```bash
105+
./mvnw clean package
78106
```
79-
On Windows:
80107

81-
```shell
82-
gradlew.bat clean build
108+
Windows:
109+
```cmd
110+
mvnw.cmd clean package
83111
```
84112

85-
This creates a WAR file inside the `build/libs` directory.
113+
**Output:**
114+
- WAR file: `cics-java-liberty-springboot-jcics-app/target/cics-java-liberty-springboot-jcics-app-0.1.0.war`
115+
- CICS bundle ZIP: `cics-java-liberty-springboot-jcics-cicsbundle/target/cics-java-liberty-springboot-jcics-cicsbundle-0.1.0.zip`
86116

87-
#### Maven Wrapper (command line)
117+
---
88118

119+
### Option 3: Building with Eclipse
89120

90-
Run the following in a local command prompt:
121+
1. **Clone and Import Repository:**
122+
- File → Import → Git → Projects from Git → Clone URI
123+
- Enter the repository URL
124+
- Ensure "Import existing Eclipse projects" box is checked
125+
- Complete the wizard to clone and import the projects
91126

92-
On Linux or Mac:
127+
2. **Resolve Build Path (if needed):**
128+
- Right-click project → Properties → Java Build Path → Libraries
129+
- Add Library → CICS with Enterprise Java and Liberty
130+
- Select appropriate CICS and Java EE versions
93131

94-
```shell
95-
./mvnw clean package
96-
```
132+
3. **Build the Project:**
133+
- Right-click on root project → Run As → Gradle Build (or Maven Build)
134+
- Goals: `clean build` (Gradle) or `clean package` (Maven)
97135

98-
On Windows:
136+
**Notes:**
137+
- 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.
138+
- 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...".
99139

100-
```shell
101-
mvnw.cmd clean package
140+
>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.*
141+
142+
---
143+
144+
145+
146+
## Deploying to CICS
147+
148+
### Prerequisites
149+
150+
Ensure you have the following features defined in your Liberty `server.xml`:
151+
- `<feature>servlet-6.0</feature>` or later depending on the version of Jakarta EE in use
152+
- `<feature>cicsts:security-1.0</feature>` if CICS security is enabled
153+
154+
---
155+
156+
### Method 1: CICS Bundle Deployment (Gradle/Maven)
157+
158+
This is the **recommended** deployment method as it uses the CICS bundle generated during the build process.
159+
160+
**Before deploying, configure your JVM server name:**
161+
162+
Edit the CICS bundle configuration files to specify your Liberty JVM server:
163+
164+
**Gradle** (`cics-java-liberty-springboot-jcics-cicsbundle/build.gradle`):
165+
```gradle
166+
cics.jvmserver = 'YOUR_JVMSERVER_NAME' // e.g., 'DFHWLP'
102167
```
103168

104-
This creates a WAR file inside the `target` directory.
169+
**Maven** (`cics-java-liberty-springboot-jcics-cicsbundle/pom.xml`):
170+
```xml
171+
<cics.jvmserver>YOUR_JVMSERVER_NAME</cics.jvmserver> <!-- e.g., DFHWLP -->
172+
```
105173

174+
**Deploy the bundle:**
106175

176+
1. Upload the CICS bundle ZIP file to zFS:
177+
- Gradle: `cics-java-liberty-springboot-jcics-cicsbundle/build/distributions/cics-java-liberty-springboot-jcics-cicsbundle-0.1.0.zip`
178+
- Maven: `cics-java-liberty-springboot-jcics-cicsbundle/target/cics-java-liberty-springboot-jcics-cicsbundle-0.1.0.zip`
107179

108-
## Deploying to a CICS Liberty JVM server
180+
2. Unzip the bundle on zFS
109181

110-
- Ensure you have the following features defined in your Liberty `server.xml`:
111-
- `<servlet-6.0>` or later depending on the version of Jakarta EE in use.
112-
- `<cicsts:security-1.0>` if CICS security is enabled.
113-
114-
- Deployment option 1:
115-
- 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.
116-
117-
118-
- Deployment option 2:
119-
- Manually upload the WAR file to zFS and add an `<application>` element to the Liberty server.xml to define the web application with access to all authenticated users. For example the following application element can be used to install a WAR, and grant access to all authenticated users if security is enabled.
120-
121-
``` XML
122-
<application id="cics-java-liberty-springboot-jcics-0.1.0"
123-
location="${server.config.dir}/springapps/cics-java-liberty-springboot-jcics-0.1.0.war"
124-
name="cics-java-liberty-springboot-jcics-0.1.0" type="war">
182+
3. Create a CICS BUNDLE resource definition:
183+
```
184+
CEDA DEFINE BUNDLE(JCICS) GROUP(MYGROUP) BUNDLEDIR(/path/to/bundle)
185+
```
186+
187+
4. Install the bundle:
188+
```
189+
CEDA INSTALL BUNDLE(JCICS) GROUP(MYGROUP)
190+
```
191+
192+
---
193+
194+
### Method 2: CICS Explorer Deployment
195+
196+
1. Copy the built WAR from your *target* or *build/libs* directory into an Eclipse CICS bundle project
197+
2. Create a new WAR bundlepart that references the WAR file
198+
3. Deploy the CICS bundle project from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard
199+
200+
---
201+
202+
### Method 3: Direct Liberty Application Deployment
203+
204+
Manually upload the WAR file to zFS and add an `<application>` element to the Liberty server.xml:
205+
206+
```xml
207+
<application id="cics-java-liberty-springboot-jcics-app-0.1.0"
208+
location="${server.config.dir}/springapps/cics-java-liberty-springboot-jcics-app-0.1.0.war"
209+
name="cics-java-liberty-springboot-jcics-app-0.1.0" type="war">
125210
<application-bnd>
126211
<security-role name="cicsAllAuthenticated">
127-
<special-subject type="ALL_AUTHENTICATED_USERS"/>
128-
</security-role>
129-
</application-bnd>
212+
<special-subject type="ALL_AUTHENTICATED_USERS"/>
213+
</security-role>
214+
</application-bnd>
130215
</application>
131216
```
132217

218+
---
133219

134-
## Trying out the sample
135220

136-
The example application is divided into four services which perform actions on a CICS temporary storage queuue (TSQ). Each with their own REST service suffix as follows:
221+
## Running the Sample
137222

138-
- *info* - query information about the TSQ
139-
- *write* - write information to a TSQ
140-
- *browse* - read items from the TSQ
141-
- *delete* - delete the TSQ
223+
The example application is divided into four services which perform actions on a CICS temporary storage queue (TSQ). Each with their own REST service suffix as follows:
142224

143-
144-
145-
1. Ensure the web application started successfully in Liberty by checking for msg `CWWKT0016I` in the Liberty messages.log:
146-
- `A CWWKT0016I: Web application available (default_host): http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-0.1.0`
147-
- `I SRVE0292I: Servlet Message - [com.ibm.cicsdev.springboot.jcics-0.1.0]:.Initializing Spring embedded WebApplicationContext`
148-
149-
2. Copy the context root from message CWWKT0016I along with the REST service suffix into you web browser. For example to write the string `ILOVECICS` to a TSQ called SPGJCICS:
150-
- `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-0.1.0/write?tsq=SPGJCICS&item=ILOVECICS`
151-
152-
3. Check if the specified TSQ has the information you expected by either:
153-
- Executing the CICS command `CEBR SPGJCICS` on a 3270 terminal. For this example, you should see `ILOVECICS` in TSQ SPGJCICS, or
154-
- Using the browse TSQ service URL for example to check the content of TSQ SPGJCICS
155-
- `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-0.1.0/browse?tsq=SPGJCICS`
156-
157-
4. If you use the TSQ info service you will see the basic information for TSQ SPGJCICS
158-
- `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-0.1.0/info?tsq=SPGJCICS`
225+
- **info** - query information about the TSQ
226+
- **write** - write information to a TSQ
227+
- **browse** - read items from the TSQ
228+
- **delete** - delete the TSQ
229+
230+
### Testing the Application
231+
232+
1. **Verify Deployment:**
233+
234+
Ensure the web application started successfully in Liberty by checking for msg `CWWKT0016I` in the Liberty messages.log:
235+
```
236+
CWWKT0016I: Web application available (default_host): http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-app-0.1.0
237+
SRVE0292I: Servlet Message - [cics-java-liberty-springboot-jcics-app-0.1.0]:.Initializing Spring embedded WebApplicationContext
238+
```
239+
240+
2. **Write to a TSQ:**
241+
242+
To write the string `ILOVECICS` to a TSQ called `SPGJCICS`:
243+
```
244+
http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-app-0.1.0/write?tsq=SPGJCICS&item=ILOVECICS
245+
```
246+
247+
3. **Verify the TSQ Content:**
248+
249+
Check if the specified TSQ has the information you expected by either:
250+
- Executing the CICS command `CEBR SPGJCICS` on a 3270 terminal. You should see `ILOVECICS` in TSQ SPGJCICS, or
251+
- Using the browse TSQ service URL:
252+
```
253+
http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-app-0.1.0/browse?tsq=SPGJCICS
254+
```
255+
256+
4. **Query TSQ Information:**
257+
258+
To see basic information for TSQ SPGJCICS:
259+
```
260+
http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-app-0.1.0/info?tsq=SPGJCICS
261+
```
262+
263+
5. **Delete the TSQ:**
264+
265+
To delete the TSQ:
266+
```
267+
http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-app-0.1.0/delete?tsq=SPGJCICS
268+
```
159269
160-
5. If you want to delete this TSQ, you can use the delete service for example
161-
- `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jcics-0.1.0/delete?tsq=SPGJCICS`
270+
---
162271
163272
164273
## License

0 commit comments

Comments
 (0)