Diff for "CyEvent_Handling"

TableOfContents([2])

About this document

This is an official Discussion page for Cytoscape Event Handling.

Status

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

Backgound

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, 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 [http://java.sun.com/j2se/1.3/docs/guide/awt/designspec/events.html 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.

Terminology

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 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 a 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.

Complexities

Use Cases

Possible Solution Strategies

General Notes

References

Discussion

PageComment2