Section 25.3.  Java Web Start (JNLP) - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

25.3. Java Web Start (JNLP)

Java Web Start, also known as JNLP, is a mechanism whereby applications are stored on a Web server and exposed to users as links on a Web page. When the user clicks on a link, his browser uses its JNLP content type handler to read the JNLP manifest and download, install, and launch the described Java resources.

25.3.1. How Java Web Start Works

Without turning this into a Java Web Start tutorial, the following is a brief introduction to the technology and its use with Eclipse.

A Web Start application is described by one or more .jnlp files. These are XML manifests that describe the application itself (e.g., its name, location, description) and the set of JARs that make up the application. JNLP manifest files can also include, or be extended by, other JNLP manifest files. Below is the top-level Hyperbola JNLP manifest file with the interesting parts highlighted:

hyperbola.jnlp.feature/rootfiles/hyperbola.jnlp
<?xml version="1.0" encoding="UTF-8"?>
<jnlp
    spec="1.0+"
    codebase="http://eclipsercp.org/hyperbola"
    href="hyperbola.jnlp">
  <information>
    <title>Hyperbola Chat Client</title>
    <vendor>eclipsercp.org</vendor>
    <homepage href="http://eclipsercp.org"/>
    <description>Hyperbola Chat Client</description>
    <icon kind="splash" href="splash.gif"/>
    <offline-allowed/>
  </information>
  <security>
     <all-permissions/>
  </security>
  <application-desc main-class="org.eclipse.core.launcher.WebStartMain">
     <argument>-nosplash</argument>
  </application-desc>
  <resources>
   <j2se version="1.4+" />
   <jar href="startup.jar"/>
   <extension
      name="Hyperbola Chat Feature"
      href="features/org.eclipsercp.hyperbola.feature_1.0.0.jnlp"/>
  <property
      name="osgi.instance.area"
      value="@user.home/Application Data/hyperbola"/>
  <property
      name="osgi.configuration.area"
      value="@user.home/Application Data/hyperbola"/>
  <property
      name="eclipse.product"
      value="org.eclipsercp.hyperbola.product"/>
  </resources>
</jnlp>

This file and the referenced resources are placed on a Web server and the manifest file is linked to from any number of Web pages. When the user clicks the link, the browser sees that it is a JNLP manifest file and invokes the Java Web Start infrastructure to handle the content. This is much like the way browsers handle Flash or PDF content. Depending on the browser configuration, the Web Start support and JRE may be dynamically downloaded and installed into the browser on first use.

After downloading and caching the JARs and extensions described in the JNLP manifest file, the Web Start handler starts Java and the requested application. While this process is kicked off via your browser, the resultant application is not run in the browser. Once a Java Web Start application is installed, the JARs and manifests need not be downloaded again. The second time the link is selected, the cached files are used. In some scenarios, the application can be configured to run directly from the user's desktop.

An additional point of interest is the startup.jar file included in the manifest. This is the standard Eclipse startup.jar. Notice that the <application-desc> tag identifies the WebStartMain rather than the standard Eclipse Main class as the entry point.

Top-level JNLP manifest files essentially play the role of hyperbola.exe, hyperbola.ini, and the config.ini in standard Eclipse deployments. They define command line arguments, some VM arguments, the splash screen, and set various system properties.

25.3.2. Hyperbola and Java Web Start

To illustrate how Web Start works in practice, let's set up Hyperbola to run via Web Start. Look back at the JNLP manifest and notice the <extension> tag. The JNLP manifest file listed there extends the current file. The snippet below shows the key elements of the extension file. Notice that it lists some plug-in JARs and it too has an extensionthe structure is recursive.

org.eclipsercp.hyperbola.feature_1.0.0.jnlp
<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" codebase="http://eclipsercp.org/hyperbola">
  <information>
    <title>Hyperbola</title>
    <vendor>eclipsercp.org</vendor>
  </information>
  <resources>
    <extension name="RCP" href="features/org.eclipse.rcp_3.1.0.jnlp"/>
    <jar href="plugins/org.eclipsercp.hyperbola_1.0.0.jar"/>
    <jar href="plugins/org.jivesoftware.smack_1.5.0.jar"/>
  ...
</jnlp>

This structure looks remarkably like Eclipse featuressome amount of identification and location information followed by a list of included plug-ins and nested lists. In general, the structure of JNLP manifest files is completely under your control, however, Eclipse maps features to JNLP manifest files as a matter of convenience and to enable tooling reuse.

For example, PDE takes advantage of this correlation and allows you to augment update sites with JNLP information as the features are built. This is convenient since update sites are already on the Web and already have the plug-ins needed. This approach has the added benefit that you do not have to change mindsets or build two parallel configurations. The tooling does not, however, generate the top-level JNLP manifest file described aboveyou have to do that.

