IBM Support

Deploying HATS rich client applications using Java Web Start

Question & Answer


Question

Beginning with HATS Version 7, HATS added the option of building rich client applications in addition to Web applications. HATS Version 7 supports Lotus Expeditor 6.1 and Eclipse 3.2 as the target platforms for rich client applications. Please refer to the HATS Version 7 Information Center for more information on the HATS rich client support. This article assumes basic knowledge of HATS rich client development. Unlike a HATS Web application, which requires only a supported Web browser installed on each client, a HATS rich client application must be deployed to either an installed Lotus Expeditor 6.1 or Eclipse 3.2 runtime environment before that application can be used. Because Lotus Expeditor 6.1 provides the Network Client Installer component, which enables the server to download Expeditor Client, users can install Expeditor Client with ease. However, there is no corresponding component to the Network Client Installer in Eclipse 3.2.

Cause

If your HATS rich client application is built for Eclipse 3.2 and client workstations do not have the Eclipse 3.2 runtime environment, users need to install the runtime environment separately. Typically, the runtime environment is installed by expanding an archive file (.ZIP file) prepared by administrators.

Answer

This paper provides instructions for deploying your Host Access Transformation Services (HATS) rich client application using Java Web Start (JWS).

JWS is the technology used for deploying stand-alone Java applications over the network with the Java Network Launch Protocol (JNLP) files, which define the characteristics of the application to be deployed. JWS enables administrators to place archives, which packages HATS rich client applications with the Eclipse 3.2 runtime, with a JNLP file on a standard Web server so that users can install HATS applications and runtime using Web browsers.

Using JWS, which is installed on client workstations with the Java Runtime Environment (JRE), you can place your HATS rich client applications on a standard Web server. Use these instructions when you have built a HATS rich client application for the Eclipse platform and want to distribute the application and the Eclipse runtime packaged with it.

How It Works

The prerequisites for installing HATS rich client applications using JWS are:

  • An operating system supported by HATS rich client
  • The JRE with JWS enabled (Version 1.4.2 or later)
  • A Web browser.

The following steps describe how a user works with JWS:
  1. The user opens a Web browser.
  2. The user enters the URL that points to the JNLP file.
  3. A Web browser dialog asks the user how to handle the JNLP file.
  4. The user opens the JNLP file with the JWS Launcher.
  5. The JWS Launcher installs a HATS rich client application.
  6. A JWS dialog asks whether to allow the execution of the application.
  7. The user clicks Run
  8. JWS starts the HATS rich client application.


Setup Instructions

Overview

The prerequisites for setting up JWS for a HATS rich client application follow:
  • Rational Software Delivery Platform (RSDP) Version 7.0.0.2 or later.
  • HATS Version 7.0.0.2 or later.
  • Java Development Kit (JDK) Version 1.4.2 or later.
  • A certificate obtained from a Certification Authority (CA) on the production system. If you do not have one, you can use a self-signed certificate for testing.

An administrator sets up JWS for a HATS rich client application using the following steps:
  1. Prepare a certificate, which is used for signing archives.
  2. Create a HATS rich client project.
  3. Create a HATS (hostaccess) feature.
  4. Create a “wrapper” feature, which includes your HATS rich client application and the Eclipse runtime environment. If you intend to deploy your HATS rich client application to client workstations that run JRE Version 1.4.2, make sure your RSDP preference (Window > Preferences > Java > Compiler) generates JRE 1.4 compatible class files.
  5. Sign the startup.jar with the certificate.
  6. Create a JNLP file that defines your HATS rich client application and details for deployment.
  7. Export the wrapper feature as a deployable feature.
  8. Deploy the JNLP file and the signed archives (JAR) on a Web server.

The following instructions are based on Deploying eclipse based application with Java Web Start in the Eclipse Platform Plug-in Developer Guide.

Preparing a certificate

JWS uses its own secure sandbox model for running applications. To have unrestricted access to the system, including the network, applications need to be digitally signed with a certificate.

In the following example, a self-signed certificate is used. However, it is highly recommended to use a certificate obtained from a Certification Authority (CA) on the production system.
  • Install a JDK, if you do not have one installed yet. With a JRE, you cannot sign an Eclipse jar file. In the following example Sun JDK 1.5.0_12 is used.
  • Create a self-signed certificate using keytool.exe with the -genkey flag. This certificate is used to sign archives. On the production system, a certificate obtained from a Certification Authority (CA) should be used. Such certificates can be imported using keytool.exe with the −import flag. You can create a self-signed certificate using keytool.exe by answering the following questions with your own information:
