The Source for All Things Java

Joe Winchester

Subscribe to Joe Winchester: eMailAlertsEmail Alerts
Get Joe Winchester: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

Related Topics: Java Developer Magazine

Java Developer : Article

Developing Java Client Applications Using Java Web Start and WebSphere Studio

Using JWS avoids the problems associated with traditional applets

Java Web Start (JWS) was created as part of JSR 56 and is included with JRE 1.4. The idea was to provide a way to distribute a Java application that would run in a JVM on the client, but avoid the problems associated with traditional applets. JWS does this by incorporating the features shown in Table 1.


If you have JRE 1.4.1 or higher, then you already have Java Web Start installed. If not, you can obtain and install a JRE from This article describes how to create and deploy a JWS application using WebSphere Studio Application Developer 5.0.

Hello World JWS
In keeping with the tradition of articles that introduce new ways to perform GUI programming, the first step is to create a Web Start application that shows a dialog with the words "Hello World". This is done in two steps, the first on the server side, where the class is created and deployed onto a Web server, and the second on the client side, where a PC accesses a URL that causes it to be downloaded and invoked locally through JWS.

The Server

  1. The HelloWorld class is created, packaged into a JAR, and imported into a dynamic Web project.
  2. A file with the suffix .jnlp is created that contains XML tags describing the application to be run.
  3. A WebSphere server configuration is created that has the .jnlp file extension associated with the mime type to cause the browser to run JWS.

Creating the HelloWorld Class
The source code for the HelloWorld class is shown below.

