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 plugin written against the 3.X API and correctly versioned should work for every version of Cytoscape up until version 4.0.

Which Plugin Type?

Cytoscape 3.0 will have two different types of plugin. The first is a “simplified” plugin that behaves similarly to plugins in Cytoscape 2.X. The simplified plugin model 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 plugin is not actually a plugin but rather a proper OSGi bundle. This type of “plugin” is a bit more complicated to write because it requires an understanding of OSGi and some of the surrounding technologies. However, this additional burden allows you to do things like safely publish APIs and avoid library version conflicts.

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

Simplified Plugin Porting

To compile your plugin, you will need to add a single jar to your classpath: plugin-api-3.0.0-jar-with-dependencies.jar. This jar contains the entire Cytoscape 3.0 public API, which are the only Cytoscape classes and interfaces that you should be using (something we’ve configured OGSi to enforce). You should not need additional references to the separate jars that comprise the API.

Writing a simplified plugin is fairly similar to Cytoscape 2.8: all you need to do is extend the CyPlugin class. The primary difference is that you need to create your constructor that accepts a single argument, a reference to the CyPluginAdapter interface and use that argument to call super(). Your code should look like this:

public class YourPlugin extends CyPlugin {

    public YourPlugin(CyPluginAdapter adapter) {
        super(adapter);

        // the rest of your initialization here
    }

}

The CyPluginAdapter is a simple (but long) interface that provides access to all of the manager and factory singletons that comprise Cytoscape. The CyPluginAdapter is your key into the Cytoscape 3.0 world! The CyPluginAdapter plays a similar role to that of Cytoscape.java in version 2.X, however the difference is that CyPluginAdapter doesn’t maintain state and just provides access to other classes. So, if you want to get the desktop for your gui, use adapter.getCySwingApplication(). If you need to know the current network, use adapter.getApplicationManager(). Each method in CyPluginAdapter provides access to some part of the system.

Once you’ve got your plugin attempting to compile (and presumably failing) and using the correct CyPlugin 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, also look at the Cytoscape 3.0 Debugging Guide.

OGSi Bundle Plugin

This section assumes the use of Maven. 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 actual functional code of an OSGi bundle plugin shouldn’t be any different than the code found in a “simplified” plugin. The part that is different is how the code 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. Cytoscape 3.0 uses Spring Dynamic Modules (Spring-DM) as the dependency injection layer between the Cytoscape code and OSGi. This approach allows us to avoid dependencies on either the OSGi or Spring APIs in our Java code at the cost of configuring each bundle with two Spring XML configuration files. This section will describe how to use Spring-DM to initialize your bundles.

The best way to start a 3.0 OSGi plugin 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-plugin -DgroupId=com.example -DartifactId=yourpluginname -Dversion=1.0-SNAPSHOT

This will create a directory called “yourpluginname” and within it a Maven project versioned at 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). Importantly, this is also where the Spring XML config files live. Specifically, they live in src/main/resources/META-INF/spring.

The two Spring XML config files are called bundle-context.xml and bundle-context-osgi.xml. They are separated into two files to distinguish those parts that are “plain” spring (bundle-context.xml) and those that rely on OSGi specific exensions to Spring (bundle-context-osgi.xml).

bundle-context.xml

The bundle-context.xml is where the object or objects that comprise your plugin are initialized. This file contains a list of “beans” (Spring parlance for instances of objects) to be created. Each bean has and identifier, a class definition, and a list of constructor arguments. Our examples use constructors, but Spring also supports factory methods as well. Here is a brief snippet of a bundle-context.xml file:

<bean id="visualLexiconManager" class="org.cytoscape.view.vizmap.internal.VisualLexiconManager" />
<bean id="visualStyleFactory" class="org.cytoscape.view.vizmap.internal.VisualStyleFactoryImpl">
    <constructor-arg ref="visualLexiconManager" />
</bean>
<bean id="visualMappingManager" class="org.cytoscape.view.vizmap.internal.VisualMappingManagerImpl">
    <constructor-arg ref="cyEventHelperServiceRef" />
    <constructor-arg ref="visualStyleFactory" />
    <constructor-arg ref="visualLexiconManager" />
</bean>

The first bean defined is given the name visualLexiconManager and this results in an object of type org.cytoscape.view.vizmap.internal.VisualLexiconManager. The constructor in this case takes no arguments, so none are listed. The second bean (visualStyleFactory) uses the first bean as an argument to its constructor. The final bean in the list has three constructor arguments, two of which are the previous two beans constructed. The remaining argument is another bean, but one specified in the bundle-context-osgi.xml file. How that bean comes into existence will be explained shortly, but as far as this bundle-context.xml file is concerned, this is a bean just like any other.

In the end, all the bundle-context.xml file does is construct objects. This is where you should construct whatever objects you need

