cytoscape.command
Class AbstractCommandHandler

java.lang.Object
  cytoscape.command.AbstractCommandHandler

All Implemented Interfaces:

CyCommandHandler

public abstract class AbstractCommandHandler
extends Object
implements CyCommandHandler

This abstract class provides a convenient (but not necessary) base class for writing CyCommandHandlers. It may be used whether your handler handles a single command or multiple commands. The general use of this base class is to add a set of known arguments using the addArgument(java.lang.String)() method and addDescription(java.lang.String, java.lang.String)() methods within the constructor of your command handler:

 public class MyCommandHandler extends AbstractCommandHandler {
   // Define our command name
   private static String COMMAND = "my command";

   // Settings
   private static String ARGKEY1 = "argkey1";
   private static String ARGKEY2 = "argkey2";
   private static String ARGKEY3 = "argkey3";

   public MyCommandHandler(CyCommandNamespace ns) {
     super(ns);
     addDescription(java.lang.String, java.lang.String)(COMMAND, "This command does something really cool");
     addArgument(java.lang.String)(COMMAND, ARGKEY1);
     addArgument(java.lang.String)(COMMAND, ARGKEY2);
     addArgument(java.lang.String)(COMMAND, ARGKEY3, "defaultValue");
   }

   public CyCommandResult execute(String command, Map<String, Object>args) throws CyCommandException {
     // Your execution code goes here....
   }
   ... or ...
   public CyCommandResult execute(String command, Collection<Tunable>args) throws CyCommandException {
     // Your execution code goes here....
   }
 }
 

Note that both of the two CyCommandHandler.execute(java.lang.String, java.util.Map) methods must be overridden, but only one of which must include your functionality. AbstractCommandHandler provides two additional methods to assist command authors with the conversion between the two execute methods. If your plugin uses Tunables, to handle the Map version of the execute method, implement the following method:

 public class execute(String command, Map arguments) {
   return execute(command, createTunableCollection(arguments));
 } 
 

where the createTunableCollection method will create a list of Tunables to call the Tunable version of execute. On the other hand, if your plugin does not use Tunables, you can use:

 public CyCommandResult execute(String command, Collection arguments) {
   return execute(command, createKVMap(arguments));
 }
 

where the createKVMap method will take a Collection of Tunables and create the corresponding Map to call your execute method. The addDescription(java.lang.String, java.lang.String)() method is used by the AbstractCommandHandler's getDescription(java.lang.String)() method to produce a formatted description of the command, including the namespace, command name, description, and options (with default values). To avoid the formatting and provide your own full description, just override the getDescription() method and return your own description. Also note that the CyCommandNamespace must be reserved before the command handler is initialized.

Field Summary

protected Map<String,List<Tunable>>	argumentMap
protected Map<String,String>	descriptionMap
protected CyCommandNamespace	namespace

Constructor Summary

AbstractCommandHandler(CyCommandNamespace ns)
You do not need to call this constructor from you class, but if you don't, you will need to make sure you assign the namespace appropriately.

Method Summary

protected void	addArgument(String command) This method adds a new command to the list of command supported by this command handler.
protected void	addArgument(String command, String vKey) Add a new argument key to a command supported by this command handler.
protected void	addArgument(String command, String vKey, String value) Add a new argument key with a value to a command supported by this command handler.
protected void	addArgument(String command, Tunable t) Add a new argument Tunable to a command supported by this command handler.
protected void	addDescription(String command, String description) This method adds a new description for a command supported by this command handler.
protected Map<String,Object>	createKVMap(Collection<Tunable> tList) Execute a given command with a particular set of arguments.
protected Collection<Tunable>	createTunableCollection(Map<String,Object> args) Use this method to support the Map version of the execute call if you support Tunables.
protected String	getArg(String command, String key, Map<String,Object> args) Return the string value of a specific argument from an args map.
List<String>	getArguments(String command) Return the arguments for a given command
List<String>	getCommands() Return the command or commands supported by this handler
String	getDescription(String command) This method returns a formatted description of the command, including the namespace, command name, plugin-provided description, and arguments.
Map<String,Object>	getSettings(String command) Return the current settings for a given command.
Map<String,Tunable>	getTunables(String command) Return the current settings for a given command as a map of setting name: tunable.
static Tunable	makeTunable(String name, Object value)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface cytoscape.command.CyCommandHandler

execute, execute

Field Detail

argumentMap

protected Map<String,List<Tunable>> argumentMap

descriptionMap

protected Map<String,String> descriptionMap

