Deploying an Eclipse-based application with Java Web Start

Enabling easy deployment for a custom product

Learn how to build a small, bare-bones application built on the Eclipse Framework and deploy it through Java™ Web Start (JWS) — a technology you can use to deploy Java applications easily over standard Internet sites, enabling easy upgrades and distribution.

Share:

Nathan A. Good, Senior Information Engineer, Freelance Developer

Nathan Good lives in the Twin Cities area of Minnesota. Professionally, he does software development, software architecture, and systems administration. When he's not writing software, he enjoys building PCs and servers, reading about and working with new technologies, and trying to get his friends to make the move to open source software. He's written and co-written many books and articles, including Professional Red Hat Enterprise Linux 3, Regular Expression Recipes: A Problem-Solution Approach, and Foundations of PEAR: Rapid PHP Development.



03 February 2009

Also available in Portuguese

Before you start

About this tutorial

When I was starting to build an application, I settled on the Java programming language for my implementation language. I wanted to write an application that could be run on Microsoft® Windows®, Linux®, or Mac OS X. The application had to use local resources, so building it as a stand-alone application made more sense than trying it in a Web application. However, I got stuck on deployment. I wanted to be able to easily deploy the application for the initial installation, and I wanted to be able to easily push updates without necessarily building an update framework into my application. Enter JWS, a technology that allows you to deploy applications over the Internet with a single click.

If you couple JWS with the ability to build an application on the Eclipse Platform, you have a pretty powerful combination that allows you to deploy some serious enterprise-class tools in a manner much easier than building and pushing out installer programs.

This tutorial shows how to build an application based on the Eclipse Platform and how to deploy that application with JWS. This is not to be confused with building a Rich Client Platform (RCP) application using the Standard Widget Toolkit (SWT) in Eclipse and using JWS to distribute it (see Resources for a tutorial on how to do that).

Objectives

After reading this tutorial, you should be able to develop a product that extends the Eclipse Platform and deploy the Eclipse-based application using JWS.

Prerequisites

You should be familiar with Eclipse and the Java programming language. Knowledge of XML will be helpful when reading the XML examples.

System requirements

To run the samples, you must have Eclipse V3.3 or later installed and running. You will also need to have Java V1.5 or later. To run the JWS example, you need access to a running Web server and the ability to add a MIME-type association to the Web server, if it's not already properly configured. Ideally, you should have a local development Web server you can use for testing.


Eclipse Framework overview

The Eclipse Java integrated development environment (IDE) is built on the Eclipse Platform. The default Java IDE most people are used to using is the standard Eclipse Platform with a set of basic plug-ins that are automatically installed with the downloadable Eclipse distribution. These plug-ins make up what a user experiences as the IDE.

From the Eclipse site, you can download just the Eclipse Platform software development kit (SDK). With only the Eclipse Platform SDK, you can't do Java development without installing additional plug-ins. If you attempt to create a new project using a wizard, you will see that none of the usual wizards (like Java Project) are available. Because of the limited behavior, the Eclipse Platform SDK by itself isn't particularly useful. But because the Eclipse Platform SDK provides a framework for building applications, it's very useful as a starting point for building more powerful tools.

When you build features on top of the Eclipse Platform and have your own application, deploying it to your users is the next step. JWS is a mechanism you can use to deploy Java applications. Eclipse, being written in the Java language, is no exception. JWS gives you the ability to deploy applications relatively easily over the Internet when a user clicks a link.

RCP applications

Eclipse also gives you the ability to build RCP applications using the SWT. This process is different from building products that become applications based on the Eclipse Platform. Applications built using SWT can be smaller and need not extend the Eclipse Platform. If you're building an application that doesn't extend the Eclipse Platform, consider using SWT, instead; you can still distribute your SWT application using JWS.


Java Web Start overview

JWS allows you to deploy stand-alone Java applications over the Internet with a single click. Your users click a link to an XML file with a Java Network Launch Protocol (.jnlp) extension, and JWS does the rest. Using the JNLP, JWS downloads the files it needs, caches them, and launches the application.

As a developer, you place the necessary files — such as Java Archives (JARs) — in a location that can be accessed from a Web server. The JNLP file contains information that tells the JWS client on your users' computers where to get the JARs. So instead of deploying your stand-alone Java application to all of your users' computers, you only have to deploy your application to your Web server. Your users take it from there.

