Launching Java WebStart from the Command Line

One generally starts a Java WebStart application by clicking on a link in a web browser. WebStart is typically registered as the helper application for content with mime type application/x-java-jnlp-file, so the browser downloads the jnlp content and hands it off to WebStart. Depending on configuration, desktop shortcuts may be installed to speed up subsequent launches, and cached applications can also be launched from within the WebStart control panel.

On occasion, though, it is useful to launch WebStart “manually” from the command line, without the overhead of getting a web browser involved. The most straightforward way to do this is to simply use the “javaws” command included in the JDK. This is located in the “bin” directory in Linux and Windows distributions of the JDK or JRE. On OSX, a link is installed as “/usr/bin/javaws“, and a specific version can be accessed from the appropriate framework directory. For example, the full path to the 1.5.0 version is:


/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Commands/javaws

When executed with the -viewer argument, e.g.,


    javaws -viewer

javaws simply opens the WebStart control panel, from which you can view or clear the cache and change various preferences. In older versions of the JDK, this was also the default behavior for the command if no arguments were given.

If javaws is given the path to a jnlp file, e.g.:


    javaws ~/test_app.jnlp

or a URL pointing to jnlp content, e.g.:


    javaws http://www.foo.com/test_app.jnlp

the WebStart application will be downloaded and run.

On OSX you can also use the ubiquitous “open” command, e.g.,


    open http://www.foo.com/test_app.jnlp

This wins points for generality, but will also bring the web browser back into the picture. The open command hands the URL to the default web browser, which will then invoke WebStart as a helper app, just as if you had clicked on a link to the jnlp file.

So far so good, but what if you need to launch a WebStart application with more control over the virtual machine settings (e.g., in such a way as to allow debugger connections from JDB), or within the context of a larger application (e.g., in a profiler such as JProfiler)? WebStart is itself a Java application, and hence can be launched like any other such application. Here are the steps:

1) The WebStart classes are not included in the set of standard library jars that are included in the classpath by default. You must therefore explicitly add the appropriate jar(s) to your classpath. On OSX, this jar is:


    /Applications/Utilities/Java/Java Web Start.app/Contents/MacOS/javaws.jar

Under a Windows or linux JDK/JRE distribution, an additional jar file is needed:


    [JDK directory]/jre/lib/javaws.jar

and

    [JDK directory]/jre/lib/deploy.jar

2) The name of the WebStart executable class is “com.sun.javaws.Main“.

3) There are a few properties that must be set. These are:

Property	Examples
`jnlpx.home`	The absolute path to the JRE `bin` directory.
	Windows: `"C:\Program Files\Java\jre1.5.0_11\bin"` Linux: `"/usr/java/jdk1.5.0/jre/"` OSX: `"/Applications/Utilities/Java/Java Web Start.app/Contents/MacOS"`
`jnlpx.jvm`	Absolute path of the virtual machine executable to be used
	Windows: `"C:\Program Files\Java\jre1.5.0_11\bin\javaw.exe"` Linux: `"/usr/java/jdk1.5.0/bin/java"` OSX: `"/System/Library/Frameworks/JavaVM.framework/ Versions/1.4.2/Home/bin/java"`
`jnlpx.remove`	Must be `"true"` or `"false"`. (This apparently controls caching of the jnlp file, though I haven’t verified this yet.)
`jnlpx.splashport`	This property specifies a port number that is used for communicating with the (native) app that handles showing the splash screen. Setting it to “`-1`” will disable the splash screen.
`jnlpx.deployment.system.home`	System-wide deployment directory, only needed under OSX
	OSX: `"/Applications/Utilities/Java/Java Web Start.app/Contents/MacOS"`
`jnlpx.deployment.user.home`	Per-user deployment directory, only needed under OSX
	OSX: `"/Users/your_user_id/Library/Caches/Java Web Start"`

4) The URL for the WebStart app’s JNLP should be given as a command-line argument.

Putting this all together, a basic command-line invocation under Linux might look something like:


/usr/java/jdk1.5.0/bin/java -cp /usr/java/jdk1.5.0/jre/lib/javaws.jar:\
        /usr/java/jdk1.5.0/jre/lib/deploy.jar \
        -Djnlpx.home="/usr/java/jdk1.5.0/jre/"    \
        -Djnlpx.jvm="/usr/java/jdk1.5.0/bin/java" \
        -Djnlpx.remove=false                      \
        -Djnlpx.splashport=-1                     \
        com.sun.javaws.Main                       \
        http://www.foo.com/test_app.jnlp

On windows, it would look like:

java -classpath "C:\Program Files\Java\jre1.5.0_11\lib\javaws.jar;
  C:\Program Files\Java\jre1.5.0_11\lib\deploy.jar" 
  -Djnlpx.home="C:\Program Files\Java\jre1.5.0_11\bin" 
  -Djnlpx.jvm="C:\Program Files\Java\jre1.5.0_11\bin\javaw.exe" 
  -Djnlpx.remove=true 
  -Djnlpx.splashport=-1 
  com.sun.javaws.Main http://www.foo.com/test_app.jnlp

And under Mac OSX, it would look like:


java -cp "/Applications/Utilities/Java/Java Web Start.app/Contents/MacOS/javaws.jar" \
        -Djnlpx.home="/usr/java/jdk1.5.0/jre/"    \
        -Djnlpx.jvm="/usr/java/jdk1.5.0/bin/java" \
        -Djnlpx.remove=false                      \
        -Djnlpx.splashport=-1                     \
        -Djnlpx.deployment.system.home=\
            "/Applications/Utilities/Java/Java Web Start.app/Contents/MacOS"          \
        -Djnlpx.deployment.user.home=\
            "/Users/your_user_id/Library/Caches/Java Web Start"                   \
        com.sun.javaws.Main                       \
        http://www.foo.com/test_app.jnlp