Diff for "Cytoscape_via_Java_Web_Start"

Introduction

This page explains how to set up your own Cytoscape application to run via Java Web Start. For help running an existing Web Start, see the [http://cytoscape.systemsbiology.net/Cytoscape2.0/user/JavaWebStart/webStart.html basic web start documentation].

Setting up Cytoscape for Java Web Start is tricky. There are lots of little detailed steps and if you get any one wrong, it won't work. Expect to get it wrong about 5 times before you get it right (we always do).

Documentation on Java Web Start itself is at [http://java.sun.com/products/javawebstart/developers.html]

In particular, specific documentation on setting up a Web Start application is at [http://java.sun.com/products/javawebstart/1.2/docs/developersguide.html]

After reading this page, get one of our web starts, see how it works, and then do the same thing with your files. Try one of the tutorials at [http://www.cytoscape.org/tut/]. Just download the file pointed to by the web start link, then look at it.

The JNLP file

1. The header section

There is a template Cytoscape JNLP file cy1.jnlp in the cytoscape build directory. Excerpts of this file are shown here:

<?xml version="1.0" encoding="utf-8"?>
<jnlp
   codebase="http://chianti.ucsd.edu/kono/"
   href="cy1.jnlp">
  <information>
    <title>Cytoscape WebStart</title>
    <vendor>Cytoscape Collaboration</vendor>
    <homepage href="index.html"/>
    <offline-allowed/>
  </information>
  <security>
      <all-permissions/>
  </security>

2. The resources section, where any jar files that are part of the application must be listed

  <resources>
    <j2se version="1.4+" max-heap-size="1024M"/>
<jar href="cytoscape.jar"/>
<jar href="lib/fing.jar"/>
<jar href="lib/coltginy.jar"/>
...
<jar href="plugins/browser.jar"/>
<jar href="plugins/control.jar"/>
...
<jar href="data.jar"/>

3. The Cytoscape command line arguments section

  <application-desc main-class="cytoscape.CyMain">
        <argument>-rp</argument>
        <argument>browser.BrowserPlugin</argument>
        <argument>-rp</argument>
        <argument>control.ControlPlugin</argument>
... 
  </application-desc>
</jnlp>

The JNLP file is an xml file that tells Java Web Start what to do. This is the file you link to from your web page. The documentation above gives a detailed description of the various elements of this file. Here are some specific things to watch out for and some things specific to Cytoscape:

codebase and href. At the top of the JNLP file are two fields, codebase and href. The first points to a directory in which your files live, and the second is a pointer to the JNLP file itself. Thus, if you copy or move the JNLP file to a new location, you have to edit the file to point to the new location.

A very common mistake is copying the JNLP file and forgetting to change these fields. If you do this, it won't crash, it will just quietly load files from the directory specified in this field instead of the directory the JNLP file is in, and you'll get completely different files than what you were expecting.

Security: Cytoscape is currently written to require access to the local computer to read and save customization files and use system resources. Thus, you must put the "all-permissions" field in the security section or Cytoscape will crash. Note that the security manager of Java Web Start will go berserk over this and put up a dialog strongly advising the user not to run the code (because of the security risks). If you really need a secure environment, then don't run Cytoscape via Web Start.

Resources: These fields point Web Start to the jar files it should load. There are three types of jar files needed in Cytoscape webstart: (1) cytoscape.jar and library jar files, (2) plugin jar files (this includes any of your own plugins that you want to use, and (3) data jar files. All of your data must be packed into one or more jar files. By default, the automated build process packs all data files into a data.jar file.

Remember that, in all cases, a relative path to the resource may be used which is relative to the codebase value specified at the top of the JNLP file.

Application arguments: Cytoscape requires command-line arguments to tell it what to do. The argument fields under the "application-desc" section provide these arguments. The most commonly-used arguments for webstart are -rp for specifying plugins, -g or -i for specifyig network data, and -e for specifying expression data.

Plugins: If you you want to add a plugin to a Cytoscape webstart bundle, there are two modifications you will need to make to your JNLP file.

1. In the resources section, add a jar declaration to include the plugin. For example:

<jar href="plugins/browser.jar"/>

2. In the application-desc section, add a runtime argument to specify the class that extends CytoscapePlugin. For example:

        <argument>-rp</argument>
        <argument>browser.BrowserPlugin</argument>

where browser.BrowserPlugin specifies the class that extends CytoscapePlugin.

Data: If you have a data file to be loaded automatically in your Cytoscape webstart bundle, you will need to specify it in your JNLP file with the jar:// syntax. For instance, if you want to load the network galFiltered.sif automatically, you should:

1. see that galFiltered.sif gets into your data.jar file (described below),

2. make sure your .jnlp file loads your data.jar file

<jar href="data.jar"/>

3. specify the galFiltered.sif with command line arguments, as follows:

<argument>-i</argument>
<argument>jar:://galFiltered.sif</argument>

Note that this works for networks and expression matrix files, but does not currently work for vizmap.props or cytoscape.props files. For other types of files, check for information on the cytoscape-discuss mailing list. For information on how Cytoscape, web start, and properties files, see ["Cytoscape, web start, and properties files"].

Building a webstart bundle

To build your own Cytoscape webstart bundle, you will need to do the following things:

1. Set up a key to sign your JAR files with (described in detail below)

2. Check out the Cytoscape source code from CVS, and go to the build directory (the one that contains the file build.xml).

3. Gather all the data files you will need to be loaded automatically (networks, expression matrix files, etc), and put them in the data subdirectory of the cytoscape build directory.

4. Put all the plugin jars you will need in the plugins subdirectory

5. Issue the command "ant webstart"

6. Copy all files and subdirectories from the build/webstart directory

7. Take the template file cy1.jnlp from the build/webstart directory, add jar declarations for any special plugins you have, modify the command line arguments for any plugins and data files you are using (discussed further below).

8. Put this whole bundle in a place where you can point to it with a URL

9. Modify the href and codebase lines of your JNLP file accordingly.

10. Write a web page with a link that points to your JNLP file.

11. If you did everything correctly, and your browser is properly enabled, you should be able to click on the link and run Cytoscape. Alternatively, you can directly run your Java Web Start executable (usually called javaws) with the JNLP file as an argument. For example, on Linux: javaws cy.jnlp.

Signing your jar files

Because Cytoscape runs with all permissions, you *must* sign all of your jar files, or Web Start will refuse to run the program. In addition, all of the jar files must be signed using the same key, and every jar can only be signed once. This can present problems if you want to take a Cytoscape webstart bundle originally built by someone else and change a few jar files (such as data.jar).

To sign a jar file you use the keytool and jarsigner applications provided with the Java SDK. In ISB's Linux environment, these tools live in /tools/java/sdk/bin. Online documentation for these tools is at [http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/jarsigner.html]

First, you have to generate an encryption key, which will live in a personal keystore. You will need to do this only once. You do this with

keytool -genkey keyName

You will be prompted for a password for this key. In addition, if this is the first key you've ever made, you will be prompted for some personal information and a password for your keystore; by default your encryption keys are stored in the file ".keystore" in your home directory. To make this easiest of yourself, generate a key with the command

keytool -genkey -alias cytoscape -keypass secret

and enter "secret" for the password. If you do this, the Cytoscape build procedure will sign your jars for you automatically. If instead you want to sign your jars manually, you can do so with the jarsigner command.

jarsigner -keystore /home/me/.keystore -storepass keystorePasswd -keypass keyPasswd data.jar keyName

Obviously, replace "/home/me" with the path to your home directory, replace the password arguments with your actual passwords, use the same key name as you did when creating the key, and change the name of the jar file to whatever you want to sign.

Troubleshooting

If it doesn't work the first time, the error messages you get may or may not be helpful. Go through the checklist carefully to make sure you did every step right.

A surprising number of errors are caused by spelling a name wrong, either a control key, the name of a file, or a parameter value. Often such errors don't create a visible error message, but make things unexpectedly not work. For example, if you misspell the name of a data file in data.jar, you will quietly see no data. Triple check all of your spelling.

Here are some other common mistakes:

• If the web start can't even get started, make sure the syntax of your JNLP file is perfect. Any tiny mistake will make it not work.
• Make sure your JNLP file has the right codebase and href fields.
• Make sure your JNLP file references the right jar files.

• If you have added some plugins, make sure you have specified them with the --rp switch, specifying the class that extends CytoscapePlugins. If you specify the wrong class, you will get an undecipherable null pointer error message.

• Make sure you put all the files in the data.jar that were supposed to be there. Use "jar tf data.jar" to see the contents of the jar.
• If you are a glutton for punishment and are not using the automated build procedure, make sure that all jar files (including data.jar) are signed with the same key.

Note that Cytoscape will read the user's personal configuration files, if available. If the user has no personal configuration files available, then Cytoscape will use default configuration data. This may cause the application to behave differently for different users.

Bug report: we've identified an obscure bug associated with JPEG images. It appears that when certain JPEGs are put into a jar that is then signed, an application that attempts to create an image from the archived JPEG file triggers a crash of the Linux Java Virtual Machine. For this reason, we suggest that you don't use JPEG images in your Web Start application. GIFs or PNGs don't appear to have this problem.

Good luck building your Cytoscape Web Start application!