This document represents the API specification for Cytoscape 3.0 using a Java Swing front-end.

Cytoscape Apps

Cytoscape 3 is build on the OSGi framework. In keeping with the underlying framework, extending Cytoscape involves adding an OSGi "bundle" that registers some set of services. For Cytoscape, we have made the process of creating and deploying extensions a little easier. Cytoscape defines two different types of extensions (called Apps in Cytoscape terminology): a "Simple App" and an OSGi Bundle App. The are only a couple of major differences between a "Simple App" and a "Bundle App". First, all "Simple Apps" are loaded using the same class loader. This means that it will be much more difficult for "Simple App" that use the same external library (not provided by the Cytoscape core) to co-exist. And second, "Simple Apps" and "Bundle Apps" access services in the Cytoscape core slightly differently.

Simple App

Simple Apps are deprecated as of Cytoscape 3.7.
Support for simple apps will be removed in a future version of Cytoscape, please provide an OSGi bundle app instead.

A Cytoscape "Simple App" will generally be an extension of AbstractCySwingApp if you intend to use the swing version of Cytoscape, or AbstractCyApp if you don't need any swing functions. Apps that inherit from AbstractCyApp can access most of the Cytoscape core functionality through the protected field AbstractCyApp.adapter. This field provides methods to access to most of the manager and factory classes in Cytoscape (see CyAppAdapter. Apps that inherit from AbstractCySwingApp can access the same classes using the AbstractCySwingApp.swingAdapter, which also provides access to some swing-specific classes (CySwingApplication, DialogTaskManager, and PanelTaskManager). In either case, the implementation must call super in it's constructor to make these methods available:

public class MyApp extends AbstractCyApp {
    public MyApp(CyAppAdapter adapter) {
       super(adapter);
       // app code here
    }
}

Bundle App

A "Bundle App" is a little different in that none of the services are provided -- the app is responsible for requesting specific services from the OSGi framework. All "Bundle Apps" should have a CyActivator class that extends AbstractCyActivator. Implementations are required to provide the "start" method, which takes an OSGi BundleContext as an argument. In the sample below, the start method gets a service and registers two services that it provides:

public class CyActivator extends AbstractCyActivator {
  public CyActivator() {
    super();
  }

  public void start(BundleContext bc) {
    CySwingApplication cytoscapeDesktopService = getService(bc,CySwingApplication.class);

    MyCytoPanel myCytoPanel = new MyCytoPanel();
    Sample02 sample02Action = new Sample02(cytoscapeDesktopService,myCytoPanel);

    registerService(bc,myCytoPanel,CytoPanelComponent.class, new Properties());
    registerService(bc,sample02Action,CyAction.class, new Properties());
  }
}

Both approaches will provide access to all Cytoscape core services, however, when publishing a service (e.g. a listener) in the "Simple App" you will need to call the CyAppAdapter.getCyServiceRegistrar() anyways in order to call the requisite CyServiceRegistrar.registerService(java.lang.Object, java.lang.Class<?>, java.util.Properties) method.

Accessing Cytoscape services

As briefly described above, accessing Cytoscape tasks and factories depends largely on the approach ("Simple App" vs. "Bundle App") that you are taking. In the case of a "Simple App", you will probabily just call the appropriate CyAppAdapter method. In the case of a "Bundle App", it's a simple matter of calling AbstractCyActivator.getService(BundleContext bc, java.lang.Class) with the bundle context that was provided as an argument to the start method, and the class of the service you want to use. For example, to create a new CyNetwork, you could:

public class CyActivator extends AbstractCyActivator {
  public CyActivator() {
    super();
  }

  public void start(BundleContext bc) {
    CyNetworkFactory factory = getService(bc, CyNetworkFactor.class);
    // call CyNetworkFactory's createNetwork method, as appropriate
  }
}

Providing services to Cytoscape (and other Apps) is also relatively straightforward:

MyService service = new MyService();
registerService(bc, service, MyService.class, new Properties());

Now, any app wanting to use "MyService" can do so by doing a "getService". The Properties object can be passed to the service listener (if there is one for this class). (For examples on how this can be used in Cytoscape, see Adding a new context menu item below).

Getting started using the API

The Cytoscape 3 core provides significant functionality to the App developer. Currently, the Cytoscape core API has 58 packages: some of which have relatively few interfaces and class (e.g. org.cytoscape.service.util) and some of which have significantly more (e.g. org.cytoscape.model). The best way to get starting using the Cytoscape API is to make sure you have a thorough understanding of the core Cytoscape model: org.cytoscape.model. This package provides all of the basic network and table concepts used throughout Cytoscape.

