cics-java-liberty-restapp

Sample RESTful web application for deployment to a Liberty JVM server in CICS. The application is supplied with two 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.
2. 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.

The following Java source components are supplied in the src/main/java directory in this repository.

Java package com.ibm.cicsdev.restapp

• CICSApplication - Sets the ApplicationPath for resources in this application
• InfoResource - Returns JSON structure using CICSInformation bean
• ReverseResource - Returns JSON structure using ReverseResult bean

Java package com.ibm.cicsdev.restapp.bean

• CICSEnvironment - JAXB bean returning JSON structure containing information about CICS product and version
• CICSInformation - JAXB bean returning JSON structure containing CICS applid, time and JVM server name and instance of CICSEnvironment
• ReverseResult - JAXB bean returning JSON structure containg input and output containers sent to EDUCHAN COBOL program

Supporting files

• DFHCSD.txt - Output from a DFHCSDUP EXTRACT for the CICS BUNDLE resource definition.
• EDUCHAN.cbl - A sample CICS COBOL that returns the date and time and reversed input using channels and containers
• build.gradle - A sample Gradle build file to enable an automated build of the deployable WAR
• pom.xml - A sample Maven build file to enable an automated build of the deployable WAR

Pre-reqs

• CICS TS V5.1 or later, due to the usage of the getString() methods.
• Java SE 1.8 or later on the workstation
• 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.

Configuration

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 a CICS bundle project.

To add the resources to Eclipse:

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
2. Add the CICS Liberty JVM server libraries to the build path of your project.
3. 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.
4. 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.

Building the Example

The sample can be built using the supplied Gradle or Maven build files to produce a WAR file and optionally a CICS Bundle archive.

Gradle (command line)

Run the following in a local command prompt:

gradle clean build

This creates a WAR file inside the build/libs directory and a CICS bundle ZIP file inside the build/distributions directory.

If using the CICS bundle ZIP, the CICS JVM server name should be modified in the jvmserver property in the gradle build properties file to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line as follows.

gradle clean build -Pjvmserver=MYJVM

Maven (command line)

Run the following in a local command prompt which will create a WAR file for deployment.

mvn clean verify

This creates a WAR file in the target directory.

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 property in the pom.xml to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line as follows.

mvn clean verify -Djvmserver=MYJVM

To start a JVM server in CICS:

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.
   • This step is not required if using CICS 5.5 or later
2. Define a Liberty JVM server called DFHWLP using the supplied sample definition DFHWLP in the CSD group DFH$WLP.
3. Copy the CICS sample DFHWLP.jvmprofile zFS file to the JVMPROFILEDIR directory specified above and ensure the JAVA_HOME variable is set correctly.
4. Add the jaxrs-1.1 (or later version) Liberty feature to server.xml depending on your version of Java EE.
5. Install the DFHWLP resource defined in step 2 and ensure it becomes enabled.

To deploy the samples into a CICS region:

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.
2. Create a CICS BUNDLE definition referencing the zFS directory created in step 1.
3. Install the CICS BUNDLE resource.
4. Download and compile the supplied COBOL program EDUCHAN and deploy into CICS.

Note: sample DFHCSDUP EXTRACT output for the required CICS resource definitions is supplied in the supporting file DFHCSD.txt file.

Running the Example

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:

{"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

This will invoke the ReverseResource class which links to the CICS COBOL program reversing the input string "ilovecics" as follows:

{"time":"2016-09-09T16:15:32.466Z","original":"ilovecics","reverse":"scicevoli","truncated":false}