## page was renamed from Cytoscape_3/PluginDeveloper/PluginPortingGuide ## page was renamed from RFC Template ||'''Cytoscape 3 Documentation''' : Cytoscape 3 Plugin Porting Guide ||'''Editor(s)''': MikeSmoot, JasonMontojo ||'''Date''': March 22, 2012 ||'''Status''': Second Version || <> == 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. 1. {{{src/main/java}}} - This is where your Java source code goes. 1. {{{src/test/java}}} - This is where your Java unit test source code goes. 1. {{{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}}}. 1. The new {{{CyNetwork}}} is found in the {{{org.cytoscape.model package}}}. 1. 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. 1. 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. 1. 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}}}. 1. Instead of just one, global {{{CyAttributes}}} object, each network has its own {{{CyTable}}}s: for the network, for the nodes, and for the edges. 1. 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. 1. 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. 1. The get method includes a {{{Class}}} argument to simplify the interface. 1. To get the "attribute" named attributeName of a node: 1. Old: {{{CyAttributes.getNodeAttibutes().getStringAttribute(node.getIdentifier(), attributeName);}}} 1. New: {{{network.getRow(node).get(attributeName,String.class));}}} === Views === 1. {{{View}}} replaces {{{NodeView}}}. 1. {{{View}}} replaces {{{EdgeView}}}. 1. Instead of {{{networkView.getNetwork()}}} or {{{getGraphPerspective()}}}, use {{{networkView.getModel()}}}. 1. A view no longer contains its {{{VisualStyle}}}. The {{{VisualMappingManager}}} keeps track of this instead. 1. {{{VisualMappingManager}}} is an OSGi service. 1. More here? === Tasks === 1. The Task framework has been completely overhauled. 1. {{{TaskManager}}}s execute a sequence of {{{Task}}}s which are provided by a {{{TaskIterator}}}. 1. {{{TaskFactory}}} instances can create {{{TaskIterator}}}s which contain a predefined set of {{{Task}}}s. 1. {{{TaskMonitor}}}s 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}}} into your constructor. 1. {{{Cytoscape.java}}} is gone. Most methods have been moved into singleton services elsewhere. 1. {{{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 ==== ##If you want to create a separate subpage for Comments, then provide this link: ["/Comment"] * ''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.'''