The next package to understand is Cytoscape's view-model: org.cytoscape.view.model. The view-model provides view-level mechanisms for the underlying model, including the way to set various visual properties (see View.setVisualProperty(org.cytoscape.view.model.VisualProperty<? extends T>, V)). After developing an understanding of the model and view-model, you should peruse the hints given below and then let the needs of your App drive your exploration of the rest of the API.

Hints

Writing a listener

Listeners in Cytoscape 3 are a little different from "traditional" Java listeners in that listeners are not "added" to an object: e.g. there is no equivilent to Java Swing's "addPropertyChangeListener" method. Instead, in Cytoscape 3, you implement the listener and register it as a service. So, in the example below, the App (a Bundle App in this case) creates and registers a listener to NetworkAddedEvents:

public class CyActivator extends AbstractCyActivator {
  public CyActivator() {
    super();
  }

  public void start(BundleContext bc) {
    MyNetworkAddedListener listener = new MyNetworkAddedListener();
    registerService(bc, listener, NetworkAddedListener.class, new Properties());
  }
}

And the code for the actual listener:

public class MyNetworkAddedListener implements NetworkAddedListener {
  public MyNetworkAddedListener(/* Whatever context your app needs */) {
  }

  public void handleEvent(NetworkAddedEvent e) {
    CyNetwork addedNetwork = e.getNetwork();
    // Respond as appropriate
  }
}

Note that you must provide the type of the class or interface you want to register (NetworkAddedListener, in this case).

Using Tasks and Task Factories

In Cytoscape 3, the basic unit of work is a Task. (Due to some unfortunate early mistakes in naming, Task is part of org.cytoscape.work package. The org.cytoscape.task package provides a list of core task types and some useful core tasks.) There three important interfaces that you should be familiar with if you are going to implement your own Task: Task, TaskIterator, and TaskFactory. In order to make your Task available to Cytoscape, you will need to provide a TaskFactory. The TaskFactory provides two important methods. The most critical is TaskFactory.createTaskIterator(), which is called by Cytoscape to get a TaskIterator, which should include at least your Task. As the name implies, though, a TaskIterator can include a number of tasks, which will be executed sequentially. The other method, TaskFactory.isReady() is called to determine if your Task can be executed. For example, if your Task requires the currently selected nodes as input, and nothing is selected, this method should return false.

The Task itself has two methods: Task.run(org.cytoscape.work.TaskMonitor), which is used to execute the task asynchronously in a separate thread, and Task.cancel(), which is used to signal the Task that it should cancel its activity and return. The Task.run(org.cytoscape.work.TaskMonitor) method has one argument: a TaskMonitor, which is used to provide feedback to the user during the operation of the task.

Cytoscape provides a large number of existing Task, and TaskFactory interface extensions as well as many abstract base classes. You should take care, however, about which base class you use and how you register the task factory since generally, the Cytoscape core is listening for the registration of certain types of TaskFactories to add them to appropriate menus.

Something about Tunables? TunableSetter? Properties?

Adding a new menu item

One common use for a TaskFactory is to add a menu item to one of Cytoscape's standard menus. For example assume we want to add a new item to the Cytoscape App menu. We would add to our CyActivator:

NetworkTaskFactory myTaskFactory = new MyTaskFactory();
Properties myNetworkTaskFactoryProps = new Properties();  
myNetworkTaskFactoryProps.setProperty(ENABLE_FOR, "network");
myNetworkTaskFactoryProps.setProperty(PREFERRED_MENU,"App.MyApp.");
myNetworkTaskFactoryProps.setProperty(MENU_GRAVITY,"1.0");
myNetworkTaskFactoryProps.setProperty(TITLE,"My Application Task");
registerService(bc,myTaskFactory,NetworkTaskFactory.class, myNetworkTaskFactoryProps);

This will put a new menu item under App: "App→MyApp→My Application Task". A couple of things to note. First, the properties are all defined as static strings in ServiceProperties, and you should always use the symbolic name. Second, note the "MENU_GRAVITY" property key. Cytoscape's menus arrange the order of items in the menu using this "MENU_GRAVITY" property. Generally speaking, larger is further down the menu menu.

Adding a new context menu item

