You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+78-32Lines changed: 78 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ Sample RESTful web application for deployment to a Liberty JVM server in CICS. T
10
10
11
11
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.
12
12
13
-
The following Java source components are supplied in the [`src/main/java`](src/main/java) directory in this repository.
13
+
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.
14
14
15
15
## Java package com.ibm.cicsdev.restapp
16
16
*[`CICSApplication`](src/main/java/com/ibm/cicsdev/restapp/CICSApplication.java) - Sets the `ApplicationPath` for resources in this application
@@ -23,44 +23,68 @@ The following Java source components are supplied in the [`src/main/java`](src/m
23
23
*[`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`
24
24
*[`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
-[cics-java-liberty-restapp-bundle](./cics-java-liberty-restapp-bundle) - CICS bundle plug-in based project. Use with Gradle and Maven builds.
31
+
-[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 CICS Explorer 'Export to zFS' deployment capability.
32
+
33
+
34
+
## Prerequisites
35
+
- CICS TS V5.5 or later
36
+
- Java SE 1.8 or later on the workstation
37
+
- One of the following on your workstation:
38
+
- Eclipse with the IBM CICS SDK for Java EE, Jakarta EE and Liberty
39
+
- An IDE of your choice that supports Gradle or Maven (or can run the Wrappers)
40
+
- A command line, to run the Wrappers or to invoke a locally installed version of Gradle or Maven
26
41
27
42
## Supporting files
28
43
*[`DFHCSD.txt`](etc/DFHCSD.txt) - DFHCSDUP sample input stream for the CICS BUNDLE resource definition.
29
-
*[`EDUCHAN.cbl`](src/cobol/EDUCHAN.cbl) - A sample CICS COBOL that returns the date and time and reversed input using channels and containers
44
+
*[`EDUCHAN.cbl`](cics-java-liberty-restapp-app/src/cobol/EDUCHAN.cbl) - A sample CICS COBOL that returns the date and time and reversed input using channels and containers
30
45
*[`build.gradle`](build.gradle) - A sample Gradle build file to enable an automated build of the deployable WAR
31
46
*[`pom.xml`](pom.xml) - A sample Maven build file to enable an automated build of the deployable WAR
47
+
32
48
49
+
## Downloading
33
50
34
-
## Pre-reqs
51
+
- Clone the repository using your IDEs support, such as the Eclipse Git plugin
52
+
-**or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-liberty-restapp/archive/main.zip) and unzip onto the workstation
35
53
36
-
* CICS TS V5.5 or later.
37
-
* Java SE 1.8 or later on the workstation
38
-
* Eclipse with the IBM CICS SDK for Java EE, Jakarta EE and Liberty, or any IDE that supports usage of the Maven Central artifact [com.ibm.cics:com.ibm.cics.server.](https://search.maven.org/artifact/com.ibm.cics/com.ibm.cics.server)
54
+
> [!TIP]
55
+
> Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository.
39
56
40
-
57
+
## Building
58
+
59
+
You can build the sample in a variety of ways:
60
+
- Using the implicit compile/build of the Eclipse based CICS Explorer SDK
61
+
- Using the built-in Gradle or Maven support of your IDE (For example: *buildship* or *m2e* in Eclipse which integrate with the "Run As..." menu.)
62
+
- Using the supplied Gradle or Maven Wrapper scripts (no requirement for an IDE or Gradle/Maven install)
63
+
- or you can build it from the command line if you have Gradle or Maven installed on your workstation
64
+
41
65
42
-
## Configuration
66
+
> [!IMPORTANT]
67
+
> 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 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.
68
+
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 hello-web project. For example, in Eclipse: right-click on "Project", select "Gradle -> Refresh Gradle Project", **or** right-click on "Project", select "Maven -> Update Project...".
43
69
44
-
The sample Java classes are designed to be added to a dynamic web project and deployed into a Liberty JVM server as a WAR, either using the dropins directory or using
45
-
a CICS bundle project.
70
+
> [!TIP]
71
+
> 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.
46
72
47
73
74
+
### Option 1: Building with Eclipse
48
75
49
-
### To add the resources to Eclipse:
50
-
1. Using an Eclipse development environment create a dynamic web project called `com.ibm.cicsdev.restapp` and add the Java samples to the `src` folder
51
-
1. Add the CICS Liberty JVM server libraries to the build path of your project.
52
-
1. Ensure the web project is targeted to compile at a level that is compatible with the Java level being used on CICS. This can be achieved by editing the Java Project Facet in the project properties.
53
-
1. Create a CICS bundle project called `com.ibm.cicsdev.restapp.cicsbundle` and add a dynamic web project include for the project created in step 1.
76
+
If you are using the Egit client to clone the repo, remember to tick the button to import all projects. Otherwise, you should manually Import the projects into CICS Explorer using File → Import → General → Existing projects into workspace, then follow the error resolution advice above.
54
77
55
-
##Building the Sample
78
+
### Option 2: Building with Gradle
56
79
57
-
The sample can be built using Gradle or Maven to produce a WAR file and optionally a CICS Bundle archive.
80
+
For a complete build you should run the settings.gradle file in the top-level 'cics-java-liberty-restapp' directory which is designed to invoke the individual build.gradle files for each project.
58
81
59
-
### Building with Gradle
82
+
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.
60
83
61
-
A WAR file is created inside the `build/libs` directory and a CICS bundle ZIP file inside the `build/distributions` directory.
84
+
[!NOTE]
85
+
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.
62
86
63
-
If using the CICS bundle ZIP, the CICS JVM server name should be modified in the `cics.jvmserver` propertyin the gradle build [file](build.gradle)to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line.
87
+
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:
64
88
65
89
**Gradle Wrapper (Linux/Mac):**
66
90
```shell
@@ -79,11 +103,12 @@ gradle clean build
79
103
gradle clean build -Pcics.jvmserver=MYJVM
80
104
```
81
105
106
+
### Option 3: Building with Apache Maven
82
107
83
-
### Building with Apache Maven
84
-
A WAR file and a CICS bundle ZIP file are created inside the `target/` directory.
108
+
For a complete build you should run the pom.xml file in the top-level 'cics-java-liberty-hello' 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.
85
109
86
-
If building a CICS bundle ZIP the CICS bundle plugin bundle-war goal is driven using the maven verify phase. The CICS JVM server name should be modified in the `<cics.jvmserver>` property in the [`pom.xml`](pom.xml) to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line.
110
+
If building a CICS bundle ZIP the CICS JVM server name for the WAR bundle part should be modified in the
111
+
`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.
87
112
88
113
**Maven Wrapper (Linux/Mac):**
89
114
```shell
@@ -102,19 +127,32 @@ mvn clean verify
102
127
mvn clean verify -Dcics.jvmserver=MYJVM
103
128
```
104
129
105
-
## Deployment
106
-
### To start a JVM server in CICS:
107
-
1. Enable Java support in the CICS region by adding the `SDFJAUTH` library to the `STEPLIB` concatenation and setting `USSHOME` and the `JVMPROFILEDIR` SIT parameters.
108
-
* This step is **not** required if using CICS 5.5 or later
109
-
1. Define a Liberty JVM server called `DFHWLP` using the supplied sample definition `DFHWLP` in the CSD group `DFH$WLP`.
110
-
1. Copy the CICS sample `DFHWLP.jvmprofile` zFS file to the `JVMPROFILEDIR` directory specified above and ensure the `JAVA_HOME` variable is set correctly.
111
-
1. Add the `jaxrs-1.1` (or later version) Liberty feature to `server.xml` depending on your version of Java EE.
112
-
1. Install the `DFHWLP` resource defined in step 2 and ensure it becomes enabled.
130
+
## Deploying
131
+
132
+
### Configuring the Liberty JVM server
133
+
1. Create a Liberty JVM server.
134
+
2. Install the JVM server.
135
+
3. Add the `jaxrs-1.1` (or later version) Liberty feature to `server.xml` depending on your version of Java EE.
136
+
137
+
138
+
### Deploying CICS Bundles with CICS Explorer
139
+
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.
140
+
2. Export the bundle project to zFS by selecting 'Export Bundle project to z/OS Unix File System' from the context menu.
141
+
3. In CICS, create a bundle definition, setting the bundle directory attribute to the zFS location you just exported to, and install it.
142
+
143
+
### Deploying CICS Bundles from Gradle or Maven
144
+
1. Manually upload the ZIP file from the _cics-java-liberty-restapp-bundle/target_ or _cics-java-liberty-restapp-bundle/build/distributions_ directory to zFS.
145
+
2. Unzip this ZIP file on zFS (e.g. `${JAVA_HOME}/bin/jar xf /path/to/bundle.zip`).
146
+
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.
147
+
148
+
### Deploying directly with Liberty's application configuration
149
+
1. Manually upload the WAR file from the _cics-java-liberty-restapp-app/target_ or _cics-java-liberty-restapp-app/build/libs_ directory to zFS.
150
+
2. Add an `<application>` element to the Liberty server.xml to define the web application.
113
151
114
152
115
153
### To deploy the samples into a CICS region:
116
154
1. Using the CICS Explorer export the CICS bundle project to a zFS directory. The samples use the directory `/u/cics1/com.ibm.cicsdev.restapp.cicsbundle_1.0.0`.
117
-
1. Create a CICS BUNDLE definition referencing the zFS directory created in step 1.
155
+
1. Create a CICS BUNDLE definition.
118
156
1. Install the CICS BUNDLE resource.
119
157
1. Download and compile the supplied COBOL program `EDUCHAN` and deploy into CICS.
120
158
@@ -146,3 +184,11 @@ This will invoke the `ReverseResource` class which links to the CICS COBOL progr
This project is licensed under [Apache License Version 2.0](LICENSE).
189
+
190
+
## Usage terms
191
+
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:
192
+
193
+
• IBM CICS development components terms: https://www.ibm.com/support/customer/csol/terms/?id=L-ACRR-BBZLGX
0 commit comments