C:\>"\Program Files\java\jdk1.5.0_12\bin\keytool.exe" –genkey

Enter keystore password:  yourpassword
What is your first and last name?
  [Unknown]:  Your Name
What is the name of your organizational unit?
  [Unknown]:  Your Unit
What is the name of your organization?
  [Unknown]:  Your Organization
What is the name of your City or Locality?
  [Unknown]:  Your City
What is the name of your State or Province?
  [Unknown]:  Your State
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Your Name, OU=Your Unit, O=Your Organization, L=Your City, ST=Your State, C=US correct?
  [no]:  yes
Enter key password for <mykey>
        (RETURN if same as keystore password):

C:\>
  • Keytool creates an output file (.keystore file) in the user's home directory. On Windows, it is typically C:\Documents and Settings\user_name.                                                                    
Creating the hostaccess feature

If you already have created the hostaccess feature, you can skip this section. You must supply a name for Provider, which is required by JWS.
  1. Start RSDP and switch to the Host Access Transformation Services perspective.
  2. Click File > New > Project...
  3. Select HATS > HATS Feature Project and click Next.
  4. Keep the default value (hostaccess) for Feature ID and Name, type your organization name for the Provider, select your HATS RC project, and click Finish.

Creating a “wrapper” feature

Like the hostaccess feature, you must supply a name for Provider.
  • Switch to the Plug-in Development perspective.
  • Click File > New > Project...
  • Select Plug-in Development > Feature Project and click Next.
  • Type hatswrapper for Project Name and your organization name for Feature Provider and click Finish.
  • Click the Included Features tab and add following features to the list:
org.eclipse.rcp
org.eclipse.emf
org.eclipse.emf.ecore.sdo
com.ibm.hats.core
com.ibm.etools.terminal.beans
com.ibm.hsrendering
hostaccess.
  • Click the Plug-ins tab and add the org.eclipse.ui.forms plugin.
  • Create a folder under the project root of the hatswrapper feature and name the folder rootfiles.
  • Open the build.properties file of the hatswrapper feature project and add the following line:

root = rootfiles
  • Copy startup.jar, which is typically found in C:\Program Files\IBM\SDP70, to the rootfiles folder.
  • The hatswrapper feature should now have the following structure:

Signing the startup.jar

JAR files under features and plugin directories are signed during the export process, but the startup.jar is not. You need to sign it using JDK’s jarsigner utility. Following is an example using a self-signed certificate:

C:\workspace\hatswrapper\rootfiles>"\Program Files\Java\jdk1.5.0_12\bin\jarsigner.exe" startup.jar mykey
Enter Passphrase for keystore:  mypassword 
 
Warning: The signer certificate will expire within six months.

C:\workspace\hatswrapper\rootfiles>


Creating a JNLP file

The main JNLP file must be in the rootfiles directory. The following example is based on the one found in Deploying eclipse based application with Java Web Start with some modifications for a HATS rich client application. You can save this as your main.jnlp file after editing some lines to match your environment. At a minimum, the codebase attribute of the jnlp element must be changed.

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+"
        codebase="http://myCompany.org/jnlpServer"
        href="main.jnlp"> <!-- URL to the site containing the jnlp
        application. It should match the value used on export. Href
        is the name of this file -->
  <information>
    <!-- user readable name of the application -->
    <title> Host Access Application </title>  
    <!-- vendor name -->
    <vendor>My company</vendor>
    <!-- vendor homepage -->
    <homepage href="My company website" />
    <!-- product description -->
    <description>This is a host access client</description>
    <shortcut online="false">
        <desktop/>
    </shortcut>
  </information>
 
  <!-- request all permission's from the application. This does not change-->
  <security>
    <all-permissions/>
  </security>
 
  <!-- The name of the main class to execute. This does not change-->
  <application-desc main-class="org.eclipse.core.launcher.WebStartMain">
    <argument>-nosplash</argument>
  </application-desc>
 
  <resources>
    <!-- Reference to the startup.jar. This does not change -->
    <jar href="startup.jar"/>
 
    <!-- Reference to all the plugins and features constituting the
           application -->
    <!-- Here we are referring to the wrapper feature since it 
           transitively refers to all the other plug-ins  necessary -->
    <extension name="Wrapper feature"
                     href="features/hatswrapper_1.0.0.jnlp"/>
 
    <!-- Information usually specified in the config.ini -->
    <property name="osgi.instance.area"
                    value="@user.home/Application Data/hostaccess"/>
    <property name="osgi.configuration.area"
                    value="@user.home/Application Data/hostaccess/.config"/>
    <property name="osgi.splashPath"
     value="platform:/base/plugins/com.ibm.hats.rcp.runtime.extension"/>
    <property name="osgi.bundles.defaultStartLevel"
                    value="4"/>
       
    <!-- The id of the product to run, like found in the overview page of the
           product editor -->
    <property name="eclipse.product"
                   value="com.ibm.hats.rcp.runtime.extension.product"/>
  </resources>

  <!-- Indicate on a platform basis which JRE to use -->
  <resources os="Windows">
    <j2se version="1.4+"/>
  </resources>
