A Guide to the Java Web Start

1. Overview

This article explains what Java Web Start (JWS) is, how to configure it on the server side, and how to create a simple application.

Note: The JWS has been removed from the Oracle JDK starting with Java 11. As an alternative, consider using OpenWebStart.

2. Introduction

JWS is a runtime environment that comes with the Java SE for the client’s web browser and has been around since Java version 5.

With the download of the JNLP files (also known as Java Network Launch Protocol) from the web server, this environment allows us to run JAR packages referenced by it remotely.

Simply put, the mechanism loads and runs Java classes on a client’s computer with a regular JRE installation. It allows some extra instructions from Jakarta EE as well. However, security restrictions are strictly applied by the client’s JRE, usually warning the user for untrustworthy domains, lack of HTTPS and even unsigned JARs.

From a generic website, one can download a JNLP file to execute a JWS application. Once downloaded, it can be run directly from a desktop shortcut or the Java Cache Viewer. After that, it downloads and executes JAR files.

This mechanism can be very helpful to deliver a graphical interface that is not web-based (HTML free), such as a secure file transfer application, a scientific calculator, a secure keyboard, a local image browser and so on.

3. A Simple JNLP Application

A good approach is to write an application and package it into a WAR file for regular web servers. All we need is to write our desired application (usually with Swing) and package it into a JAR file. This JAR must then, in turn, be packaged into a WAR file together with a JNLP that will reference, download and execute its application’s Main class normally.

There is no difference with a regular web application packaged in a WAR file, except for the fact that we need a JNLP file to enable the JWS, as will be demonstrated below.

3.1. Java Application

Let’s start by writing a simple Java application:

public class Hello {
    public static void main(String[] args) {
        JFrame f = new JFrame("main");
        f.setSize(200, 100);
        f.setLocationRelativeTo(null);
        f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        JLabel label = new JLabel("Hello World");
        f.add(label);
        f.setVisible(true);
    }
}

We can see that this is a pretty straightforward Swing class. Indeed, nothing was added to make it JWS compliant.

3.2. Web Application

All we need is to JAR package this example Swing class into a WAR file along with the following JNLP file:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" 
  codebase="http://localhost:8080/jnlp-example">
    <information>
        <title>Hello</title>
        <vendor>Example</vendor>
    </information>
    <resources>
        <j2se version="1.2+"/>
        <jar href="hello.jar" main="true" />
    </resources>
    <application-desc/>
</jnlp>

Let’s name it hello.jndl and place it under any web folder of our WAR. Both the JAR and WAR are downloadable, so we don’t need to worry putting the JAR in a lib folder.

The URL address to our final JAR is hard coded in the JNLP file, which can cause some distribution problems. If we change deployment servers, the application won’t work anymore.

Let’s fix that with a proper servlet later in this article. For now, let’s just place the JAR file for download in the root folder as the index.html, and link it to an anchor element:

<a href="hello.jnlp">Launch</a>

Let’s also set the main class in our JAR Manifest. This can be achieved by configuring the JAR plugin in the pom.xml file. Similarly, we move the JAR file outside of the WEB-INF/lib, since it is meant for download only, i.e. not for the classloader:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    ...
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <archive>
                    <manifest>
                        <mainClass>
                            com.example.Hello
                        </mainClass>
                    </manifest>
                </archive>
                <outputDirectory>
                    ${project.basedir}/target/jws
                </outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

4. Special Configurations

4.1. Security Issues

To run an application, we need to sign the JAR. Creating a valid certificate and using the JAR Sign Maven Plugin goes beyond the scope of this article, but we can bypass this security policy for development purposes, or if we have administrative access to our user’s computer.

To do so, we need to add the local URL (for instance: http://localhost:8080) to the security exceptions list of the JRE installation on the computer where the application will be executed. It can be found by opening the Java Control Panel (on Windows, we can found it via the Control Panel) on the Security tab.

5. The JnlpDownloadServlet

5.1. Compression Algorithms

There is a special servlet that can be included in our WAR. It optimizes the download by looking for the most compressed compiled version of our JAR file if available, and also fix the hard coded codebase value on the JLNP file.

Since our JAR will be available for download, it’s advisable to package it with a compression algorithm, such as Pack200, and deliver the regular JAR and any JAR.PACK.GZ or JAR.GZ compressed version at the same folder so that this servlet can choose the best option for each case.

Unfortunately, there is no stable version of a Maven plugin yet for this compression algorithm, but we may work with the Pack200 executable that comes with the JRE (usually, installed on the path {JAVA_SDK_HOME}/jre/bin/).

Without changing our JNLP and by placing the jar.gz and jar.pack.gz versions of the JAR in the same folder, the servlet picks the better one once it gets a call from a remote JNLP. This enhances the user experience and optimizes network traffic.

5.2. Codebase Dynamic Substitution

The servlet can also perform dynamic substitutions for hardcoded URLs in the <jnlp spec=”1.0+” codebase=”http://localhost:8080/jnlp-example”> tag. By changing the JNLP to the wildcard <jnlp spec=”1.0+” codebase=”$$context”>, it delivers the same final rendered tag.

The servlet also works with the wildcards $$codebase, $$hostname, $$name and $$site, which will resolve “http://localhost:8080/jnlp-example/“, “localhost:8080“, “hello.jnlp“, and “http://localhost:8080” respectively.

5.3. Adding the Servlet to the Classpath

To add the servlet, let’s configure a normal servlet mapping for JAR and JNLP patterns to our web.xml:

<servlet>
    <servlet-name>JnlpDownloadServlet</servlet-name>
    <servlet-class>
        jnlp.sample.servlet.JnlpDownloadServlet
    </servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>JnlpDownloadServlet</servlet-name>
    <url-pattern>*.jar</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>JnlpDownloadServlet</servlet-name>
    <url-pattern>*.jnlp</url-pattern>
</servlet-mapping>

The servlet itself comes in a set of JARs (jardiff.jar and jnlp-servlet.jar) that are nowadays located on the Demos & Samples section on the Java SDK download page.

In the GitHub example, these files are included in the java-core-samples-lib folder and are included as web resources by the Maven WAR plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    ...
    <configuration>
        <webResources>
            <resource>
                <directory>
                    ${project.basedir}/java-core-samples-lib/
                </directory>
                <includes>
                    <include>**/*.jar</include>
                </includes>
                <targetPath>WEB-INF/lib</targetPath>
            </resource>
        </webResources>
    </configuration>
</plugin>

6. Final Thoughts

Java Web Start is a tool that may be used in (intranet) environments where there is no application server. Also, for applications that need to manipulate local user files.

An application is shipped to the end user by a simple download protocol, without any additional dependencies or configuration, except for some security concerns (HTTPS, signed JAR, etc.).

We can download it directly from GitHub to an OS with Tomcat and Apache Maven. After download, we need to run the mvn install command from the source directory and copy the generated jws.war file from the target to the webapps folder of the Tomcat installation.

After that, we can start Tomcat as usual.

From a default Apache Tomcat installation, the example will be available at the URL http://localhost:8080/jws/index.html.