Cytoscape_via_Java_Web_Start

<<TableOfContents: execution failed [Argument "maxdepth" must be an integer value, not "[2]"] (see also the log)>>

Introduction

This page explains how to set up your own Cytoscape application to run via Java Web Start.

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://cytoscape.org/cgi-bin/moin.cgi/Presentations. Just download the file pointed to by the web start link, then look at it.

The JNLP file

There is a template Cytoscape JNLP file cy1.jnlp created in the cytoscape build resources/webstart directory at build time. Excerpts of this file are shown here.

The header section

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

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

  <resources>
    <j2se version="1.5+" 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 may not crash if there are files available in that location 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 webstart 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 two types of jar files needed in Cytoscape webstart: (1) cytoscape.jar and library jar files and (2) plugin jar files (this includes any of your own plugins that you want to use. Note that because libraries may be added or removed between releases a jnlp file from a previous release may not work with a new release of Cytoscape. A new jnlp file may need to be generated.

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 (see Command Line Arguments in the Cytoscape_User_Manual). The argument fields under the "application-desc" section provide these arguments.

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.

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

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

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

        <argument>-p</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 then you'll need to specify the data as URLs in the command line arguments. All files can be loaded using a direct url link, relative paths can not be used in the <argument> tags.

If you want to import the network galFiltered.sif you should:

<argument>-N</argument>
<argument>http://example.com/galFiltered.sif</argument>

To load a vizmap.props file:

<argument>-V</argument>
<argument>http://path-to-resource/vizmap.props</argument>

Other command line arguments for file loading are handled the same way.

Building a Webstart Bundle

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

First set up a key to sign your JAR files with (described in detail below) then choose which option you want to create your webstart:
Then follow one of the options below for creating your webstart bundle.

Build your own

Check out the Cytoscape source code from SVN (see the page on SVN access), and go to the build directory (the one that contains the file build.xml).
Put all the plugin jars you will need in the plugins/core subdirectory
Issue the command "ant -DwebstartURL=http://your-url webstart"
Copy all files and subdirectories from the build/webstart directory to your web server OR just double click on the "index.html" file.

Use installed version

Take the release version currently on your computer, sign all jar files (described below) including cytoscape.jar, all files under the lib/ and plugins/ directory (add your plugins to this directory first)
Take the template file cy1.jnlp from the build/webstart directory if you followed 2a or cy1.jnlp if you used 2b, 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).
Put this whole bundle in a place where you can point to it with a URL
Modify the href and codebase lines of your JNLP file accordingly.
Write a web page with a link that points to your JNLP file.
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 cy1.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. 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 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 (storepass) password. If you do this, (and use steps 2a above) 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-path/.keystore -storepass <from keytool above> -keypass <from keytool above> jar-file-name.jar  <alias, from keytool above>

Obviously, replace "/home-path/" 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.

If you are not using the automated build process above, here is a template jnlp file. You will need to be sure it specifies all of the jar files in the lib directory and the plugins directory: cy1.jnlp

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 in the <arguments> section, specifying the class that extends CytoscapePlugins. If you specify the wrong class, you will get an undecipherable null pointer error message.
If you are using a data.jar file for data files, 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 using the http://path-to-resource/something.sif syntax for data or props files, but sure that url is actually reachable, try it in your browser.
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.
Here is a link to some information that may help with plugin-network connectivity issues: WebstartNetworkConnectivityIssues

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!