RCP and Java Web Start

Intro

The Eclipse Rich Client Platform (RCP) came under fire at a recent internal meeting. Most notably “RCP is a bear to work with”, and “RCP and Java Web Start don’t play nicely together”.

The first point is fairly subjective, but the second is more tangible. Now, the speaker and his team are smart people, and mitigating circumstances undoubtedly explain his statements, but to my mind, RCP and Web Start play together very nicely indeed. In this article, I will present a step-by-step tutorial on how to create a simple RCP-based Hello, World application and how to extend it for deployment by Java Web Start.

My defence of RCP will come as no surprise to many of you: I’ve been a fan of Eclipse since 1.0 days, tackled my first plug-in 4 years ago (no, it didn’t work), and was involved 3 years ago in the adoption of SWT on one of our biggest projects. I also believe that the Plug-in Development Environment (PDE) represents the most effective way of breaking up one of our largest, most monolithic projects, opening the technological door to productization, and providing support for component re-use.

Background

When Eclipse was first introduced, it was designed to be a shell of an IDE, a platform that knew about nothing, but one that could be extended through the development of plug-ins. The Java Development Tools (JDT) project was essentially a proof-of-concept. This combination of Platform and JDT is what most of us know as Eclipse.

A number of enterprising people realized that this platform could be more generally useful, and made local changes to the framework to support general rich-client development. The Eclipse developers responded to this by teasing apart the IDE-specific from the rich-client-generic, and introduced it as the Eclipse Rich Client Platform.

Getting Started

This tutorial was written using Eclipse 3.1.2, and I recommend that you use that version. It will probably work 3.2, although some of the wizards have changed slightly.

The PDE supports 2 kinds of projects, plug-in projects and feature projects. Plug-in projects typically have Java classes that define behaviour, while feature projects are typically groupings of plug-ins for the purpose of deployment. We will need to create 3 projects:

Project Name
A plug-in project defining our Hello RCP application ca.intelliware.hellorcp.app
A feature project that references the application ca.intelliware.hellorcp.feature
A wrapping feature project to allow for deployment to Java Web ca.intelliware.hellorcp.feature.jnlp

Why so many projects? In future versions of the PDE it may be possible to wrap plug-in projects directly, without the need for an intervening feature project. In addition, the wrapping project itself may become redundant. But for now, we seem to need them all.

Due to the proliferation of projects involved, I’ve used conventions similar to package naming conventions for my project names, and recommend that you do the same.

So, without further ado, let’s get started…

Create the Hello RCP application Plug-in project

Start Eclipse. You may want to switch to a new workspace:

  • Press Ctrl-N to bring up the Newwizard
  • Select Plug-in Project
  • Call it ca.intelliware.hellorcp.app
  • Press the Next button to go to the Plug-in Contentpage
  • Deselect the Generate the Java class that controls the plug-in’s life cyclecheckbox
  • Select the Would you like to create a rich client application?checkbox
  • Next to Templates
  • Select the Hello RCPtemplate
  • Press the Finishbutton
  • Dismiss the prompt to use the Plug-in Development Perspective: the answer is immaterial to this tutorial.
  • Click the Launch an Eclipse application link: you should see something like this:

Obviously, this app does nothing useful yet, but it is a true RCP application.

Create the Hello RCP application Feature project

After you’re done basking in the glory of your first RCP application, shut it down and go back to Eclipse:

  • Press Ctrl-N to bring up the New wizard
  • From the Plug-in Development node, select Feature Project
  • Call it ca.intelliware.hellorcp.feature
  • Next to Feature Properties
  • In Feature Provider field, enter “Intelliware” {note|this is required to populate the <vendor> element of .jnlp files created for each plugin by the PDE export}
  • Next to Referenced Plug-ins and Fragments
  • Ensure that ca.intelliware.hellorcp.appis selected
  • Finish

You need to indicate that your new feature relies on RCP. You do this by editing feature.xml. The Feature Manifest Editor should be open, displaying the contents of feature.xml:

  • Select the Included Features tab
  • Press the Add… button of the Included Feature stable
  • select org.eclipse.rcp
  • Press Ctrl-S to save your changes

Create the Java Web Start feature project

Here things gets a little complicated. The extra complexity comes from a number of different directions:

  1. We introduce the concept of a PDE product
  2. Java Web Start requires signed jars, so we’ll need to use the JDK keytoolcommand to create a keystore
  3. The PDE doesn’t really help too much in the initial setup of Java Web Start features, so we’ll have to do a little first-time work

Create a Hello RCP product

Java Web Start will launch your application by referencing a Product, a PDE entity that allows you to brand your application with a custom splash screen, application window icon, etc. To create a product and configure it:

  • Press Ctrl-N to bring up the New wizard
  • Select Product Configuration
  • Next
  • On the Product Configuration page, select ca.intelliware.hellorcp.app
  • For File name, enter “hellorcp.product”
  • In the Initialize the file content section, select Use a launch configuration
  • Select Eclipse Application: NOTE: you created this launch configuration when you tested your RCP app. If you missed that step, go back and run it now.
  • Finish