import javax.swing.*;
public class HelloWorld {
public static void main(String[] args) {
JFrame frame = new JFrame("Hello World");

When executed using RunAs>JavaApplication, a Swing JFrame is displayed whose title is Hello World, as shown in Figure 1.


Running an application using RunAs>Application allows you to test the application; however, it does so by creating a JVM on the same machine as WebSphere Studio and running the program there. For JWS the next steps are to create a JNLP file and deploy the HelloWorld class into an instance of the WebSphere Application Server, so that it can be run th rough a browser connection on another PC.

A dynamic Web project should be created for the purpose of creating and deploying the JWS application. This is done using the menu option from the File menu or New pulldown list on the toolbar.

We'll call the example project "JavaWebStartTest". The HelloWorld class should exist in the Web project within a JAR file. This is done by using the Export pop-up menu option for the file, selecting JAR file, and specifying a location in the file system. Having done this, now import the JAR into the JavaWebStartTest project using the menu option File>Import.

Note: If you change and wish to re-deploy it to the Web project, you will need to re-export it as a JAR and import it back into the JavaWebStartTest project. To simplify this scenario, you can download the zipCreation utility created by Tim DeBoer, which allows you to configure a project to be automatically re-JARred into another project techarticles/0112_deboer/deboer2.html.

Creating the JNLP File
The next step is to create the JNLP file that will be used to download and launch the HelloWorld class. This will be called HelloWorld.jnlp, and placed in the WebContent directory of the project. There is no specific wizard for JNLP files, so use the File>New>Other and select Simple>File to specify the name HelloWorld.jnlp. A JNLP file is XML and contains a number of tags, as shown in Listing 1. The JNLP tag specifies the codebase where the code that is going to be run is located. Listing 1 hard-codes it to be the URL of the Web server (which happens to be our IP address), the port number, and the name of the Web project.

Later we will show you how to use a servlet to avoid having to hard-code the Web server URL, but for simple examples it can be explicitly set. The information tag specifies details such as the title of the application, the vendor, and some descriptions that will be shown to users when they download and invoke the application, and that are also used by JWS administration. The tag <offline-allowed> specifies that once the application has been downloaded by JWS and cached locally, users can relaunch it from their client without the need for a connection. Including the tag <offline-allowed=false> would prevent users from relaunching without a connection. For the application to run on the client, we need to specify the JRE level required for it. In our case we need 1.3 or higher, and the JAR file containing the application must be specified in the <resources> tag. The name of the Java class that will be run through its main(String[] args) method is entered in the <application-desc> tag. We'll go into more detail about this tag later.

The location of the JAR file in the <resources> tag is relative to the codebase specified in the <jnlp> tag. The full syntax of a JNLP file can be found at In this article we will cover the most commonly used tags.

Listing 2 shows the code for an index.html page with an anchor tag pointing to the JNLP file, which allows the user to click the link on a browser and start HelloWorld through JWS.

The locations of the three files in the Web project are shown in Figure 2. Because the HelloWorld.jnlp file is in the WebContent folder of the JavaWebStartTest project, the codebase of the deployed EAR is going to be ServerURL /JavaWebStartTest. For the WebSphere test environment the server URL is the machine name:port number.


Configuring WebSphere
To configure WebSphere, the file extension .jnlp must be associated with the application mime type application/x-java-jnlp-file. To do this, select the server in the Servers view and edit its configuration using the Open option on its pop-up menu. Select the Web tab, and use the Add button to enter the MIME type for JNLP extension as shown in Figure 3. If you don't have a server already configured, use the menu option New>Server and Server Configuration from the pop-up menu in the Servers view, selecting WebSphere version 5.0 and Test Environment, as shown in Figure 3.


The Client
To test the HelloWorld application, run the index.html file on the test environment by right-clicking on the file in the Project Navigator and selecting Run on Server from the pop-up menu. If there is more than one server configured, make sure that the one with the MIME type extension for JNLP is the one launched. Once the test environment has started up, select the anchor tag in the index.html file. This will download the HelloWorld.jnlp file to the client browser. In Figure 4 the browser embedded within WebSphere Studio is used, so the same PC is acting as the server (running the WebSphere Studio test environment) and the client (running the Web browser).


After you've tested the JNLP file this way, a good next step is to go to a PC other than the one running the WebSphere test environment, and try to access the JNLP file from there (typing in the full URL rather than localhost, e.g., Having downloaded the application, JWS will show details about the title and vendor of the application, together with a progress bar as it downloads the JAR file, caches it, and executes it.

Because of the http attribute in the <jnlp> tag, the HelloWorld application will be installed in the JWS Application Manager. This allows a shortcut to the program to be automatically installed onto the desktop, and the user is prompted to choose whether or not to create the shortcut, as shown in Figure 5.


Having downloaded the JAR file, the HelloWorld class is then launched. This application is run in a window that identifies itself to the user as a Java Application Window, as shown in Figure 6. This is so that Trojan horse applications masquerading as other programs can be distinguished as having come from JWS by the status line message at the bottom. If the JNLP file was using a signed JAR with a certificate, then the status message is not shown. I'll go into more detail on security later.


Administering the Client
Once the client PC has downloaded and run the HelloWorld application, a local copy is kept. You might notice that subsequent attempts to run the application are faster, and also that you won't get the same sequence of launch dialogs; instead you get just a single splash screen.

The Application Manager shown in Figure 7 allows a client PC to administer all of its JWS applications. The program javaws.exe is located in the javaws directory beneath the JRE, e.g., "C:\ProgramFiles\Java\j2re1.4.2\javaws\javaws.exe". You can also obtain it from the following URL, which is itself a JWS-enabled version of the application manager,


Because the href="HelloWorld.jnlp" attribute was specified in the <jnlp> tag, the program is listed in the application manager. If no href attribute is used, the client application is not included in the application manager, and the user will not be prompted to create a shortcut. The icon used is the one specified in the <icon href=""> tag in the JNLP file, and as none was specified in HelloWorld.jnlp, the default coffee cup is shown. To install a shortcut to the application on the desktop, use the menu option Application>Create shortcuts, which will place a desktop icon so you can launch HelloWorld directly without going through a Web browser. The icon used is the one specified in the <icon href=""/> tag in the JNLP file, which defaults to the Java coffee cup logo.

You can also use the menu option Application>Remove shortcuts to take a shortcut away, and the menu option Application>Remove application to delete the locally installed program. To control whether or not JWS applications are automatically installed as desktop shortcuts, you can use the menu option File> Preferences and open the Shortcuts tab. The preferences dialog also lets you configure details such as whether you are connecting through a proxy server.

Automatic Detection of Client Java Level
The index.html file we created earlier assumed that the client browser had JWS installed. If the client PC has JRE 1.4.1 or higher, then JWS should be installed by default, but in an environment like the Internet it might not be fair to assume that all of the clients are going to be at a particular JRE level. To deal with the inherent uncertainty of Internet environments, a piece of JavaScript can be written to detect whether or not JWS is installed, and if not, prompt the user to download and install it. A description of the scripts to do this is in the JWS documentation at jws/developersguide/launch.html#intro. Listing 3 shows how the index.html file can be rewritten to perform automatic detection of whether the client has the correct JRE level and JWS installed, and if not, prompt them to download a version. The first step is to see whether the browser is Netscape or IE, and if Netscape, inspect the MIME types to see whether JWS is installed. The second piece of VBScript runs on IE, and by using a COM object that is part of the Web Start DLL, it tries to detect what version, if any, of JWS is present. The final piece of JavaScript either links the page to the JNLP file, or else prompts the user with a link to download and obtain JRE 1.4.2 from Sun's Web site. The file indexTestingJreLevel.html includes all of the HTML and JavaScript shown in Listing 3 and is part of the downloadable EAR file included with this article. (All of the code referenced in this article can be downloaded from

Some JWS applications may be required to access services on the client PC such as IO for reading and writing files or opening sockets and making connections. For security purposes you don't want malicious programs to have unlimited access to these facilities on your PC, so JWS uses the Java security model and JAR file certification. By default a JWS virtual machine is a restricted sandbox denying access to these services. If you try to go outside the permissions of the security manager, e.g., to perform some file IO, then an exception is raised.

To be able to use restricted Java services you must ask the client to grant access. This is done with the <security> tag in the JNLP file, which is a child of the <jnlp> tag. If the program is to have unrestricted access to the machine resources, the tag would be:


The JAR file must be signed in order for security to be used; failure to sign the JAR file will result in a security error being raised. To sign a JAR file you can use the keytool command that is supplied with the JDK, although if you are going to put your JWS application into full production it is recommended that you obtain a certificate from an authority such as Thawte or VeriSign. For more information on Java security, see

Improving Deployment and Configuration
In the steps described above there were two steps that can be simplified with a simple servlet. They are the inclusion of the explicit URL for the codebase in the JNLP file, and the changing of the mime type associations for the WebSphere test environment.

To automate these steps, obtain the jnlp-servlet.jar file and add it to the WEB-INF/lib folder of the Web project. The file is included with the JNLP developer's pack, available at

Then update the web.xml file in the WEB-INF folder as shown in Listing 4. XML tags for <servlet>, <servlet-mapping>, and <mime-mapping> should be inserted inside the <web-app> tag. These tags should be placed before the <welcome-file-list> tag, and WebSphere Studio validation of the web.xml file will report errors if these tags are incorrectly positioned.

The <servlet> tag tells WebSphere Studio how to invoke the servlet class com.sun.javaws.servlet.JnlpDownloadServlet, which is part of the jnlp-servlet.jar. The <servlet-mapping> tag tells the container when to invoke the servlet, and that we wish it to run for files with a suffix of .jnlp. Finally, the <mime-mapping> tag allows you to specify the application MIME type to associate with the JNLP file without having to change the configuration of WebSphere. This allows you to more easily create a packaged EAR that can be deployed into an existing server that contains all the information required to run within it, and doesn't require the server administrator to update its configuration.

Now that you have included the jnlp-server.jar file in the /lib directory and updated the web.xml file to specify the MIME type and JnlpDownloadServer, the JNLP file itself can be simplified. When we created HelloWorld.jnlp earlier, we hard-coded the explicit URL of the Web server in its JNLP tag. What the JnlpDownloadServlet does, however, is run over all files with the .jnlp extension and allow this information to be substituted. Therefore, the phrase "$$codebase" can be soft-coded into the JNLP file and it will become the codebase of wherever the JNLP file is deployed, as shown below:

<?xml spec="1.0+" version="1.0" encoding="utf-8"?>
<jnlp codebase=$$codebase>
... remainder of jnlp file

Also, because the <mime-mapping> tag has been set in the web.xml file, the explicit association of the .jnlp file suffix with the application in the Web tag of the server configuration can be removed.

Client Detection of Changes
The client PC caches the application JAR file, as well as the date and time stamp of the original JNLP file, in a folder specified on the Advanced tab of the Application Manager.

When an application is launched using JWS, it first checks the cache to see whether it has accessed the JNLP file with the specified name from the same URL. If so, it then checks the date and time stamp of the JNLP file on the server against the one stored in the cache. A match means that the local version is not stale, and JWS will use it to launch the application without re-downloading the JAR files. If the date and time stamp don't match, then JWS will download the latest version from the location specified in the JNLP file, recache it, and continue launching the program. This approach, in which JWS lazily pulls the new version of software from the server when it is required, allows you to administer changes in a single location while ensuring that clients will be automatically updated.

One problem with this approach - in which the date and time stamp of the JNLP file are used as a trigger to force clients to redownload a version - is that the same JNLP file may be replicated onto several servers for load balancing. In this case, the client will detect that the file has changed and download a new version of the program when the cached version would have sufficed. To avoid this it is possible to have an explicit time stamp included in the JNLP file by starting the first line with TS: followed by an ISO 8601 date and time stamp. For example, if you wanted to time-stamp your file to be August 13th at 3 p.m. and 30 seconds, a line would be inserted before the opening <?xml> tag, as shown in Listing 5.

The JnlpDownloadServlet is responsible for recognizing the line beginning with TS and replacing the date and time stamp in the response returned to the client, so for this approach to work, the steps outlined earlier to use the jnlp-servlet.jar must have been taken.

With the TS: line included, the JNLP file can be moved between servers and JWS on the client will always pick up the encoded date and time stamp as the application's signature. This means that as the provider of the application you are responsible for explicitly changing the date and time stamp when you wish to deploy a new version of the program, but it has the advantage that the file can be moved across servers without clients falsely detecting that it has changed.

This article has shown how Java Web Start can be used to distribute rich Java applications from within WebSphere to be run on client PCs. This is done through the use of JNLP files that specify information about the application. This article has shown how these are cached on the client PC and can be installed as desktop shortcuts. When the application needs to be updated, it is changed centrally in a single location on the server and all clients will fetch the new copy when they next connect, based on the JNLP file date and time stamp.

The article also showed how the JnlpDownloadServlet can be used to softcode the codebase of the JNLP file and to give an explicit date and time stamp, thereby allowing the JNLP file to be replicated across multiple copies of WebSphere in a distributed environment but still appear to the client as a single program. I hope that you find JWS to be a powerful and flexible way to administer true rich Java client applications, and I welcome all feedback.


  • Java Web Start Technology:
  • Java Web Start demos, including SwingSet and simple draw program:
  • The Saturn Times: Daily Web Start News From Around The Globe:
  • Deploy an SWT application using Java Web Start:
  • More Stories By Joe Winchester

    Joe Winchester, Editor-in-Chief of Java Developer's Journal, was formerly JDJ's longtime Desktop Technologies Editor and is a software developer working on development tools for IBM in Hursley, UK.

    More Stories By Gunturi Srimanth

    Gunturi Srimanth is a software developer working on IBM's Visual Editor for Java in Research Triangle Park Lab, NC.

    More Stories By Gili Mendel

    Gili Mendel is an IBM Master Inventor and a Senior Technical Staff Member. He has been working for IBM since 1993 leading the development of various software products. These products span highly parallel device drivers for AIX clusters, to Eclipse based and now Cloud-based tools. He holds a PhD in computer science and is currently the development architect for the Ops Console for Dedicated and Local Bluemix.

    Comments (3)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.