WebStarting Equinox OSGi Apps

Java WebStart is a nice and easy way of deploying Java applications with one click from the web. In this blog I describe how to webstart an OSGi (Equinox) based application using Eclipse as IDE. First you develop your OSGi bundles as usual, to run your application, just create an OSGi framework launcher and run it. To webstart this set of bundles, you need to take care about a few things:

  • All bundles have to be deployed as signed JAR files
  • You need a feature that contains all the necessary bundles
  • When exporting the feature, make sure that PDE creates a JNLP (Java Network Lauching Protocol)  file (a checkbox in the export wizard) for this feature
  • Provide a root JNLP file for you application
  • Deploy your application to a web server and make sure that the web server is aware of the  application/x-java-jnlp-file mime type

To sign the JAR files, you just need to create a keystore and a key. Sun’s tutorial gives a good overview about that. So, first create a feature and put all your bundles and the OSGi runtime bundles needed by your application in the feature. When exporting the feature, make sure that you sign all JARs and that a JNLP file is created (The wizards provides 2 tabs for that). For testing you can specify a file URL as Site URL for Java WebStart. Make sure that your site URL for testing is the file location where you deploy your feature. Here is an example for a file based Site URL: “file:/c:/temp/pm-feature-export”. Now, we need a root JNLP file and make sure it is deployed together with our feature. To do that, create a directory within your feature named “rootfiles”. In this directory, create a file yourapp.jnlp. To make sure that your JNLP file is deployed properly, edit the build.properties of your project and include “root=rootfiles” as first entry. Now you can edit the JNLP file. Here is the file I use for my dynamic OSGI demo:

<!-- URL to the site containing the jnlp application. It should match the value used on  export. Href, the name of this file -->

<!-- user readable name of the application -->
<title>Person Manager (A dynamic Swing OSGi demo)</title>
<!-- vendor name -->
Kai Tödter
<!-- vendor homepage -->

<!-- product description -->
Person Manager is a demo application to demonstrate best practices when it comes to dynamic OSGi based applications

<!--request all permissions from the application. This does not change-->

<!-- The name of the main class to execute. This does not change-->


<!-- Reference to the launcher jar. The version segment must be updated to the version being used-->

<!-- 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 -->

<!-- Information usually specified in the config.ini -->

<!-- Indicate on a platform basis which JRE to use -->

While I don’t explain all the details, I focus on the Equinox specific things: In the resources section, you need to specify the main JAR file, which is your preferred Equinox launcher. The you have to link to the JNLP file for your feature. This JNLP file was created by PDE for you. Then you want to specify a few Equinox-specific properties:

  • osgi.configuration.area: the configuration area where OSGi stores runtime information
  • osgi.bundles: The list of bundles you want to start. You don’t have to specify versions here, just use the schema: @start. You can also specify the start level of the bundles like @2:start
  • osgi.noShutdown: Must be true, since you did not specify an Eclipse application
  • eclipse.ignoreApp: Must be true for the same reason
  • org.osgi.framework.bootdelegation: Value “*” helps to load JRE classes, e.g. if you use a Swing GUI

Having created a similar JNLP file for your application, you can deploy it locally and test it usinf file based Java WebStart. If everything is OK, change the WebStart Site URL (in both, your root JNLP file and the feature export wizard) to the web server real URL.

If want to take a detailed look at a running example, check our my dynamic OSGi demo. If you have Java 6 running and want to launch the demo using WebStart, just click here.

Have fun!


This Post Has 3 Comments

  1. Jens Goldhammer

    Hallo Herr Trödter,

    vielen Dank für den guten Tipp. Was ist aber, wenn ein Bundle nicht als Jar exportiert werden kann, sondern entpackt auf der Platte landen muss, um z.B. DLL-Dateien zu laden und im Windows zu registrieren, die per com4j benutzt werden.
    Erlaubt das Webstart nicht? Gibt es einen Workaround dafür?

    Viele Grüße
    Jens Goldhammer

  2. K. Morales

    Good example. Do you have one that translates this into a headless build? That is, an example that generates a web-startable build wherein a jnlp file is auto-generated for each feature that is an extension, in the same manner that the Export Feature Wizard behaves when the “Package as individual JAR archives” option is checked?

Leave a Reply

I accept the Privacy Policy