Run eclipse RCP application via WebStart

The last days I need to create a small prototype to demonstrate how to start a eclipse RCP application via webstart. After reading many tutorials and tipps I have now a working setup which I want to share with you.

The main tutorial which I followed was the eclipse help itself. But there are some hidden points which are important to respect.

Lets start:

You need 4 Projects:

• Eclipse RCP plugin
• Feature for the plugin
• Wrapping feature for webstart
• entry or start JNLP file

At least you need an webserver which can deliver your files.

Create eclipse RCP plugin with a example RCP application provided by eclipse:

This plugin will provide the RCP application with a small demo UI. In a larger project you will normally have more than one plugin. But for demonstration proposed this would be enough.

1. From the eclipse main menu, go to File > New > Project… (the New Project wizard opens), select Plugin-in Development > Plug-in Project
2. Press Next > enter „org.test.webstart.demo.plugin“ as Project name
3. Press Next > change the Version to „0.1.0“
4. Press Next > select RCP application with an view > press Finish

At this point you should have a small RCP „application“ which can started from eclipse. Select the project root > select Run from the menu > select Run As > Eclipse Application. Now you should see the demo UI.

Next we need a Eclipse feature project which uses the plugin.

Create eclipse feature which contains the plugin and a reference to the eclipse rcp feature:

We need a feature which depends on the demo plugin and on the eclipse rcp feature. The dependency to the eclipse rcp feature is required to export later all required plugins and features for webstart, to run the complete rcp application.

1. In the eclipse main menu go to File > New > Project… (the New Project Dialog opens), select Plug-in Development > Feature Project
2. Press Next > enter „org.test.webstart.demo.feature“ as project name > change the Version to „0.1.0“
3. Press Next > select „org.test.webstart.demo.plugin“ from plug-ins list > press Finish

The feature editor opens. Now you need to add the eclipse rcp feature as included feature. To do so select Included Feature tab in the feature editor > add „org.eclipse.rcp“ as feature. Save and close the feature editor.

This feature contains now all you need to run your application as a full featured eclipse RCP application. Now we need another wrapping feature to get the Webstart launcher on board.

Create wrapping feature for webstart

This feature will be used to export all required JAR files with the eclipse java webstart exporter into a local filesystem.

1. From the eclipse main menu select File > New > Project… (the New Project Dialog opens), select Plug-in Development > Feature Project
2. Press Next > enter „org.test.webstart.demo.wrapperfeature“ as project name > change the Version to „0.1.0“
3. Press Finish. The feature editor opens.

Now we need a dependency to the equinox launcher plugin and include our own feature.

1. In the feature editor select the Plug-ins tab > add „org.eclipse.equinox.launcher“.
2. Select the Included Feature tab > add „org.test.webstart.demo.feature“ > save the editor.
3. From the project root select the eclipse main menu > select File > Export… > select Deployable Features (the export wizard opens)
4. Press Select All
5. In the Desitination tab select a directory where you want to export the JAR and JNLP files.
6. In the Options tab only select Package as individual JAR archives. If you select Generate metadata repository nothing will be exported!
7. In the JAR Signing tab fill in all fields with the information from your keystore. If you do not have an keystore you can create your own by follow these instructions.
8. In the Java Webstart tab select Create JNLP manifests for the JAR archives > add the Site URL like http://localhost:8080/demoui-webstart > set 1.5+ for the JRE version > pess Finish

Now you should have in your destination folder a folder structure like
– features
– plugins

Under the features folder you should have some JNLP files. Because of an error in the eclipse exporter you need to adjust the JNLP files. For example the JNLP file of the feature looks like:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" codebase="http://localhost:8080/demoui-webstart">
	<information>
		<title>Demo_rcp_feature</title>
		<offline-allowed/>
	</information>
	<security>
		<all-permissions/>
	</security>
	<component-desc/>
	<resources>
		<j2se version="1.5+" />
	</resources>
	<resources>
		<extension href="features/org.eclipse.rcp_3.5.2.R35x_v20100119-9SA0FxwFnoCU5XxWItFdXXb27BA6.jnlp" />
		<jar href="plugins/demo_rcp_0.1.0.201103241351.jar"/>
	</resources>
