HeadlessModeRFC

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

About this document

This is an official Request for Comment (RFC) for Cytoscape Headless Mode Operation.

For details on RFCs in general, check out the Wikipedia Entry: Request for Comments (RFCs)

Status

"Not yet completely written"

How to Comment

To view/add 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. Be sure to include today's date and your name for each comment. Here is an example to get things started: /Comment.

Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the RFC makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.

Proposal

Cytoscape currently runs only in "window" mode, that is, as a complete, self-contained application. There is a need to access Cytoscape functionality in alternative ways, such as laying out graph images on a webserver or embedding a cytoscape window in a different application.

Biological Questions / Use Cases

1. A user has hundreds of SIF files that s/he would like to generate images for (say for a web page) without doing so manually via Cytoscape.
2. A developer would like to provide a Cytoscape network visualization window in his or her application without necessarily providing all of Cytoscape's functionality.
3. A developer would like to generate network images of graphs from within a separate Java application.
4. A program or user would like to interact with a single instance of a Cytoscape "server" running in the background without creating a new instance of Cytoscape each time.

General Notes

• In discussions of the various needs, we've identified several different modes of interacting with cytoscape.

• Window mode - This means running Cytoscape as a complete, self-contained application, with a full user interface and initialization and teardown routines. This is how Cytoscape currently operates.

• Text mode - This means running Cytoscape (generally from the command line) without opening the gui. The goal here is an application that provides access to Cytoscape features. For example, a user might specify a SIF file along with a vizmap.props file and rather than bringing up a window, simply create an image of the layed out graph using the specified vizmap.props. Text mode would allow calls to the cytoscape application to be embedded in scripts for other purposes, such as CGI scripts.

• Library mode - This means providing a set of libraries that provide access to Cytoscape capabilities from other Java applications. For example, if a developer of a different application wanted to create a graph image based on some sort of network structure, instead of running a script in an external process to create the image, a developer could call specific Cytoscape methods directly to create the image.

• Embedded Window mode - This means embedding one or more Cytoscape windows or panels in a separate application, possibly as a plugin to that application. An embedded Cytoscape would not necessarily create all of the normal frames and panels. For instance, an application may want to show the network window without showing the menus or cytopanels. Interaction with the embedded window could be controlled through an external interface that calls various actions directly.

• Daemon mode - This means having a single Cytoscape process running perpetually in the background. A program would interact with the daemon using some sort of IPC mechanism. The interface could be direct method calls or something like a BeanShell that allows command line interaction.

Requirements

Deferred Items

Possible Design

• Write an interface CyInitParams that contains the initialization parameters needed by cytoscape. The method can be a bunch of getters modeled on those found in CyCommandLineParser.

• CyInitParams should have a method called getMode() that returns one of four modes: GUI, TEXT, EMBEDDED_WINDOW, and LIBRARY (I'm ignoring DAEMON for the time being, because I think it is subsumed by LIBRARY).

• Have CyCommandLineParser implement CyInitParams.

• CytoscapeInit should be changed so that it initializes only based on CyInitParams.

• The init() method in CytoscapeInit needs to be modularized a bit (e.g. moving the vizmap stuff into a separate method).

• The init() method in CytoscapeInit will determine how to initialize based on the getMode() method found in the CyInitParams object.

• CyMain should be changed to handle processing of the -h flag (help) which is currently handled in CytoscapeInit.

• Write a new class that implements CyInitParams using setter methods (and/or one very long constructor). This class would be used by LIBRARY and EMBEDDED_WINDOW mode.

Open Issues

• Cytoscape (on linux) currently needs an X11 process to be running before it can do anything. This is a result of PhoebeCanvas adding a DropTarget to itself to support Drag-n-drop operations. It is unclear how deeply rooted this behavior is and whether or not it can be turned on/off in a reasonable way./Comment

• Exiting from Cytoscape currently calls System.exit(), which means that if it is embedded in another application, when Cytoscape is closed, the other application will be as well.

• When Cytoscape is used as a library without calling CytoscapeInit (i.e. simply calling Cytoscape.getRootGraph() and a few other static methods), there is currently no way to specify the vizmap.props file. This means that applying visual properties fails.

• CytoscapeInit is currently monolithic and needs to be made modular with respect to the different modes of operation. Perhaps initialization and teardown functionality should migrate to the top-level classes for each mode of operation. /CommentInit

• CytoscapeDesktop currently contains much of the information needed to draw graphs and, in general, do anything useful with Cytoscape. This is a problem because CytoscapeDesktop is a JFrame which pretty much demands to be drawn. At this point I'm leaning towards the following.

  • Deprecate Cytoscape.getDesktop().
  • Create a method that will return an implementation of a Component - possibly a cytoscape specific Component - that can be used for tasks like creating JOptionPanes, resizing windows, scrollbars, etc.

  • Create a second method that will return an implementation of an interface that defines Cytoscape specific methods (i.e. getVisualMappingManager, etc.). We should consider using CyWindow for this.

  • The CytoscapeDesktop class should be cleaned up as there is a ton of cruft in the class.

  • In GUI mode, the Cytoscape object can continue to return CytoscapeDesktop for both method calls, although the users won't know this, they'll just know that they're either getting an implementation of an interface.

Backward Compatibility

Proper support for headless mode would almost certainly imply significant changes to Cytoscape's current command line interface. It would be important to maintain the current options.

Expected growth and plan for growth

References

Implementation Plan

• /Implementation Plan