bundle-context-osgi.xml

The bundle-context-osgi.xml contains the OSGi specific extensions to the Spring configuration format. For our purposes, the bundle-context-osgi.xml file defines how our bundle interacts with the OSGi runtime engine, which is to say, how our bundle interacts with the rest of our system.

There are three types of entries in our bundle-context-osgi.xml files. One defines how we consume a single service (i.e. and implementation of an interface) provided by a different bundle, the second defines how we consume all services of a specified type and the last defines how we register our own service for other bundles to use. This snippet of XML contains each element:

<osgi:reference id="cyEventHelperServiceRef" interface="org.cytoscape.event.CyEventHelper">
</osgi:reference>
<osgi:set id="renderingEngineFactorySet" interface="org.cytoscape.view.presentation.RenderingEngineFactory" cardinality="0..N">
    <osgi:listener bind-method="addRenderingEngineFactory" unbind-method="removeRenderingEngineFactory" ref="visualLexiconManager" />
</osgi:set>
<osgi:service id="visualMappingManagerService" ref="visualMappingManager" interface="org.cytoscape.view.vizmap.VisualMappingManager">
    <osgi:service-properties>
        <entry key="title" value="Visual Mapping Manager" />
    </osgi:service-properties>
</osgi:service>

The first element shows how we get a reference to an OSGi service that is provided by a different bundle. This element actually creates a Spring bean that can be used elsewhere in the bundle-context-osgi.xml file or in the bundle-context.xml. The bean is identified with the name cyEventHelperServiceRef and the type of the bean, which is to say the type of the OSGi Service, is identified by the interface. This is how the third constructor argument to the visualMappingManager bean (described in the previous section) was created and this is generally how we reference singleton OSGi services. The result will always be reference to a valid object and if no object is found, Spring will not finish initializing the bundle and eventually throw an exception.

Not all services are singletons. In the case of the TaskFactory interface (where each factory defines a specific type of task), there can be many TaskFactory instances registered as services. The second element in the example above shows how we tell Spring to call a specific method on a bean every time a service of a specific type gets registered, thus creating a set of service objects. The element begins by identifying itself and defining which service interface it is interested in. The cardinality attribute defines the allowable number of services that can be registered. As Cytoscape uses the cardinality attribute, there are really two options 0..N and 1..N. The difference is that the set will initialize without any services being present in the first case, whereas the second demands that at least one instance of the service be registered. Other possibilities can be explored in the Spring documentation. The next element (osgi:listener) in the set defines the bean which will actually contain the service objects. This element has three attributes: a reference to a bean (which you will have created in the bundle-context.xml) and then the methods on that bean to call when either a service is registered (bind-method) or unregistered (unbind-method). The bean above, expects Java code like this:

class VisualLexiconManagerImpl {

    public void addRenderingEngineFactory(RenderingEngineFactory ref, Map props) {

        // Do something with the RenderingEngineFactory object,

        // like store it in a list.

    }

    public void removeRenderingEngineFactory(RenderingEngineFactory ref, Map props) {

        // Clean up whatever you’ve done with the RenderingEngineFactory object.

    }

}

Note that the method names, but not signatures are specified in the XML. This is because in all cases the methods expect exactly two objects: a object of the type of the service and a Map (string -> string) of properties. The properties are metadata associated with the service and are delivered with every OSGi service.

To summarize: the set element simply defines two methods on an object that get called when a service of the specified type gets registered or unregistered with OSGi. The end result is POJO code that gets service instances injected dynamically.

The final type of element type found in the bundle-context-osgi.xml is one that registers a service provided by this bundle for use by others. In the example above, we register a VisualMappingManager service. The service has an identifier, a reference to a bean that will be the service (visualMappingManager) and the interface that the service will be registered as. There is also the option for optionally specifying properties associated with this instance of the service (in this case the title of service: “Visual Mapping Manager”).

To summarize, all objects in the bundle should be initialized in the bundle-context.xml file while all OSGi services used and provided are defined and registered in the bundle-context-osgi.xml. Together these files will construct all objects in your plugin and begin communicating with world.

Writing Your Plugin

Assuming that you’ve got the bundle-context.xml and bundle-context-osgi.xml properly configured, then the actual Java code that needs to be written for your plugin is even simpler than the “simplified” plugin model, because there are no interfaces to implement. All you should do is write normal Java objects where any necessary references to objects provided by other bundles (i.e. services) are passed into the object through the constructor. Just make sure that you construct the right objects in bundle-context.xml and you should be all set.

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. CyNetworkView replaces CyNetworkView.

2. View<CyNode> replaces NodeView.

3. View<CyEdge> replaces EdgeView.

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

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

6. VisualMappingManager is an OSGi service.

7. 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 using CyNetworkTaskFactories and CyNetworkViewTaskFactories.

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.