Recipe 23.13 Java Web Start

Problem

You have an application (not an applet) and need to distribute it electronically.

Solution

Sun's Java Web Start combines browser-based ease of use with applet-like " sandbox" security (which can be overridden on a per-application basis) and "instant update" downloading but also lets you run a full-blown application on the user's desktop.

Discussion

Java Web Start (JWS^[4]) provides application downloads over the Web. It is distinct from applets (see Chapter 18), which require special methods and run in a browser framework. JWS lets you run ordinary GUI-based applications. It is aimed at people who want the convenience of browser access combined with full application capabilities. The user experience is as follows. You see a link to an application you'd like to launch. If you've previously installed JWS (explained toward the end of this recipe), you can just click on its Launch link and be running the application in a few seconds to a few minutes, depending on your download speed. Figure 23-9 shows the startup screen that appears after clicking a Launch link for my JabaDex application.

^[4] JWS used to stand for Java Web Server, which was discontinued, so the acronym has been recycled. Things recycle quickly on the Web.

Figure 23-9. Starting JabaDex as a JWS application

After the application is downloaded successfully, it starts running. This is shown in slightly compressed form in Figure 23-10.

Figure 23-10. JabaDex up and running

Figure 23-11. JWS application control screen

For your convenience, JWS caches the JAR files and other pieces needed to run the application. You can later restart the application (even when not connected to the Web) using the JWS application launcher. In Figure 23-11, I have JabaDex in my JWS launcher. JWS also allows you to create desktop shortcuts and start menu entries on systems that support these.

The basic steps in setting up your application for JWS are shown in the following sidebar.

Ian's Basic Steps: Java Web Start

To set up Java Web Start:

Package your application in one or more JAR files.
Optionally, provide icons to represent your application in JWS format.
Describe your application in a JNLP (Java Net Launch Protocol) description file.
If necessary, set your web server's MIME types list to return JNLP files as type application/x-java-jnlp-file.
If necessary, modify your application to use ClassLoader's getResource( ) method instead of opening files.
If necessary, sign the application's JAR files.
Make links to your application's JNLP file and a download link for JWS itself.
Enjoy using your application locally with easy web downloading!

Let's go over these instructions in detail. The first step is to package your application in one or more JAR files. The jar program was described earlier in this chapter. The main JAR file should include the application classes and any resources such as properties files, images, and the like.

You should also include on the web site any JAR files containing extra APIs, such as JavaMail, com.darwinsys.util, or any other APIs. You can even include native code files, but they are platform-dependent.

Optionally, you can provide icons to represent your application in JWS format. The application icons should be in GIF or JPEG format and should be 64 64 bits.

The next step is to describe your application in a JNLP (Java Net Launch Protocol) description file. The JNLP file is an XML file. The official specification is at http://java.sun.com/products/javawebstart/download-spec.html; a less formal description is in the Developer's Guide at the web site http://java.sun.com/products/javawebstart/docs/developersguide.html. The file I used for enabling JabaDex to run with JWS is a subset of the allowable XML elements but should be moderately self-explanatory. See Example 23-5.

Example 23-5. JabaDex.jnlp

<?xml version="1.0" encoding="utf-8"?>  <!-- JNLP File for JabaDex Application -->  <jnlp spec="1.0+"       codebase="http://www.darwinsys.com/"      href="/jabadex/">       <information>         <title>JabaDex Personal Information Manager Application</title>         <vendor>Darwin Open Systems</vendor>         <homepage href="/"/>         <description>JabaDex Personal Information Manager Application</description>         <description kind="short">A simple personal information manager.</description>         <icon href="images/jabadex.jpg"/>         <offline-allowed/>       </information>       <security>           <all-permissions/>       </security>       <resources>         <j2se version="1.3"/>         <j2se version="1.2"/>         <jar href="jabadex.jar"/>         <jar href="com-darwinsys-util.jar"/>       </resources>       <application-desc main-/>     </jnlp>

If necessary, set your web server's MIME types list to return JNLP files as of type application/x-java-jnlp-file. How you do this depends entirely on what web server you are running; it should be just a matter of adding an entry for the filename extension .jnlp to map to this type.

Also if necessary, modify your application to get its ClassLoader and use one of its getResource( ) methods, instead of opening files. Any images or other resources that you need should be opened this way. For example, to explicitly load a properties file, you could use getClassLoader( ) and getResource( ), as shown in Example 23-6.

Example 23-6. GetResourceDemo (partial listing)

// Find the ClassLoader that loaded us. // Regard it as the One True ClassLoader for this app. ClassLoader loader = this.getClass( ).getClassLoader( ); // Use the loader's getResource( ) method to open the file. InputStream is = loader.getResourceAsStream("widgets.properties"); if (is == null) {     System.err.println("Can't load properties file");     return; } // Create a Properties object Properties p = new Properties( ); // Load the properties file into the Properties object try {     p.load(is); } catch (IOException ex) {     System.err.println("Load failed: " + ex);     return; }

Notice that getResource( ) returns a java.net.URL object here while getResourceAsStream( ) returns an InputStream.

If you want the application to have "nonsandbox" (i.e., full application) permissions, you must sign the application's JAR files. The procedure to sign a JAR file digitally is described in Recipe 23.14. If you request full permissions and don't sign all your application JAR files, the sad note shown in Figure 23-12 displays.

Figure 23-12. Unsigned application failure

If you self-sign (i.e., use a test certificate), the user sees a warning dialog like the one in Figure 23-13.

Figure 23-13. Unverifiable certificate warning

Finally, make links to your application's JNLP file in the web page and, optionally, a download link for JWS itself. JWS is a compiled program that must be loaded before the user can download any JWS-enabled applications; it runs as a "helper application" for the browsers. You can download it as a binary program from the JWS home page. In theory, you could write your own implementation of this helper from the JNLP Specification, if you needed to.

Actually, if the user has JWS installed, you don't need the download link; if they don't, the Launch link does not function correctly. The Developer's Guide shows how you can use client-side HTML scripting (JavaScript or VBScript) to make only one of these links appear. The Launch link must refer to the JNLP file:

If you have JWS installed, you can <a href="jabadex.jnlp">launch JabaDex<</a> If not, you should <a href="http://java.sun.com/products/javawebstart/"> read about Java Web Start</a>.

You should now be ready to use your application in a downloadable fashion!