[Java] Moving CICS-Java applications-(3) build management with Gradle

11 minute read

Introduction

Gradle, along with Maven, is also supported as a build management tool for CICS-Java applications in CICS TS V5.6. Here, try the build management of the CICS-Java application using Gradle.

Related article

Run CICS-Java application-(1) Running simple sample application Run CICS-Java application-(2) Maven build management Run CICS-Java application-(3) Build management by Gradle Move CICS-Java application-(4) Spring Boot application

Advance preparation

This is similar to the Maven case. (Use Gradle instead of Maven)

Suitable Java EE development environment

Please use those that can develop Java EE applications such as Eclipse and VS Code. Since I will use the sample as it is, I do not need to edit the source, so I do not need to use it, but normally I will use some development environment. It would be nice to be able to work with Gradle, git, etc. If you want to use CICS Explorer together, use Eclipse.

CICS Explorer

This is also not required, but it can be used to check the resource definition of CICS. Refer to the following and download and set up an Eclipse-based tool called CICS Explorer. Reference: Downloading and starting CICS Explorer *This tool is free for CICS users.

Gradle

Follow the steps below to install. Installing Gradle Basically, just unzip the downloaded one and pass it through the path.

As a prerequisite, Java 8 or later is required.

c:\>java -version
java version "1.8.0_144"
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

Download the latest version of Gradle V6.5 from the following (gradle-6.5.zip). Releases

