Deploying a web application
In this chapter, we describe the three options that are available to deploy a web application into a CICS Liberty JVM server and the key differences between these options.
We used the CICSDev sample restapp, which is a simple RESTful web application that is deployed by using an Eclipse dynamic web project as a WAR archive and is available at the GitHub website. Similar considerations and procedures apply to any web application that you want to build from source and deploy to a CICS Liberty server.
This chapter includes the following topics:
2.1 Building the restapp sample
In this section, we describe how to download the application from GitHub, import it into a CICS Explorer development environment, and build the .war file.
2.1.1 Obtaining the sample code
The source project for restapp is available at the cicsdev GitHub website (search for “cics-java-liberty-restapp”). The results for matching repositories are shown in Figure 2-1.
Figure 2-1 GitHub cicsdev repositories view
The following related RESTful web applications are available:
•cics-java-liberty-restapp
The restapp sample is a sample Java web application that provides RESTful APIs that uses JAX-RS. The following services are provided:
– cicsinfo: Includes no intrinsic CICS dependency, and might be on any Java EE server.
•cics-java-liberty-restapp-ext
The restapp-ext sample differs from the basic restapp because it consists of a suite of examples that use the JCICS API to access various CICS resources, and a specially annotated linkable Java class.
Complete the following steps to download restapp:
1. Select the cics-java-liberty-restapp repository, click Clone or download → Download ZIP (see Figure 2-2). The master branch of the repository is downloaded as cics-java-liberty-restapp-master.zip into your download directory.
Figure 2-2 GitHub restapp repository download
2. Extract the downloaded repository .zip files to a suitable location on your workstation. The /cics-java-liberty-restapp-master directory is created, which includes the artifacts for the sample.
2.1.2 Creating the Eclipse projects
To build and deploy the sample application, you need an Eclipse development environment. We used CICS Explorer version 5.4 with the CICS SDK for Java EE and Liberty plug-in, which was installed by using into the IBM Explorer for z/OS Aqua V3.1. This installation is available at the IBM Installation Manager website.
After your Eclipse development environment is installed, complete the following steps to create a dynamic web project and a CICS bundle project:
1. In CICS Explorer, switch to the Java EE perspective by clicking Window → Perspective → Open Perspective → Other → Java EE. Create a dynamic web project that is named com.ibm.cicsdev.restapp by using clicking File → New → Dynamic Web Project. Add the Project name com.ibm.cicsdev.restapp, as shown in Figure 2-3 on page 30.
Figure 2-3 Creating dynamic web project for restapp
2. Click Finish to complete (the defaults that are shown in the next windows of the process are used). A project is created that is named com.ibm.cicsdev.restapp.
|
Note: A web.xml deployment descriptor is not created now. Such a descriptor is not essential, although one is needed to specify some advanced deployment options that are used in Chapter 7, “Securing web applications ” on page 175.
|
3. Add the Java source code to the src folder in the Eclipse project. In the Windows OS, complete the following steps:
a. Open the cics-java-liberty-restapp-master folder. Select the src/com folder and drag this folder into the src folder in the Eclipse project.
b. Click Copy files and folders when prompted in the File and Folder Operation window (see Figure 2-4 on page 31). Click OK to finish.
Figure 2-4 File and Folder Operation window
Two new packages, com.ibm.cicsdev.restapp and com.ibm.cicsdev.restapp.bean, are added to the /src folder, as shown in Figure 2-5. Build errors are flagged within the com.ibm.cicsdev.restapp package because the build path is incomplete at this stage.
Figure 2-5 Eclipse project after import
4. Complete the following steps to add the Liberty JVM server libraries to the build path of your project:
a. Right-click the Eclipse com.ibm.cicsdev.restapp project and select Build Path → Configure Build Path in the Java Build Path window.
b. Select the Libraries tab and click Add Library.
c. Select library type CICS with Java EE and Liberty and click Next.
d. Select version CICS TS 5.4 and click Finish. Then, click OK to complete the process.
The project build path is updated and the build errors in the project are removed as it is rebuilt.
5. Now we need to ensure that the web project is targeted to compile at a level that is compatible with the Java level that is being used on CICS. The compiler target level must be less than or equal to the CICS runtime Java level. We used the Java V8 SDK in CICS; therefore, the web application Java target level must be 1.8 or earlier.
A compatible level can be selected or checked in the Java project facet. Right-click the Eclipse com.ibm.cicsdev.restapp project and select Properties. Then, enter Project Facets. Click Project Facets and the configured facets are displayed (see Figure 2-6 on page 32). The Java Version should be equal or less than the Java level that is used in the Liberty JVM server (1.7 or 1.8). Correct this information if needed.
Figure 2-6 Project facets: Java version
2.2 Deploying a web application to Liberty
The following projects can be used to package Java EE web projects for deployment into Liberty:
•Dynamic web projects, for deployment as a WAR file archive
•Enterprise application projects, for deployment as an EAR file archive
•OSGi application projects, for deployment as an EBA file archive
In our example, we use dynamic web projects with the .war file archive type.
The following options are available for a Liberty JVM server to provide for the deployment of web applications (see Figure 2-7):
•By using the Liberty dropins directory
•As a Liberty application
•As a CICS bundle
Figure 2-7 CICS Liberty application deployment options
In the following sections, we describe how each of these deployment options can be used.
Common deployment tasks
Whichever one of the three deployment options is used, the following common tasks must be performed before our restapp application can be deployed:
•A Liberty JVM server must be configured. For more information, see Chapter 1, “Installation and configuration ” on page 1.
•The JAX-RS feature must be enabled in Liberty. If this feature is not enabled, the JAX-RS annotations in the REST classes are not recognized and the REST URIs are not found, which causes 404 error responses to be returned.
•Any dependent CICS resources that are used by the application must be available. For restapp, the COBOL program EDUCHAN that is linked to by the reverse service should also be download from the GitHub website and deployed to a library in the CICS region.
2.2.1 Deployment by using Liberty dropins
The simplest options to deploy a web application to Liberty in CICS is to copy the web application archive (.war or .ear file) to the Liberty dropins directory. Liberty then automatically installs and activates the application.
|
Note: The dropins mechanism offers limited qualities of service. It does not set security roles and it incurs more runtime CPU cost in directory scanning. For these reasons, the dropins deployment option is best-suited to development systems.
|
This option is available only if the dropins directory deployment option was enabled in the server.xml for Liberty. The CICS auto-generated server.xml includes a default applicationMonitor configuration element with this option disabled, as shown in Example 2-1.
Example 2-1 applicationMonitor in server.xml
<applicationMonitor
dropins="dropins"
dropinsEnabled="false"
pollingRate="5s"
updateTrigger="disabled" />
dropins="dropins"
dropinsEnabled="false"
pollingRate="5s"
updateTrigger="disabled" />
Complete the following steps to deploy the restapp sample by using the dropins method:
1. Enable the dropins capability by setting dropinsEnabled="true" and adding the dropins directory to the applicationMonitor element in server.xml, as shown in Example 2-2.
Example 2-2 Enabling dropins in server.xml
<applicationMonitor
dropins="/var/cicsts/SC8CICS7/ITSOJVM1/dropins"
dropinsEnabled="true"
dropins="/var/cicsts/SC8CICS7/ITSOJVM1/dropins"
dropinsEnabled="true"
pollingRate="5s"
updateTrigger="disabled" />
updateTrigger="disabled" />
|
Note: At this stage, the attribute updateTrigger="disabled" causes Liberty to not detect application updates in the dropins folder; however, it does allow any new files to be detected and installed.
|
2. Complete the following steps to export the application as a .war file:
a. In CICS Explorer right-click the com.ibm.cicsdev.restapp project and select File → Export → WAR file. In the WAR Export window, select Browse to choose a suitable local directory for the exported .war file. Then, click Finish.
b. Transfer the .war file from the workstation to the dropins directory in zFS.
In our example, we used a binary FTP transfer from the export directory to our zFS directory /var/cicsts/SC8CICS7/ITSOJVM1/dropins.
c. Validate that the CICS region user ID includes read access to the com.ibm.cicsdev.restapp.war file in the dropins directory.
We modified the file owner to our CICS region user ID (CICSREGN) and the group owner to our CICS admin group (CICSADMIN), and verified both had read/write permissions by using ISPF option 3.4 (see Figure 2-8).
Figure 2-8 ISPF z/OS UNIX directory list of dropins
3. Check the Liberty messages.log for the application enablement messages. A few seconds after copying the .war file to the dropins directory, messages that are similar to messages that are shown in Example 2-3 should appear in the Liberty messages.log file.
Example 2-3 Liberty messages after enabling dropins
[10/27/17 6:58:07:239 EDT] 000067fa com.ibm.ws.webcontainer.osgi.webapp.WebGroup I SRVE0169I: Loading Web Module: com.ibm.cicsdev.restapp.
[10/27/17 6:58:07:240 EDT] 000067fa com.ibm.ws.webcontainer I SRVE0250I: Web Module com.ibm.cicsdev.restapp has been bound to default_host.
[10/27/17 6:58:07:240 EDT] 000067fa com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0016I: Web application available (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/
[10/27/17 6:58:07:240 EDT] 000067fa com.ibm.ws.app.manager.AppMessageHelper A CWWKZ0001I: Application com.ibm.cicsdev.restapp started in 0.040 seconds.
Now, you can test the restapp cicsinfo service by sending an HTTP GET request to the application by using the following URI in a web browser:
http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/rest/cicsinfo
This test should result in a JSON response that includes information about the CICS region, as shown in Figure 2-9 on page 35.
Figure 2-9 Liberty: restapp cicsinfo service
Further scanning of the dropins directory can be performed to detect application updates or the addition and removal of applications to the dropins directory. This feature is enabled by setting updateTrigger to polled. The pollingRate attribute determines how often the dropins directory is scanned for updates (see Example 2-4).
Example 2-4 Enabling updateTrigger for dropins
<applicationMonitor
dropins="/var/cicsts/SC8CICS7/ITSOJVM1/dropins"
dropinsEnabled="true"
pollingRate="5s"
updateTrigger="polled" />
dropins="/var/cicsts/SC8CICS7/ITSOJVM1/dropins"
dropinsEnabled="true"
pollingRate="5s"
updateTrigger="polled" />
Removing web applications from the dropins directory
A web application that was deployed by using the dropins mechanism can be removed by deleting the application archive from the dropins directory. When the deletion is detected by Liberty, the application is stopped and the messages that are shown in Example 2-5 are written to the Liberty messages.log file.
Example 2-5 Application removal by using dropins
[10/27/17 7:21:18:669 EDT] 00006516 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0017I: Web application removed (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/
[10/27/17 7:21:18:682 EDT] 00006516 com.ibm.ws.app.manager.AppMessageHelper A CWWKZ0009I: The application com.ibm.cicsdev.restapp has stopped successfully.
[10/27/17 7:21:18:822 EDT] 00006550 com.ibm.ws.webcontainer.osgi.mbeans.PluginGenerator I SRVE9103I: A configuration file for a web server plugin was automatically generated for this server at /var/cicsts/SC8CICS7/wlp/servers/itsowlp1/logs/state/plugin-cfg.xml.
Subsequent requests to the application fail, and an HTTP GET to the restapp returns the Context Root Not Found error page to the browser (see Figure 2-10 on page 36) because the web application context root com.ibm.cicsdev.restapp no longer is known.
Figure 2-10 Context Root Not Found error message
Updating applications by using dropins directory
An application can be dynamically updated in the dropins directory by overwriting the version of an application with a new version in the directory. To enable this function, the updateTrigger on the applicationMonitor element must be set to polled.
When Liberty detects that an application archive is updated in the dropins directory, it stops the old version and loads the new version of the application. Messages similar to the messages that are shown in Example 2-6 are written to the messages.log file.
Example 2-6 Updating dropins
[10/27/17 7:45:30:009 EDT] 00006ea7 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0017I: Web application removed (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/
[10/27/17 7:45:30:023 EDT] 00006ea7 com.ibm.ws.app.manager.AppMessageHelper A CWWKZ0009I: The application com.ibm.cicsdev.restapp has stopped successfully.
[10/27/17 7:45:30:044 EDT] 000065bf com.ibm.ws.webcontainer.osgi.mbeans.PluginGenerator I SRVE9103I: A configuration file for a web server plugin was automatically generated for this server at /var/cicsts/SC8CICS7/wlp/servers/itsowlp1/logs/state/plugin-cfg.xml.
[10/27/17 7:45:30:045 EDT] 00006ea7 com.ibm.ws.app.manager.AppMessageHelper I CWWKZ0018I: Starting application com.ibm.cicsdev.restapp.
[10/27/17 7:45:30:092 EDT] 00006ea7 com.ibm.ws.webcontainer.osgi.webapp.WebGroup I SRVE0169I: Loading Web Module: com.ibm.cicsdev.restapp.
[10/27/17 7:45:30:092 EDT] 00006ea7 com.ibm.ws.webcontainer I SRVE0250I: Web Module com.ibm.cicsdev.restapp has been bound to default_host.
[10/27/17 7:45:30:092 EDT] 00006ea7 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0016I: Web application available (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/
[10/27/17 7:45:30:092 EDT] 00006ea7 com.ibm.ws.app.manager.AppMessageHelper A CWWKZ0003I: The application com.ibm.cicsdev.restapp updated in 0.047 seconds.
2.2.2 Deployment as an application element in server.xml
The second deployment option we describe uses an application element in the Liberty server.xml file. This option is highly customizable and allows the context root, security roles, and classloader definitions to be modified. For more information, see 2.3.1, “Shared libraries” on page 53 and 2.3.2, “Global libraries” on page 54.
Liberty supports several different elements that can be used in server.xml to define applications. You can use the <application> element, or you can use one of specific elements <webApplication>, <osgiApplication>, or <ejbApplication> as appropriate to the file archive type.
We used the <webApplication> element that is shown in Example 2-7 in our server.xml to install restapp into our Liberty JVM server. The application bindings that are shown in the <application-bnd> element use the same pattern as used in the installedApps.xml, which uses the cicsAllAuthenticated role to grants access to all authenticated Liberty users. However, these permissions can be further customized as described in Chapter 7, “Securing web applications ” on page 175.
Example 2-7 Liberty server.xml - webApplication element
<webApplication id="com.ibm.cicsdev.restapp"
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.restapp.war"
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.restapp.war"
name="com.ibm.cicsdev.restapp">
<application-bnd>
<security-role name="cicsAllAuthenticated">
<special-subject type="ALL_AUTHENTICATED_USERS" />
</security-role>
</application-bnd>
</webApplication>
Using a server.xml include file
A variation of this deployment method is to define the application in a separate XML fragment file, and then include this fragment in server.xml by using the <include> element in the server.xml. In our configuration, we added the following include into our server.xml file:
<include location="${server.output.dir}/restapp.xml"/>
Although the referenced restapp.xml fragment needs to contain only the webApplication element as shown in Example 2-7, it can also contain more resources, such as library definitions or features.
For more information about how we used server.xml include files, see Chapter 5, “Connecting to IBM MQ by using JMS” on page 113.
Configuration dropins directory
An alternative to using a specific include file is to use the Liberty server configuration dropins directory. This directory is a specifically named directory structure, which is automatically scanned by Liberty to dynamically add server.xml configuration fragments. This technique can allow self-contained server.xml fragments to be deployed for an application without needing to modify the configuration files.
To enable this function, we created the configDropins directory in the /var/cicsts/SC8CICS2/wlp/servers/itsowlp1/ directory. Then, we created the overrides directory within this directory, as shown in Figure 2-11.
Figure 2-11 configDropins directory structure
We then created the restapp.xml fragment that includes a <server/> element and a <webApplication/> element, as shown in Example 2-8.
Example 2-8 configDropins/overrides/restapp.xml fragment
<server>
<webApplication id="com.ibm.cicsdev.restapp"
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.restapp.war"
name="com.ibm.cicsdev.restapp">
<application-bnd>
<security-role name="cicsAllAuthenticated">
<special-subject type="ALL_AUTHENTICATED_USERS"/>
</security-role>
</application-bnd>
</webApplication>
</server>
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.restapp.war"
name="com.ibm.cicsdev.restapp">
<application-bnd>
<security-role name="cicsAllAuthenticated">
<special-subject type="ALL_AUTHENTICATED_USERS"/>
</security-role>
</application-bnd>
</webApplication>
</server>
When the restapp.xml file was deployed to the configDropins directory, we noted that the Liberty server scanned the configDropins/overrides directory and installed the new restapp application, as shown in the messages.log file (see Example 2-9).
Example 2-9 Liberty messages with configDropins enabled
[11/14/17 10:02:55:983 EST] 00000068 com.ibm.ws.config.xml.internal.ConfigRefresher
A CWWKG0016I: Starting server configuration update.
[11/14/17 10:02:55:988 EST] 00000068 com.ibm.ws.config.xml.internal.XMLConfigParser A CWWKG0028A: Processing included configuration resource: /var/cicsts/SC8CICS2/wlp/servers/itsowlp1/installedApps.xml
[11/14/17 10:02:55:992 EST] 00000068 com.ibm.ws.config.xml.internal.ServerXMLConfiguration A CWWKG0093A: Processing configuration drop-ins resource: /var/cicsts/SC8CICS2/wlp/servers/itsowlp1/configDropins/overrides/restapp.xml
[11/14/17 10:02:56:019 EST] 00000068 com.ibm.ws.config.xml.internal.ConfigRefresher A CWWKG0017I: The server configuration was successfully updated in 0.035 seconds.
[11/14/17 10:02:56:034 EST] 00000055 com.ibm.ws.app.manager.AppMessageHelper I CWWKZ0018I: Starting application com.ibm.cicsdev.restapp.
[11/14/17 10:02:56:118 EST] 00000055 com.ibm.ws.webcontainer.osgi.webapp.WebGroup I SRVE0169I: Loading Web Module: com.ibm.cicsdev.restapp.
[11/14/17 10:02:56:118 EST] 00000055 com.ibm.ws.webcontainer I SRVE0250I: Web Module com.ibm.cicsdev.restapp has been bound to default_host.
[11/14/17 10:02:56:119 EST] 00000055 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0016I: Web application available (default_host): http://wtsc80.cpolab.ibm.com:52080/com.ibm.cicsdev.restapp/
[11/14/17 10:02:56:119 EST] 00000055 com.ibm.ws.app.manager.AppMessageHelper A CWWKZ0001I: Application com.ibm.cicsdev.restapp started in 0.085 seconds.
Removing a Liberty application
A web application that is deployed by using the Liberty application definition mechanism is removed by deleting the application element from server.xml or any included fragment. If the include method was used, it is sufficient to delete the include reference in the server.xml.
Updating a Liberty application
An application can be dynamically updated in Liberty by overwriting the deployed archive file with a new version. To enable this function, the updateTrigger attribute on the <applicationMonitor> element must be set to polled as shown in the following example:
<applicationMonitor pollingRate="5s" updateTrigger="polled" />
The use of this technique causes the application to be stopped and then started when the polling mechanism detects that the .war file was updated.
|
Note: Updating Liberty applications requires a stop and restart of the web application. During this period, a Context Root Not Found response is returned because the HTTP listener is still active, but the web context root is unavailable.
|
Deploying with a modified context root
In Liberty, only one application per context root can be deployed. A second version of an application that shares the context root as another installed application fails to install. However, an alternative way to deploy an application update is by deploying a new version of the application to a new location on the file system with a different web context root. This process installs the new version of the application alongside the previous version and allows any updates to be tested by using a different URI for each version.
To demonstrate this method, we installed a new version of restapp into our Liberty server by using the context-root tag on the webApplication element, as shown in Example 2-10. The second version of the restapp was deployed as the com.ibm.cicsdev.restapp2.war and accessed by using the URL http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp2/rest/cicsinfo
Example 2-10 Liberty server.xml: webApplication element
<webApplication id="com.ibm.cicsdev.restapp2"
context-root="com.ibm.cicsdev.restapp2"
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.
restapp2.war"
context-root="com.ibm.cicsdev.restapp2"
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.
restapp2.war"
name="com.ibm.cicsdev.restapp2">
<application-bnd>
<security-role name="cicsAllAuthenticated">
<special-subject type="ALL_AUTHENTICATED_USERS" />
</security-role>
</application-bnd>
</webApplication>
Other methods can be used to control the web application’s context root (such as in the ibm-web-ext.xml or application.xml deployment descriptors), depending on the type of web application. For more information about these options, see the topic “Deploying a web application to Liberty” at IBM Knowledge Center.
2.2.3 Deployment in a CICS bundle
The third deployment method you can use for application deployment to Liberty is a CICS bundle project. A CICS bundle project is a specific type of Eclipse project that is supported by the CICS Explorer SDK. It allows a collection of CICS resources (known as bundle parts) to be defined within it.
The bundle parts can include one or more Liberty Web applications that are packaged as a .war, .ear, or .eba file archive types. Bundle projects also support various other CICS resources to be defined, such as transactions, programs, files, and URI map definitions.
CICS bundles are defined as BUNDLE resource definitions in the CSD, which then refer to a zFS directory that includes all of the assembled bundle components.
In the following sections, we describe how to define a web application in a CICS bundle, export the bundle directory structure, and install it into CICS. To show some of the advantages of this deployment approach, we create a single CICS bundle to deploy the restapp sample web application and an associated CICS transaction definition and URI map.
The starting point for CICS bundle deployment assumes that the sample web application restapp was downloaded from GitHub and imported into the CICS Explorer development environment, as described in 2.1, “Building the restapp sample ” on page 28. It is also assumed that the WAR was removed from the dropins directory if this method was used as described in 2.2.1, “Deployment by using Liberty dropins” on page 33.
Creating a CICS bundle project
Complete the following steps to create the CICS bundle project:
1. In CICS Explorer, switch to the Java EE perspective and click New → Other. The Select a wizard window opens, as shown in Figure 2-12.
Figure 2-12 Select a wizard: CICS Bundle Project
2. Enter CICS Bundle Project and select CICS Bundle Project from the list. Click Next.
3. Enter a name for the new project. In our example, we used com.ibm.cicsdev.restapp.cicsbundle, as shown in Figure 2-13.
Figure 2-13 New CICS bundle project
4. Click Finish to complete the process. The project is created and the bundle manifest editor is displayed, as shown in Figure 2-14 on page 42.
Figure 2-14 Bundle manifest editor for com.ibm.cicsdev.restapp.bundle
Adding the web applications to the CICS bundle
The next task is to add the web project to a CICS bundle project, which is required for deployment of the application in a CICS bundle. Complete the following steps:
1. In the CICS bundle editor, the Bundle Overview window includes is a section for Defined Resources. These CICS resources are included in the bundle.
2. Click New and select Dynamic Web Project Include. The Dynamic Web Project Include window opens and displays the com.ibm.cicsdev.restapp project as a potential candidate, as shown in Figure 2-15.
Figure 2-15 Dynamic Web Project Include window
3. Select the project com.ibm.cicsdev.restapp and enter the name of the JVM server to use (see Figure 2-16). In our example, we used ITSOJVM1. Click Finish.
Figure 2-16 Bundle Overview that shows the defined WARBUNDLE part
Adding CICS resources to the CICS bundle
The restapp application requires minimal extra CICS resources for operation. We chose to define a URI map and a specific request processor transaction rather than allow requests to run under the default transaction ID CJSA. We can add these resource definitions to the CICS bundle rather than define them in the CSD, which allows all the application component to be defined in a single package for deployment.
Complete the following steps:
1. In the Defined Resources section of the CICS Bundle Editor, click New. Select URIMAP Definition. A Create URI Map Definition window opens. Add the following attributes as shown in Figure 2-17 on page 44:
– Name: RESTAPP
– Host: *
– Path: /com.ibm.cicsdev.restapp/*
– Usage: JVM Server
– Port: NO
Figure 2-17 Create URI Map Definition window
2. Click Finish. The attribute editor is displayed and shows the resulting URIMAP.
Next, we must modify the transaction ID to which this URI map refers. Click Transaction and enter JRES as the value, as shown in Figure 2-18.
Figure 2-18 Editing the URI map attributes
3. Close the attribute editor and click Yes to save the changes when prompted.
Next, we must create a TRANSACTION definition for the JRES transaction that we referred to in our URI map definition.
4. In the Defined Resources section of the CICS Bundle Editor, click New then, select Transaction Definition. The Create Transaction Definition window opens. Add the following attributes that are shown in Figure 2-19. You must enter the program name as DFHSJTHP because it handles the security checking of inbound Java EE requests to the Liberty server.
Figure 2-19 Create Transaction Definition window
Exporting the CICS bundle to zFS
We must build the bundle and export it to z/OS. We can build the bundle from CICS Explorer or use the CICS build toolkit to automate this process as a batch job. Both methods automatically build the Java web application in a .war file and include this file with the transaction and URI map in the assembled CICS bundle directory on zFS.
In CICS Explorer, complete the following steps:
1. Ensure that a connection to z/OS is configured. CICS Explorer can use FTP, RSE, or z/OS MF to export CICS bundles. Complete the following steps to create an FTP connection:
a. In the CICS SM perspective, open the Host Connections view. Click Add → z/OS FTP to define a new connection (see Figure 2-20 on page 47).
Figure 2-20 Add z/OS FTP Connection
b. Enter the host name of the FTP server and add the default remote EBCDIC character set. In our example, we supplied the value IBM-1047 for US EBCDIC.
|
Tip: Instead of setting the default EBCDIC encoding for each connection in CICS Explorer, this encoding can be set on z/OS by using the SBDATACONN parameter in the SYS1.TCPPARMS(FTPDATA) member, as shown in the following example:
SBDATACONN (IBM-1047,ISO8859-1)
|
c. Click Save and Connect. You are prompted to create a user ID and the connection status icon should now be green.
2. Now a connection is available to which we can export the CICS bundle project to zFS. Complete the following steps:
a. Using the Project Explorer in the Java EE perspective, right-click the CICS bundle project com.ibm.cicsdev.restapp.bundle and select Export Bundle Project to z/OS UNIX File System.
b. Select Export to a specific location in the file system. Click Next.
c. The Export to z/OS UNIX File System window opens. For Parent Directory, enter the target zFS directory you chose to contain your exported CICS bundles (see Figure 2-21 on page 48 and Figure 2-22 on page 48).
d. Click Finish to complete the export.
For our example, we used the parent directory /var/cicsts/SC8CICS7/ITSOJVM1/bundles/ and CICS Explorer then, we created the sub-directory com.ibm.cicsdev.restapp.cicsbundle_1.0.0 within this directory that contains the following components (see Figure 2-21 on page 48):
• com.ibm.cicsdev.restapp.war: WAR archive
• com.ibm.cicsdev.restapp.warbundle: XML WAR bundle part descriptor
• JRES.transaction: XML transaction bundle part descriptor
• RESTAPP.urimap: XML URI map bundle part descriptor
• META-INF/cics.xml: XML CICS bundle manifest
Figure 2-21 Restapp bundle directory structure
Figure 2-22 Export to z/OS UNIX File System
|
Tip: When bundles are exported to zFS, you can copy the fully qualified target bundle directory name to the clipboard before completing the export porcess. This copying is useful when the CICS BUNDLE resource is defined in the next step.
|
Installing the CICS bundle
Complete the following steps to install the CICS bundle:
1. A CICS BUNDLE resource definition must be defined and installed to install the exported CICS bundle project into our target CICS region. You can use various tools to perform this task, including CEDA, CICS Explorer, DFHCSDUP, or DFHDPLOY. We used CEDA, as shown in Figure 2-23 to add the BUNDLE definition to our CSD.
Figure 2-23 CEDA - DEFINE BUNDLE
The CICS BUNDLE features an attribute that is named BUNDLEDIR, which is the fully qualified path to the bundle directory in zFS where the bundle was exported and should be set to the bundle root directory, as shown in the following example:
/var/cicsts/SC8CICS7/ITSOJVM1/bundles/com.ibm.cicsdev.restapp.cicsbundle_1.0.0
2. The BUNDLE definition must be installed and added to a CSD group list to ensure it is also installed on a CICS cold start. We installed the BUNDLE resource and checked the Liberty messages.log file for the messages SRVE0250I and CWWKT0016I, which indicate that com.ibm.cicsdev.restapp is now available, as shown in Example 2-11.
Example 2-11 Liberty messages.log - installing CICS bundle
[10/31/17 10:51:37:448 EDT] 0002a80c com.ibm.ws.webcontainer I SRVE0250I: Web Module com.ibm.cicsdev.restapp has been bound to default_host.
[10/31/17 10:51:37:448 EDT] 0002a80c com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0016I: Web application available (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/
3. In CICS Explorer, we can now validate that the URI map and transaction resources were installed. Switch to the CICS SM perspective in CICS Explorer and select Operations → Bundles. The RESTAPP bundle is shown. It should be in the ENABLED status with the Enabled Count, Part Count, and Target Count set to 3 because three bundle parts are used (see Figure 2-24).
Figure 2-24 RESTAPP bundle
To validate the bundle parts, right-click the RESTAPP bundle and select Show Bundle Parts. The components that are in the bundle are shown (see Figure 2-25). In our example, the WAR bundlepart, JRES transaction, and RESTAPP URI map are all marked as ENABLED.
Figure 2-25 Show bundle parts
4. We can now test the restapp again by sending a simple HTTP request to the application by using the following URI:
http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/rest/cicsinfo
This test returns a JSON response that includes information about the CICS region, as shown in Figure 2-26 on page 51.
Figure 2-26 Liberty - restapp - cicsinfo service
|
Note: The installation mechanism that CICS uses for web applications in a CICS bundle involves copying the web application archive into the /installedApps directory and then adding an application element for each Liberty application to the installedApps.xml, which is included as part of the server.xml. The addition of new application elements in the installedApps.xml causes Liberty to install the web applications by using its standard application installation process.
|
Removing a CICS bundle
To uninstall a web application that is installed by using a CICS bundle, the CICS bundle must be disabled. This process disables all of the resources that are defined by the bundle, including web application bundle parts, which stop the applications within Liberty.
Disabling a web application causes CICS to remove the .war file from the /installedApps directory and to remove the application entry from the installedApps.xml file. This process in turn causes Liberty to remove the web application because the installedApps.xml is included as part of the server.xml configuration.
Updating a CICS bundle
To update a web application that was deployed as a CICS bundle, update the application in the development environment. Then, reexport the CICS bundle project to zFS by following the deployment instructions that are described in 2.2.1, “Deployment by using Liberty dropins” on page 33.
Then, disable and re-enable the BUNDLE resource by using the CICS SPI. This task can be completed by using one of the following methods:
•CEMT SET BUNDLE() DISABLED and ENABLED commands
•CICS Explorer Bundle Operations view
•Batch job by using DFHDPLOY SET BUNDLE STATE(DISABLED) and (ENABLED) commands
•CICS SPI program by using EXEC CICS SET BUNDLE() DISABLED and ENABLED
These commands cause the web application to be removed from the installedApps.xml file when the bundle is disabled, and then, added again when the bundle is enabled. Liberty messages that indicate that this process occurred are written to the Liberty messages.log, as shown in Example 2-12.
Example 2-12 Liberty messages.log - updating a CICS bundle
[11/2/17 11:46:23:345 EDT] 00003282 com.ibm.ws.config.xml.internal.ConfigRefresher A CWWKG0016I: Starting server configuration update.
[11/2/17 11:46:23:348 EDT] 00003282 com.ibm.ws.config.xml.internal.XMLConfigParser A CWWKG0028A: Processing included configuration resource: /var/cicsts/SC8CICS7/wlp/servers/itsowlp1/installedApps.xml
[11/2/17 11:46:23:374 EDT] 00003282 com.ibm.ws.config.xml.internal.ConfigRefresher A CWWKG0017I: The server configuration was successfully updated in 0.029 seconds.
[11/2/17 11:46:23:390 EDT] 000027b3 com.ibm.ws.app.manager.AppMessageHelper I CWWKZ0018I: Starting application com.ibm.cicsdev.restapp.
[11/2/17 11:46:23:440 EDT] 000027b3 com.ibm.ws.webcontainer.osgi.webapp.WebGroup I SRVE0169I: Loading Web Module: com.ibm.cicsdev.restapp.
[11/2/17 11:46:23:440 EDT] 000027b3 com.ibm.ws.webcontainer I SRVE0250I: Web Module com.ibm.cicsdev.restapp has been bound to default_host.
[11/2/17 11:46:23:440 EDT] 000027b3 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0016I: Web application available (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp/
|
Warning: If the CICS bundle contains any other bundle parts aside from a Liberty web application, these bundle parts are updated only if the CICS bundle is discarded and reinstalled.
|
2.2.4 Comparison of the deployment options
The three deployment options we described can all achieve the basic effect of deploying and activating a web application in a Liberty JVM server. However, each option features different characteristics in other respects.
Liberty dropins directory
This option includes the following features:
•Requires minimal setup
•Not integrated with CICS security because of a lack of security role support
•Requires dropins scanning mechanism to be enabled
•Does not support customization of the application element
•Best-suited to development systems
•Deployment artifact is a single Java archive
Liberty application element in server.xml
This option includes the following features:
•Highly customizable
•Supports custom class loaders, security roles, and context root modification
•Deployment artifact is a single Java archive
CICS bundles
This option includes the following features:
•Integrated with CICS Explorer, CICS build toolkit, and DFHDPLOY tooling
•Supports packaging of multiple applications and CICS resources in the same bundle
•CICS SET BUNDLE SPI and CICS Explorer can be used to manage lifecycle
•Does not support customization of web application elements
•Deployment artifact is a directory structure
2.3 Advanced deployment options
In this section, we describe some of the other options that are available to customize the deployment process for web applications in a Liberty JVM server.
2.3.1 Shared libraries
Shared libraries are files that are used by multiple applications. You can use shared libraries and global libraries to reduce the number of duplicate library files on your system.
Shared libraries are named by using a <library> element and then specified on an individual application by modifying the application class loader. This configuration enables libraries to be shared between multiple applications, or other libraries to be added to the application.
As shown in Example 2-13, the userlib.jar library was added to our restapp by using the <classloader> child element on the <webApplication>.
Example 2-13 Adding library to class loader
<webApplication id="com.ibm.cicsdev.restapp"
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.restapp.war"
name="com.ibm.cicsdev.restapp">
location="/var/cicsts/SC8CICS7/ITSOJVM1/apps/com.ibm.cicsdev.restapp.war"
name="com.ibm.cicsdev.restapp">
<classloader commonLibraryRef="privatelib" />
</webApplication>
<library id="privatelib">
<fileset dir="/var/cicsts/SC8CICS7/ITSOJVM1/apps"
includes="userlib.jar" />
</library>
|
Note: OSGi applications do not use shared libraries. Instead, they should use a shared bundle repository for sharing common libraries between applications.
|
2.3.2 Global libraries
When CICS bundle-defined applications are used, the application elements that are automatically created by CICS cannot be modified. However, you can use a global library to make a library available to all deployed applications, including web applications that are defined in CICS bundles.
As shown in Example 2-14, the library is defined by using id=global, which indicates that it is a global library that can be used by any web application that is deployed into the Liberty server.
Example 2-14 Liberty server.xml - global library
<library id="global">
<fileset dir="/var/cicsts/SC8CICS7/ITSOJVM1/apps"
includes="library.jar" />
</library>
For more information about how we used a global library in a web application to make the DB2 libraries available to our SQLJ application, see Chapter 4, “Connecting to Db2 by using JDBC” on page 91.
|
Note: A class in a global library takes precedence over the same class that is deployed within an application. Therefore, it must be used with caution for any application that might require modification.
|
2.3.3 Deploying a prebuilt Java archive in a CICS bundle
If you want to deploy a web application in a CICS bundle by using a Java archive that is built or is being ported from another application server, add the archive directly into a CICS bundle project. Complete the following steps:
1. In CICS Explorer, switch to the Java EE perspective and click File → New → Other. The Select a wizard window opens.
2. Enter CICS Bundle Project in the search field and select CICS Bundle Project from the resulting list, as shown in Figure 2-27 on page 55. Click Next.
Figure 2-27 Creating a CICS Bundle Project
3. Enter a name for the new project. In our example, we used com.ibm.cicsdev.restapp2.cicsbundle, as shown in Figure 2-28.
Figure 2-28 Creating a CICS Bundle Project
4. Browse to the folder on your workstation where the Java archive is stored and drag the Java archive into the root of the newly created CICS bundle project in Eclipse.
5. You are prompted to select how files should be imported into the project. Select Copy files and click OK to proceed.
The CICS bundle project should now show the .war file in the root of the project, as shown in Figure 2-29.
Figure 2-29 CICS bundle project with .war file
6. The .war file can now be added directly to the CICS bundle under Defined Resources by clicking New → Dynamic Web project include. The current project (com.ibm.cicsdev.restapp2) is listed because it now contains a web artifact, as shown in Figure 2-30.
Figure 2-30 CICS bundle project with WAR artifact
7. Select the com.ibm.cicsdev.restapp2 project and add the name of the JVM server, which in our environment is ITSOJVM1.
8. The CICS bundle project now displays the .war file and the .warbundle part file as the two components in the project, as shown in Figure 2-31.
Figure 2-31 CICS bundle project completed
The CICS bundle project is now ready to be exported to zFS by using the same method as described in 2.2.2, “Deployment as an application element in server.xml ” on page 37. We exported this project to the following zFS directory location:
/var/cicsts/SC8CICS7/ITSOJVM1/bundles/com.ibm.cicsdev.restapp2_1.0.0/
9. A CICS BUNDLE resource definition is also needed. We created another CICS BUNDLE that is named RESTAPP2 with the BUNDLEDIR attribute pointing to this bundle directory and installed this BUNDLE into our CICS region.
The Liberty messages.log now shows that this application was installed by using the URL http://wtsc80:57080/com.ibm.cicsdev.restapp2, as shown in Example 2-15.
Example 2-15 Installing restapp2
11/2/17 11:31:17:120 EDT¨ 000025b5 com.ibm.ws.config.xml.internal.ConfigRefresher
A CWWKG0016I: Starting server configuration update.
11/2/17 11:31:17:131 EDT¨ 000025b5 com.ibm.ws.config.xml.internal.XMLConfigParser
A CWWKG0028A: Processing included configuration resource: /var/cicsts/SC8CICS7/wlp/servers/itsowlp1/restapp.xml
11/2/17 11:31:17:160 EDT¨ 000025b5 com.ibm.ws.config.xml.internal.ConfigRefresher
A CWWKG0017I: The server configuration was successfully updated in 0.041 seconds.
11/2/17 11:31:17:175 EDT¨ 000027b3 com.ibm.ws.app.manager.AppMessageHelper
I CWWKZ0018I: Starting application com.ibm.cicsdev.restapp2.
11/2/17 11:31:17:263 EDT¨ 000027b3 com.ibm.ws.webcontainer.osgi.webapp.WebGroup
I SRVE0169I: Loading Web Module: com.ibm.cicsdev.restapp2.
11/2/17 11:31:17:263 EDT¨ 000027b3 com.ibm.ws.webcontainer
I SRVE0250I: Web Module com.ibm.cicsdev.restapp2 has been bound to default_host.
11/2/17 11:31:17:264 EDT¨ 000027b3 com.ibm.ws.http.internal.VirtualHostImpl
A CWWKT0016I: Web application available (default_host): http://wtsc80.cpolab.ibm.com:57080/com.ibm.cicsdev.restapp2/
11/2/17 11:31:17:264 EDT¨ 000027b3 com.ibm.ws.app.manager.AppMessageHelper
A CWWKZ0001I: Application com.ibm.cicsdev.restapp2 started in 0.089 seconds.
2.3.4 Pausing and resuming a server
When a web application is deployed or updated into a Liberty JVM server, a period can occur when not all of the dependent resources are available, which results in application level errors. During the update process, a web application also must be removed to allow the new version to be installed. During this period, the Liberty server returns an HTTP 404 response code and a Context Root Not Found error page for any requests to the web application.
In this situation, pausing and resuming the Liberty server HTTP endpoint can allow updates to proceed while the application is taken offline, which prevents application-level errors from occurring during the update. When combined as part of a highly available port sharing cluster, this pausing and resuming the Liberty server can be used to provide a continuously available application environment. For more information, see Chapter 9, “Port sharing and cloning regions” on page 251.
The Liberty server pause function is started by using the Liberty server script, which can be driven from the UNIX System Services command line or BPXBATCH shell by using the CICS-supplied wlpenv script, which is in the JVM server working directory, as shown in Example 2-16.
Example 2-16 Server pause
> cd /var/cicsts/SC8CICS7/ITSOJVM1/
> ./wlpenv server pause itsowlp1
Executing: /usr/lpp/cicsts/cicsts54/wlp/bin/server pause itsowlp1
JAVA_HOME=/usr/lpp/java/J8.0_64_SR4
WLP_INSTALL_DIR=/usr/lpp/cicsts/cicsts54/wlp
WLP_USER_DIR=/var/cicsts/SC8CICS7/wlp
WLP_OUTPUT_DIR=/var/cicsts/SC8CICS7/wlp/servers
SERVER_NAME=itsowlp1
Pausing the itsowlp1 server.
Pausing the itsowlp1 server completed.
Running the server pause command for our Liberty server itsowlp1 produced the messages that are shown in Example 2-17. These messages indicate that the defaultHttpEndpoint was stopped and the restapp and restapp2 applications were removed.
Example 2-17 Liberty messages.log: Server pause
[11/14/17 7:08:04:292 EST] 00000027 m.ws.kernel.launch.internal.PauseableComponentControllerImpl I CWWKE0924I: A request was received to pause the following components in the server: defaultHttpEndpoint
[11/14/17 7:08:04:293 EST] 00000027 com.ibm.ws.tcpchannel.internal.TCPChannel I CWWKO0220I: TCP Channel defaultHttpEndpoint has stopped listening for requests on host wtsc80.cpolab.ibm.com (IPv4: 9.76.61.131) port 57080.
[11/14/17 7:08:04:293 EST] 00000027 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0028I: Web application moved (default_host): https://wtsc80.cpolab.ibm.com:57443/restapp2/
[11/14/17 7:08:04:293 EST] 00000027 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0028I: Web application moved (default_host): https://wtsc80.cpolab.ibm.com:57443/com.ibm.cicsdev.restapp/
[11/14/17 7:08:04:295 EST] 00000027 com.ibm.ws.tcpchannel.internal.TCPChannel I CWWKO0220I: TCP Channel defaultHttpEndpoint-ssl has stopped listening for requests on host wtsc80.cpolab.ibm.com (IPv4: 9.76.61.131) port 52443.
[11/14/17 7:08:04:295 EST] 00000027 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0017I: Web application removed (default_host): https://wtsc80.cpolab.ibm.com:57443/restapp2/
[11/14/17 7:08:04:295 EST] 00000027 com.ibm.ws.http.internal.VirtualHostImpl A CWWKT0017I: Web application removed (default_host): https://wtsc80.cpolab.ibm.com:57443/com.ibm.cicsdev.restapp/
[11/14/17 7:08:04:295 EST] 00000027 m.ws.kernel.launch.internal.PauseableComponentControllerImpl
I CWWKE0938I: A pause request completed.
After an application is updated, the Liberty server or a specific endpoint can then be resumed by using the following command:
> ./wlpenv server resume itsowlp1
|
Note: In addition to pausing a server, an HTTP endpoint can be started in the paused state by setting the attribute enabled="false" on the httpEndpoint element. This configuration allows applications to then be made available after server startup by using the server resume command.
|
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.