Project

General

Profile


Java Web Start

This page outlines the deployment of the TaxonomicEditor via Java Web Start. For a brief overview of how JWS works from the user's perspective, please see TaxonomicEditorImplementation#JavaWebStart.

Instructions

The following instructions are largely based on:

1. Create a feature project

The feature project is a wrapper for all JAR files necessary for the Editor to function. Create it with Ctrl-N -> Plug-in Development -> Feature Project. Name it "eu.etaxonomy.taxeditor.feature", and enter "EDIT" as the provider. Hit "Next", then

Under the "Plug-ins" tab, add "eu.etaxonomy.taxeditor", "org.eclipse.equinox.launcher", and any plug-ins necessary for the Editor to run; "2. Create a product" describes how to ensure these are all present. Under the "Included Features" tab, add "org.eclipse.rcp".

2. Create a product

Choose Ctrl-N -> Plug-in Development -> Product Configuration. Create the product in the eu.etaxonomy.taxeditor directory, and call the product eu.etaxonomy.taxeditor.product. Choose "Use a launch configuration: Eclipse Application", and hit "OK".

Under the "Overview" tab of the new product, go to "Product ID" and hit the "New" button. In the Product Definition wizard, choose "eu.etaxonomy.taxeditor" as the Defining Plug-in, choose a Product ID ("product1"), and under "Application:", choose "eu.etaxonomy.taxeditor.application". Back in the "Overview" tab, choose "features" under "The product configuration is based on". Under the "Configuration" tab, add "eu.etaxonomy.taxeditor.feature".

Now go back to "Overview" and attempt to launch the product. At this point, you can tell whether the feature has all the plug-ins it needs; error logs after unsuccessful launches should tell you exactly what's missing. Note that the feature needs to include not only the plug-ins listed in eu.etaxonomy.taxeditor/plugin.xml's "Required Plug-ins", but also the plug-ins that they in turn depend on.

3. Generate a keystore

All plug-ins must be signed since the application needs full permission from the client in order to run. Download, install, and run this keytool plugin to create a Java keystore (JKS), the keytool application that comes with the JDK. Be sure to note the keystore's location, alias, and password for the next step.

Note that when the user downloads the Editor for the first time, he will see a message that this signature could not be verified.

4. Export the feature

Choose File -> Export -> Deployable features, then hit "Next". Choose "eu.etaxonomy.taxeditor.feature" and an appropriate destination directory. Under the "Options" tab, choose "Package as individual JAR archives". Two new tabs appear. Under "JAR Signing", check "Sign the JAR archives using a keystore" and enter the appropriate data. Under "Java Web Start", check "Create JNLP manifests" and enter the URL and directory where the application files will be made available for download (currently "http://cybertaxonomy.eu/taxeditor"); JRE Version should be 1.6.

Note: If the project "eu.etaxonomy.taxeditor" has files with Java errors in them, a nasty-looking error will occur at this point: "Errors occurred during the operation. A zip file containing the build logs has been generated ...", even if the files are not referenced during Tax Editor sessions and will not cause problems during execution. Ignore!

