cicsdev/cics-eventprocessing-java

Sample Java™ web application to demonstrate how to emit and consume CICS® events in Java™ using the JCICS API

cics-eventprocessing-java

This Java web application demonstrates how to emit and consume CICS events in Java using the JCICS API.

Overview

This sample shows how to consume and emit CICS events using Java code. Events are emitted from a Java EE servlet using the JCICS Event API, equivalent to an EXEC CICS SIGNAL EVENT call. This event is processed by CICS event processing and is handled by an event processing adapter. This adapter is configured to call the CICS program EVNTCONS when an event is received.

The CICS program EVNTCONS is a Java EE program designed to consume CICS events and, in this basic sample, log that an event was received to STDOUT.

Requirements

• CICS TS V5.5 or later
• A configured Liberty JVM server
• Java SE 1.8 or later on the workstation
• Either Gradle or Apache Maven on the workstation (optional if using Wrappers)

Structure

The project consists of two parts:

1. cics-eventprocessing-java-webapp - the Java source code for this example
2. cics-eventprocessing-java-bundle - the bundle definition for this example

Code Structure

There are two Java classes:

1. EventEmitter.java - a servlet that emits CICS events
2. EventConsumer.java - the Java code to define the CICS program resource EVNTCONS and consume the CICS events

The code is built into a WAR file, packaged into a CICS bundle, and deployed to a Liberty JVM server as a web application.

Bundle Structure

The CICS bundle contains the following elements:

1. EVNT.transaction - transaction which targets the EVNTCONS program
2. ACCOUNTADAPTER.epadapter - event processing adapter which starts the EVNT transaction
3. ACCOUNT.evbind - event binding which targets the EVENTADAPTER adpater
4. WARBUNDLE - Java WAR bundle is added when built

Building

There are several ways to build this project. We suggest you build with a build toolkit such as Gradle or Maven.

Building with Gradle

./gradlew assemble

This will compile the Java code, build a WAR file and package it and the EP adapter and Event binding into a CICS bundle as a ZIP file at ./cics-eventprocessing-java-bundle/build/distributions/cics-eventprocessing-java-bundle-0.0.1-SNAPSHOT.zip

Building with Maven

./mvnw verify

This will compile the Java code, build a WAR file and package it and the EP adapter and Event binding into a CICS bundle as a ZIP file at ./cics-eventprocessing-java-bundle/target/cics-eventprocessing-java-bundle-0.0.1-SNAPSHOT.zip

Configuration

You will need to define a CICS Liberty JVM server with the name DFHWLP. This name can be modified in the pom.xml of the cics-eventprocessing-java-bundle module.

The Liberty JVM server will need the following features installed at a minimum: cicsts:core-1.0 and cicsts:link-1.0 and servlet-3.1. For example:

<server name="cics-eventprocessing-java">
    <featureManager>
        <feature>cicsts:core-1.0</feature>
        <feature>cicsts:link-1.0</feature>
        <feature>servlet-3.1</feature>
    </featureManager>
  
  <!-- More configuration -->
</server>

A template server.xml is provided here.

Deploying

1. Upload the built bundle ZIP file to zFS on your z/OS system in binary using FTP, or similar
2. Logon to zFS on your z/OS system using SSH, OMVS, or similar
3. Extract the ZIP file contents, for example using command unzip /path/to/bundle.zip
4. In CICS, define a new BUNDLE resource with the BUNDLEDIR set to the extracted ZIP file contents, then install the BUNDLE resource

You can confirm the application has started by inquiring the state of the BUNDLE, for example using transaction CEMT INQUIRE BUNDLE, or the CICS Explorer bundle view.

A message will be written to the Liberty messages.log file to confirm the application has started, and the base URL for this application.

Running

1. Use a browser to target the address http://my.zos:9080/cics-eventprocessing-java-webapp/emit?event=ACCOUNT replacing my.zos with the hostname of your z/OS system and 9080 with the port the Liberty JVM server is listening on.
2. View the JVM server CURRENT.STDOUT file, this should contain two log messages
   • Emitted event
   • Consumed event

You can also emit an event using EXEC CICS SIGNAL EVENT(event) either in another CICS program, or using transaction CECI.

License

This project is licensed under Eclipse Public License - v 2.0.

cics-eventprocessing-java's Issues

Gradle build does not include annotation processor

Issue 1

Gradle build does not produce annotation classes, and therefore the CICS program definition EVNTCONS is not automatically defined and installed.

cics-eventprocessing-java/cics-eventprocessing-java/cics-eventprocessing-java-webapp/build.gradle

Line 11 in 876a8ff

providedCompile 'com.ibm.cics:com.ibm.cics.server.invocation.annotations:5.5-PH25409'

Example that works is below, but this is based on CICS TS 5.5, but see below to switch to either 5.3 or 5.6.

    annotationProcessor enforcedPlatform('com.ibm.cics:com.ibm.cics.ts.bom:5.5-20200519131930-PH25409')
    annotationProcessor("com.ibm.cics:com.ibm.cics.server.invocation")
    compileOnly("com.ibm.cics:com.ibm.cics.server.invocation.annotations")

Issue 2

README.md says CICS TS V5.3 or later but the Gradle build is configured to use CICS TS 5.5 which neither matches the README.md nor is the latest. Suggest Gradle and Maven builds are either based on CICS TS 5.3 as should be forward compatible, or CICS TS 5.6 and instructions added to say if targeting different release to update build properties.

cics-eventprocessing-java/cics-eventprocessing-java/cics-eventprocessing-java-webapp/build.gradle

Line 11 in 876a8ff

providedCompile 'com.ibm.cics:com.ibm.cics.server.invocation.annotations:5.5-PH25409'

Suggestion 1

CICS topic Managing Java dependencies using Maven or Gradle says You're recommended to use the BOM to control version numbers of the other dependencies and omit their version numbers from their own specifications. but Gradle build does not BOMs.

Add CI builds.

Look at adding an automated build to the project to ensure the Java code compiles cleanly.

README.md refers to ?name=EVENT when it should be ?event=EVENT

README.md says

Use a browser to target the address http://my.zos:9080/cics-eventprocessing-java-webapp/emit?name=EVENT

when code says

cics-eventprocessing-java/cics-eventprocessing-java/cics-eventprocessing-java-webapp/src/main/java/com/ibm/cicsdev/eventprocessing/EventEmitter.java

Line 47 in 7fec2b9

String eventName = request.getParameter("event");

Example needs to use event named ACCOUNT

ACCOUNT.evbind requires the event to be named ACCOUNT at

cics-eventprocessing-java/cics-eventprocessing-java/cics-eventprocessing-java-bundle/src/main/bundleParts/ACCOUNT.evbind

Line 25 in 876a8ff

<EVENT keyword="EVENT" filterOperator="EQ" filterValue="ACCOUNT"/>

So when going to the URL in the README.md

http://my.zos:9080/cics-eventprocessing-java-webapp/emit?event=EVENT

The event is not captured as described.