Outdated_Cytoscape_3.0/ViewModelDiscussions

TableOfContents([2])

--- DOCUMENT IN PROGRESS 2007-12-10 ---

About this document

In discussions between Mike and Sarah during the repackaging of the current Cytoscape it was determined that we needed to do some significant work to separate model from the view. Several requirements have fallen out of various discussions that these class diagrams should help clarify and hopefully address.

• Each network can have any number of views
• A view may need to share the visual state (selection, color, etc) of any other view
• View data should be persistable (IO needs access in order to save it in a session/project file)
• Plugins need to be able to create their own views and their view data should also be persistable

General Notes

Initially we need to add another package for a ViewModel (see NewPackageStructure.jpg). These can contain whatever mappings we need for color, selection, location, and any other persistable display type information. The IO package would have a dependency now on both the Model and the ViewModel packages (separating them to keep clear what data goes where). On top of this ViewModel is a Controller that will do a couple of things: 1) Make the calls to the ViewModel to change it’s mappings 2) Publish these calls as events (selectionEvent for instance) for other view’s controllers to listen to 3) Register interest in other view controllers events. The controller becomes basically the public API to the underlying model. The reason for this is to keep logic out of the data objects, so the controller can handle any necessary logic.

On the presentation side (org.cytoscape.view module) has a View interface. The View will make calls on it’s Controller to change the underlying ViewModel. This should make it fairly easy to switch out presentation layers without having to change how the models behave. In this way IO will only have to deal with the model layer, but the model layer will have all necessary data.

attachment:NewPackageStructure.jpg

References

I have put together several class and sequence diagrams, mainly to help visualize the flow of data and some prototype code to follow that flow.

Class Diagrams

attachment:MVC_interface.jpg

This diagram is just an example at the class level of the dependencies. A View (GraphView/NodeView) is the presentation layer model, it depends on both a Network model (CyNetwork) and a ViewModel (GraphViewModel/NodeViewModel). The models each hold just the mapping data (what nodes are selected, what nodes are colored blue or red, etc). Each view would then have it's own controller. The controller can be thought of as the publically accessible API of the model that handles any actual logic, especially concerning events that the View may want published/handled. The controllers would all depend on a single EventPublisher class that handles registering listeners and propagating events to those listeners. As a quick note, views would not be required to publish their events so a basic view would be as simple as the SingleViewSequence diagram below minus the EventPublisher.

attachment:MVC_class.jpg

Sequence Diagrams

Single View

The basic case with a single view that is just publishing it's events, it is not handling events from any other view.

attachment:SingleViewSequence.jpg

1. The GraphView gets a user-initiated mouse event to change the color of a node to blue

2. GraphView calls changeColor on the Controller (note the method name is dependent on what the ViewModel chooses to expose through it's controller)

3. GraphController calls setColor on the GraphViewModel, the model updates it's mappings. The controller also publishes the color change event to the EventPublisher for any other Views to listen.

4. The last step is debatable. The View could assume the controller has done it's work and refresh itself, if the ViewModel was correctly updated the View would also be updated. Alternately the Controller could publish a refresh event for the View to listen to. The updside is that the refresh would then not occur until it was sure the mappings had been changed on the ViewModel. The downside is that all views (models and controllers) would be required to use an EventPublisher and all views would have to implement a listener. While this is not hard it just adds a little more work for a plugin writer.

Multiple Views

attachment:MultiViewSequence.jpg

This sequence describes the case where one view is listening for another view's events and updating accordingly. The sequence where a view is listening to other events:

1. NodeController creates a listener for GraphSelectNodeEvents and registers that listener with the EventPublisher.

2. User-initiated mouse event selects a node in the GraphView

3. GraphView calls selectNode on the GraphController

4. GraphController calls setSelected on the GraphViewModel (which updates it's mappings). The controller also creates a GraphSelectNodeEvent and publishes it to the EventPublisher then refresh is called on the GraphView (see the last step above).

5. The EventPublisher then tells all listeners of the event to handleEvent().

6. The listener.handleEvent() method registered in the first step calls on the NodeController to setSelected on the NodeViewModel then refresh the NodeView (again, see last step above).

7. Now the NodeView mirrors the selection state of the GraphView.

attachment:MultiSameViewSequence.jpg

• This describes the case of two of the same type of view (both graph views in this case) publishing and listening to each other's events. Although the diagram is a little ugly, it is basically all of the steps for the sequence above, mirrored. Each view and it's controller is both publishing and listening to each other events so the views will always mirror each other.

attachment:AdaptorSequence.jpg

• This sequence merely separates out the listener (Adaptor) part that in previous sequences lived in the Controller. This mostly helps to keep the Controller class clean and free from any ugly logic that may be required to match up two views. This is especially helpful if, for instance, a view wants to listen to the view whose GraphModel it doesn't share. The logic required to match up two nodes (which are separate objects but may represent the same biological entity) would be handled in the Adaptor class rather than the Controller.