Java Web Start

Deploying Jmol Using Java Web Start

The following describes how to deploy the Jmol Application using Java Web Start. It involves the following steps:

Assumptions

The instructions that follow are based on the Java Web Start v1.4 and Jmol v10.00.xx. For more details see the Java Web Start Developers Guide.

Requirements

The client machine requires support for the Java Runtime Environment v1.4 or later (download here).

The Web server must be configured with support for the application/x-java-jnlp-file MIME type.

Configure Web Server

Configure the Web server so that all files with the .jnlp file extension are set to the application/x-java-jnlp-file MIME type. For example, for the Apache Web server you must add the following line to the .mime.types configuration file:

application/x-java-jnlp-file JNLP 

Create a directory on the Web server to hold the Web Start files. In the following the directory used is <document-root>/javaws/jmol/.

Create JNLP File

Create a file named jmol.jnlp with contents similar to the following (replace www.example.com with your Web server's fully-qualified domain name):

<?xml version="1.0" encoding="utf-8"?>
<jnlp
  spec="1.0+"
  codebase="http://www.example.com/javaws/jmol"
  href="jmol.jnlp">
  <information>
    <title>Jmol Application</title>
    <vendor>Jmol.org</vendor>
    <homepage href="http://www.jmol.org"/>
    <description>3D Molecule Viewer</description>
    <description kind="short">Jmol is a free, open source molecule viewer for students, educators, and researchers in chemistry and biochemistry.</description>
    <offline-allowed/>
    <icon href="http://jmol.sourceforge.net/images/Jmol_smallLogo.jpg"/>
  </information>
  <security>
    <all-permissions/>
  </security>
  <resources>
    <j2se version="1.4+"/>
    <jar href="Jmol.jar"/>
  </resources>
  <application-desc main-class="org.openscience.jmol.app.Jmol"/>
</jnlp>

and save it in your Web server's <document-root>/javaws/jmol/ directory. Ensure that jmol.jnlp is readable so that it can be accessed via the Web server, in this case the URL http://www.example.com/javaws/jmol/jmol.jnlp.

Copy JAR File

Copy Jmol.jar from the Jmol distribution (download here) to your Web server's <document-root>/javaws/jmol/ directory. Ensure that Jmol.jar is readable so that it can be accessed via the URL in jmol.jnlp, in this case http://www.example.com/javaws/jmol/Jmol.jar.

Signing the JAR File

The Jmol application needs access to the client's system resources, e.g. file system and environment variables. Therefore, Web Start must run it in a trusted environment (see <all-permissions/> in the jmol.jnlp above). This requires that, Jmol.jar be signed. As of Jmol v10.00.45, Jmol.jar is signed. If you want to use a previous version of Jmol.jar, you can sign it with a test certificate using the instructions below but this is not suitable for a production environment. You will need keytool and jarsigner tools from the Java Development Kit (download here).

1. Create a new key in a new keystore as follows:
   keytool -genkey -keystore myKeystore -alias myself
   You will be prompted for information about the new key, such as password, name, etc. This will create the myKeystore file. A self-signed test certificate also will be created.
2. Then create a self-signed test certificate as follows:
   keytool -selfcert -alias myself -keystore myKeystore
   This will prompt for the password. Generating the certificate may take a few minutes.
3. Finally, sign Jmol.jar with the test certificate as follows:
   jarsigner -keystore myKeystore Jmol.jar myself

Please note that a self-signed test certificate should only be used for internal testing, since it does not provide any guarantees about the identity of the user and therefore cannot be trusted. A trust-worthy certificate can be obtained from a certificate authority, such as VeriSign or Thawte, and should be used when the application is put into production.

Test

You should then be able to launch the Jmol application from a Java Web Start enabled browser using a URL similar to http://www.example.com/javaws/jmol/jmol.jnlp.

You will be prompted to trust the Jmol application (the certificate is used to authenticate the identity of the person/organisation who created Jmol.jar).

On Windows you might also be prompted about desktop integration, i.e. whether to create a desktop shortcut from which you can directly launch the Jmol application in future.

If the URL successfully launches the Jmol application then you can include it in Web pages.

Updates

Whenever the Jmol application is launched, whether from a jmol.jnlp URL, desktop shortcut or the Java Web Start GUI, Web Start will check whether the Jmol.jar has been updated on the server. If it has then the new Jmol.jar will be downloaded into the Web Start cache and used to run the Jmol application. In this way new versions of Jmol can be automatically deployed by simply updating the copy of <document-root>/javaws/jmol/Jmol.jar on the Web server.

Contributors

Pimpim, NicolasVervelle