Discussion Title : Cytoscape Event Handling

Editor(s): ...

<<TableOfContents: execution failed [Argument "maxdepth" must be an integer value, not "[2]"] (see also the log)>>

About this document

This is an official Discussion page for Cytoscape Event Handling.


Open for public discussion.

How to Discuss

To view/add discussion comments, click on any of 'Comment' links below. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Try to keep the discussion as concrete and constructive as possible. Be sure to include today's date and your name for each comment.

Discussion Topic


Event handling considers how to cleanly, flexibly, and efficiently notify other classes, components, and plugins of important events that take place. In Cytoscape, examples of events are the creation or deletion of a CyNode, the addition of a CyEdge to a given CyNetwork, change of an attribute value associated with a CyNode, and user selection of some CyEdges and CyNodes within a CyNetworkView.

There are many situations where event handling is needed. One common one is whenever a component must monitor the content of another component or class. For example, the CytoscapeEditor would monitor any changes to a CyNetwork being edited so that changes to the CyNetwork, outside of the editor, could be correctly reflected in the Editor. Another example is the Agilent Literature Search plugin that keeps and displays literature information associated with CyEdges in a CyNetwork. If one of these CyEdges is deleted, the associated literature information in the plugin must be updated.

A key concern of most event handling mechanisms is to avoid strongly coupling the components that fire events with the components that want to find out about events. For example, it is not a viable solution to hardcode event notification calls from a component to the components that want to find out about events. This is because the components interested in event information are usually unknown, or likely to change (e.g., any arbitrary plugin).

To avoid strongly coupling components, a general mechanism is used throughout Java's AWT, Swing, and within Java Beans, called the Delegation Event Model. This model is based on the Observer Design pattern (see Design Patterns, Gamma et. al, p. 293). Cytoscape's event handling is an extension of this model.


Some terminology used in this discussion:

Event Listener (or just Listener)

An instance of a class that implements a specific listener interface in order to obtain event notifications. This is equivalent to the ConcreteObserver in the Observer design pattern.

Event Source (or just Source)

The object whose state changes are of interest to Event Listeners (which will find out about the state change through an event notification). This is equivalent to the ConcreteSubject in the Observer design pattern.

Event Notification (or just Notification)
The method invoked on an Event Listener to specify that an event took place. The method invocation may include extra information about the event through extra passed parameters.

Source of Issue

Cytoscape's existing event handling is spotty, inconsistent, and undocumented. This has led to various bugs, inefficiencies, and the need for various work arounds by several plugins (and probably in the core). A consistent overall procedure and design are needed for how Cytoscape should treat event handling and existing core code should be changed to follow this procedure and design.


1. For what types of events should we fire notifications?

2. What objects can be examined by a Listener and how does the Listener know if the Objects are in a consistent state?

3. How specific are the Sources to which a Listener can listen?

4. How specific are the events to which a Listener can listen?

5. How much information should be passed in an event notification (push vs pull)?

6. When should event notifications be fired in batches or not fired at all?

7. Do we want to centralize event handling in a "ChangeManager"?

Use Cases

Possible Solution Strategies

1. General Approach: Rule #1: When notifications are invoked, the state of all Cytoscape objects directly referened by the notificaton should be well defined and consistent.

2. All Sources should completely and carefully document fired notifications.

3. Creation event notifications should always be signalled after the created object is fully created or restored.

4. An Object deletion event notification should occur before the object is deleted (follow Rule #1).

5. Change event notifications (e.g., renames, deletions, additions) should never be fired when an object is not yet fully defined (e.g,. during object deletion or creation).

6. For more push oriented event notifications, create a standard EventNotification object used to pass all needed information.

7. Consider adding a "LifeState" to Cytoscape objects.

      if (isState(LifeState.DELETED)) { // throw exception here }

General Notes



GaryBader - 2006-10-09 11:42:47

We should investigate the event handling model in the caWorkbench software by the Califano group at Columbia. They claim to have written an event model from scratch that is very efficient (for both of our use cases). Their software is project based and the user can load many tabs (their version of plugins). Changes to any project settings, such as selection of genes in a list, are propagated to all tabs, which dynamically update themselves. The code is open source.

CyEvent_Handling (last edited 2009-02-12 01:04:13 by localhost)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux