Deploying eclipse based application with Java Web Start

Applications built on eclipse 3.1 can now be deployed using Java Web Start.

Java Web Start "is an application-deployment technology that gives you the power to launch full-featured applications with a single click from your web browser".

The prerequisites to start eclipse from Java Web Start are:

• The deployed application must be eclipse 3.1 based;


• All deployed plug-ins must be jar'ed;


• All plug-ins must be signed since the application need full permission from the client.

The following steps describe how to setup a Java Web Start site serving up a feature based RCP application.

Step 1, creating a wrappering feature

• Create a feature including all the features that are listed in your product definition;


• Copy in a folder of your feature the startup.jar;


• Add the following line to the build.properties of the feature.
  

  root=<folderContainingStartup.jar>/  

  
  

Step 2, exporting the wrappering feature and the startup.jar

Note. Before proceeding with this step make sure to have a keystore available. Eclipse does not provide any facility to create keystores. You need to use keytool. In addition, ensure that the eclipse you are developing with is running on a Java SDK instead of a JRE. If this constraint is not satisfied, the jar signing will fail.

• Select the wrappering feature and do File > Export > Feature. In the wizard, select the wrappering feature, choose the "directory" option to export your jnlp application to, and check the option "package features and plug-ins as individual JAR archives". On the next page of the wizard, fill in the information relative to your keystore in the "Signing JAR Archives" section. Then in the "JNLP section", enter the name of the server that will serve up your application and the level of JRE required to start your application. That last value will be used to in the generated JNLP files to fill in the value of <j2se version="1.4+" /> . Click finish.


• Once the export is done you should have the following structure on disk
  

  site/   (The root of your jnlp site)    startup.jar    features/      WrapperingFeature_1.0.0.jar      WrapperingFeature_1.0.0.jnlp      com.xyz.abc_1.0.0.jar      com.xyz.abc_1.0.0.jnlp      ...    plugins/      org.eclipse.core.runtime_3.1.0.jar      com.foo.baz_1.0.0.jnlp      ...  

  
  


• Using the same keystore than the one used to export the feature, sign startup.jar using jarsigner.
  
  Tips: if you don't change keystore, replace the startup.jar from the feature with this signed version so you don't have to do this manual step on every export.

Step 3, creating the main jnlp file

A Java Web Start application is described by JNLP files. They replace the eclipse.exe and the config.ini files by some equivalent mechanism. For example, JNLP has its own mechanism to control splash screen, ways to pass parameters and define what constitutes the application.

When you did the export, all the simple JNLP files have been created, so you are left with writing the main file that will control the application. Because the majority of the main file is common to all applications, it is recommended to start from the following self documented template.

On the site serving up your application, the file must be located in the same folder than startup.jar. Once you will be done editing this file, your application will be ready.

<?xml version="1.0" encoding="UTF-8"?>  <jnlp       spec="1.0+"       codebase="http://myCompany.org/jnlpServer"       href="mail.jnlp"> <!-- URL to the site containing the jnlp application. It should match the value used on  export. Href, the name of this file -->    <information>      <!-- user readable name of the application -->      <title> Mail Application </title>        <!-- vendor name -->      <vendor>My company</vendor>      <!-- vendor homepage -->       <homepage href="My company website" />       <!-- product description -->      <description>This is a mail client</description>       <icon kind="splash" href="splash.gif"/>    </information>       <!--request all permissions 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 consituting the application -->      <!-- Here we are refering to the wrappering feature since it transitively refers to all the other plug-ins  necessary -->      <extension           name="Wrappering feature"          href="features/Wrappering_1.0.0.jnlp"/>         <!-- Information usually specified in the config.ini -->      <property           name="osgi.instance.area"           value="@user.home/Application Data/mail"/>      <property           name="osgi.configuration.area"           value="@user.home/Application Data/mail"/>                <!-- The id of the product to run, like found in the overview page of the product editor -->      <property           name="eclipse.product"           value="mail.product"/>    </resources>      <!-- Indicate on a platform basis which JRE to use -->     <resources os="Mac">      <j2se version="1.5+" java-vm-args="-XstartOnFirstThread"/>    </resources>    <resources os="Windows">      <j2se version="1.4+"/>    </resources>    <resources os="Linux">      <j2se version="1.4+"/>    </resources>  </jnlp>  

Tips: once you have created this file, you can store it in the wrappering feature in the same folder than the startup.jar, such that on every export you will get the complete structure.

Plug-ins based application

Even though your RCP application does not use features, Java Web Start-ing it is possible.

To do so, it is recommended to create a wrappering feature in order to facilitate the creation of the main jnlp file and ease the deployement. This wrappering feature will list all the plug-ins of your application. Once the feature has been updated copy the generated JNLP file and modify it to become your main JNLP file.

Known limitations

• Eclipse Update and Java Web Start
  
  Those two deployment technologies can work together but under the following restrictions: plug-ins installed by Java Web Start can not be updated by Update and vice-versa. Features and plug-ins installed by Java Web Start can't be refered in the prerequisites of features that needs to be installed by Update;


• Help can not be deployed through Java Web Start. However it could be installed using eclipse Update, or the server serving your application could run a help server;


• Request to exit the application with a restart code are ignored;


• On the mac, applications can only be webstarted by clients using java 1.5.