</jnlp>


Exporting the wrapper feature as a deployable feature

Click hatswrapper on the Package Explorer view of RSDP, click the right mouse button, and click Refresh. The hatswrapper feature should now have the following structure:



Click the right mouse button again, click Export... on the context menu, select Plug-in Development > Deployable features, and click Next.
Specify detailed information on the feature:

Available Features:
- Select hatswrapper only.

Destination tab:
- Using Windows Explorer, create a new directory, for example c:\myexportedfeature, and specify this directory in the Directory field.

Options tab:
- Check "Package as individual JAR archives (required for JNLP
and update sites)”.

JAR Signing tab: (*)
-
Check “Sign the JAR archives using a keystore (a password-protected database)”.
- Keystore location. Set the keystore location. By default, it is
C:\Documents and Settings\user_name\.keystore.
- Alias: Set the alias of the certificate used for signing. If you are going to
use a self-signed certificate, the default value is mykey.
- Password: Password for keystore.

Java Web Start tab: (*)
- Site URL: URL where the Java Web Start files are placed, like http://yourserver/directory/.
- JRE version: JRE version that are needed for running this feature. It would be fine with 1.4+.

(*) The JAR Signing and the Java Web Start tabs become visible when “Package as individual JAR archives (required for JNLP and update sites)” is checked.

Click Finish.
Open a command prompt window and change the directory to where the deployable feature is to be exported. The directory structure should appear like the following list:

main.jnlp
startup.jar
features\(feature jnlp and jar files)
plugins\(plugin jar files).


Deploying the JNLP file and archives on a Web server

You are now ready to deploy those files on your Web server. Copy the contents of the export directory to an accessible directory on your Web server.

If you are running the Apache Web server, add the following lines to the httpd.conf file:

AddType application/x-java-jnlp-file .jnlp
AddType application/x-java-archive .jar


When the deployment is completed, restart the Web browser and verify the deployment using the steps described in the How It Works section.

Runtime properties files and tracing

With JWS, HATS runtime properties files (runtime.properties and runtime-debug.properties) are stored in the <osgi.configuration.area>\com.ibm.hats.rcp.runtime directory, where <osgi.configuration.area> is the directory specified in the osgi.configuration.area property of the JNLP file. When either the com.ibm.hats.rcp.runtime or the com.ibm.hats.rcp.runtime.extension plugin is updated, those runtime properties files are overwritten by the new ones included in the com.ibm.hats.rcp.runtime.extension plugin.

When HATS tracing is enabled, log files are created in the <osgi.configuration.area>\com.ibm.hats.rcp.runtime\logs directory by default. You can change the default location by setting the traceLogDirectory property.

The Eclipse runtime creates log files in the <osgi.configuration.area> directory. If your HATS rich client application does not start and JWS does not display any errors, look at the log files stored in the directory.

JWS also provides tracing and its trace levels can be set in a .javawsrc file. You can also use the JAVAWS_TRACE_NATIVE and the JAVAWS_VM_ARGS environment variables for debugging. Please refer to Trouble shooting and debugging Java[TM] Web Start Applications for more details.


Uninstalling the application

When the HATS rich client application is no longer needed, you can uninstall it from the Java Control Panel. Please check the documentation of your JRE.

Note: In some views of a list of applications, the names of application and providers display as "%featureName" and "%providerName" instead of actual names. For further information on the cause of this, please see this report.

On Windows platforms, you can uninstall the HATS rich client application from Control Panel > Add or Remove Programs as well.

[{"Product":{"code":"SSXKAY-2","label":"Rational Host Access Transformation Services"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"7.0.2","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}},{"Product":{"code":"SSXKAY","label":"IBM Host Access Transformation Services"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"Not Applicable","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"","label":"i5\/OS"},{"code":"PF016","label":"Linux"},{"code":"","label":"Linux iSeries"},{"code":"","label":"Linux pSeries"},{"code":"","label":"Linux zSeries"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"7.1","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]

Document Information

Modified date:
26 August 2022

UID

swg21289818