Two directories - "features" and "plugins" - are then created. Copy these to the download directory. In features/org.eclipse.rcp_*.jnlp, comment out the following (don't ask me why - anything with "wpf" crashes the application, and apparently makes no difference when commented out):

<!--jar href="plugins/org.eclipse.equinox.launcher.wpf.win32.x86_1.0.0.v20070523.jar"/-->
<!--jar href="plugins/org.eclipse.swt.wpf.win32.x86_3.3.0.v3346.jar"/-->

5. Create the JNLP file

Replace the test values in [this template](http://dev.e-taxonomy.eu/trac/attachment/wiki/JavaWebStart/test.jnlp with the production settings. For more information on the JNLP file, please consult the JNLP syntax guide) .

<jnlp 
    spec="1.0+" 
    codebase="http://c084.bgbm.fu-berlin.de/webstart" 
    href="test.jnlp">

Replace "codebase" with the production server and download directory, and "href" with the name you give the JNLP file.

    <icon kind="splash" href="http://c084.bgbm.fu-berlin.de/webstart/splash.PNG"/>
    <icon href="http://c084.bgbm.fu-berlin.de/webstart/edit.gif" kind="default" />
    <shortcut online="false">
      <desktop />
      <menu />
    </shortcut>    

These are the hrefs to the splash page and the icon that will appear on the user's desktop, as well as instructions to put links on the desktop and in the start menu.

    <offline-allowed />

This tag says the user is allowed to use the cached application even when Web Start cannot contact the production server.

  <application-desc main-class="org.eclipse.equinox.launcher.WebStartMain">  
    <jar href="plugins/org.eclipse.equinox.launcher_1.0.0.v20070606.jar"/>

Make sure these reflect the current versions you're using.

    <extension 
        name="Wrapper feature"
        href="features/eu.etaxonomy.taxeditor.feature_1.0.0.jnlp"/>
    <property 
        name="eclipse.product" 
        value="eu.etaxonomy.taxeditor.product"/>

These are the references to the Editor feature and product.

<security>
   <all-permissions/>
</security> 

The "all-permissions" tag gives the application full access to the client system if all its JAR files are signed.

  <resources os="Mac">
    <j2se version="1.5" java-vm-args="-XstartOnFirstThread"/>
  </resources>
  <resources os="Windows">
    <j2se version="1.5"/>
  </resources>
  <resources os="Linux">
    <j2se version="1.5"/>
  </resources>

Here is where you specify which JRE the user needs on his machine. If he has an earlier version, Web Start automatically upgrades.

6. Create a link to the JNLP file

The final step is to create a webpage with a link to the JNLP file. When the user clicks on this link, the fun starts.

Testing

This location in the JNLP:

    <property 
        name="osgi.instance.area" 
        value="@user.home/Application Data/taxeditor"/>
    <property 
        name="osgi.configuration.area" 
        value="@user.home/Application Data/taxeditor"/>

is used by Web Start for various application information. (In Windows, @user.home = "C:\Documents and Settings_username_"). If the application dies without an error message, check here for an error log, for instance, to see which JAR files are missing.

To remove the cached version of the application, go to the Java Cache Viewer located in the temporary internet files part of the Java Control Panel. Delete everything relating to the application from "Applications" AND from "Resources". For descriptions on clearing the Web Start cache on different platforms, see https://www.vaultletsoft.com/support/clear-jws-cache.html.

Putting updates on the download site

The JNLP file and the two directories "features" and "plugins" should be placed on the EDIT server under:

  • /var/www/cybertaxonomy.eu/taxeditor

The download site during testing is TaxonomicEditorDownload.

Miscellaneous

The version of Eclipse used for development must run on a Java SDK instead of a JRE. If this constraint is not satisfied, the JAR signing will fail. To run Eclipse under the Java SDK, go to Window ~~> Preferences -> Java -> Installed JREs. If no JDK is listed, click "Add ..." and enter the JDK home directory ~~ i.e. "C:\Programme\Java\jdk1.6.0_02" - under "JRE home directory". Then be sure the JDK entry has a check mark next to it before hitting "OK".

Important: Java 6 Update 7 causes a Web Start error

See https://bugs.eclipse.org/bugs/show_bug.cgi?id=240500. New security restrictions prevent Web Start from getting information about cached jars on the user's machine.

The result is the following entry in the log file in @user.home/Application Data/taxeditor/:

 !SESSION Thu Jul 10 11:42:00 CEST 2008
-----------------------------------------
!ENTRY org.eclipse.equinox.launcher 4 0 2008-07-10 11:42:00.680
!MESSAGE Exception launching the Eclipse Platform:
!STACK
java.lang.NullPointerException
    at org.eclipse.equinox.launcher.Main.readFrameworkExtensions(Main.java:669)
    at org.eclipse.equinox.launcher.Main.addBaseJars(Main.java:720)
    at org.eclipse.equinox.launcher.Main.getDevPath(Main.java:642)
    at org.eclipse.equinox.launcher.Main.getBootPath(Main.java:827)
    at org.eclipse.equinox.launcher.Main.basicRun(Main.java:431)
    at org.eclipse.equinox.launcher.WebStartMain.basicRun(WebStartMain.java:78)
    at org.eclipse.equinox.launcher.Main.run(Main.java:1173)
    at org.eclipse.equinox.launcher.WebStartMain.main(WebStartMain.java:56)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
    at java.lang.reflect.Method.invoke(Unknown Source)
    at com.sun.javaws.Launcher.executeApplication(Unknown Source)
    at com.sun.javaws.Launcher.executeMainClass(Unknown Source)
    at com.sun.javaws.Launcher.doLaunchApp(Unknown Source)
    at com.sun.javaws.Launcher.run(Unknown Source)
    at java.lang.Thread.run(Unknown Source)

Web Start Alternatives

If another installation tool is chosen, here is a general description of how to write an Eclipse installer: http://help.eclipse.org/help33/topic/org.eclipse.platform.doc.isv/reference/misc/eclipse-install.html

test.jnlp - JNLP Template (2.53 KB) Pepe Ciardelli, 03/29/2008 09:39 AM

Add picture from clipboard (Maximum size: 40 MB)