Adding a node or edge context menu is essentially the same as adding a menu item shown above:

NodeViewTaskFactory myTaskFactory = new MyTaskFactory();
Properties myNodeViewTaskFactoryProps = new Properties();  
myNodeViewTaskFactoryProps.setProperty(ENABLE_FOR, "selectedNodesOrEdges");
myNodeViewTaskFactoryProps.setProperty(PREFERRED_MENU,"App.MyApp.");
myNodeViewTaskFactoryProps.setProperty(MENU_GRAVITY,"1.0");
myNodeViewTaskFactoryProps.setProperty(IN_TOOL_BAR,"false");
myNodeViewTaskFactoryProps.setProperty(TITLE,"My Application Task");
registerService(bc,myTaskFactory,NodeViewTaskFactory.class, myNodeViewTaskFactoryProps);

As with the menu item above, the Cytoscape core will "notice" that this TaskFactory has been registered and what it's type is. When the user does a right-click over a node, all TaskFactories of that NodeViewTaskFactory type will be called.

Packages

Package	Description
org.cytoscape.app	This is the Cytoscape App API, which supports development of Cytoscape 3.X apps in a manner similar to apps developed in Cytoscape 2.X.
org.cytoscape.app.event
org.cytoscape.app.swing	This is the Cytoscape Swing App API, which supports development of Cytoscape 3.X apps in a manner similar to apps developed in Cytoscape 2.X and provides full access to the Swing specific services of the Cytoscape API in addition to all other services provided in Cytoscape App API.
org.cytoscape.application	This package provides Cytoscape version number, application-wide setting, basic access to current network, selected networks, views and rendering engines.
org.cytoscape.application.events	This package provides application events/listeners, including Cytoscape startup/shutdown, setCurrentNetwork/setCurrentNetworkView/ setSelectedNetwork.
org.cytoscape.application.swing	This package defines the various interfaces, abstract classes, and enums that represent the Cytoscape Swing Application API.
org.cytoscape.application.swing.events	This package defines the various events fired by the Cytoscape Swing Application API.
org.cytoscape.application.swing.search
org.cytoscape.command	Interface to support execution of tasks as commands, including the ability to get a list of namespaces, commands, and arguments, and then execute those commands with a set of arguments.
org.cytoscape.command.util	Tunable classes useful for command applications
org.cytoscape.equations	Various types and utility methods relating to attribute equations.
org.cytoscape.equations.event
org.cytoscape.event	This package contains the basic interfaces necessary for defining, firing, and listening for Cytoscape events.
org.cytoscape.filter	Provides interfaces for constructing and executing Transformers and Filters.
org.cytoscape.filter.model	Provides interfaces and classes for defining Transformers and Filters.
org.cytoscape.filter.predicates	General purpose predicates used to perform comparisons against numbers and strings.
org.cytoscape.filter.transformers	Provides interfaces for working with the Transformers provided by the core.
org.cytoscape.filter.view	Provides interfaces for contributing user interfaces for Transformers to Cytoscape.
org.cytoscape.group	This package provides an API for creating and managing groups in Cytoscape.
org.cytoscape.group.data	An api for configuring CyGroups.
org.cytoscape.group.events	This package contains the various events and listeners related to group management, creation, and destruction.
org.cytoscape.io	Handle import/export of Cytoscape data structures to/from local files/remote URLs.
org.cytoscape.io.datasource	API to provide data files as a bundle.
org.cytoscape.io.read	Handle importing Cytoscape data (network, attributes, session, properties, etc) from files/URLs.
org.cytoscape.io.util	A small number of utilities related to IO.
org.cytoscape.io.webservice	Interfaces for SOAP/REST web service clients, web services that return results as networks or tables, or query results.
org.cytoscape.io.webservice.client	Provides an abstract class for all web service clients, i.e.
org.cytoscape.io.webservice.events	This package defines events/listeners related to data query/import from web services.
org.cytoscape.io.webservice.swing	Web Service Clients with Swing GUI.
org.cytoscape.io.write	This package provides factory interfaces to be used by anyone wishing to provide export or writing capabilities to the rest of Cytoscape.
org.cytoscape.jobs	This package provides a mechanism for executing remote jobs from within Cytoscape.
org.cytoscape.model	This package has the core interfaces of network and table data structures that are foundational to Cytoscape.
org.cytoscape.model.events	This package contains the event interfaces necessary for communicating with the classes in org.cytoscape.model.
org.cytoscape.model.subnetwork	This package contains rootnetwork and subnetwork extensions to the CyNetwork interface that provide a more complex meta-network data model.
org.cytoscape.property	This package provides a general property service interface for providing access to different types of property objects as OSGi services.
org.cytoscape.property.bookmark	This package provides a set of utility methods to manipulate the bookmarks XML format which is used to store and categorize collections of URL bookmarks pointing to data sources.
org.cytoscape.service.util	This package contains a simple utility for registering OSGi services without requiring use of the OSGi API.
org.cytoscape.service.util.internal
org.cytoscape.session	This package contains the interfaces and classes necessary to capturing, storing, and retrieving the state of a Cytoscape session.
org.cytoscape.session.events	This package contains the interfaces and classes necessary to capturing, session change events.
org.cytoscape.task	This package provides base classes for common task factory types as well as their associated task types found in Cytoscape.
org.cytoscape.task.analyze
org.cytoscape.task.create	This package provides a variety of task factory interfaces for creating new instances of network and other objects.
org.cytoscape.task.destroy	This package includes a set of task factory interfaces for deleting or or destroying objects within Cytoscape.
org.cytoscape.task.edit	This package include a set of task factory interfaces that allow the modification or editing of various objects within Cytoscape.
org.cytoscape.task.hide	This package includes a set of task factory interfaces showing and hiding nodes and edges within network views.
org.cytoscape.task.read	This package contains a set of task factory interfaces for reading various Cytoscape objects from files and URLs.
org.cytoscape.task.select	This package includes a set of task factory interfaces for selecting, de-selecting and inverting selections of nodes, edges, or combinations of both based on specific criteria.
org.cytoscape.task.visualize	This package include a set of task factory interfaces used to manipulate the visualizations of network views.
org.cytoscape.task.write	This package contains a set of task factory interfaces used for exporting or writing a variety of Cytoscape objects to files.
org.cytoscape.util.color
org.cytoscape.util.json
org.cytoscape.util.swing	This package contains misc helper classes for Cytoscape Desktop application.
org.cytoscape.view.layout	This package provides access to the available layout algorithms, as well as provides abstract layout classes and layout information containers for the convenience of implementing other layout algorithms.
org.cytoscape.view.model	Module for View Models and Visual Properties.
org.cytoscape.view.model.events	Definitions for View-Model related events and their listeners.
org.cytoscape.view.model.spacial
org.cytoscape.view.presentation	API set for rendering engines (visualizers).
org.cytoscape.view.presentation.annotations	This package provides support for graphical annotations associated with a Cytoscape CyNetworkView.
org.cytoscape.view.presentation.customgraphics	This package provides an API for augmenting a RenderingEngines node rendering with custom graphics.
org.cytoscape.view.presentation.events	Event implementations and listener interfaces for the Presentation layer.
org.cytoscape.view.presentation.property	Implementations of basic VisualProperty objects and VisualLexicons.
org.cytoscape.view.presentation.property.values	Interfaces for VisualPropertyValues -- ArrowShape, LineType and NodeShape
org.cytoscape.view.vizmap	Visual Mapping basic API module.
org.cytoscape.view.vizmap.events	Events for Visual Mappings.
org.cytoscape.view.vizmap.gui	This package provides access to GUI component of VizMap GUI, and interfaces of mapping related managers.
org.cytoscape.view.vizmap.gui.editor	Provides editors for Visual Properties and editor managers for VizMap GUI.
org.cytoscape.view.vizmap.gui.event	Provides events and listeners of LexiconState, visual style switch and vizMap event, as well as VizMap event handler manager.
org.cytoscape.view.vizmap.gui.util	Create discrete mapping for a given set of attribute values
org.cytoscape.view.vizmap.mappings	APIs for different mapping functions -- continuous mapping, discrete mapping and pass through mapping.
org.cytoscape.work	This package defines the task framework, where tasks are units of work.
org.cytoscape.work.json
org.cytoscape.work.properties
org.cytoscape.work.swing	This packages provides Swing-specific specialisations of concepts from work-api This includes TaskFactory, TaskManager, and TaskIterator.
org.cytoscape.work.swing.undo	This packages provides Swing-specific extensions for undo support.
org.cytoscape.work.swing.util
org.cytoscape.work.undo	Cytoscape's undo framework.
org.cytoscape.work.util	Various supporting classes for Cytoscape the work (Task) framework.