cytoscape.command
Interface CyCommandHandler

All Known Implementing Classes:

AbstractCommandHandler

public interface CyCommandHandler

The CyCommandHandler interface allows a Cytoscape plugin to make it's functions available to other plugins in a loosely-coupled manner (by passing command strings and arguments). It is intended as a stop-gap measure until the ability to directly call methods in other plugins (through OSGI services) is available in Cytoscape 3.0.

CyCommandHandler provide a simple method for a plugin to expose some functionality that can be used by other plugins. The idea is simple: a plugin registers one or more CyCommandHandlers with the CyCommandManager. In the simplest case, the plugin will directly implement CyCommandHandler:

 public class MyPlugin extend CytoscapePlugin implements CyCommandHandler {
   public MyPlugin() {
      // Plugin initialization
      try {
        // You must reserve your namespace first
        CyCommandNamespace ns = CyCommandManager.reserveNamespace("my namespace");

        // Now register this handler as handling "command"
        CyCommandManager.register(ns, command, this);
      } catch (RuntimeException e) {
        // Handle already registered exceptions
      }
   }
 }
 

Alternatively, a plugin could implement multiple CyCommandHandlers, each one handling a single command string. This has the advantage of providing a clear separation where each class handles a single command, and is the recommended way to structure new plugins.

Commands

Each command handler can provide any number of commands. A command provides the actual functionality, and the passed arguments (name, value pairs) are specific to commands. Note that there aren't any restrictions about the number of words in a command handler name or command name. So, for example, the view layout command handler could provide a get current command.

Arguments

Arguments for commands may be specified either as name, value pairs (using a string, string map) or as a list of Tunable. It is recommended that whenever possible, plugins use Tunables as they provide type information that is useful to allow client plugins to perform some limited validation. In either case, both signatures (maps and Tunables) should be supported.

Return Values

CyCommandHandlers pass information about the execution of a command in a CyCommandResult. It is expected that a command will provide some limited information in the CyCommandResult message and the actual information in the results map.

Exceptions

A CyCommandHandler should always return a valid CyCommandResult to provide feedback to the user about the execution. If a processing error occurs, the CyCommandHandler should throw a CyCommandException with an appropriate message.

Client Usage

Using a CyCommandHandler from another plugin is relatively straightforward: get the CyCommandHandler, get the arguments for the desired command, set the arguments, and execute the the command:

     CyCommandHandler handler = CyCommandManager.getCommand("view layout", "force-directed");
     Map layoutTunables = handler.getTunables("force-directed");
     Tunable t = layoutTunables.get("iterations");
     t.setValue("100");
     try {
       CyCommandResult layoutResult = handler.execute("force-directed", layoutTunables);
     } catch (CyCommandException e) {
     }
 

Alternatively....

     Map args = new HashMap();
     args.put("iterations", new Integer(100));
     try {
       CyCommandResult layoutResult = CyCommandManager.execute("view layout", "force-directed", args);
     } catch (CyCommandException e) {
     }
 

Method Summary

CyCommandResult	execute(String command, Collection<Tunable> arguments) Execute a given command with a particular set of arguments.
CyCommandResult	execute(String command, Map<String,Object> arguments) Execute a given command with a particular set of arguments.
List<String>	getArguments(String command) Return the list of arguments supported by a particular command.
List<String>	getCommands() Return the list of commands supported by this CyCommandHandler.
String	getDescription(String command) Get the description/documentation of the command.
Map<String,Object>	getSettings(String command) Get the current values for all of the arguments for a specific command.
Map<String,Tunable>	getTunables(String command) Get the current Tunables for all of the arguments for a specific command.

Method Detail

getCommands

List<String> getCommands()

Return the list of commands supported by this CyCommandHandler. This implies that a single CyCommandHandler might support multiple commands, but it may also support only one, in which case, this is the same as the handler name;

Returns:

list of commands supported by this CyCommandHandler

getArguments

List<String> getArguments(String command)

Return the list of arguments supported by a particular command. CyCommandHandler argument values are always Strings that can be converted to base types when passed. Internally, these are usually directly mapped to Tunables.

Parameters:

command - the command we're inquiring about

Returns:

list of arguments supported by that command

getSettings

Map<String,Object> getSettings(String command)

Get the current values for all of the arguments for a specific command. Argument values are always Strings that can be converted to base types when passed. Note that this interface is expected to be deprecated in Cytoscape 3.0 where everything is expected to be based on the new Tunable implementation.

Parameters:

command - the command we're inquiring about

Returns:

map of arguments supported by that command, where the key is the argument and the value is the String value for that argument.

getTunables

Map<String,Tunable> getTunables(String command)

Get the current Tunables for all of the arguments for a specific command. This is an alternative to getSettings for plugins that provide tunables, and is expected to be the standard approach for Cytoscape 3.0 and beyond.

Parameters:

command - the command we're inquiring about

Returns:

map of Tunables indexed by Tunable name supported by that command, or null if the plugin doesn't support tunables.

getDescription

String getDescription(String command)

Get the description/documentation of the command. This could be used to describe the command's function or usage and is meant to be used by UI's that act as clients for the command.

Parameters:

command - the command we're inquiring about

Returns:

the description/documentation for this command

execute

CyCommandResult execute(String command,
                        Map<String,Object> arguments)
                        throws CyCommandException

Execute a given command with a particular set of arguments. As with the getSettings method above, this is expected to be retired in 3.0 when most things will use Tunables.

Parameters:

command - the command we're executing

arguments - to map of key, value pairs for the arguments we want to pass

Returns:

the results as a map of key, value pairs. If null, then the execution failed.

Throws:

CyCommandException

execute

CyCommandResult execute(String command,
                        Collection<Tunable> arguments)
                        throws CyCommandException

Execute a given command with a particular set of arguments. This is the preferred method signature.

Parameters:

command - the command we're executing

arguments - the list of Tunables

Returns:

the results as a map of key, value pairs. If null, then the execution failed.

Throws:

CyCommandException