You must now configure the product. In the Product Configuration Editor:

  • Press the New… button by the Product ID combo to take you to the New product Definitionwizard
  • Press Browse to select the ca.intelliware.hellorcp.featureplug-in
  • For Product ID, enter “hellorcp”
  • Finish

Back in the Product Configuration Editor:

  • For The product configuration is based on, select Features
  • Select the Configurationtab
  • Press the Add… button of the Featurestable
  • Select ca.intelliware.hellorcp.feature
  • Select the Overviewtab
  • Press Ctrl-Sto save your changes
  • Click the Launch the product link: again, you should see something like this:

Create a keystore

JNLP requires that jars be signed. The PDE export wizard can handle the signing for you, as long as you indicate the location of your keystore. But, you must set up the keystore yourself using the JDK keytoolutility. From a command prompt:

  • keytool -genkey -alias alias -keypass password
  • Answer questions as required
  • Say yes, the data is correct

Create the Java Web Start feature project

Back in Eclipse:

  • Press Ctrl-N to bring up the Newwizard
  • From the Plug-in Development node, select Feature Project
  • Call it ca.intelliware.hellorcp.feature.jnlp
  • Finish

From the Feature Manifest Editor:

  • Select the Plug-instab
  • Ensure that no plug-ins are selected
  • Select the Included Featurestab
  • Ensure that ca.intelliware.hellorcp.featureis selected
  • Select the build.propertiestab
  • replace the entire file with this:
root=rootfiles

Having referred to the rootfiles directory, we now have to create and populate it. We’ll need a signed copy of the Eclipse startup.jar. From the Package Explorer:

  • create a folder called rootfilesat the root of the new project
  • copy startup.jar from the root of your Eclipse installation into the rootfilesdirectory
  • sign it using the JDK jarsigner utility and your newly created keystore

We’ll also need a suitable .jnlp file. Cut and paste the following .jnlp file into rootfiles, calling it hellorcp.jnlp:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" codebase="file:/c:/site" href="hellorcp.jnlp">
	<information>
		<title>HelloRCP</title>
		<vendor>Intelliware</vendor>
		<icon kind="splash" href="splash.gif"/>
		<offline-allowed/>
	</information>
	<security>
		<all-permissions/>
	</security>
	<application-desc main-class="org.eclipse.core.launcher.WebStartMain">
		<argument>-nosplash </argument>
	</application-desc>
	<resources>
		<j2se version="1.4+" />
		<jar href="startup.jar"/>
		<extension name="the feature" href="features/ca.intelliware.hellorcp.feature_1.0.0.jnlp"/>
		<property name="eclipse.product" value="ca.intelliware.hellorcp.app.hellorcp"/>
	</resources>

	<resources os="Windows">
		<property name="osgi.instance.area" value="@user.home/Application Data/hellorcp"/>
		<property name="osgi.configuration.area" value="@user.home/Application Data/hellorcp"/>
	</resources>
</jnlp>

If you used different project, product or .jnlp names, you’ll need to edit the .jnlp file. I’ll leave finding the exact changes as an excercise to the reader, but here are a few clues to their whereabouts:

  • the <extension> tag
  • the 3 property definitions
  • the .jnlp file name

You should note a couple of curiosities in this file:

  1. the file-based codebase value: in a real deployment we would obviously use the JNLP servlet or similar technique to dynamically set this value. Loading from a fixed location in the local file system will work for now.
  2. the <extension> element: each plug-in is represented in the .jnlp file by an <extension> element referencing a PDE-generated, nested, .jnlp file.

Export the JNLP Wrapper project

From the Overview tab, select Export Wizard:

  • For the Destination directory, enter “c:

    site”
  • Select the Package features and plug-ins as individual jarscheckbox
  • Next
  • Select the Sign jarscheckbox
    • Enter your keystore location, alias and password
  • Select the Create manifestscheckbox
    • For URL, enter “file:/c:/site”
    • For JDK version, enter “1.4+”

Try your app

Open a command prompt and type:

  • javaws c:

    site

    hellorcp.jnlp

Or, from a Web Start enabled browser of your choice, browse to:

  • file:/c:/site/hellorcp.jnlp

Java Web Start will “download” the signed jars, verify the signatures, and prompt you for authorization. Assuming you trust yourself, once again, you should see something like this:

In Conclusion

So there you have it. For the uninitiated, there is certainly something of a learning curve regarding the PDE concepts of plug-ins, features, products, wrapper projects, etc. In addition, there are some nasty wrinkles in the later steps involving the Java Web Start feature.

Did RCP and Web Start play nicely together? I’ll let you be the judge.

Further Reading

If you are interested in reading more about RCP, I most strongly recommend eclipse Rich Client Platform: Designing Coding and Packaging Java Applications, by Jeff McAffer and Jean-Michel Lemieux.

It's only fair to share...
Share on FacebookGoogle+Tweet about this on TwitterShare on LinkedIn

Leave a Reply