Java Web Start

From Jmol
Revision as of 13:17, 11 July 2007 by Pimpim (talk | contribs) (added running jmol template)
Jump to navigation Jump to search
Installing Jmol / JSmol

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 File icon.gif.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 File icon.gifjmol.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 File icon.gifjmol.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 File icon.gifJmol.jar from the Jmol distribution (download here) to your Web server's <document-root>/javaws/jmol/ directory. Ensure that File icon.gifJmol.jar is readable so that it can be accessed via the URL in File icon.gifjmol.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 File icon.gifjmol.jnlp above). This requires that, File icon.gifJmol.jar be signed. As of Jmol v10.00.45, File icon.gifJmol.jar is signed. If you want to use a previous version of File icon.gifJmol.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 File icon.gifmyKeystore 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 File icon.gifJmol.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.

Running Jmol in Java Webstart

Running Jmol / JSmol

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 File icon.gifJmol.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 File icon.gifjmol.jnlp URL, desktop shortcut or the Java Web Start GUI, Web Start will check whether the File icon.gifJmol.jar has been updated on the server. If it has then the new File icon.gifJmol.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 File icon.gif<document-root>/javaws/jmol/Jmol.jar on the Web server.

Contributors

Pimpim, NicolasVervelle