</jnlp

You need to change the tag and add the required vendor information. The resulting information tag should look like

	<information>
		<title>Demo_rcp_feature</title>	
		<vendor>Me</vendor>
		<offline-allowed/>
	</information

You need to do this for all JNLP files in the features folder!

Create start.jnlp file as the entry point for the web application

As a final step you need to create your entry JNLP file which is the starting point of your webstart application. Here is an example for start.jnlp:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp 
    spec="1.0+" 
    codebase="http://localhost:8080/demoui-webstart" 
    href="start.jnlp"> 
  <information>
    <!-- user readable name of the application -->
    <title> Demo UI Application </title>  
    <!-- vendor name -->
    <vendor>Me</vendor>
    <!-- vendor homepage --> 
    <homepage href="http://www.me.org" /> 
    <!-- product description -->
    <description>description</description> 
    <offline-allowed/>
  </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.equinox.launcher.WebStartMain">
    <argument>-nosplash</argument>
  </application-desc>
 
  <resources>
    <!-- Reference to the launcher jar. The version segment must be updated to the version being used-->
    <jar href="plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.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/
org.test.webstart.demo.wrapperfeature_0.1.0.jnlp"/>
 
    <!-- Information usually specified in the config.ini -->
    <property 
        name="osgi.instance.area" 
        value="@user.home/Application Data/demoui-rcp"/>
    <property 
        name="osgi.configuration.area" 
        value="@user.home/Application Data/demoui-rcp"/>
    <!-- The id of the product to run, like found in the overview page of the product editor -->
    <property 
        name="eclipse.application" 
        value="org.demo.webstart.plugin.application"/>
  </resources>

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

Some remarks according the main JNLP file:

You need to adjust (or take care) of the lines 04, 30, 36, 48.

Line 04 defines the codebase. Every time you want to deploy you application on an websever you need to adjust the codebase (in every JNLP file in your project!) to the web application location.

Line 30 depends on you eclipse distribution (I have used eclipse 3.5 with some updates). You have to check the right version in your plugins folder and update the start.jnlp file.

Line 36 defines the starting feature JNLP file. This file itself refers to the other JNLP files in the features folder (which is automatically done from the eclipse exporter). You need to adjust this line if your project name differs from this example.

Line 48 defines the entry point to your application. This is the application ID from the example plugin. You can find the ID if you open the plugin editor of your example plugin. To do so open your example plugin and open the plugin.xml file. Under the tab Overview you can find the ID: „org.demo.webstart.plugin“. Now you also need to open the tab Extensions. Under the Extensions Details you can find the ID of your application. The complete application ID which you need to refer in the JNLP file is then „org.demo.webstart.plugin.application“.

If you now put the main JNLP file and the plugins + features folders under an webserver which delivers the files from http://localhost:8080/demoui-webstart/ you can see your test application. You should have following structure:

– start.jnlp
|– features
|– plugins

Simple click following link: http://localhost:8080/demoui-webstart/start.jnlp

Hint:
A small problem over which I stumbled while developing the example application:

If you start the application and you get from webstart an exception that plugin with *WTP* are not found, you can have a look into the JNLP files in the features folder. Some of these files define resources which are not exported by the eclipse webstart exporter. I have simple removed these resources from the JNLP files and it works.

Update:
I have created a Github repository with some code examples. You may clone my repo or send me patches with corrections.

Additional update:
I have now finished my github example and pushed also a complete working example. If you want to see how it works you can pull the https://github.com/waffel/Wordpress-examples/tree/master/org.waffel.worpress.demo.webstart.result project. With the help of maven you can simple start the application via

mvn jetty:run

This launches the jetty webserver and you can hit your browser to http://localhost:8080/demoui-webstart/start.jnlp

I have done all the mentioned steps from this blog for myself with a eclipse 3.7.