To build the JNLP-enabled update site, first create a feature to describe the Web Start version of Hyperbola. Follow the same basic steps as in Chapter 24 when you created hyperbola.product.feature. This time, name the feature "hyperbola.jnlp.feature". Once created, add org.eclipsercp.hyperbola.feature to the Included Features list, and on the build.properties page, remove the bin.includes line altogether. Add in a root declaration, as shown below. It should be the only line in the file.

root=rootfiles

In the case of building an update site, declared root files get copied to the root of the site. In the Web Start case, we want startup.jar and the top-level JNLP manifest file to be at the root.

Create a rootfiles directory at the root of the hyperbola.jnlp.feature project and copy in startup.jar from your target. Use File > New > File to create a text file called hyperbola.jnlp in the rootfiles directory. This is the top-level JNLP manifest file. Fill it in with the content shown above. For simplicity, set the codebase attribute to file:/c:/siteyou can change that later when you deploy to a real site.

When you are done, the hyperbola.jnlp.feature project should look like Figure 25-1. As usual, you can get a pre-configured setup from the sample code for this chapter.

25.3.3. JAR Signing

Eclipse must run with all-permissions since it creates classloaders, reads and writes files, and performs other protected operations. To run a Java Web Start application with all-permissions, all JARs must be signed. Signing makes the JARs a bit bigger, but otherwise does not affect their normal use. The PDE Export wizard allows you to sign JARs as they are exported or added to a build output.

Before you can sign a JAR, you must have a keystore set up. To do this for production scenarios, you should acquire the appropriate certificates from a trusted certificate authority. If you use your own self-signed key, your users will get warnings that the JAR signatures cannot be authenticated.

For testing, you can set up a simple keystore using the keytool program included with typical JDKs, as shown below. For more options, see the keytool documentation.

keytool genkey alias <alias> keypass <password>

Once you've set up the keystore, sign the startup.jar you added to the hyperbola.jnlp.feature project using the command below. The <alias> is an arbitrary string of your choosing.

jarsigner.exe <location of startup.jar> <alias>

25.3.4. Exporting for Java Web Start

Now you are ready to export Hyperbola for Web Start. Open the File > Export... > Deployable features wizard and select the hyperbola.jnlp.feature. Ensure that the Package features and plug-ins as individual JAR archives checkbox is checked, and for this example, set the export location to c:\site. Click Next until you get to the Advanced Options page shown in Figure 25-2.

Fill in your JAR signing information and ensure that the Site URL is the same as you put in your top-level hyperbola.jnlp manifest file. Note that by default, keytool creates the keystore in your home directory in a file called .keystore.

Click Finish and PDE builds and signs the features and plug-ins included in Hyperbola. Note that signing JARs is costly, so expect your exports to take a little longer. The resulting update site is shown in Figure 25-3. Notice that the structure looks like a normal update site but with some .jnlp files added in. The site.xml is left over from Chapter 14, "Adding Update."

Test the Web Start version of Hyperbola by double-clicking on the hyperbola.jnlp manifest file. Depending on your OS, you may have to launch it via a Web browser. You should be able to just enter the following URL:

file:/c:/site/hyperbola.jnlp

or, if that doesn't work, create the simple HTML file shown below and click on the link:

<html>
   <a href="file:/c:/site/hyperbola.jnlp">Start Hyperbola</a>
</html>

25.3.5. Building JNLP Manifests

The PDE Build automated build infrastructure can also be configured to generate JNLP manifest files. Go back to the setup you had in Chapter 24 and add the following to the builder's build.properties and build the hyperbola.jnlp.feature. You might want to set the output format to be -folder to build the required update site directly.

hyperbola.builder/build.properties
jnlp.codebase=file:/c:/site
jnlp.j2se=1.4+
sign.alias=<alias>
sign.keystore=<keystore location>
sign.storepass=<password>

25.3.6. Java Web Start and Update

Each time the user starts his Web Start application, the Web Start infrastructure checks to see if the application has been changed. If it notices updated manifests or JARs, it replaces the local copies with the newer versionsWeb Start manages the install. As such, there is no particular need to use the Update technology in Web Start configurations. WebStartMain automatically discovers and installs downloaded plug-ins based on the classpath used to start the Java Web Start JVM.

It is possible, however, to use the Eclipse Update mechanism in concert with Web Start. Once the Web Start-based application is running (and assuming it includes the Update infrastructure), users can use Update to add functions, as outlined in Chapter 14. Newly acquired features and plug-ins are downloaded to a local site of their choosing and installed into Eclipse. These features and plug-ins are managed on the client by UpdateWeb Start does not install new versions for you even if they are added to the update/Web Start download site.