tutorials
tips
software development
experiments
computers

Java Web Start (jnlp) simple example

9 years ago

UPDATE (2013/05/28): Since most people already know, WebStart is a bit of a crappy piece of tech with a bunch of limitations. The good news is there are alternatives :)

One of my current projects requires me to deliver a Swing application via Java Web Start. This meant some research to figure out how that works. Since i'm a nice guy, here's the result for everyone that needs it.

As you can see - in the folder structure image - there are some files that are required for the whole thing to work. Here's a brief explanation about each of them (in my creation order ;)):

  • src/org/Test.java : My source code. It's just a simple main that creates a JFrame and displays it;
  • Manifest.txt : The manifest file used to create the jar file that gets served by Java Web Start;
  • faren.jar : My application's jar. I'll explain how to create it in a while;
  • faren.jnlp : The Java Web Start description file;
  • faren.html : The html file that contains the button to start the application.

The first thing we want to do is create the source file. In the case of my simple test, here are its contents (blank lines removed for brevity):

Test.java 


package org;

import javax.swing.JFrame; 
import java.awt.Dimension;

public class Test {   
  public Test() {     
    JFrame faren = new JFrame("Test");     
    faren.setSize(new Dimension(300, 300));     
    faren.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);     
    faren.setVisible(true);   
  }   

  public static void main(String[] args) {     
    new Test();   
  } 
}

Moving on to the jar manifest file, it basically just says what the main class will be:

Manifest.txt 

Main-Class: org.Test

Creating the jar is as simple as running the following command:

jar cfm faren.jar Manifest.txt org

It creates the faren.jar file, using the manifest file and the sources contained within the org folder. If - like me - you use Maven, you will have this for free using the app-assembler plugin, but for the test's purposes i didn't want to create a full maven project :)

Now we need to define a description file for the Java Web Start mechanism:

faren.jnlp 


<?xml version="1.0" encoding="UTF-8"?> 
<jnlp spec="1.0+" codebase="file:///Users/pedroassuncao/Desktop/jnlp_example">   
  <information>     
    <title>Dynamic Tree Demo</title>     
    <vendor>Dynamic Team</vendor>   
  </information>   
  <resources>     
    <!-- Application Resources -->     
    <j2se version="1.6+" href="http://java.sun.com/products/autodl/j2se"/>     
    <jar href="faren.jar" main="true" />   
  </resources>   
  <application-desc name="Dynamic Tree Demo Application" main-class="org.Test" width="300" height="300"></application-desc>
  <update check="background"/>
</jnlp>

Just to explain a little bit of what is going on in here (the important parts), what you want to make sure is that the codebase property is set correctly to the absolute path where the html file will be served from (in the case of a final deployment this will be something like http://myserver/jnlp/myapp, but in this case i'm serving without a web server, hence the file:/// part). You will also want to define a minimum version for the virtual machine of the client (the 1.6+ part) and eventually extend this information with the <shortcut> tag, that allows you to ask web start to create a desktop icon for your application on the clients' computers. A full description of the structure of this file can be found here.

Finally, we need an html file that will show the java web start button. The following will suffice for now:

faren.html 


<html>   
  <head></head>   
  <body>     
    <script src="http://www.java.com/js/deployJava.js"></script>     
    <script>       
      // using JavaScript to get location of JNLP file relative to HTML page       
      var dir = location.href.substring(0, location.href.lastIndexOf('/')+1);       
      var url = dir + "faren.jnlp";       
      deployJava.createWebStartLaunchButton(url, '1.6.0');     
    </script>     
    <noscript>       
      <a href="faren.jnlp">Launch</a>     
    </noscript>   
  </body> 
</html>

If the client's browser supports javascript, this will use a special script from the java website that will ask to install the virtual machine if the client does not have it (or upgrade an existing one). If he doesn't support javascript it will just show a link that will try to launch the java web start (depending a lot on whether the user's file associations are correct (i.e. .jnlp files being assigned to the java executable).

Finally, with all this in place, point your browser to the place where you have the faren.html file and click the button; the application should launch.

By the way, does anyone know why my desktop shortcut is not being added on OSX? :)

<< back to posts