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 and one instance method (starting in version 2.5): getPluginInfoObject, which should be overridden to describe what the plugin does as well as other information about it. 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 method has been added to CytoscapePlugin that all plugins need to implement.

   1 public class MyPlugin extends CytoscapePlugin {
   2 
   3     public MyPlugin() {
   4         RealPlugin plugin = new RealPlugin();
   5     }
   6 
   7     public PluginInfo getPluginInfoObject() {
   8         PluginInfo infoObj = new PluginInfo();
   9         infoObj.setName(“Real Plugin”);
  10         infoObj.setDescription(“Information about the plugin that will be displayed to users”);
  11         infoObj.setPluginVersion(“1.0”);
  12         
  13         /* This method sets the site describing plugins available for install/update
  14          * if not implemented it will default to the cytoscape plugin site.
  15          * This is required for automatic updating of plugins */         
  16         infoObj.setProjectUrl(http://my-project/update-site/plugins.xml);
  17 
  18        /* The above  methods are the only required ones and will be set to default values
  19         * if not set by the plugin developer.  The following methods may be set or not
  20         * as the developer chooses. */
  21 
  22          // compatible Cytoscape version
  23          infoObj.setCytoscapeVersion(“2.5”)
  24          // set to “Unknown” by default
  25          infoObj.setCategory(PluginInfo.Category.ANALYSIS);
  26     
  27          return infoObj;
  28     }
  29 
  30 }
  31 

Versioning Your Plugin

The PluginInfo object 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

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

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