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 the tutorial directory at http://cytoscape.systemsbiology.net/tutorial/yeast0/. Just download all of the files in this directory, then look at them. cy.jnlp and project are the key files that reference all of the others.

The JNLP file

The Cytoscape tutorial JNLP file.

<?xml version="1.0" encoding="utf-8"?>
<jnlp
  codebase="http://cytoscape.systemsbiology.net"
  href="tutorial/yeast0/cy.jnlp">
  <information>
    <title>Cytoscape Tutorial #1 </title>
    <vendor>ISB, Whitehead Institute</vendor>
    <homepage href="docs/help.html"/>
    <offline-allowed/>
  </information>
  <security>
      <all-permissions/>
  </security>
  <resources>
    <j2se version="1.4+" max-heap-size="1024M"/>
    <jar href="bin/cytoscape.jar"/>
    <jar href="tutorial/yeast0/data.jar"/>
  </resources>
  <application-desc>
    <argument>-p</argument>
    <argument>jar://project</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 files it should load. All of your data must be packed into one or more jar files. We usually pack Cytoscape and all its auxilliary libraries into a cytoscape.jar file and pack all the data files into a data.jar file. However, you can specify as many jar files as you like. For example, plugins can be included as separate jars.

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.

Note that the cytoscape.jar must include all of the auxillary libraries that Cytoscape needs. That is, you need the release version of Cytoscape, not just a jar containing the Cytoscape core classes. For those with access to the Cytoscape source distribution, 'ant jar' creates lib/cytoscape.jar that only contains the core classes, while 'ant release' creates release/cytoscape.jar that bundles all the libraries as well.

Application arguments: Cytoscape requires command-line arguments to tell it what to do. The argument fields under the "application-desc" section provide these arguments. We usually make a project file that tells Cytoscape what to do. In this case only two arguments are required: the first is "-p" (to specify a project file) and the second is the name of the project file.

The Cytoscape project file

The Cytoscape tutorial project file:

sif=jar://network.sif
props=jar://props
species=Saccharomyces cerevisiae
dataServer=jar://annotationList
noa=jar://gal4rgExpression.noa
noa=jar://sgd.noa
noa=jar://perturbation.noa

The project file tells Cytoscape what files to load at startup and where to find them. The format is very simple: each line is of the form "key=value", where the key is a tag known to Cytoscape and the value is the value for that key, often the location of a data file. Here is a complete specification of all the recognized keys:

Note that three of the keys (noa, eda, and arg) support multiple instances that are concatenated. For any other key, the last entry in the file overrides any previous duplicate entries. Also, note that any file specified by the "props" or "vprops" keys is in addition to the cytoscape.props and vizmap.props files in the users's home directory, which are always read.

You can use project files with Cytoscape regardless of whether you're using Web Start. The syntax is

java cytoscape.cytoscape -p projectFile

Note that, for Java Web Start applications, all of the files referenced by the project file should begin with the string "jar://" to tell Cytoscape that the files live in one of the supplied jar files instead of on the local disk. If you include this string, Java and Cytoscape will figure out how to find the file you're talking about.

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. In other words, if someone else builds a Cytoscape Web Start, and you want to create one with your own data, you must get your own fresh unsigned copy of cytoscape.jar and sign it yourself along with your data.jar (or get them to sign your data.jar for you with the same key they used before). If this sounds bad, there are a couple of alternatives that might work for you: see below.

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 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.

Once you've generated an encryption key (you only need to do this once), you sign a jar with the following 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.

The cytoscape.jar file you get from downloading the public distribution is not signed, so you can copy this jar and sign it yourself along with your data jar file.

Alternatives to signing every jar

Since signing all of your jar files with the same key can be annoying, here are a couple of alternatives that might work for you. Apparently you can use the extension mechanism in Java Web Start to reference other JNLP files. These different files can include jars signed with different keys, since they live in separate JNLP files. The code in the primary JNLP file would look like this:

  <resources>
    <j2se version="1.4+" max-heap-size="1024M"/>
    <jar href="bin/cytoscape.jar"/>
    <extension name="myData" href="data.jnlp"/>
  </resources>

The file data.jnlp would then have the same form as the primary JNLP file, but would only reference the data.jar file. This would allow you to sign the jars with different keys. We've never actually tried this, so we can't guarantee that it will work.

If you want to include jar files that contain plugins that should be loaded by Cytoscape, an alternative is to use either the --JLW or --JLL arguments to Cytoscape. The --JLW argument is followed by another argument which is the URL of the jar file to load. The --JLL is also followed by a URL argument, which should be a file containing a list of URLs that point to the plugin jars you want to load. If you use either of these two options, then you don't need to sign the plugin jars since Cytoscape's plugin loading system is not covered by the JNLP security manager. You would add these arguments to the application-desc section of the JNLP file, using the same format as the other arguments. For example:

  <application-desc>
    <argument>--JLW</argument>
    <argument>http://mySite.org/plugin.jar</argument>
    <argument>--JLL</argument>
    <argument>http://mySite.org/pluginList</argument>
  </application-desc>

Building the Cytoscape Web Start application

To build your Cytoscape Web Start, follow these steps:

1. Gather all of your data files into one directory, including a cytoscape.props file and vizmap.props file as appropriate.
2. Write a project file that references all of your files. Remember to preference each file with "jar://".
3. Bundle all of your data files, including the project file, into a jar. We usually call this "data.jar".
4. Get a cytoscape.jar file that includes all the auxilliary libraries it needs. The public distribution has already done this for you.
5. Sign your cytoscape.jar and data.jar files.
6. Build your JNLP file. Easiest is to copy an existing file. Remember to change the codebase and href fields to point to the correct location of this application. Also make sure all your jar files are referenced by the JNLP file, and that the project argument is the correct name of your project file prefaced with "jar://".
7. Write a web page with a link that points to your JNLP file.
8. 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.

If you're a fan of make, you can build a makefile that will do many of these steps automatically. Of course, then you have to make sure you write the makefile properly, spell all the file names properly, and update the makefile every time you change what you want to do.

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 special key "species" in your project file or misspell "Saccharomyces cerevisiae", you will quietly get no annotation information available. 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 and the correct name of your project file preferenced with "jar://".
• Make sure your project file has all the keys and all the values spelled properly. Remember that all the files should be preferenced with "jar://".
• 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.
• Don't forget to resign the data.jar file every time you rebuild it.

Note that Cytoscape will read the user's personal configuration files in addition to the configuration files bundled in the Web Start. The bundled configuration settings override identical values in the user's configuration, but any settings that aren't defined by the Web Start will have user-defined values. 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!