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

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.

Java Web Start (JWS^[55]) is a new technology for providing application downloads over the Web. It is distinct from applets (see Chapter 17), 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 minutes. Figure 23-6 shows the startup screen that appears after clicking a Launch link for my JabaDex application.

Figure 23-6. Starting JabaDex as a JWS application

After the application is downloaded successfully, it will start running. This is shown in slightly compressed form in Figure 23-7.

Figure 23-7. JabaDex up and running

Figure 23-8. 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-8 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.

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 these are platform-dependent.

Optionally, you can provide icons to represent your application in JWS format. The application icons should be in GIF or JPEG and should be 64 x 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 and 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.

<?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-class="JDMain"/> 
   </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.

// 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 “non-sandbox” (i.e., full application) permissions, you must sign the application’s JAR files. The procedure to sign a JAR file digitally is described in Section 23.13. If you request full permissions and don’t sign all your application JAR files, the sad note shown in Figure 23-9 will display.

Figure 23-9. Unsigned application failure

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

Figure 23-10. 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. As such, there is a binary program that you can download 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 will 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">lauchh 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!

The JWS home page at http://java.sun.com/products/javawebstart/.