Differences between revisions 4 and 24 (spanning 20 versions)
← Revision 4 as of 2005-07-26 03:08:18 →
Size: 15339
Editor: GaryBader
Comment:
← Revision 24 as of 2008-12-25 10:20:54 →
Size: 12358
Editor: evogene
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= Note: this page is out of date and will be updated. = [[TableOfContents([2])]]
Line 5: Line 5:
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]. This page explains how to set up your own Cytoscape application to run via Java Web Start.
Line 13: Line 13:
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. 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.
Line 16: Line 16:
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.
Line 17: Line 18:
The Cytoscape tutorial JNLP file.
 		  1. The header section
Line 22: Line 22:
  codebase="http://cytoscape.systemsbiology.net"
  href="tutorial/yeast0/cy.jnlp"> 		  codebase="http://your-url-here/
  href="cy1.jnlp">
Line 25: Line 25:
    <title>Cytoscape Tutorial #1 </title>
    <vendor>ISB, Whitehead Institute</vendor>
    <homepage href="docs/help.html"/> 		    <title>Cytoscape WebStart</title>
    <vendor>Cytoscape Collaboration</vendor>
    <homepage href="index.html"/>
Line 33: Line 33:
}}}

  2. The resources section, where any jar files that are part of the application must be listed
{{{
Line 34: Line 38:
    <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> 		    <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>
        ...
Line 47: Line 63:
'''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. === <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.
Line 49: Line 66:
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. 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.
Line 51: Line 68:
'''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. === 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.
Line 53: Line 71:
'''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. === 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.
Line 57: Line 76:
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 (see ''Command Line Arguments'' in the ["Cytoscape_User_Manual"]). The argument fields under the "application-desc" section provide these arguments.
Line 59: Line 79:
'''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. === 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.
Line 61: Line 82:
== The Cytoscape project file ==   1. In the resources section, add a jar declaration to include the plugin. For example:
{{{
<jar href="plugins/browser.jar"/>
}}}
Line 63: Line 87:
The Cytoscape tutorial project file:   2. 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:
Line 66: Line 100:
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 		<argument>-N</argument>
<argument>http://example.com/galFiltered.sif</argument>
Line 75: Line 104:
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: To load a vizmap.props file:
Line 77: Line 106:
||sif||The location of a graph file in the simple interactions format.||
||gml||The location of a graph file in GML format. The "sif" and "gml" keys should not both be used in the same project file.||
||noa||The location of a node attributes file. This key may be duplicated any number of times to specify multiple files.||
||eda||The location of an edge attributes file. This key may be duplicated any number of times to specify multiple files.||
||expr||The location of an expression data file.||
||dataServer||The location of a server providing synonym and annotation information. Often this is simply a file that lists other files containing this information, but may also be a web-accessible server.||
||species||The default species for objects in the graph, used when accessing the dataServer.||
||layout||The preferred graph layout strategy.||
||props||The location of a properties file giving Cytoscape customization parameters.||
||vprops||The location of a file defining visual styles for Cytoscape's visual mapping system.||
||canonicalizeNames||A boolean flag, recognized values are "true" and "false". If true, then names in the graph or attributes files are converted to canonical names using the dataServer.||
||arg||An arbitrary argument. This key may be duplicated any number of times to specify multiple arguments. These arguments are appended to the command-line arguments in the order they appear. This enables the specification of arguments recognized by Cytoscape plugins.|| 		{{{
<argument>-V</argument>
<argument>http://path-to-resource/vizmap.props</argument>
}}}
Line 90: Line 111:
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. Other command line arguments for file loading are handled the same way.
Line 92: Line 113:
You can use project files with Cytoscape regardless of whether you're using Web Start. The syntax is == Building a Webstart Bundle ==
Line 94: Line 115:
{{{java cytoscape.cytoscape -p projectFile}}} To build your own Cytoscape webstart bundle, you will need to do the following things:
Line 96: Line 117:
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.   1. 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:
  1. Then follow one of the options below for creating your webstart bundle.

=== Build your own ===
  1. Check out the Cytoscape source code from SVN (see the page on [:SVN_Access: SVN access]), and go to the build directory (the one that contains the file ''build.xml'').
  1. Put all the plugin jars you will need in the plugins/core subdirectory
  1. Issue the command "ant -DwebstartURL=http://your-url webstart"
  1. 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 ===
  1. 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)
  1. Take the template file ''cy1.jnlp'' from the ''build/webstart'' directory if you followed 2a or attachment: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).
  1. Put this whole bundle in a place where you can point to it with a URL
  1. Modify the ''href'' and ''codebase'' lines of your JNLP file accordingly.
  1. Write a web page with a link that points to your JNLP file.
  1. 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'''.
Line 100: Line 135:
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. 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).  
Line 102: Line 137:
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] 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]
Line 104: Line 139:
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: 		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
Line 124: Line 142:
  <resources>
    <j2se version="1.4+" max-heap-size="1024M"/>
    <jar href="bin/cytoscape.jar"/>
    <extension name="myData" href="data.jnlp"/>
  </resources> 		keytool -genkey -alias cytoscape -keypass secret
Line 131: Line 145:
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: 		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.
Line 136: Line 148:
  <application-desc>
    <argument>--JLW</argument>
    <argument>http://mySite.org/plugin.jar</argument>
    <argument>--JLL</argument>
    <argument>http://mySite.org/pluginList</argument>
  </application-desc> 		jarsigner -keystore /home-path/.keystore -storepass <from keytool above> -keypass <from keytool above> jar-file-name.jar <alias, from keytool above>
Line 144: Line 151:
== Building the Cytoscape Web Start application == 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.
Line 146: Line 153:
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. 		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: attachment:cy1.jnlp
Line 163: Line 159:
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.
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.
Line 168: Line 165:
 * 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. 		 * 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
 
Line 173: Line 173:
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. 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.
Line 175: Line 175:
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. '''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.

TableOfContents([2])

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.

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

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

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

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

  1. 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:
  2. Then follow one of the options below for creating your webstart bundle.

Build your own

  1. Check out the Cytoscape source code from SVN (see the page on [:SVN_Access: SVN access]), and go to the build directory (the one that contains the file build.xml).

  2. Put all the plugin jars you will need in the plugins/core subdirectory

  3. Issue the command "ant -DwebstartURL=http://your-url webstart"

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

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

  2. Take the template file cy1.jnlp from the build/webstart directory if you followed 2a or attachment: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).

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

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

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

  6. 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: attachment: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!

Cytoscape_via_Java_Web_Start (last edited 2009-02-12 01:03:15 by localhost)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux