Skip to main content

Java Sketchbook: Getting Started with Java Web Start

August 11, 2005


What is Java Web Start?
How It Works
Deploying "My Pirate!"
Add a Description and Icon, and
Splash Screen Building
Add an Icon
Add a Splash Screen
Updating an Application
Removing an Application

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
(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

How It Works

Java Web Start works by using a special file called the JNLP
, 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.

[prettify]<?xml version="1.0" encoding="UTF-8"?>
<jnlp codebase="" 
        <title>My Pirate!</title>
        <jar href="mypirate.jar"/>
    <application-desc main-class="mypirate.Startup"/>

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, 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 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:

[prettify]AddType application/x-java-jnlp-file .jnlp

That should be it. If I point my web browser at, 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

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.

    &lt;title&gt;My Pirate!&lt;/title&gt;
    &lt;icon href=&quot;icon.png&quot;/&gt;

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.

Standard JWS Icon
Figure 1. Standard JWS icon

Custom Pirate 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

    &lt;title&gt;My Pirate!&lt;/title&gt;
    &lt;icon href=&quot;icon.png&quot;/&gt;       
    &lt;icon href=&quot;splash.png&quot; kind=&quot;splash&quot;/&gt; <br />

Which will look like Figure 3:

<br "'My Pirate!' Splash Screen" />
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

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.


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


width="1" height="1" border="0" alt=" " />
Josh Marinacci first tried Java in 1995 at the request of his favorite TA and has never looked back.
Related Topics >> GUI   |