Skip to content

Commit 2583aa4

Browse files
SoftlySplinterSoftlySplinter
authored
Add documentation around Maven/Gradle
1 parent 2eaab13 commit 2583aa4

File tree

1 file changed

+127
-20
lines changed

1 file changed

+127
-20
lines changed

‎README.md‎

Lines changed: 127 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,153 @@
11
# cics-java-liberty-link
22
[![Build](https://github.com/SoftlySplinter/cics-java-liberty-link/actions/workflows/java.yaml/badge.svg)](https://github.com/SoftlySplinter/cics-java-liberty-link/actions/workflows/java.yaml)
33

4-
Sample CICS Java program showing use of the com.ibm.cics.server.invocation.CICSProgram annotation for Link to Liberty.
5-
6-
## License
7-
This project is licensed under [Apache License Version 2.0](LICENSE).
4+
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.
85

96
## Contents
107
This is a set of sample Eclipse projects for Link to Liberty, demonstrating how you can annotate a POJO packaged in a WAR in a Liberty JVM server, to allow it be called from a CICS program.
118

12-
- projects/com.ibm.cics.server.examples.wlp.link - Web project
13-
- projects/com.ibm.cics.server.examples.wlp.link.bundle - CICS bundle project
9+
- [cics-java-liberty-link-app](./cics-java-liberty-link-app) - Web project
10+
- [cics-java-liberty-link-bundle](./cics-java-liberty-link-bundle) - CICS bundle project (Maven/Gradle)
11+
- [etc/config/liberty/server.xml](./etc/config/liberty/server.xml) - Template `server.xml` file.
12+
- [etc/eclipse_projects/com.ibm.cics.server.examples.wlp.link.bundle](./etc/eclipse_projects/com.ibm.cics.server.examples.wlp.link.bundle) - CICS bundle project (CICS Explorer)
1413

1514
## Prerequisites
1615
* CICS TS V5.4 or later
1716
* Java SE 1.8 or later on the workstation
1817
* 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)
18+
* Either Gradle or Apache Maven on the workstation (optional if using Wrappers)
19+
20+
## Downloading
21+
22+
- Clone the repository using your IDEs support, such as the Eclipse Git plugin
23+
- **or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-liberty-springboot-jcics/archive/main.zip) and unzip onto the workstation
24+
25+
>*Tip: Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository.*
26+
27+
### Check dependencies
28+
29+
Before building this sample, you should verify that the correct CICS TS bill of materials (BOM) is specified for your target release of CICS. The BOM specifies a consistent set of artifacts, and adds information about their scope. In the example below the version specified is compatible with CICS TS V5.5 with JCICS APAR PH25409, or newer. That is, the Java byte codes built by compiling against this version of JCICS will be compatible with later CICS TS versions and subsequent JCICS APARs.
30+
You can browse the published versions of the CICS BOM at [Maven Central.](https://mvnrepository.com/artifact/com.ibm.cics/com.ibm.cics.ts.bom)
31+
32+
Gradle (build.gradle):
33+
34+
`compileOnly enforcedPlatform("com.ibm.cics:com.ibm.cics.ts.bom:5.5-20200519131930-PH25409")`
35+
36+
Maven (POM.xml):
37+
38+
``` xml
39+
<dependencyManagement>
40+
<dependencies>
41+
<dependency>
42+
<groupId>com.ibm.cics</groupId>
43+
<artifactId>com.ibm.cics.ts.bom</artifactId>
44+
<version>5.5-20200519131930-PH25409</version>
45+
<type>pom</type>
46+
<scope>import</scope>
47+
</dependency>
48+
</dependencies>
49+
</dependencyManagement>
50+
```
51+
52+
## Building
53+
54+
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.
55+
56+
On the command line, you simply swap the Gradle or Maven command for the wrapper equivalent, `gradlew` or `mvnw` respectively.
57+
58+
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.
59+
60+
The required build-tasks are typically `clean bootWar` for Gradle and `clean package` for Maven. Once run, Gradle will generate a WAR file in the `build/libs` directory, while Maven will generate it in the `target` directory.
61+
62+
**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.
63+
64+
**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...".
65+
66+
>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.*
67+
68+
### Eclipse
69+
70+
Import the projects into CICS Explorer using File &rarr; Import &rarr; General &rarr; Existing projects into workspace.
71+
> **Note:** If using the egit client, you can just clone the repo and tick the button to import all projects.
72+
73+
### Gradle Wrapper (command line)
74+
75+
Run the following in a local command prompt:
76+
77+
On Linux or Mac:
78+
79+
```shell
80+
./gradlew clean bootWar
81+
```
82+
On Windows:
83+
84+
```shell
85+
gradlew.bat clean bootWar
86+
```
1987

88+
This creates a WAR file inside the `build/libs` directory.
2089

21-
## Deploying the sample
22-
1. Import the projects into CICS Explorer using File -> Import -> General -> Existing projects into workspace.
23-
- If using the egit client, you can just clone the repo and tick the button to import all projects.
24-
2. Change the name of the JVMSERVER in the .warbundle file from DFHWLP to the name of the JVMSERVER resource defined in CICS.
25-
3. Export the bundle project to zFS by selecting 'Export Bundle project to z/OS Unix File System' from the context menu.
26-
4. Ensure the `cicsts:link-1.0` feature is present in server.xml and the JVMSERVER is ENABLED.
27-
5. Create a bundle definition, setting the bundle directory attribute to the zFS location you just exported to, and install it.
28-
6. Check the CICS region for the dynamically created PROGRAM resource HELLOWLP using the PROGRAMS view in CICS Explorer, or the CEMT INQUIRE PROGRAM command.
90+
### Maven Wrapper (command line)
2991

30-
## Trying out the sample
31-
You can use CECI to invoke the sample program:
32-
`CECI LINK PROGRAM(HELLOWLP)`
33-
and look for output in the STDOUT location for the JVMSERVER.
92+
93+
Run the following in a local command prompt:
94+
95+
On Linux or Mac:
96+
97+
```shell
98+
./mvnw clean package
99+
```
100+
101+
On Windows:
102+
103+
```shell
104+
mvnw.cmd clean package
105+
```
106+
107+
This creates a WAR file inside the `target` directory.
108+
109+
## Deploying to a Liberty JVM server
110+
111+
Ensure you have the following features defined in your Liberty server.xml:
112+
* `cicsts:link-1.0`
113+
114+
A template server.xml is provided [here](./etc/config/liberty/server.xml).
115+
116+
### Deploying CICS Bundles with CICS Explorer
117+
1. Change the name of the JVMSERVER in the .warbundle file of the CICS bundle project from DFHWLP to the name of the JVMSERVER resource defined in CICS.
118+
2. Export the bundle project to zFS by selecting 'Export Bundle project to z/OS Unix File System' from the context menu.
119+
3. Create a bundle definition, setting the bundle directory attribute to the zFS location you just exported to, and install it.
120+
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.
121+
122+
### Deploying CICS Bundles from Gradle or Maven
123+
TODO
124+
125+
### Deploying with Liberty configuration
126+
1. Manually upload the WAR file from the _cics-java-liberty-link-app/target_ or _cics-java-liberty-link-app/buid/libs_ directory to zFS.
127+
2. Add an `<application>` element to the Liberty server.xml to define the web application.
128+
129+
130+
## Running
131+
132+
You can use the CECI transaction to invoke the sample program:
133+
134+
```text
135+
CECI LINK PROGRAM(HELLOWLP)
136+
```
137+
138+
The program prints a message to the STDOUT output stream of the JVM server it runs on.
34139

35140
You can pass a channel with a container:
36141

37142
```text
38143
CECI PUT CONTAINER(NAME) CHAR FROM(MATTHEW) CHANNEL(CHAN)
39-
40144
CECI LINK PROG(HELLOWLP) CHANNEL(CHAN)
41145
```
42146

43-
(ensure both commands are entered in the same CECI session)
147+
(ensure both commands are entered in the same CECI session).
44148

45149
## Find out more
46150
For more information on invoking Java EE applications in a Liberty JVM server from CICS programs see [this article](https://developer.ibm.com/cics/2016/11/14/link-to-liberty-now-available-in-cics-ts-v5-3/).
151+
152+
## License
153+
This project is licensed under [Apache License Version 2.0](LICENSE).

0 commit comments

Comments
 (0)