In total there are currently three mechanisms for deploying applications to Liberty JVM servers in CICS. If you’re already familiar with OSGi JVM servers and CICS bundles, the CICS BUNDLE resource can be used to install applications to Liberty JVM servers in the same way they’re installed to OSGi JVM servers. Alongside the traditional CICS route, the Liberty runtime provides two additional means of installing applications.

This article will take you through using a deployment mechanism called dropins. Prior to starting this article you’re going to need to have completed the previous two articles in this series. You can find the links for these articles here:

Developing Liberty applications for CICS: Part 1 – Setting up an effective development environment

Developing Liberty applications for CICS: Part 2 – Writing your first application

Please note that although useful for testing applications, dropins is not suited for production level environments as it does not allow you to use security in applications deployed this way.

Step 1 – Enable dropins for your Liberty JVM server

First we’re going to need to make sure the dropins mechanism is enabled for your Liberty JVM server. To do this we’re going to open up the server.xml configuration file for your Liberty JVM server using Eclipse. In your Eclipse environment, locate the z/OS UNIX Files view. You may need to reconnect to your system again using Host Connections. In the z/OS UNIX Files view, use the filter box to navigate to the WORK_DIR of your JVM server. (If you don’t know where this is, you can find out by looking at your .jvmprofile file).

On CICS TS V5.3 onwards you will see a symbolic link to the liberty configuration directory called wlp.defaultServer.config, expand that directory and open the file called server.xml. This file is a simple XML structure which describes the technologies the server is using. You can use this file to add or remove Java EE features from your JVM server’s runtime, or change other configurable options such as how often Liberty scans for updates.

<?xml version="1.0" encoding="UTF-8"?>
<server description="CICS Liberty profile sample configuration">

    <!-- Enable features -->
    <featureManager>
        <feature>cicsts:core-1.0</feature>
        <feature>jsp-2.3</feature>
	<feature>ssl-1.0</feature>
    </featureManager>

    <!-- Default HTTP End Point -->
    <httpEndpoint host="*" httpPort="26013" httpsPort="26054" id="defaultHttpEndpoint"/>

    <!-- CICS Bundle Installed Applications -->
    <include location="${server.output.dir}/installedApps.xml"/>
  
    <config monitorInterval="5s" updateTrigger="polled"/>

    <applicationMonitor dropins="dropins" dropinsEnabled="false" pollingRate="5s" updateTrigger="disabled"/>

    <executor id="allowCICSconfigure" maxThreads="15"/>

</server>

One of the configurable mechanisms in Liberty is the application monitor. The application monitor looks for changes to Liberty applications so that it can keep them up to date. The XML tag for the application manager provides the configuration option for dropins.

<applicationMonitor dropins="dropins" dropinsEnabled="true" pollingRate="5s" updateTrigger="disabled"/>

dropins is a location in Liberty’s directory structure which will be monitored for applications. When you copy a valid application into the directory, it will automatically be installed and made available by Liberty. It’s a fantastic way to quickly test changes or new applications. To enable dropins, simply change the dropinsEnabled value to true.

You can also use this configuration tag to change the location of dropins if you like. Liberty will then automatically create the required directory. By default you can find it alongside server.xml in the swlp.defaultServer.config directory.

Step 2 – FTP your application to your system

Now that your dropins functionality has been enabled, we need to compile the application in your Eclipse environment, and export it to the USS directory to get Liberty to pick it up.

In the Project Explorer view of Eclipse, right click on your dynamic web project (The project created in part one) and select Export from the menu. In the export wizard, type WAR into the filter box, then select WAR file from the list and press Next >. In the following panel, pick a destination on your local machine.

The 'Export WAR' wizard in Eclipse
The ‘Export WAR’ wizard in Eclipse

Next you need to use an ftp client to transfer the resulting .war file to your USS dropins directory. Make sure to set your ftp client’s transfer mode to binary.

Personally, I like to use command line ftp. To change the transfer mode in command line ftp, simply enter the command type binary to switch to binary transfer mode.

Step 3 – Use Eclipse to check Liberty’s logs

Once you’ve transferred the .war file across to the dropins directory on your USS file system, Liberty will automatically try to install and enable it. We’re going to use Liberty’s primary logging file, messages.log, to check that no problems occurred when it started your application.

Locate the z/OS Unix Files view in your Eclipse environment. If you’re still in the Liberty configuration directory (the directory containing server.xml) simply expand out the directory called logs to find Liberty’s messages.log file and open it.

If you’re not in the configuration directory already, go to the Java work directory for your JVM server, and expand out the symlink for wlp.defaultServer.logs. This will take you to the directory containing the messages.log file. Open up the log once you’re there.

[4/29/16 14:39:04:638 GMT] 0000003b com.ibm.ws.webcontainer                                      I SRVE0250I: Web Module iberty.tutorial has been bound to default_host.
[4/29/16 14:39:04:639 GMT] 0000003b com.ibm.ws.http.internal.VirtualHostImpl                     A CWWKT0016I: Web application available (default_host): http://winmvs2c.hursley.ibm.com:26013/liberty.tutorial/
[4/29/16 14:39:04:739 GMT] 00000040 com.ibm.ws.app.manager.AppMessageHelper                      A CWWKZ0001I: Application liberty.tutorial started in 1.338 seconds.

In your logs, look for the log entries listed above. These are the three standard messages printed out to the log whenever a web application is installed successfully.

The first message tells you that your application has been picked up and that it has a web component. The second message tells you the URI for your web application and the final message simply indicates that Liberty has successfully started your application.

Step 4 – Test your application

Now Liberty has confirmed your application is available, we can send it a HTTP GET request to it.

We can use the URI provided by Liberty in its logs to get most of our servlet’s address. Liberty will tell us the host and port, as well as something called the context root. The context root forms the basis of where your web application’s HTTP endpoints are enabled and is a configurable option, outlined in the web.xml file inside your web application. Any servlets you have in your dynamic web project will be made available on the context root. To call our servlet, you simply need to add on the servlet’s class name to the end of the URI reported by Liberty, for a class called SimpleServlet it would look something like this:

http://winmvs2c.hursley.ibm.com:26013/liberty.tutorial/SimpleServlet

It’s worth noting that although your servlet has a class name of SimpleServlet, you don’t have to use that name to decide it’s URL. You can actually change the value to be any valid String. However since we didn’t change it in this tutorial, we can safely assume it will use the same name as the class. If you visit the address using your web browser, you should receive the following response, demonstrating that your application is working:

HTTP response from SimpleServlet
HTTP response from SimpleServlet

If you successfully receive a response from CICS, your first application is officially completed and deployed. That completes our introductory tutorial on applications in Liberty. In this series we’ve shown you everything you need to write and deploy applications. The application we’ve written in this series is a very simple example, but the Liberty support for Java Enterprise Edition gives you an enormous range of technologies, which can help you solve a huge variety of problems.

If you want to know more about Liberty, the WASdev site hosts a number of fantastic tutorials for Liberty and Java EE
https://developer.ibm.com/wasdev/docs/category/java-ee/

If you want to know more about Java Enterprise Edition technologies, the Java EE website covers each technology in detail
https://docs.oracle.com/javaee/7/tutorial/

A useful resource for learning more about how to write Java EE 7 applications is MyKong, which has a number of development tutorials for Java EE technologies.
http://www.mkyong.com/

Join The Discussion

Your email address will not be published. Required fields are marked *