Diff for "Cytoscape_Plugin_Tutorial"

TableOfContents([2])

Cytoscape Plugin Development Tutorial

Cytoscape allows programmers to write plugins that access the core data structures and windows of Cytoscape to do a wide variety of operations. This tutorial explains how to write a plugin and how to get Cytoscape to load and use your plugin.

It is assumed that the reader is familiar with the basics of the Java programming language and has some kind of programming environment available. See the [http://java.sun.com/docs/books/tutorial/index.html Java Tutorial] for an excellent introduction and handy reference guide for Java. You will also want to check out the [http://www.cbio.mskcc.org/cytoscape/javadoc/ Cytoscape core API documentation].

Each plugin tutorial includes the Java source code and a jar file containing the compiled classes. To run Cytoscape via Java WebStart with all of these plugins automatically loaded, click here: [http://cytoscape.org/pluginTutorial/webStart/cy.jnlp WEB START]. To create your own webstart please read through this tutorial first [“Cytoscape via Java Web Start"].

["Plugin license policy"]

The CytoscapePlugin class

The CytoscapePlugin class is very simple. It defines a default constructor A static method also exists that is used by Cytoscape to load plugins. Since the constructor takes no arguments, it is not necessary to explicitly call a parent constructor from your plugin's constructor. The only requirement is that your plugin must have a default (no arguments) constructor, as Cytoscape will call this constructor to instantiate your plugin.

Java only allows a class to inherit from one parent. Since every plugin must extend CytoscapePlugin, this seems to be a severe limitation. The way around this is to define your Cytoscape plugin class as a simple wrapper around your real code. For example:

   1 public class PluginWrapper extends CytoscapePlugin {
   2 
   3     public PluginWrapper() {
   4         RealPlugin plugin = new RealPlugin();
   5     }
   6 
   7 }
   8 

This scheme can also be used to link to more complicated services, like a web server, or to connect to code written in other languages via the JNI mechanism (see the JNI section of the Java tutorial).

Cytoscape Plugin Management

Starting in Cytoscape version 2.5 plugin management has been added to allow users to search for, download, install, update and delete plugins from within Cytoscape. In order for plugins to be integrated into this management scheme a properties file called "plugin.props" must be added to the plugin jar file in the same path location as your class that extends CytoscapePlugin (ie. If your plugin is in the following package 'my.package.MyPlugin' your plugin.props file must be in the jar file under 'my/package'). The following information is in the plugin.props file (this can be copy/pasted into your own plugin.props file and changed appropriately):

#plugin.props

# This props file should be filled out and included in the plugin jar file.  This props file will be used
# to put information into the Plugin Manager about the plugin

# -- The following properties are REQUIRED -- #

# The plugin name that will be displayed to users, white space within name is not allowed
pluginName=MyPlugin

# Description used to give users information about the plugin such as what it does.
# Html tags are encouraged for formatting purposes.
pluginDescription=Information about the plugin that will be displayed to users.<br>Please use html tags for all formatting and do not add newlines.<p>

# Plugin version number, this must be two numbers separated by a decimlal.  Ex. 0.2, 14.03
pluginVersion=1.0

# Compatible Cytoscape version. If there are more than one version, seperate by ",".
cytoscapeVersion=2.5

# Category, use one of the categories listed on the http://cytoscape.org/plugins2.php site
pluginCategory=Scripting/Communication

# -- The following properties are OPTIONAL -- #

# URL to a website that gives more information about your plugin, Ex. http://my-lab-site.org
projectURL=http://my-lab-site.org/myCytoscapePlugin

# List of authors.  Note each author and institution pair are separated by a : (colon)
# each additional author institution pair must be separated from other pairs bye a ; (semicolon)
pluginAuthorsInstitutions=Sarah and Victor:ISB;Mike, Kei and Peng:UCSD

# Date this plugin/plugin version was released
releaseDate=May 1, 2008

Versioning Your Plugin

The Plugin Manager expects your plugin version to be two numbers separated by a decimal (ex. 1.5 or 4.30). Please note that when comparing for newer versions 1.10 is a newer version than 1.1 or 1.9. Any version that does not match this scheme will cause the manager to error and ignore that plugin.

Creating the Jar File

Plugin jar file should not have white space in the name. Cytoscape encourages all plugins to add an attribute to the jar manifest file called “Cytoscape-Plugin” to make loading the plugin faster and easier. This attribute is required in order for automatic installation to work. If you are using an ant build file to create your plugin jar file, add the manfiest tag to your jar step with the attribute name “Cytoscape-Plugin” and the value set to the full class name of the file which extends CytoscapePlugin. Example:

<target name="jar" description="Create MyPlugin jar file" depends="compile">
    <copy file="${basedir}/plugin.props" todir="{$classes.dir}/my/package" />
    <jar destfile="${build.dir}/MyPlugin.jar">
         <manifest>
         <attribute name="Cytoscape-Plugin"
                    value="my.package.MyPlugin" />
         </manifest>

         <fileset dir="${classes.dir}" />
    </jar>
</target>

If you are creating your jar file via the command line, first create a text file with the Cytoscape-Plugin attribute:

myManifest.txt

Cytoscape-Plugin: my.package.MyPlugin

Then run the jar command with the ‘m’ flag and the manifest file name to add the attributes to the manifest file (it is important that the ‘f’ flag is before the ‘m’ flag).

jar -cfm MyPlugin.jar myManifest.txt <input files>

Sharing Your Plugin

There are two ways to share your plugin with the Cytoscape community. First is to submit your plugin(s) to http://cytoscape.org The other is to set up your own site to offer your plugin(s) from. Please read the ["Plugin Download Site Tutorial"] to learn how to set up your own site.

Example Plugins (these do not yet include the plugin.props file)

["Hello World Plugin"]

["Neighbor Node Selection Cytoscape Plugin"]

["Multi-Network Node Selection Cytoscape Plugin"]

Important Plugin Design Note

Cytoscape is designed to allow plugins to communicate with each other only through Cytoscape core data structures. It is recommended (but not required) that all plugins be independent of each other except for data sharing through the Cytoscape API. One reason for this is that it is impossible to guarantee that any specific plugin will be loaded, so dependencies among plugins should not exist.