namespace

protected CyCommandNamespace namespace

Constructor Detail

AbstractCommandHandler

public AbstractCommandHandler(CyCommandNamespace ns)

You do not need to call this constructor from you class, but if you don't, you will need to make sure you assign the namespace appropriately.

Parameters:

ns - the CyCommandNamespace for this command

Method Detail

getCommands

public List<String> getCommands()

Return the command or commands supported by this handler

Specified by:

getCommands in interface CyCommandHandler

Returns:

a list of strings with one or more commands

getArguments

public List<String> getArguments(String command)

Return the arguments for a given command

Specified by:

getArguments in interface CyCommandHandler

Parameters:

command - the command to check for arguments

Returns:

the list of arguments this command will take

getSettings

public Map<String,Object> getSettings(String command)

Return the current settings for a given command. At this point, for simplicity the only Object type supported as values are those that have "toString()" methods. This allows for simple mappings between textual input and settings without resorting to inspection of the object types. This signature is expected to be removed sometime in the 3.0 timeframe and only the getTunables version will remain.

Specified by:

getSettings in interface CyCommandHandler

Parameters:

command - the command we want the settings for

Returns:

the current settings as a map

getTunables

public Map<String,Tunable> getTunables(String command)

Return the current settings for a given command as a map of setting name: tunable.

Specified by:

getTunables in interface CyCommandHandler

Parameters:

command - the command we want the settings for

Returns:

the current settings as a map of setting name: tunable.

getDescription

public String getDescription(String command)

This method returns a formatted description of the command, including the namespace, command name, plugin-provided description, and arguments. Override this to provide your own description.

Specified by:

getDescription in interface CyCommandHandler

Parameters:

command - the command we're inquiring about

Returns:

the description/documentation for this command

createKVMap

protected Map<String,Object> createKVMap(Collection<Tunable> tList)

Execute a given command with a particular set of arguments. As with the /** Use this method to support the Tunable version of the execute call if you don't support Tunables. This is actually pretty simple -- just add the following:

 public CyCommandResult execute(String command, Collection<Tunable>args) throws CyCommandException {
   return execute(command, createKVMap(args));
 }
 

assuming that you've implemented the Map version of execute. Note that you must handle one version of execute at least.

Parameters:

tList - a Collection of Tunables

Returns:

a Map of String:Object pairs derived from tList

createTunableCollection

protected Collection<Tunable> createTunableCollection(Map<String,Object> args)

Use this method to support the Map version of the execute call if you support Tunables. This is actually pretty simple -- just add the following:

 public CyCommandResult execute(String command, Map<String,Object>args) throws CyCommandException {
   return execute(command, createTunableCollection(args));
 }
 

assuming that you've implemented the Collection version of execute. Note that you must handle one version of execute at least.

Parameters:

args - a Map of String,Object pairs

Returns:

a Collection of Tunables that correspond to the String,Object pairs

addDescription

protected void addDescription(String command,
                              String description)

This method adds a new description for a command supported by this command handler. addDescription, in conjunction with the getDescription method provided by this class provide an easy way to get a formatted description, including available options. On the other hand, if a plugin want's to provide its own description, without any additional formatting, it should override getDescription and return the description directly

Parameters:

command - the name of the command to add the description to

description - the description to add

addArgument

protected void addArgument(String command)

This method adds a new command to the list of command supported by this command handler. This assumes that this command has no arguments.

Parameters:

command - the name of the command to add

addArgument

protected void addArgument(String command,
                           String vKey)

Add a new argument key to a command supported by this command handler. If the command hasn't already been registered, register it.

Parameters:

command - the name of the command to add this argument key to

vKey - the key to add

addArgument

protected void addArgument(String command,
                           String vKey,
                           String value)

Add a new argument key with a value to a command supported by this command handler. If the command hasn't already been registered, register it.

Parameters:

command - the name of the command to add this argument key to

vKey - the key to add

value - the value to associate with the key

addArgument

protected void addArgument(String command,
                           Tunable t)

Add a new argument Tunable to a command supported by this command handler. If the command hasn't already been registered, register it.

Parameters:

command - the name of the command to add this argument key to

t - the Tunable to add

getArg

protected String getArg(String command,
                        String key,
                        Map<String,Object> args)

Return the string value of a specific argument from an args map.

Parameters:

command - the command we're getting the argument for

key - the argument we're interested in

args - the map of arguments that was passed to us

Returns:

the String value corresponding to the key

makeTunable

public static Tunable makeTunable(String name,
                                  Object value)