by Dave Nice, Steve Bolton, and Nick Bishop - IBM CICS Explorer Development
In 2012 we posted this article on IBM developerWorks about deploying CICS Explorer with Java Web Start, a Java standard for deploying Java applications from the web. The article provided as-is samples of how to do this as a convenience for our customers. It's not something we've ever supported, as we could not control the customer environment in which Java Web Start would run.
Java Web Start was introduced in 2001 at a time when the security vulnerabilities of Java plugins in web browsers were not well understood. Here are the problems with Java Web Start today:
- The application is run with the system JVM installed. We can't guarantee that CICS Explorer will run as the system JVM may not be compatible with the JVM version features we use in CICS Explorer.
- In Java 9, Oracle has deprecated the Web Start function for future removal (JDK 9 Release Notes Deprecated APIs, Features, and Options).
Since 2016 CICS Explorer is regularly delivered as part of the IBM Explorer for z/OS Aqua. This ensures that (currently 20) IBM Eclipse products are compatible and run on the same releases of Java and Eclipse. All products are supported on Eclipse Luna 4.4 and newer versions are supported on Eclipse Neon 4.6. Once you install IBM Explorer for z/OS you can install any of the other tools from the IBM Update Site and within an Eclipse release boundary you can update them. This mechanism has increased reliability and simplified installation and maintenance for our z/OS Eclipse tools customers.
There are two mechanisms for installation.
- IBM Installation Manager is supported for all of the IBM Eclipse products and this can be done online from the Aqua repository. For customers that don't have general internet access, pre-packaged repository zip files are provided for products supported on Eclipse Neon 4.6.
- Customers can download IBM Explorer for z/OS and IBM CICS Explorer as Eclipse (p2) packages for local installation from a shared folder on the network.
Find out more about installing CICS Explorer on the Mainframe Dev site.
Because of these reasons we recommend against deploying CICS Explorer using Web Start.
CICS Explorer Development
Original article (not recommended - see the above update):
This article explains how to provide a web-based installation of CICS Explorer. This is useful for system administrators who want to deploy the software to multiple desktops and provide automatic updates. The solution uses Java™ Web Start, which is an industry standard solution for deployment of Java applications from the web (and as such is not part of CICS Explorer or its support infrastructure). If you have any problems implementing it consult Java information sources, or seek informal support such as the CICS Explorer forum (see "Further Information" at the bottom of this post for links).
CICS Explorer is installed from a web server and cached on the workstation. When a new version is available on the web server, the cached version is automatically updated when the user next starts the CICS Explorer from the web site. If the version on the web site is the same as the cached version then the local version is started immediately.
The solution uses Java Web Start, which is an industry standard solution for deployment of Java applications from the web. Java Web Start provides the following advantages:
- Finer control over the user's installation experience
- Helps to ensure the correct versions of CICS Explorer are used when managing critical systems
- Automatic updates
- Cached on client side, which means that start-ups are fast
- Simplified deployment (no zip files)
Oracle will update Java at the start of 2014 to require stricter permissions information to be set out in the MANIFEST file of signed JAR files. This guide has been updated to tolerate these requirements, documented here ⇒New security requirements for RIAs in 7u51 (January 2014)
The following steps outline the deployment process:
- The system administrator prepares a version of CICS Explorer that looks exactly as end users will see it. This version is packaged for Web Start deployment and posted on a web server.
- The user launches Java Web Start using the file from the web server (either via command-line or web browser file association).
- Java Web Start finds no local copy, so it downloads the CICS Explorer archive and extracts it a cache folder ".explorerjws" in the user's home folder.
- CICS Explorer is started as normal.
- If the System administrator changes CICS Explorer on the web server, the time stamp will change. The user's next web start detects the time stamp on the web server is newer than the cached local folder and automatically refreshes the workstation cache with the updated copy from the web site.
Client workstation requirements
The following steps outline the client workstation requirements:
- Java Runtime Environment must be installed on Client
- (Optional) Web browser association that starts javaws when JNLP file is opened in the browser. Alternatively a short cut can invoke javaws with a URL to the JNLP file on the web server.
How to prepare a web start version of the CICS Explorer
- Java 7 SDK.
- Download of the CICS Explorer with any customization for your environment
- A Certificate for signing the jar file
- explorer_webstart.jar, install.jnlp and launch.jnlp provided with this article
The following example Windows command file illustrates the steps for creating the web start version of the CICS Explorer. It is illustrative only and not all of the steps need to be run every time, but it has been tested on Windows 7.
REM Command to set up Java Web Start Explorer JAR
REM Edit these environment variables
set java="c:\Program Files\IBM\Java70\"
@echo Step 1. Create a certificate for signing the jars in the keystore
@echo "explorerstore". If you have your own keystore and certificate
@echo already, modify the script to point to it. If you create it
@echo using this line, you'll be prompted for details about your
@echo organization, and a password.
%java%\bin\keytool -genkey -alias %keyalias% -keystore %keystore% -validity %days%
@echo Step 2. Sign the explorer_webstart jar with the certificate. This file
@echo will be hosted on the web server.
%java%\bin\jarsigner -keystore %keystore% explorer_webstart.jar %keyalias%
@echo verify explorer_webstart signature
%java%\bin\jarsigner -verify explorer_webstart.jar
@echo Step 3. Remove the JRE from CICS_Explorer - saves download time because
@echo when using Java Web Start, Explorer will run using the JRE on
@echo the client workstation.
rmdir CICS_Explorer\jre /S /Q
@echo Step 4. Create the explorer.jar - this will be unzipped on the client
@echo workstation, and held within the signed jar.
%java%\bin\jar -cf explorer.jar CICS_Explorer
@echo Step 5. Create the explorer_container.win32.x86.jar which will be
@echo hosted on the web server. The jar manifest must contain
@echo "all-permissions" to match the permissions required in the JNLP file.
%java%\bin\jar -xf explorer_webstart.jar manifest.line
%java%\bin\jar -cmf manifest.line explorer_container.win32.x86.jar explorer.jar
@echo Step 6. Sign the explorer jar
%java%\bin\jarsigner -keystore %keystore% explorer_container.win32.x86.jar %keyalias%
@echo Verify explorer_container.win32.x86 signature
%java%\bin\jarsigner -verify explorer_container.win32.x86.jar
@echo Step 7. Clean-up files that were created temporarily
Prepare to run the example
Create a working folder, for example "ExplorerWebStart", and extract all of the sample files from ExplorerWebStart.zip (last update November 4; September 19, 2013 update was for Java 7) into it.
Download the CICS Explorer zip file and extract the CICS_Explorer folder from the archive as a sub-folder of your working folder: "ExplorerWebStart/CICS_Explorer"
Customize CICS Explorer as required for your user base.
You can run the Explorer from "ExplorerWebStart/CICS_Explorer" and customize it. For example you may want to set-up connections, customize perspectives and pick columns for views. Once you have completed customization close the explorer.
Ensure you have a copy of the Java 7 SDK installed. The example assumes the IBM Java 7 SDK is installed in c:\Program Files\IBM\Java70\. If the SDK is installed elsewhere, then update the BuildWebStart.cmd at the beginning with the correct path to the SDK. You may also want to change the number of days the certificate lasts for and the path to the keystore or alias name if you already have your own certificate.
Now you are ready to package CICS Explorer for Java Web Start.
Run BuildWebStart.cmd as an initial step or manually carry out the steps documented within the file.
How to deploy the web start version of the CICS Explorer
Update the install.jnlp and launch.jnlp XML with the URL of the web folder where you are deploying the CICS Explorer. The information is in the codebase attribute of the XML. For example:
Put the signed explorer_container.win32.x86.jar, explorer_webstart.jar, install.jnlp and launch.jnlp into the web server folder identified in the codebase attribute above.
IMPORTANT: If you are using FTP, ensure that you use a binary transfer.
How to give users access to the Web Start version of the CICS Explorer
- Link to the launch.jnlp in the web folder from a web page. If you do this you should ensure that the web server is configured to handle Java Network Launch Protocol (JNLP) files correctly. Otherwise the Java Web Start won't be launched when the link to the JLNP file is used.
- Configure the web server so that files with the .jnlp extension are set to the application/x-java-jnlp-file MIME type.
- Deploy a short cut to user's desktops, using a command similar to:
- P2 style installation of tools on the client is not supported with Java Web Start, because any refresh from the server will overwrite the client cached version.
- Linux is not supported by the CICS Explorer for Java Web Start at present.
Installation log file
When the explorer provided web start install code runs, it produces a log file at %appdata%\..\local\Temp\cicsexplorerjws_installer.log
Here is a sample file for a successful installation:
1376991382750 Installing CICS Explorer
1376991382751 >> Looking for CICS Explorer jar.
1376991386786 >> Expanding CICS Explorer jar.
1376991386786 Inflating jar to C:\Users\niced\.cicsexplorerjws
1376991386787 extractJar: C:\Users\niced\AppData\Local\Temp\explorer4635257026253675766.tmp,
1376991386788 jar has 3690 entries
1376991415704 Jar inflated.
1376991415704 Install succeeded.
- ExplorerWebStart.zip - (last update November 4, 2013) contains the sample files referenced in this article. See Note 1 below for details on the updates.
- BuildWebStart.cmd - (Updated April 11, 2014 - new version of BuildWebStart.cmd previously included in ExplorerWebStart.zip. This new version better handles paths with spaces in them, prints out the command before it is run - making diagnosing issues easier, and contains additional error checking that is better for use in real practice. Note: the html file extension should be removed from the filename so that the resulting filename is "BuildWebStart.cmd". The html extension was only added to allow the upload/download to work properly for this blog entry).
- explorer_webstart.src.zip - (last update November 4, 2013) contains the sample files referenced in this article. See Note 1 below for details on the updates.
- CICS Explorer discussion forum
- For information about Java Web Start, see the JAVA Web Start tutorial
- For information about Java signing, see the keytool information
Note 1 (regarding the updates):
The zip file and text of this blog entry are updated for Java 7. The Web Start sample binary and source code are updated to allow the system administrator to override the install directory for the CICS Explorer instance installed via Java Web Start. This guide was also updated to tolerate the changes to Java in 2014 by Oracle that require stricter permissions information to be set out in the MANIFEST file of signed JAR files.
"This document and the associated sample programs ("Samples") are ©Copyright International Business Machines Corporation 2012, 2013.
Permission is hereby granted to licensees of IBM products to copy, use and modify the Samples for their internal business purposes only. No other permission is granted.
THE SAMPLES ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT OF PATENTS, COPYRIGHTS OR OTHER PROPRIETARY RIGHTS OF OTHERS. NEITHER THE AUTHOR NOR IBM WARRANT THAT THE FUNCTIONS, ROUTINES, AND DATA CONTAINED IN, OR GENERATED AS A RESULT OF THE SAMPLES, WILL MEET YOUR REQUIREMENTS OR BE ERROR-FREE. The entire risk related to the quality and performance of the Samples is with you. In the event that there is any defect, you assume the entire cost of all necessary services, repair or correction. IN NO EVENT WILL THE AUTHOR OR IBM BE LIABLE TO YOU OR TO ANY THIRD PARTY FOR ANY DIRECT OR INDIRECT DAMAGES (INCLUDING, WITHOUT LIMITATION, LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES) ARISING OUT OF THE USE OR INABILITY TO USE THE SAMPLES, EVEN IF THE AUTHOR OR IBM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Some jurisdictions do not allow the exclusion of implied warranties or the limitation or exclusion of liability for incidental or consequential damages, so some of the above may not apply to you."