Cytoscape_3/AppDeveloper/PluginPortingGuide

Purpose

This document is a guide to porting plugins written against the 2.X API to the new 3.0 API. A key motivation for writing the 3.0 API is to avoid the constant change that the 2.X API currently sees. Because nearly all classes in Cytoscape 2.X are effectively part of the public API it has become extremely difficult to change one part of the code without suffering unintended consequences in other parts of the code. As a result, plugins written against earlier versions of the API (e.g. 2.5) will often stop working in more recent versions (e.g. 2.7). We recognize that this is extremely frustrating for both plugin authors and users. To address this problem, we’ve written Cytoscape 3.0 with the goal of providing clear backwards compatibility guidelines and guarantees for core developers and plugin developers alike. The full explanation of how and why we anticipate that this will work can be seen here in the Cytoscape 3.0 Backwards Compatibility Guide, but the summary is that any app written against the 3.X API should work for every version of Cytoscape up until version 4.0.

Starting with Cytoscape 3, plugins will be referred to as apps, as app is a more ubiquitous term amongst novice users. From the programmer's point of view, there is no difference between app and plugin.

Getting Started

This section assumes the use of the Apache Maven build system. Nothing we’re doing here can’t be done with Ant or some other build tool, we just aren’t doing it that way and thus have less experience and can’t teach it as well.

The best way to start a Cytoscape 3 app is to use one of the Maven archetypes that we’ve created. There are several available examples to help you get started. Since providing a TaskFactory service is a very common use case for plugins, that is the example we’ll use here. To generate a project run this command:

mvn archetype:generate \
  -DarchetypeRepository=http://code.cytoscape.org/nexus/content/repositories/snapshots/ \
  -DarchetypeGroupId=org.cytoscape \
  -DarchetypeArtifactId=task-app \
  -DgroupId=com.example \
  -DartifactId=YourAppName \
  -Dversion=1.0-SNAPSHOT

This will create a directory called "YourAppName" and within it a Maven project with version 1.0-SNAPSHOT and with a package structure beginning with com.example.

From this project, you will notice several import files. Here is a brief explanation of each.

1. pom.xml - This file tells Maven what to do and defines how your bundle is to be built. This is where you put list dependencies on the Cytoscape 3.0 API, among other things. This file is also used to define which packages OSGi considers public (and thus visible to other bundles) and which it considers private (invisible to other bundles). Unless you are explicitly providing a public API (and this doesn’t mean implementing a public service interface like TaskFactory, rather we’re talking about defining your own interfaces that you expect others to use and/or implement) then all of the packages defined in your bundle should start as private.

2. src/main/java - This is where your Java source code goes.

3. src/test/java - This is where your Java unit test source code goes.

4. src/main/resources - This is where “resource” files you want included in your jar go (e.g. images used in your UI).

Writing Your App

Whether you’re porting an existing plugin or writing one from scratch, the next step will be to understand the Cytoscape 3.0 API. You can read about that here: Cytoscape 3.0 API Overview. To understand how the 2.X API calls map to 3.0, see the section Mapping Old APIs to New APIs below. Once you’ve written your code, also look at the Cytoscape 3.0 Debugging Guide.

Mapping 2.X APIs to 3.0 APIs

Networks, Nodes, Edges

1. Most methods in the old CyNetwork should have corresponding methods in the new CyNetwork.

2. The new CyNetwork is found in the org.cytoscape.model package.

3. The getIdentifier() methods are gone. While there is a getSUID() method, this is not necessarily a replacement. The getIdentifier() was frequently used for accessing attributes, which you now do through the getRow() method.

4. Likewise, the concept of a rootGraphIndex is also gone. Again, while there is a getIndex() method, this is not necessarily a replacement. In general, you should probably be using CyNode or CyEdge references instead of integers. You should only resort to getIndex() if you really need to keep an array of nodes and need an index into it.

5. Node names, selected state, and other methods that used to exist are now columns in the default CyTable.

Attributes

1. CyAttributes has been replaced by the concept of CyTable.

2. Instead of just one, global CyAttributes object, each network has its own CyTables: for the network, for the nodes, and for the edges.

3. Whereas you used to get an "attribute" using the attribute name, now you get a CyRow in the CyTable with a column name. Column name is effectively the same as attribute name.

4. To access a row you can call CyNetwork.getRow(network|node|edge) to get a CyRow object and then call the get(columnName,classType) method.

5. The get method includes a Class argument to simplify the interface.

6. To get the "attribute" named attributeName of a node:

7. Old: CyAttributes.getNodeAttibutes().getStringAttribute(node.getIdentifier(), attributeName);

8. New: network.getRow(node).get(attributeName,String.class));

Views

1. View<CyNode> replaces NodeView.

2. View<CyEdge> replaces EdgeView.

3. Instead of networkView.getNetwork() or getGraphPerspective(), use networkView.getModel().

4. A view no longer contains its VisualStyle. The VisualMappingManager keeps track of this instead.

5. VisualMappingManager is an OSGi service.

6. More here?

Tasks

1. The Task framework has been completely overhauled.

2. TaskManagers execute a sequence of Tasks which are provided by a TaskIterator.

3. TaskFactory instances can create TaskIterators which contain a predefined set of Tasks.

4. TaskMonitors have been be simplified. Whenever you encounter an exception, just rethrow it (or don’t catch it at all). Otherwise only the status and progress method names have been updated.

Misc

1. CytoscapeInit is gone. If you need to get a properties object, then pass the service CyProperty<Properties> into your constructor.

2. Cytoscape.java is gone. Most methods have been moved into singleton services elsewhere.

3. Cytoscape.getCurrentNetwork() and Cytoscape.getCurrentNetworkView() are now part of the CyApplicationManager interface, however their use is discouraged in favor of implementing NetworkTaskFactory and NetworkViewTaskFactory services (found in the core-task-api bundle).

Issues

List any issues, conflict, or dependencies raised by this proposal

Comments

• Add comment here…

How to Comment

Edit the page and add your comments under the provided header. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Be sure to include today's date and your name for each comment. Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the documentation makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.