Diff for "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 and correctly versioned 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.

Which App Type?

Cytoscape 3 uses OSGi, a sophisticated module system for Java. Anticipating the challenge of learning OSGi, there are two ways to write apps for Cytoscape 3: an app that is easier to write, because it doesn't require learning OSGi, and an app that uses OSGi with all the benefits of a sophisticated module system.

The first kind of app is simplified in that it is constructed similarly to plugins in Cytoscape 2.X. This simplified app assumes no knowledge beyond basic Java and the Cytoscape 3.0 API and was designed to help developers port their existing 2.X plugin as quickly and painlessly as possible in 3.0.

The second type of app is a proper OSGi bundle. This type of app is more complicated to write because it requires learning about OSGi and its related technologies. However with OSGi, the developer can write modules used by other bundles through a public API and avoid library version conflicts.

Deciding which app style to use should be your first decision.

Simplified App Porting

To compile your app, you will need to add a single jar to your classpath: app-api-3.0.0-jar-with-dependencies.jar. This jar alone is sufficient for writing apps, as it contains the entire Cytoscape 3.0 public API that has the Cytoscape classes and interfaces you need.

Writing a simplified app is fairly similar to Cytoscape 2.8: all you need to do is extend the CyApp class. The primary difference is that you need to create your constructor that accepts a single argument, a reference to the CyAppAdapter interface that must be passed to CyApp's constructor. Your code should look like this:

public class YourApp extends CyApp {

    public YourApp(CyAppAdapter adapter) {
        super(adapter);

        // the rest of your initialization here
    }

}

The CyAppAdapter is a simple (but long) interface that has all of the manager and factory singletons that comprise Cytoscape. The CyAppAdapter is your key into the Cytoscape 3.0 world! The CyAppAdapter plays a similar role to that of cytoscape.Cytoscape class in version 2.X. However CyAppAdapter doesn’t maintain state and is merely a gateway to classes that let you work with various aspects of Cytoscape. For example, if you want to get the desktop for your gui, use adapter.getCySwingApplication(). Or if you need to know the current network, use adapter.getApplicationManager().

Once you’ve got your app using the correct CyApp constructor, you’ll need to change all of your 2.X API calls to their 3.0 equivalents. To get a basic understanding of what the 3.0 API provides and how it works, please read the 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, take a look at the Cytoscape 3.0 Debugging Guide.

OGSi Bundle App

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 code of an OSGi bundle app that interacts with various aspects of Cytoscape isn't any different than the code found in a “simplified” app. The part that is different is how the app is initialized. Since this is an OSGi bundle there are actually several valid ways of doing this, some of which include using the raw OSGi APIs or dependency injection layers like iPojo, Blueprint, Declarative Services, and Guice+Peaberry to hide the OSGi details.

The best way to start a 3.0 OSGi 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://cytoscape.wodaklab.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 Cytpscape 3.0 API, among other things.

2. osgi.bnd - This file is 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.

3. src/main/java - This is where your Java source code goes.
4. src/test/java - This is where your Java unit test source code goes.
5. 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 getCyRow() 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. CyAttrbibutes has been replaces 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 getCyRow() 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: node.getCyRow().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. Every Task is now coupled with a TaskFactory that creates instances of that Task.

3. TaskMontiors 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 get the service CyProperty<Properties> injected 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.