Java Web Start

http://today.java.net/pub/a/today/2005/08/11/webstart.html

Java Sketchbook: Getting Started with Java Web Startby Joshua Marinacci
08/11/2005

Many web developers long for a way to build applications with richer interfaces. They would love to build desktop applications with all of the power that client-side Java provides, but don't want to give up the ease of deployment that comes with web apps. How do you launch a program without downloading installers? How to you make it secure and safe to use? How do you update the program without asking your users to go download a new version? These are features that web app developers take for granted and don't want to give up in exchange for a richer interface. It may seem hopeless, but there is an answer: Java Web Start.

Java Web Start (JWS) is a technology that lets you deploy a desktop Java application directly from a web page. It provides security, safety, and automatic updates when you roll out new versions. It will even give your program an icon on the desktop. In short, Java Web Start gives you the power of a desktop app with the ease of deployment users expect from a web app.

This two-part series will tell you everything you need to know to start using Java Web Start. By the end of part one, you will have a simple running application that can be launched and updated from the web. Part two will cover security, optimized downloads, and how to polish your program to give it a professional shine.

What is Java Web Start?

Java Web Start is an implementation of the Java Network Launching Protocol (JNLP) specification. It provides a way to launch a desktop Java program from a web link and install it to your users' desktops. Once installed, JWS will check for updates every time the users run your program, ensuring they always have the most recent version installed.

In addition to its launch capabilities, Java Web Start also provides a protected sandbox for running untrusted applications. This is similar to the applet sandbox in a web browser. It allows users to run programs from potentially unsafe locations without worrying that the program could delete files, steal information, or replicate itself to other computers. In the age of viruses, worms, and spyware, this is a big concern. With Java Web Start, you can know that both you and your users will be protected.

Originally bundled as a separate download, Java Web Start is now included in the JRE. If you have J2SE 5.0 on your computer (or Java 1.4, on Mac OS X) then you already have Java Web Start installed and you can get started right away. While it does introduce a few new APIs (mainly for dealing with the sandbox), you can get started without writing any new code. You just need a JNLP descriptor file.

How It Works

Java Web Start works by using a special file called the JNLP descriptor, which is a small XML document that describes your application and its needs. This file lists the .jars that make up your program, the starting class with the main method, security settings, and most visibly, a splash screen and an icon. Together, these settings describe how the program is launched and how it looks to your users.

Once you've written a JNLP file, you can put it on your web server and make a link to it. When someone clicks on the link, their web browser will download the JNLP file and start the JWS application launcher. JWS will then download all of the .jars that make up your program (along with any other resources like images and icons), install an icon on the desktop (if requested), and then start your program. The next time the user runs the program from the desktop icon, JWS will check for any updated resources before starting the program again.

If this all sounds pretty complicated, don't worry. We'll start with a simple example so you can see how it all works. Imagine a virtual pet game where the player raises pirates, leading them on treasure hunts and boarding raids. The program could be called "My Pirate!". This is what its JNLP might look like.

<?xml version="1.0" encoding="UTF-8"?>
<jnlp codebase="http://mypirate.com/downloads/" 
        href="mypirate.jnlp">
    <information>
        <title>My Pirate!</title>
    </information>
    <resources>
        <jar href="mypirate.jar"/>
    </resources>
    <application-desc main-class="mypirate.Startup"/>
</jnlp>

Let's go through this one line at a time. The first line contains the XML prolog. This is what tells a parser that what follows will be an XML file. This should be the same for any JNLP file. Next is the jnlp element, with two attributes, one for the href of the jnlp itself and one for the codebase, which says where the .jars and other resources will be downloaded from.

Inside the jnlp element are three sections: information, resources, and application-desc. information has purely descriptive content. The title specifies, as you would expect, the name of the program. This title will be used in the JWS control panel, for the name of the desktop icon, and in the platform-specific application manager, like the "Add and Remove Programs" control panel in Windows. The information section can contain other things like icons, a splash screen, or longer descriptions, but the title is enough to get started.

The resources section tells Java Web Start which .jars and other resources are required to run your program. These are all relative to the codebase attribute in the jnlp element. For example, the mypirate.jar file must be on my web server at the URL codebase plus href; in other words, http://mypirate.com/downloads/mypirate.jar. The resources section can also contain native libraries, extensions, properties, and other elements, but jar is the most important.

The last section, application-desc, specifies some attribute about the application. In this case I have told JWS that the main class of my program is mypirate.Startup. All JNLPs need this section so that JWS will know how to start the program. Without, it JWS would throw an exception the first time I try to run the program.

Deploying "My Pirate!"