Extract to an appropriate directory. (Here (c:\x\Gradle\gradle-6.5) Add the extracted bin (C:\x\Gradle\gradle-6.5\bin) to your PATH.

Confirmation

c:\>gradle -v

- ------------------------------------------------- ----------
Gradle 6.5
- ------------------------------------------------- ----------

Build time: 2020-06-02 20:46:21 UTC
Revision: a27f41e4ae5e8a41ab9b19f8dd6d86d7b384dad4

Kotlin: 1.3.72
Groovy: 2.5.11
Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM: 1.8.0_144 (Oracle Corporation 25.144-b01)
OS: Windows 10 10.0 amd64

This is OK.

git

Since you will be using the sample provided on gitHub, install git as well. The setup method etc. is omitted because it is rolling around there.

c:\>git --version
git version 2.21.0.windows.1

Execution environment (z/OS, CICS)

*The host side is exactly the same as Maven’s case. If you have already executed the Maven scenario, you can use the same one as it is.

Prepare a CICS region to run the sample. We will use a region named CT56B4A1 under CICSplex management. Add a resource called JVMServer to run the Java application. This time, since the sample (JavaEE application) for CICS-Liberty is used, create JVMServer for Liberty.

JVM profile

Prepare a JVM profile on USS. (The properties related to JVMServer are effectively specified in a file on this USS. The JVMSERVER resource definition points to the file name of this JVM profile.) A sample is provided so you can copy it and use it.

Create a directory called /var/cicsts/cicsts56/CT56B4A1/JVMProfiles and copy /usr/lpp/cicsts/cicsts56/JVMProfiles/DFHOSGI.jvmprofile (sample definition for OSGi located under the CICS installation directory) into it. To do. Customize as appropriate for your environment.

DFHWLP.jvmprofile excerpt


JAVA_HOME=/usr/lpp/java/J8.0_64/
WORK_DIR=/var/cicsts/cicsts56/CT56B4A1/work
WLP_INSTALL_DIR=/usr/lpp/cicsts/cicsts56/wlp
- Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true
- Dcom.ibm.cics.jvmserver.wlp.server.host=*
- Dcom.ibm.cics.jvmserver.wlp.server.http.port=56441
- Dcom.ibm.cics.jvmserver.wlp.server.https.port=56451
- Xms128M
- Xmx256M
- Xmso1M
- Xgcpolicy:gencon
- Xscmx256M
- Xshareclasses:name=cicsts%g,groupAccess,nonfatal
- Xtune:virtualized
- Dcom.ibm.tools.attach.enable=no
- Dfile.encoding=ISO-8859-1
_BPXK_DISABLE_SHLIB=YES

SIT

Specify the directory where the above property file is placed in the SIT parameter “JVMPROFILEDIR”.

JVMPROFILEDIR=/var/cicsts/cicsts56/CT56B4A1/JVMProfiles

Restart the region for the changes to take effect.

JVMServer definition

Prepare the JVMSERVER resource definition. Copy the JVMSERVER definition “DFHWLP” in the product-provided DFH$WLP group and install it.

OBJECT CHARACTERISTICS CICS RELEASE = 0730
 CEDA View JVmserver( DFHWLP)
  JVmserver: DFHWLP
  Group: TAGGRP
  DEScription: CICS JVM server to run WLP samples
  Status: Enabled Enabled | Disabled
  Jvmprofile :DFHWLP (Mixed Case
  Lerunopts: DFHAXRO
  Threadlimit: 015 1-256
 DEFINITION SIGNATURE
  DEFinetime: 06/04/20 16:20:21
  CHANGETime: 06/04/20 16:20:21
  CHANGEUsrid: CICSUSER
  CHANGEAGEnt :CSDApi CSDApi | CSDBatch
  CHANGEAGRel: 0730

*Jvmprofile: DFHWLP, but this means that the file DFHWLP.jvmprofile under the directory specified in JVMPROFILEDIR of SIT is used as the JVM property file.It is OK if CEMT I JVM SERVER shows Enable.

I JVMS
STATUS: RESULTS-OVERTYPE TO MODIFY
 Jvm(DFHWLP )Ena Prf(DFHWLP )Ler(DFHAXRO)
    Threadc(005) Threadl( 015) Cur(48314096)

CICS Bundle Deployment API

You must have set up the CICS Bundle Deployment API, which is now provided by CICS TS V5.6. This feature was added for application deployment as one of the REST-based management APIs called CMCI. Set up CMCI on the WUI server that manages the target CICS region and specify the parameters for the CICS Bundle Deployment API in the properties of the CMCI JVM server. Reference: How it works: CICS bundle deployment API

The minimum required settings are as follows. Create a directory for placing Bundle files on USS. Here it is /var/cicsts/cicsts56/bundles. Set the following parameters in the JVM profile (EYUCMCIJ.jvmprofile) for CMCI JVM Server of WUI. -Dcom.ibm.cics.jvmserver.cmci.bundles.dir=/var/cicsts/cicsts56/bundles

Sample operation check

Clone locally

Clone https://github.com/IBM/cics-bundle-gradle.git to an appropriate directory on your local PC.

C:\y\workspace\cicsts56>git clone https://github.com/IBM/cics-bundle-gradle.git
Cloning into'cics-bundle-gradle'...
remote: Enumerating objects: 125, done.
remote: Counting objects: 100% (125/125), done.
remote: Compressing objects: 100% (87/87), done.
remote: Total 1855 (delta 43), reused 86 (delta 13), pack-reused 1730Receiving objects: 99% (1837/1855), 2.08 MiB | 2.01 MiB/s
Receiving objects: 100% (1855/1855), 4.19 MiB | 2.83 MiB/s, done.
Resolving deltas: 100% (610/610), done.

Understanding the file structure

Since the sample called gradle-multipart-sample below samples is used, move the directory and check the file structure.

C:\y\workspace\cicsts56\cics-bundle-gradle\samples\gradle-multipart-sample>tree /f /a
Folder Path List: Volume Windows
Volume serial number is 1866-E2FC
C:.
| build.gradle
| gradlew
| gradlew.bat
| README.md
| settings.gradle
|
+---gradle
| \---wrapper
| gradle-wrapper.jar
| gradle-wrapper.properties
|
+---gradle-bundle-demo
| build.gradle
|
\---gradle-war-demo
    | build.gradle
    |
    \---src
        \---main
            +---java
            | \---demo
            | SimpleServlet.java
            |
            \---web-app
                | index.html
                | index.js
                | style.css
                |
                +---images
                | cics.png
                |
                \---WEB-INF
                        web.xml


There are multiple build.gradle and it has a hierarchical structure, but this is a structure of Gradle’s “multi project”. Reference: Basic of multi-project with Gradle

Normally, when creating a CICS-Java application, create an OSGi project (jar) or Web project (WAR) that is the main body of the application, create a CICS bundle project to organize the application, and deploy these as a package. To do that. In this sample, the gradle-war-demo part corresponds to the application main body (WAR) project, and the gradle-bundle-demo part corresponds to the CICS bundle project. It is summarized in the gradle-multipart-sample project. The relationship of build.gradle is summarized as follows. image.png

It seems that you can also display the project relationships with the following command.

c:\y\workspace\cicsts56\cics-bundle-gradle\samples\gradle-multipart-sample>gradle -q projects

- ------------------------------------------------- ----------
Root project
- ------------------------------------------------- ----------

Root project'gradle-multipart-sample'
+--- Project':gradle-bundle-demo'
\--- Project':gradle-war-demo'

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :gradle-bundle-demo-test04:tasks

Check/edit contents

gradle-war-demo (javaEE application)

This is a web application that is supposed to run on CICS-Liberty. Implemented with simple html and Servlet. (It looks like the Maven sample)

SimpleServlet.java


package demo;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.ibm.cics.server.InvalidRequestException;
import com.ibm.cics.server.Task;

/**
 * Servlet implementation class SimpleServlet
 */
@WebServlet("/SimpleServlet")
public class SimpleServlet extends HttpServlet {
    private static final long serialVersionUID = 1L;

    /**
     * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse response)
     */
    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        response.setContentType("text/html");

        response.getWriter().print("Hello world!");
        Task task = Task.getTask();

        try {
            String userid = task.getUSERID();
            response.setContentType("text/html");
            response.getWriter().print("\nI am "+ userid);
        } catch (InvalidRequestException e) {
            throw new RuntimeException(e);
        }
    }

}

The process of acquiring the object of the own task running in the JCICS Task Class, and acquiring and displaying the user information that is executing itself from that object is performed.There is no need to change the application itself, so just check the contents.

gradle-bundle-demo (CICS bundle)

Normally, when creating a CICS-Java application with CICS Explorer (when Gradle is not used), you will create a CICS bundle project and set the applications (WAR, OSGi, etc.) to be embedded in it. As a result, files such as cics.xml and xxx.warbundle will be created.

This is the part corresponding to the CICS bundle project, but only build.gradle exists. It seems that the Gradle plugin (cics-bundle-gradle) provided by CICS will automatically create the files required for the CICS bundle project by specifying the dependencies using the Gradle mechanism. Therefore, as a user, you only have to make necessary settings in build.gradle and do not have to be directly aware of the CICS bundle project.

Edit build.gradle to suit your environment. Changes are described in comments (1) to (7)

plugins {
    id'com.ibm.cics.bundle' version '1.0.0'
}

group'com.ibm.cics'
version '1.0.0'

repositories {
    mavenCentral()
}

cicsBundle {
    build {
        defaultJVMServer ='DFHWLP' // (1)JVMSERVER name
    }
    deploy {
        cicsplex ='C73PLX' // (2) CICSplex name to which the target CICS region belongs
        region ='CT56B4A1' // (3) Target CICS region name
        bunddef ='GRDBUNDL' // (4) Bundle definition resource name defined in the target CICS region
        csdgroup ='TAGGRP' // (5) CSD group name to which the bundle definition of (4) belongs
        url ='http://etp1:56002' // (6) WCI CMCI URL
        username ='TAG' // (7) With the user used when issuing the Deployment API by CMCI
        password ='********' // password
        //caution: uncomment the line below to disable TLS/SSL checking for certificates
        //insecure = true
    }
}

dependencies {
    cicsBundlePart group:'org.codehaus.cargo', name:'simple-war', version: '1.7.7', ext:'war'
    cicsBundlePart project(path:':gradle-war-demo', configuration:'archives')
}

I changed the directory name of the project for the CICS bundle from gradle-bundle-demo to gradle-bundle-demo-test04. This directory name will be used as the directory name when transferring products to USS. The directory <CICS bundle project name>_<version> is created in the bundle directory directory (/var/cicsts/cicsts56/bundles) specified in the WUI JVM Server, and various files are created. Will be expanded. Example: /var/cicsts/cicsts56/gradle-bundle-demo-test04_1.0.0/

Other changed parameters are as follows.

(1)defaultjvmserver: Specify the JVM SERVER name to run the application. It must be installed in the target CICS region beforehand. (2)cicsplex: CICSplex name to which the target CICS region belongs (3)region: Target CICS region name (4)bunddef: Bundle definition resource name defined in the target CICS region (5)csdgroup: CSD group name to which the bundle definition of (5) belongs (6)url: Specify the CMCI URL of the WUI. The CICS Bundle Deployment API must be enabled for this WUI. (If it is a template, there is no description of http://, but if you do not specify this, an error will occur!) (7)username/password: User and password used when issuing Deployment API by CMCI

*The build/deploy operation is not done here yet.

Since we have changed the project directory name, we will also modify the parent setting.gradle accordingly.

setting.gradle


rootProject.name ='gradle-multipart-sample'
include'gradle-war-demo'
include'gradle-bundle-demo-test04'

BUNDLE definition creation

Create a bundle definition according to the contents specified in build.gradle above.

OBJECT CHARACTERISTICS CICS RELEASE = 0730
 CEDA View Bundle( GRDBUNDL)
  Bundle: GRDBUNDL
  Group: TAGGRP
  DEScription: CICS-BUNDLE-DEMO
  Status: Enabled Enabled | Disabled
  BUndledir: /var/cicsts/cicsts56/bundles/gradle-bundle-demo-test04_1.0
  (Mixed Case): .0
                 :
                 :
                 :
  BAsescope:
  (Mixed Case):
                 :
                 :
                 :
 DEFINITION SIGNATURE
  DEFinetime: 06/17/20 14:19:33

Specify CSD group (5), BUNDLE definition name (4), and BUNDLEDIR based on the project directory name and version information values. *We will not install it yet

Sample correction

It seems that it will be corrected soon, but there is a flaw in the directory structure of the provided sample, and if you perform the subsequent processing as it is, the sample will not work well. There is a directory called ...\gradle-multipart-sample\gradle-war-demo\src\main\web-app\, but change this web-app to webapp. Let’s remove the hyphen. As the operation of Gradle’s War plugin, by default the files under webapp are copied at the time of WAR creation, but in the sample it is web-app, so web.xml and index.html under this directory Etc. are not copied, and the sample application cannot be called.

Reference: Gradle-The War Plugin>The default behavior of the War task is to copy the content of src/main/webapp to the root of the archive.Your webapp directory may of course contain a WEB-INF sub-directory, which may contain a web.xml file. Your compiled classes are compiled to WEB-INF/classes.All the dependencies of the runtime [1] configuration are copied to WEB-INF/lib.

Build/deploy execution

  • In the following procedure, the build “gradelw build” and the deploy “gradlew deployCICSBundle” are executed in two stages, but the build-deploy execution is also performed with only the latter command.

To build, execute the following command under the gradle-multipart-sample directory. At first, it takes time because the necessary packages are downloaded.

c:\y\workspace\cicsts56\cics-bundle-gradle\samples\gradle-multipart-sample>gradlew build
Downloading https://services.gradle.org/distributions/gradle-5.0-all.zip
.................................................. .................................................. .......................

Welcome to Gradle 5.0!

Here are the highlights of this release:
 -Kotlin DSL 1.0
 -Task timeouts
 -Dependency alignment aka BOM support
 -Interactive `gradle init`

For more details see https://docs.gradle.org/5.0/release-notes.html

Starting a Gradle Daemon (subsequent builds will be faster)

> Task :gradle-bundle-demo-test04:buildCICSBundle
Adding Java-based bundle parts from'cicsBundlePart' dependency configuration
Adding Java-based bundle part:'C:\Users\TomohiroTaguchi\.gradle\caches\modules-2\files-2.1\org.codehaus.cargo\simple-war\1.7.7\5f462015066db63c2e240b4fc3674c6f4910bb73\simple-war-1.7. 7.war'
Adding Java-based bundle part:'C:\y\workspace\cicsts56\cics-bundle-gradle\samples\gradle-multipart-sample\gradle-war-demo\build\libs\gradle-war-demo-1.0.0 .war'
Adding non-Java-based bundle parts from'src/main/resources'

BUILD SUCCESSFUL in 1m 12s
4 actionable tasks: 4 executed

The project is now built. Under the gradle-bundle-demo directory, each file of the CICS bundle project and the zip file (used at the time of deployment) that collects them are generated.

c:\y\workspace\cicsts56\cics-bundle-gradle\samples\gradle-multipart-sample>tree gradle-bundle-demo-test04 /f /a
Folder Path List: Volume Windows
Volume serial number is 1866-E2FC
C:\Y\WORKSPACE\CICSTS56\CICS-BUNDLE-GRADLE\SAMPLES\GRADLE-MULTIPART-SAMPLE\GRADLE-BUNDLE-DEMO-TEST04
| build.gradle
|
\---build
    +---distributions
    | gradle-bundle-demo-test04-1.0.0.zip
    |
    \---gradle-bundle-demo-test04-1.0.0
        | gradle-war-demo-1.0.0.war
        | gradle-war-demo-1.0.0.warbundle
        | simple-war-1.7.7.war
        | simple-war-1.7.7.warbundle
        |
        \---META-INF
                cics.xml

Next, deploy the work. Execute the following command under the gradle-multipart-sample directory.

c:\y\workspace\cicsts56\cics-bundle-gradle\samples\gradle-multipart-sample>gradlew deployCICSBundle

> Task :gradle-bundle-demo-test04:deployCICSBundle
Task deployCICSBundle

BUILD SUCCESSFUL in 12s
5 actionable tasks: 1 executed, 4 up-to-date

If you look at the status of bundles and bundle parts in CICS Explorer, you can see that they have been successfully installed and enabled. image.png

In other words, the following processing has been performed with the above Gradle command.

Build: Compile Java EE application (gradle-war-demo)/create WAR, generate CICS bundle (gradle-bundle-demo) Package: related module packaging Deploy: Transfer/Unzip CICS Bundle File to USS, Install BUNDLE Definition

Application operation check

Try accessing the application deployed in Liberty running on the target CICS from the browser. image.png

Since it is running as the default user “CICSUSER”, its user name is displayed.

With this, we were able to confirm that the application was running properly!