Differences between revisions 4 and 5
← Revision 4 as of 2005-07-26 03:08:18 →
Size: 15339
Editor: GaryBader
Comment:
← Revision 5 as of 2006-01-17 14:39:45 →
Size: 11606
Editor: cumin
Comment:
Deletions are marked like this. Additions are marked like this.
Line 17: Line 17:
The Cytoscape tutorial JNLP file. There is a template Cytoscape JNLP file cy1.jnlp in the cytoscape build directory. Excerpts of this file are shown here:

 
1. The header section
Line 22: Line 25:
  codebase="http://cytoscape.systemsbiology.net"
  href="tutorial/yeast0/cy.jnlp"> 		  codebase="http://chianti.ucsd.edu/kono/"
  href="cy1.jnlp">
Line 25: Line 28:
    <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 36:
}}}

2. The resources section, where any jar files that are part of the application must be listed
{{{
Line 35: Line 42:
    <jar href="bin/cytoscape.jar"/>
    <jar href="tutorial/yeast0/data.jar"/>
  </resources>
  <application-desc>
    <argument>-p</argument>
    <argument>jar://project</argument> 		<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 43: Line 62:
Line 53: Line 73:
'''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 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.
Line 57: Line 77:
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. 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.
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. If you you want to add a plugin to a Cytoscape webstart bundle, there are two modifications you will need to make to the .jnlp file.
Line 61: Line 81:
== The Cytoscape project file ==

The Cytoscape tutorial project file: 		1. In the resources section, add a jar declaration to include the plugin. For example:
Line 66: Line 84:
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 		<jar href="plugins/browser.jar"/>
Line 75: Line 87:
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: 2. In the application-desc section, add a runtime argument to specify the class that extends CytoscapePlugin. For example:
Line 77: Line 89:
||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>-rp</argument>
        <argument>browser.BrowserPlugin</argument>
}}}
Line 90: Line 94:
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. where browser.BrowserPlugin specifies the class that extends CytoscapePlugin.
Line 92: Line 96:
You can use project files with Cytoscape regardless of whether you're using Web Start. The syntax is 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
Line 94: Line 100:
{{{java cytoscape.cytoscape -p projectFile}}} {{{
<jar href="data.jar"/>
}}}
Line 96: Line 104:
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. 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.
}}}

== 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.
Line 100: Line 132:
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 104: Line 136:
First, you have to generate an encryption key, which will live in a personal keystore. You do this with 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
Line 108: Line 140:
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. 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 110: Line 142:
Once you've generated an encryption key (you only need to do this once), you sign a jar with the following 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.
Line 116: Line 150:
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.
Line 163: Line 154:
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 159:
 * 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 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.
Line 171: Line 162:
 * Don't forget to resign the data.jar file every time you rebuild it.  * 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.
Line 173: Line 164:
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.

Note: this page is out of date and will be updated.

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

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

1. The header section 

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

If you you want to add a plugin to a Cytoscape webstart bundle, there are two modifications you will need to make to the .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.

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

== 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!

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