Photo credit: Windell H. Oskay, www.evilmadscientist.com bridell.com
on creative engineering and new media art

How to start a Java application with web start

December 14th, 2007

These are some notes I made while trying to get a Java OpenAL (JOAL) application start from a web page. The tutorial applies to Java 1.4.2, but it probably works similarly in newer versions.

There are some things you need to master:

  1. Generate a manifest that indicates the main class
  2. Package everything in jar file(s)
  3. Generate your keys using java keytool
  4. Sign the jar file(s)
  5. Make the JNLP XML file
  6. Put everything on a web server

Kudos

Kevin Glass (at cokeandcode.com) has written a nice web start tutorial that helped me sort this all out.

0. Before you start

I usually do stuff from Eclipse, and I’ve adopted the style of putting the java source files in a “src” directory and the classes in a “bin” directory. I assume this is the case for you too.

I also assume you have a Java JDK installed and set up so the java tools (java, javac, javadoc, keytool, jarsigner) are on your path.

1. Generate a manifest file

For our purposes, all we need to do is create a text file “manifest.txt” in the root folder of the project, containing only a single line containing the fully qualified name of the main class of your project:

Main-Class: com.bridell.example.HelloWorld

Obviously (I hope) you should replace the part in italics with the actual class you’re using.

2. Putting everything in a jar file

Open a command window in the root folder for the project, and execute

jar cvfm MyArchive.jar manifest.txt -C bin .

Where MyArchive is a name of your choice. The letters are create, verbose, manifest, files. The “-C bin .” bit roughly translates to “cd to the bin folder and treat it as the root”

To pack other archives, without a manifest, just cd to where where your class files are (i.e. in the bin folder) and execute jar cvf MyArchive.jar *

See also: Java Tutorial, Packaging programs in JAR files

3. Generate your keys

This is something you only need to do once. Actually, the proper way of doing this is getting a certificate from a Certifications Authority such as VeriSign or Thawte, but this is the sneaky way of just signing jars yourself, without a certificate.

All you need to do is to type

keytool -genkey -alias MyAlias

where MyAlias is the name you want to use when you sign the jars. Just fill in the information when prompted. Don’t forget your keyword! This will generate a .keystore file on your computer (on Windows XP, as C:\Documents and Settings\User\.keystore). If you want to, you can place it somewhere else and supply a -keystore location argument to keytool and jarsigner.

When you’re done, you can do keytool -list to see that the key is there.

See also: keytool documentation (1.4.2 version)

4. Sign the jars

To sign a jar, execute

jarsigner MyArchive.jar MyAlias

where MyArchive.jar matches the archive from step 2 and myAlias matches the alias from step 3, of course.

If you want to see who signed a jarfile, execute
jarsigner -verify -verbose -certs MyArchive.jar
and try to make sense of what rolls by.

5. Make the JNLP file

The JNLP file is an XML file that you just create with a text editor. Here’s a complete sample of a JNLP file I used to deploy a Java application that also relies on native libraries – so this is a fairly advanced example.

<?xml version=\”1.0\” encoding=\”UTF-8\”?>
<jnlp
spec=”1.0+”
codebase=”http://www.tii.se/temp/webstart/awn”
href=”awn-demo1.jnlp”
>

<information>
<title>Auditory Wab Navigator Demo 1</title>
<vendor>Interactive Institute</vendor>
<homepage href=”http://www.tii.se”/>
<description>Auditory Web Navigator Demo 1</description>
<description kind=”short”>Deployment using Processing and OpenAL</description>
<offline-allowed/>
</information>

<security>
<all-permissions/>
</security>

<resources>
<j2se href=”http://java.sun.com/products/autodl/j2se” version=”1.4+”/>
<jar href=”awn-demo1.jar”/>
<jar href=”lib/joal.jar” />
<jar href=”lib/core.jar” />
<jar href=”lib/gluegen-rt.jar” />

</resources>

<resources os=”Windows”>
<j2se href=”http://java.sun.com/products/autodl/j2se” version=”1.4+”/>
<nativelib href=”lib/joal-natives-windows-i586.jar”/>
<nativelib href=”lib/gluegen-windows.jar” />

</resources>

<application-desc/>
</jnlp>

The stuff in this JNLP file is pretty straight-forward once you’ve seen it. The parts shown here in bold font are the actual references to the jar files.

  • The codebase is the URL of the directory on the web server where you put yout files.
  • The whole information part is just information (some of which is shown when you load the web start application).
  • In the first resources part are the general, signed jar files – the ones you made above, holding your class files – the file names should be relative to the codebase above. The first jar file should be your main jar file, the one that contains the manifest that points to the main class.
  • The second resources part, with the os=”Windows” parameter, contains OS-specific stuff, in this case the stuff that is only needed on Windows. Note that the nativelib also points to a jar file, but in this case they point to a jar containing native libraries (dll:s). You should be able to make stuff for Mac and Linux, too – if anybody tried that, why not tell me how it went.

See also: Deploying Software with JNLP and Java Web Start from Sun

6. Put everything on the web server

Just put the jars and the JNLP file on a web server with URLs that match what you wrote in the JNLP file, and then tell “the user” to point his web server to the jnlp file. (E.g. by linking to them from a web page…)

If your web server does not support JNLP, there are some neat hacks in Kevin Glass’ tutorial.

EXTRA: how to clear the webstart cache

A problem I came across was that webstart would not reload the jars after I resigned them. The problem was that they were already downloaded and cached by web start. The way to force a reload is to clear the webstart cache. On windows, you do this using Control Panel > Java and then removing temporary internet files.

Using native libraries with web start

This is, in fact, supported. I’ve only tried it on Windows (XP and Vista) so far, but it works. The trick is to put your .dll files directly in the “root” of a jar file, and then add this jar file using the “nativelib” code in the JNLP file, see example above.

See also: A note about using native library loading from the Lopica project

Deploying JOAL using web start

JOAL is a Java wrapper around OpenAL, a tool for playing audio. The neat thing is that it lets you place audio sources in a 3D environment and move a listener around in this 3D space, and the sound that comes out your speakers should be adapted to the position and orientation of the listener. It also lets you do a lot of other stuff, like pitch shifting and doppler effects. Unfortunately I have yet to figure out if it really is possible to use the Effects extension (EFX) from JOAL – I have failed so far. Get JOAL from joal.dev.java.net.

Processing is a free, open-source programming environment based on Java and the weapon of choice for most people doing artistic productions that require a bit of coding. Get it at processing.org

What we wanted to do was to put a Java application that uses JOAL for audio and Processing for graphics online, so it can be started using Java web start. Here’s how I did it.

This refers to the JOAL 1.1.0 release build. (All downloads are at joal.dev.java.net) You download joal-1.1.0-windows-i586.zip and unzip this. It contains four important files:

  1. gluegen-rt.jar
  2. gluegen-rt.dll
  3. joal.jar
  4. joal_native.dll

The other file to get is joal-1.1.0-webstart.zip. It contains five files

  1. joal.jar
  2. joal-natives-linux-i586.jar
  3. joal-natives-macosx-ppc.jar
  4. joal-natives-macosx-universal.jar
  5. joal-natives-windows-i586,jar

Of particular interest to us, since we were initially happy to get things working on windows, or indeed at all, was the joal-natives-windows-i586.jar. It contains three files:

  1. joal_native.dll
  2. OpenAL32.dll
  3. wrap_oal.dll

As it happens, these seem to be the same ones that are copied to your windows\system32 folder if you install the OpenAL runtime. (The point of using web start was that we want to let end users skip the hassle of installing this!)

At first I tried using the jars from the joal-1.1.0-webstart.zip – but then webstart would complain that my jars were signed by different people. I tried signing the jars myself, so that all were signed my me (and the ones that came in the webstart zip archive were also sigend by Sun) but it still would not run.

The solution

  • For gluegen-rt.jar: sign it
  • For joal.jar (from joal-1.1.0-windows-i586.zip): sign it
  • For joal-natives-windows-i586.jar: unzip the jarfile, remove the META-INF folder, make a new jar, and sign it
  • For core.jar (that comes with Processing – copy it from the Processing installation): sign it
  • For gluegen-rt.dll: make a jar from it (gluegen-windows.jar), and sign it

Finally, put all the jars and the JNLP file on a web server, like this

awn-demo1.jnlp
awn-demo1.jar
lib/core.jar
lib/gluegen-rt.jar
lib/gluegen-windows.jar
lib/joal.jar
lib/joal-natives-i586.jar
The JNLP file is the one above.
You can try it here: http://www.tii.se/temp/webstart/ – it’s the “AWN Demo #1″