In theory, you can just upload your JNLPs, .jars, and other files to your website and call it a day. In practice, however, it's not that simple. First, you must make sure you upload your files to the same place specified in the codebase attribute of your JNLP. For "My Pirate!" I would have to upload the files to http://mypirate.com/downloads/. Even if I load the JNLP file from somewhere else (generated by a servlet on another server, perhaps), Java Web Start will still load the .jars relative to the codebase specified in the JNLP file.

The second common stumbling block is the MIME type. Most web servers don't yet understand how to serve jnlp files. If I just dropped the files into a standard Apache server, the web browser would probably think the file is plain text and show it in a browser window rather than calling Java Web Start. I have to tell my web server to serve any file with a .jnlp extension as application/x-java-jnlp-file. Each web server has its own configuration, but for Apache, you can add a line to your httpd.conf next to the other AddType lines, like this:

AddType application/x-java-jnlp-file .jnlp

That should be it. If I point my web browser at http://mypirate.com/downloads/mypirate.jnlp, I will see the JNLP downloaded and my program will start. Depending on my particular Java Web Start implementation, it may ask me if I want to keep this JNLP as a permanent application. If I say yes, it will create a program icon on my desktop or hard drive.

Add a Description and Icon, and Splash Screen Building

A plain JNLP file for my program works, but it's missing a few things. The "Add/Remove Programs" control panel in Windows will list it simply as "My Pirate!" with no further information about who made the program or what it does. It has no splash screen when it starts, and it uses the generic coffee cup icon. In short, it doesn't feel professional. Fortunately, the Java Web Start developers thought of this and provided easy ways to add some polish.

Add an Icon

To add an icon you must add an <icon> element to the information section of your JNLP. The icon element needs an href attribute containing the URL of the icon to use. This icon can be a GIF or a JPEG, or another platform-dependent format (BMP, ICO, PICT). Be sure to test the platforms you are targeting to determine which formats will work. Mustang will improve PNG support to give icons full transparency.

<information>
    <title>My Pirate!</title>
    <icon href="icon.png"/>
</information>

The icon will be loaded relative to the codebase, so I upload it to the same location on my web server. Now my application on disk will look like Figure 2 instead of Figure 1.

Figure 1. Standard JWS icon

Figure 2. Custom pirate icon

Add a Splash Screen

Java Web Start also supports splash screens. A splash screen is an image that will appear while the program is launching. It provides feedback to let the user know the program hasn't crashed during a potentially long initialization routine. A splash screen also serves as a visual identifier for your program and your company, creating a consistent feel throughout. You can create a splash screen by providing a second icon with its kind set to splash.

<information>
    <title>My Pirate!</title>
    <icon href="icon.png"/>       
    <icon href="splash.png" kind="splash"/> 

</information>

Which will look like Figure 3:

Figure 3. "My Pirate!" splash screen

If you don't provide a splash screen, Java Web Start will use another icon element in your application. If there is no icon element at all, then it will generate a splash screen using the description and title of your program. This typically is ugly, however, so I highly recommend you provide your own splash screen.

Note: splash screens do not currently work on Mac OS X.

Updating an Application

Updating your application is very easy. Just recompile your code and upload your new .jars to the web server. The next time one of your users starts the program (either via a link on a website or from an icon on the desktop), JWS will check for the new .jars. If the web server's .jar file timestamps are newer than the .jars on disk, then JWS will download the new .jars, add them to the cache, and then start your program. Java Web Start also provides a way to send out incremental updates, where only the changes to a .jar are downloaded instead of the entire .jar, but that is beyond the scope of this article and is only useful for large (multi-megabyte) applications. For more information on JarDiffs, take a look at the " Mapping Requests to Resources" section of the Java Web Start Download Servlet Guide.

Removing an Application

Java Web Start makes installing an application super easy, so it's nice that uninstalling is easy, as well. There is a program called the Application Manager that lets you manage the Web Start programs installed on your computer. This is part of the Java Control Panel on Windows and Linux. On Mac OS X, it is an application in the /Applications/Utilities/Java directory. You can also run the javaws program from the command line with no arguments to get to the cache viewer. The manager program shows information about each JWS application and allows you to start, update, or remove them. It also lets you create a desktop icon for a JWS app if you want it to feel more native.

Conclusion

Java Web Start is a great technology for deploying desktop Java applications without the usual headaches of desktop apps. In the first part of this article you have learned how to create a simple application, launch it from a web page, update it, and how to improve the look of the application with icons and a splash screen. Please join me in the second part, where we will look at the Java Web Start security model, use Pack 200 to decrease download time, and add some extra polish with documentation and file associations.

Resources

• Sample code for this article
• Sun's Java Web Start home page
• Java Web Start Developer's Guide and specifications