In addition to deployments, JWS greatly simplifies updates. Whenever a JWS application starts, the JWS client on the users' computers attempts to find the server and make sure the client has the latest files. If the local files are out of date, it automatically downloads the updated files to the client. The updates are more or less transparent to the user, which presents an ideal environment through which to deploy an application based on the Eclipse Platform.

Security

Applications commonly require that users have elevated permissions to install them. The need for users to have higher-level permissions than they typically have is often a barrier to providing the ability for users to install applications on their computers — particularly in large companies. Because JWS caches the JARs in a nonsystem directory and have other security permissions, users don't need to have elevated permissions to install and run JWS applications locally. The ability for relatively restricted users to take advantage of JWS is another compelling reason to consider it for deployment in large organizations.

JWS runs the application in a "sandboxed" execution, similar to a Java applet. Entries in the JNLP file — which is covered in greater detail later — provide the ability to request permissions to access the file system and network. To request all permissions, you must sign the JARs. Eclipse takes care of this for you, provided you have a keystore. (More information about configuring Eclipse to use your keystore is provided in the "Packaging the application" section.)

Running offline

When your users have downloaded the application and run it once, and when JWS has the resources it needs in its local cache, your users are free to use the application without being connected to the Internet (as long as your application doesn't require Internet connectivity). JWS simply uses the locally cached resources to run the application.


Setting up

Install JWS

If you have Java Platform, Standard Edition (Java SE) V5 or later, you already have JWS installed. If you have Windows, JWS is installed in your Java home directory (for example, C:\Program Files\Java\jre\bin). On Mac OS X, JWS resides in Applications/Utilities/Java. You can start the JWS console without actually installing or running a JWS application.

By starting the JWS console, you can view the applications in your JWS cache. From the console, you can start any JWS applications you have installed, delete them from your cache, or install shortcuts to the applications. To start the console, type the following command, making sure Java is in your path:

javaws -viewer

Once started, the viewer looks something like Figure 1. You may have no applications installed if you've never used JWS before.

Figure 1. The Java Web Start viewer
The Java Web Start viewer

If you don't have a Java Runtime Environment (JRE) installed, download the latest version and install it. As long as it's Java SE V5 or later, it will include JWS.

Configure your Web server

In most cases, JWS should automatically start if you open a JNLP file. If the JNLP file is on a Web server that doesn't have the JNLP file associated correctly, you can download the file and open it locally. I've actually e-mailed the JNLP file before — still having the resources located at the URL in the file — and the recipients were able to successfully run the application using JWS.

If you're setting up a Web server to serve JNLP files, which is the easiest method of distribution, you need to add the following file association:

application/x-java-jnlp-file JNLP

Follow your Web server's documentation for setting up the MIME association correctly. If you're using an ISP, consult your ISP's documentation to learn how you can add the JNLP MIME type.

JNLP file structure

The JNLP file is an XML file that contains instructions for how JWS will download and use your application. It helps to understand the different parts of the JNLP file so you can modify it with confidence.

Listing 1 shows a basic JNLP file. It has only those elements absolutely required to distribute a stand-alone application with JWS.

Listing 1. A basic JNLP file
<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+" codebase="http://www.example.com/applications/" href="app.jnlp">
  <information>
    <title>Application Title</title>
    <vendor>Application Vendor</vendor>
    <homepage href="http://www.example.com" />
    <description>This is an application.</description>
  </information>
  <security>
    <all-permissions />
  </security>
  <!-- The name of the main class to execute. -->
  <application-desc main-class="com.example.MyMainClass">
  </application-desc>
  <resources>
    <jar href="exampleApp.jar" />
  </resources>
</jnlp>

The example in Listing 1 would tell JWS to download the exampleApp.jar file from the URL. The full URL would be http://www.example.com/applications/exampleApp.jar. When the JAR is downloaded, JWS would execute the class com.example.MyMainClass. Assuming that everything the class needs to run is included in exampleApp.jar, it would run as users initialized it themselves. This file would be the equivalent of running the command:

java -cp exampleApp.jar com.example.MyMainClass

In this example, because the <all-permissions> element is present, exampleApp.jar must be signed.

The <jnlp> element, which is the root element of the file, has the attributes in Table 1.

Table 1. <jnlp> element attributes
AttributeDescription
specThe minimum version of the JNLP specification this file will work with
codebaseThe base URL of your application (the other URLs in the file will be relative to this base)
hrefThe URL of the JNLP file itself (JNLP files can be used offline, and this URL tells JWS where to get the online version)
versionThe version of the application and the JNLP file (when you're building JWS applications, think of these as the same thing)

The <information> element has the attributes shown in Table 2.

Table 2. Attributes of the <information> element
AttributeDescription
osThe operating systems the JWS application supports
archThe architecture (processor) supported
platformThe supported platform
localeThe locale supported

Other required elements:

  • The <title> element contains the title of the application. This is displayed in the JWS control panel. It's also displayed when users start the application with JWS.
  • The <vendor> element contains the name of the software vendor for the application.
  • The <resources> element contains the information about the resources the application requires. Resources here include the JARs that contain classes your application uses or properties your application can set and use. Typical resources can be listed in any one of the elements shown in Table 3 (see Resources for a full listing).
Table 3. Typical <resource> elements
ElementDescription
<jar>An href attribute that contains the href to a JAR
<nativelib>An href attribute that contains the href to native library JAR
<j2se>The version and arguments given to the virtual machine (VM)
<property>Specifies properties that can be found by System.getProperty

For the full syntax of the JNLP file, see links to Sun Microsystems' documentation in Resources.


Building a basic Eclipse-based application

At this point, you should have an understanding of what the JNLP file does and what it needs to contain for you to deploy an application using JWS. You should have a Web server from which you can launch a JNLP file with the correct association. With a basic understanding of JWS and the JNLP file, you can start building your application based on Eclipse.

Install Eclipse

To begin, you need to download the Eclipse Platform SDK (if you don't already have Eclipse installed). If you already have Eclipse, you can use the version that you have installed. When you have the Platform SDK, you need to install the Eclipse Plug-in Development Environment feature (see Figure 2 for an example of the feature selected in the installer). To find out more about installing plug-ins in Eclipse, see Resources.

Figure 2. Selecting the Eclipse Plug-in Development Environment
Selecting the Eclipse Plug-in Development Environment

Create a new product

Checking out an example

To look at an example from Eclipse, check out the example Web browser. The code is available through the Concurrent Versions System (CVS), so to get it, you must have a CVS client on your computer. You can check the project out using the following command: cvs -d :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse export -r HEAD org.eclipse.ui.examples.rcp.browser. After you have the project locally, you can import it into your Eclipse workspace.

To get a picture of the JWS deployment in action, create a new product. Your product will contain an application that will automatically be loaded when the Eclipse launcher launches the Eclipse platform.

The application has a simple view that shows you that it has loaded correctly, similar to the quintessential Hello World application. The view opens in a new perspective in the workbench. A Unified Modeling Language (UML) diagram of these classes is shown in Figure 3.

Figure 3. UML of basic classes for a product
UML of basic classes for a product

For brevity, I have kept the classes as simple as possible. They're just enough to show that a new, custom product is being loaded with its own custom view. If you build your own product, you can add menu bars, other views, help screens, and more. To add these custom features, look at the Resources section to find more places to learn about extending Eclipse.

To build a simple product example, start by building a new plug-in project. Choose File > New > Project. In the Select a wizard window, expand Plug-in Development, then select Plug-in Project, as shown in Figure 4. Click Next to continue.

Figure 4. Selecting the plug-in project
Selecting the plug-in project

For the Project name, type a name that fits your project. I like to use my plug-in's base package name as the project, such as com.nathanagood.examples.rcp.simpleApp. Eclipse's plug-in projects seem to be named the same way, so I follow that convention. After typing the project name, leave the other values as default.

Figure 5. Entering project information
Entering project information

In the Plug-in Content window (see Figure 6), you have a chance to adjust the name of the plug-in, the name of the provider, and the version. I add .plugin onto the end of the default value for the Plug-in ID, but just as a preference. It's not necessary to change it. If you want to change the name of the Activator class or the class's package, do so in this window. When you're finished making changes, click Next.

Figure 6. Entering the plug-in content
Entering the plug-in content

The Templates page (see Figure 7) contains a list of templates that can get you started in your plug-in. Because I wanted to create an example view, then add the product and application extensions to it, I selected Plug-in with a view to get started. Choose the template you want to use and click Finish to build your project.

Figure 7. Choosing a template
Choosing a template

Complete the sample project

At this point, you have a new plug-in project with the view. To complete building the example project:

  1. Extend the WorkbenchAdvisor class (SimpleApplicationAdvisor, in this example).

    This class has a method that returns the ID of the perspective to load on the application's initialization so you see the custom perspective with the custom view right away without seeing the Welcome workbench.

  2. Create an implementation of IPerspectiveFactory (that is, SimpleAppPerspectiveFactory).

    The factory creates your initial perspective by modifying the IPageLayout passed to its createInitialLayout() method.

  3. Extend WorkbenchWindowAdvisor (that is, SimpleWindowAdvisor).

    By overriding preWindowOpen(), you can set up the initial size and other attributes of the workbench.

  4. Create an implementation of IApplication (that is, SimpleApplication).

    The implementation class creates and runs your custom workbench configuration, loading your perspective and view upon startup.

Examples of these classes are available in the code download that comes with this tutorial.

Modify the plugin.xml file

After building the classes, modify the plugin.xml file to include the extension points that have references to all of the classes just created. The advantage of writing all the classes first, like in this tutorial, is that you can use the graphical editor for the plugin.xml file to select the extension points and classes. Although you can also easily edit the source XML manually, using the GUI to add the extension points reduces the likelihood of mistyped class names or extension points. Much of my troubleshooting has resulted in copy-and-paste errors, where I mistyped IDs or class names.

Figure 8 shows the extension points on the Extensions tab of the graphical Plug-in Manifest Editor.

Figure 8. Extension points
Extension points

An example of the plugin.xml file is shown in Listing 2.

Listing 2. Sample plugin.xml file
<?xml version="1.0" encoding="utf-8"?>
<?eclipse version="3.2"?>
<plugin>
  <extension point="org.eclipse.ui.views">
    <category name="Sample Category"
    id="com.nathanagood.examples.rcp.simpleApp.plugin"></category>
    <view name="Sample View" icon="icons/sample.gif"
    category="com.nathanagood.examples.rcp.simpleApp.plugin"
    class="com.nathanagood.examples.rcp.simpleapp.plugin.views.SampleView"
    id="com.nathanagood.examples.rcp.simpleapp.plugin.views.SampleView">
    </view>
  </extension>
  <extension point="org.eclipse.ui.perspectives">
    <perspective id="com.nathanagood.examples.rcp.simpleApp.plugin.perspective"
    name="Simple App Perspective"
    class="com.nathanagood.examples.rcp.simpleapp.SimpleAppPerspectiveFactory"
    fixed="false" />
  </extension>
  <extension point="org.eclipse.ui.perspectiveExtensions">
    <perspectiveExtension targetID="org.eclipse.jdt.ui.JavaPerspective">

      <view ratio="0.5" relative="org.eclipse.ui.views.TaskList"
      relationship="right"
      id="com.nathanagood.examples.rcp.simpleapp.plugin.views.SampleView">
      </view>
    </perspectiveExtension>
  </extension>
  <extension point="org.eclipse.help.contexts">
    <contexts file="contexts.xml"></contexts>
  </extension>
  <extension point="org.eclipse.core.runtime.products"
  id="product">
    <product name="Simple App"
    application="com.nathanagood.examples.rcp.simpleApp.plugin.app">

      <property name="appName" value="Simple App" />
    </product>
  </extension>
  <extension id="app"
  point="org.eclipse.core.runtime.applications">
    <application>
      <run class="com.nathanagood.examples.rcp.simpleapp.SimpleApplication">
      </run>
    </application>
  </extension>
</plugin>

Add the configuration file

After fully modifying and saving the plugin.xml file, it's time to add the product configuration file used to tell the Eclipse Platform about your product:

  1. Choose File > New > Product Configuration.

    The Product Configuration window appears.

    Figure 9. Product configuration
    Product configuration
  2. Choose your plug-in project as the parent folder.
  3. Add the name of the file (for example, SimpleApplication.product).
  4. Select Use an existing product, then, from the list, select the ID of your product.

    The ID of the product is what you defined in the plugin.xml file under the org.eclipse.core.runtime.products extension point.

After you've added the product configuration file, you can use the graphical Product Configuration Editor to edit the details about your product. On the Overview tab, click Synchronize to make sure your configuration is up to date. Now, you can click Launch an Eclipse Application (see Figure 10) to test your product. If you need to debug it, click Launch an Eclipse application in Debug mode.

Figure 10. Launching the Eclipse application
Launching the Eclipse application

Run your product

Before proceeding, make sure you can successfully run your product. Making sure it runs fine now eliminates frustration and troubleshooting later. The code download, when started, looks like Figure 11.

Figure 11. The simple sample application
The simple sample application

Packaging the application

At this point, you should have a basic understanding of JWS and the JNLP file structure. You should have a Web server on which you can publish your product's files and the JNLP file, and you should have a working product you can launch from your Eclipse IDE. With all of that done, you're ready to build a wrapper feature that will be used to publish your product.

Create the wrapper feature

The wrapper feature is simply a feature project that contains two files, each of which contains references both to your product plug-in and any necessary plug-ins and features required to run your product plug-in. To add the new wrapper feature project, choose File > New > Project. Then in the Select a wizard window, expand Plug-in Development and select Feature Project, as shown in Figure 12.

Figure 12. Creating a new feature project
Creating a new Feature Project

In the Feature Properties window, type the name of the project, the feature ID, the name, the version, and provider information, as shown in Figure 13, then click Next.

Figure 13. Editing the feature properties
Editing the feature properties

In the Referenced Plug-ins and Fragments window, shown in Figure 14, select Initialize from a launch configuration, then choose the name of your product's configuration file (for example, SimpleApp.product) from the list. Click Finish when you're done.

Figure 14. Selecting the product configuration
Selecting the product configuration

To deploy the plug-ins and features through JWS, you must sign the JARs. Signing the JARs requires a keystore, which you can generate using the Java keytool that comes with your Java software development kit (JDK). For more information about creating a keystore, see Resources.

The new feature project will have two files: build.properties and feature.xml. The feature.xml file has a graphical editor like the graphical product configuration and plug-in editors. Open the graphical editor for the feature.xml file.

On the Plug-ins tab, make sure that your product plug-in is listed. Also, verify that the org.eclipse.equinox.launcher plug-in is listed. On the Features tab, include any extra features your plug-in or feature requires. If you're in a hurry to see your product with JWS, you can select all of them; it won't hurt anything other than the directory size of your application. However, for a real-world product, you should track down the dependencies to make your download size as lean as possible.

Export the wrapper feature

When you've selected the plug-ins and features, you can export the feature wrapper project to a directory. To export the project, choose File > Export. In the Select window, expand Plug-in Development, then click Deployable Features, as shown in Figure 15. Click Next.

Figure 15. Creating a deployable feature
Creating a deployable feature

Now:

  1. In the Deployable features window, shown in Figure 16, select your feature.
    Figure 16. Selecting the feature to deploy
    Sample feature to deploy
  2. On the Destination tab, click Directory and type the name of the directory to which you will publish the files. This directory should be under a Web folder so that it's accessible with the URL you provide on the Java Web Start tab.
  3. On the Options tab, select Package as individual JAR archives.
  4. On the JAR Signing tab, select Sign the JAR archives using a keystore. Then browse to your keystore location and type the alias and password.

    Note: If you don't have a keystore, see Resources for links on how to create one.

  5. On the Java Web Start tab, select Create JNLP manifests for JAR archives.
  6. Update the Site URL to the base URL of the JWS directory. Accessing this URL from a browser should access the directory you entered on the Destination tab. See Figure 1for an example.
    Figure 17. Setting the JWS properties
    Setting the JWS properties

Click Finish when you're done updating the information about your feature's deployment. Eclipse exports the information in the directory provided. Depending on the number of plug-ins and features selected and your hardware resources, it can take some time to export the feature. When Eclipse is finished, you'll have two new directories inside the provided directory: features and plugins. Your feature's JNLP file will be in the features directory. For an example listing of the contents of the features directory, see Listing 3.

Listing 3. Contents of the features directory
$ ls
com.nathanagood.examples.simpleApp.feature_1.0.0.jar
com.nathanagood.examples.simpleApp.feature_1.0.0.jnlp
org.eclipse.equinox.p2.user.ui.source_1.0.1.r34x_v20080721-7d-7OEMsLAz-vTBJ.jar
org.eclipse.equinox.p2.user.ui.source_1.0.1.r34x_v20080721-7d-7OEMsLAz-vTBJ.jnlp
org.eclipse.equinox.p2.user.ui_1.0.1.r34x_v20080721-7d-7OEMsLAz-vTBJ-ZHQaF155CE.jar
org.eclipse.equinox.p2.user.ui_1.0.1.r34x_v20080721-7d-7OEMsLAz-vTBJ-ZHQaF155CE.jnlp
org.eclipse.help.source_1.0.1.R34x_v20080827-7r7xEIxEI6Zu5nEqN7M3UBpglaat.jar
org.eclipse.help.source_1.0.1.R34x_v20080827-7r7xEIxEI6Zu5nEqN7M3UBpglaat.jnlp
org.eclipse.help_1.0.1.R34x_v20080827-7r7xEIxEI6Zu5nEqN7M3UBpglaat.jar
org.eclipse.help_1.0.1.R34x_v20080827-7r7xEIxEI6Zu5nEqN7M3UBpglaat.jnlp
org.eclipse.platform.source_3.4.1.r341_v20080731-9I96EiDElYevwz.jar
org.eclipse.platform.source_3.4.1.r341_v20080731-9I96EiDElYevwz.jnlp
org.eclipse.platform_3.4.1.r341_v20080731-9I96EiDElYevwz-p1bP5z-NlAaP7vtX6Utotqsu.jar
org.eclipse.platform_3.4.1.r341_v20080731-9I96EiDElYevwz-p1bP5z-NlAaP7vtX6Utotqsu.jnlp
org.eclipse.rcp.source_3.4.100.r341_v20080814-989JESIEdAciFYfkZZsBfSwQ2341.jar
org.eclipse.rcp.source_3.4.100.r341_v20080814-989JESIEdAciFYfkZZsBfSwQ2341.jnlp
org.eclipse.rcp_3.4.100.r341_v20080814-989JESIEdAciFYfkZZsBfSwQ2341.jar
org.eclipse.rcp_3.4.100.r341_v20080814-989JESIEdAciFYfkZZsBfSwQ2341.jnlp

With the wrapper feature successfully exported into a directory accessible from a Web server, it's time to build the application's main JNLP file.


The JNLP file

In this section, you build and publish your JNLP file, then you test your deployment and perform any troubleshooting that may be necessary.

Build the JNLP file

At this point, you should have successfully exported the feature to a directory and verified that the features and plugins directories exist in a location accessible from a Web server. Now it's time to write the JNLP file for your application. An example JNLP file is provided in its entirety.

Listing 4. Example JNLP file for the simple application
<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+"  
    codebase="http://localhost/~user/jws2" href="simpleapp.jnlp">
  <information>
    <title>SimpleApp Test</title>
    <vendor>Nathan Good</vendor>
    <homepage href="http://www.nathanagood.com" />
    <description>This is my simple JWS Eclipse 
     application test.</description>
  </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">
  </application-desc>
  <resources>
    <jar href="plugins/org.eclipse.equinox.launcher_1.0.101.R34x_v20080819.jar"/>
    <extension name="Simple App Feature" 
     href="features/com.nathanagood.examples.simpleApp.feature_1.0.0.jnlp" />
    <property name="eclipse.product" 
     value="com.nathanagood.examples.rcp.simpleApp.plugin.product" />
  </resources>
  <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>

In this JNLP file, the value of the codebase attribute is set to the base URL of the location to which you have published the wrapper feature. It should match the URL you used on the Java Web Start tab in the Deployable features window in Figure 17. The href attribute is the name of the your JNLP file.

Using localhost

You may have noticed that in my examples, I'm using localhost as my URL. This is because I tested this application using a local Web server and didn't actually deploy my file to anyone else. Using localhost won't work if you plan on deploying this application (although it's fine for testing). Make sure to use an externally resolvable host name (for example, myhost.example.com) or an IP address.

The <information> element includes the title, description, and other information about the application being distributed. The <security> and <application-desc> elements need to be as shown in Listing 4.

Modify the <resources> element to include the correct version of the Equinox launcher plug-in for the <jar> element. You may have to look in the features directory to find the correct full name of the launcher's JAR. It's likely that the name in Listing 4 will soon be out of date as new versions of the file become available.

Update the <extension> element's href attribute to include the URL (relative to the URL in the codebase attribute) of your wrapper feature's JNLP file. Your wrapper feature's JNLP file will include all the other required features and plug-ins.

Finally, update the <property> element to include the ID of the your product. This ID will be the ID from the plug-in's product configuration file (that is, SimpleApp.product).

Publish the JNLP file

By now, you've built the JNLP file. You have features and plugins directories from exporting the deployable feature. The feature includes your plug-in, as well as all dependencies. You're ready to publish the JNLP file.

The JNLP file goes in the same directory as the features and plugins directories. It should be the same directory you used when you exported the deployable feature. Listing 5 shows an example directory listing.

Listing 5. Directory listing with JNLP file
drwxr-xr-x   20 user  user   680 Dec 19 09:46 features
drwxr-xr-x  280 user  user  9520 Dec 19 09:46 plugins
-rw-r--r--    1 user  user  1222 Dec 19 10:05 simpleapp.jnlp

To make it easy to test the file, create a simple HTML page and call it index.html. It should include the code shown in Listing 6, where simpleapp.jnlp is updated to be the name of your JNLP file.

Listing 6. Example HTML file
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>My Application</title>
</head>
<body>
<a href="simpleapp.jnlp">My Application</a>
</body>
</html>

Save the HTML file in the folder that will be accessible from the codebase URL in the application's main JNLP file. After saving the HTML file in the directory, the directory listing should look like Listing 7.

Listing 7. Directory listing with all files
drwxr-xr-x   20 user  user   680 Dec 19 09:46 features
-rw-r--r--    1 user  user   288 Dec 19 08:37 index.html
drwxr-xr-x  280 user  user  9520 Dec 19 09:46 plugins
-rw-r--r--    1 user  user  1222 Dec 19 10:05 simpleapp.jnlp

Testing the deployment

At this point, you:

  • Understand the basic structure of the JNLP file.
  • Configured your Web server with the appropriate MIME type.
  • Have a basic Eclipse product build in a plug-in project.
  • Have a wrapper feature project that includes the plug-in.
  • Exported the wrapper feature to a directory.
  • Created and saved a JNLP file for your application.

Now it's time to test the deployment. Open a Web browser and navigate to the URL you provided for the codebase URL (for example, http://localhost/~user/jws/). The index.html file you created in the "Publish the JNLP file" section should appear. Click the link. Provided everything is configured properly, a splash screen for JWS should appear (see Figure 18). Then, the progress for downloading the application appears. Depending on the final size of your features and plug-ins, as well as the network connection, this process could take some time.

Figure 18. The JWS splash screen
The JWS splash screen

When all the dependencies are downloaded, the application opens. My simple view looks like Figure 19.

Figure 19. The simple application started from JWS
The simple application started from JWS

Troubleshooting

I encountered a couple of problems while I was building my first example of an Eclipse product being deployed through JWS:

  • The JNLP file is displayed in the browser as text. If this occurs, the most likely cause is a missing MIME type association for the JNLP type in your Web server's configuration. Make sure the correct MIME type is associated (see the "Configure your Web server" section).
  • Unable to launch the application. If you get this error from JWS, click Details to get more information about the error. If the error is a java.io.FileNotFoundException, chances are there's an incorrect URL. I received this error when I renamed my initial JNLP file, but forgot to update the value in the href attribute of the <jnlp> element.
  • Unable to load a resource. Similar to the previous error, this message is visible after you click Details. I got this error when I attempted to test the application on a different computer. In my URLs for this example, I've used localhost as the name of the host. To resolve this issue, change the URL to be the IP address or host name of the server on which you are publishing the JNLP file.
  • JWS appears to start, but nothing is visible and JWS closes. The most likely cause of this problem is an incorrect product ID in the eclipse.product property in the <resources> element. Double-check the value of the product ID and make sure it matches the ID in the product configuration file (SimpleApp.product).

Summary

This tutorial demonstrates how to build a simple product — an application built on the Eclipse Platform — and deploy it to your users using JWS. By following the steps here and adding your own extensions, you can build a sophisticated application that can be deployed to many platforms from a central location. Updates are as easy as deploying the updates to the directory from which the JWS resources are deployed.

To successfully build a product, you need to understand a bit about how the JNLP file is structured. You need to build a plug-in with a the implementations of at least a couple of classes. You need to provide extension points in your plug-in. And finally, you need to add a product configuration to your plug-in project.

When your plug-in project is complete, you need to build a wrapper feature that includes your plug-in and all the other features and plug-ins required to run your plug-in. When you're done with your wrapper feature, you can use an Eclipse wizard to deploy the necessary files to a directory structure.

A simple JNLP file contains references to the wrapper feature's JNLP file you created. It also contains any additional parameters you need to have Eclipse run your product, such as the startup product ID.


Download

DescriptionNameSize
Source codeos-eclipse-jws-code.zip25KB

Resources

Learn

Get products and technologies

Discuss

  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=366792
ArticleTitle=Deploying an Eclipse-based application with Java Web Start
publish-date=02032009