henplus
Interface Command

All Known Implementing Classes:
AboutCommand, AbstractCommand, AbstractPropertyCommand, AliasCommand, ConnectCommand, DescribeCommand, DriverCommand, DumpCommand, EchoCommand, ExitCommand, ExportCommand, HelpCommand, ImportCommand, KeyBindCommand, ListUserObjectsCommand, LoadCommand, PluginCommand, PropertyCommand, SamplePlugin, SessionPropertyCommand, SetCommand, ShellCommand, SpoolCommand, SQLCommand, StatusCommand, SystemInfoCommand, TableDiffCommand, TreeCommand

public interface Command

Interface to be implemented for user level commands.

The CommandDispatcher and the HelpCommand operate on this interface. This interface needs to be implemented by your own Commands or Plugins that should be supported by HenPlus. If the documenation given here is not enough (though I hope it is), just read some of the implementations given in henplus.commands.

If you are writing Plugins, consider extending the AbstractCommand as it provides a default implementation and you are immune to NoSuchMethodErrors if this interface changes but not yet your plugin...

Version:
$Revision: 1.10 $
Author:
Henner Zeller

Field Summary
static int EXEC_FAILED
          constant returned by the execute(SQLSession,String,String) if the command could not be executed because of some problem, that is not a syntax error.
static int SUCCESS
          constant returned by the execute(SQLSession,String,String) method, if everything went fine.
static int SYNTAX_ERROR
          constant returned by the execute(SQLSession,String,String) if the command could not be executed because of an syntax error.
 
Method Summary
 Iterator complete(CommandDispatcher disp, String partialCommand, String lastWord)
          Returns a list of strings that are possible at this stage.
 int execute(SQLSession session, String command, String parameters)
          execute the command given.
 String[] getCommandList()
          returns the prefices of all command-strings this command can handle.
 String getLongDescription(String cmd)
          returns a longer string describing this action.
 String getShortDescription()
          return a short string describing the purpose of the commands handled by this Command-implementation.
 String getSynopsis(String cmd)
          retuns a synopsis-string.
 void handleCommandline(CommandLine line)
          After parsing the parameters, this method is called.
 boolean isComplete(String command)
          returns, whether the command is complete.
 boolean participateInCommandCompletion()
          returns 'false', if the commands supported by this Commands should not be part of the toplevel command completion.
 void registerOptions(Options r)
          This method is called before parsing the commandline.
 boolean requiresValidSession(String cmd)
          returns true, if this command requires a valid SQLSession, i.e.
 void setOptions(Options options)
          Options are set, after the commandline has been parsed.
 void shutdown()
          shutdown this command.
 

Field Detail

SUCCESS

static final int SUCCESS
constant returned by the execute(SQLSession,String,String) method, if everything went fine.

See Also:
Constant Field Values

SYNTAX_ERROR

static final int SYNTAX_ERROR
constant returned by the execute(SQLSession,String,String) if the command could not be executed because of an syntax error. In that case, the CommandDispatcher will display the synopsis of that command.

See Also:
Constant Field Values

EXEC_FAILED

static final int EXEC_FAILED
constant returned by the execute(SQLSession,String,String) if the command could not be executed because of some problem, that is not a syntax error.

See Also:
Constant Field Values
Method Detail

getCommandList

String[] getCommandList()
returns the prefices of all command-strings this command can handle. The special prefix is the empty string that matches anything that is not handled by all other commands. It is used in the SQLCommand.


participateInCommandCompletion

boolean participateInCommandCompletion()
returns 'false', if the commands supported by this Commands should not be part of the toplevel command completion. So if the user presses TAB on an empty string to get the full list of possible commands, this command should not show up. In HenPlus, this returns 'false' for the SQL-commands ('select', 'update', 'drop' ..), since this would clobber the toplevel list of available commands. If unsure, return 'true'.


execute

int execute(SQLSession session,
            String command,
            String parameters)
execute the command given. The command is given completely without the final delimiter (which would be newline or semicolon). Before this method is called, the CommandDispatcher checks with the isComplete(String) method, if this command is complete.

Parameters:
session - the SQLsession this command is executed from.
command - the command as string.
parameters - the rest parameters following the command.
Returns:
one of SUCCESS, SYNTAX_ERROR, EXEC_FAILED to indicate the exit status of this command. On SYNTAX_ERROR, the CommandDispatcher displays a synopsis if available.

complete

Iterator complete(CommandDispatcher disp,
                  String partialCommand,
                  String lastWord)
Returns a list of strings that are possible at this stage. Used for the readline-completion in interactive mode. Based on the partial command and the lastWord you have to determine the words that are available at this stage. Return 'null', if you don't know a possible completion.

Parameters:
disp - the CommandDispatcher - you might want to access other values through it.
partialCommand - The command typed so far
lastWord - the last word returned by readline.

isComplete

boolean isComplete(String command)
returns, whether the command is complete.

This method is called, whenever the input encounters a newline or a semicolon to decide if this separator is to separate different commands or if it is part of the command itself.

The delimiter (newline or semicolon) is contained (at the end) in the String passed to this method. This method returns false, if the delimiter is part of the command and will not be regarded as delimiter between commands -- the reading part of the command dispatcher will go on reading characters and not execute the command.

This method will return true for most simple commands like 'help'. For commands that have a more complicated syntax, this might not be true.

Note, this method should only apply a very lazy syntax check so it does not get confused and uses too much cycles unecessarily..

Parameters:
command - the partial command read so far given to decide by the command whether it is complete or not.

requiresValidSession

boolean requiresValidSession(String cmd)
returns true, if this command requires a valid SQLSession, i.e. if the execute(SQLSession,String,String) method makes use of the session (e.g. to get some Database connection) or not. Return 'true' if unsure (you should be sure..). This is to thwart attempts to execute a command without session.

Parameters:
cmd - the subcommand this is requested for; one of the commands returned by getCommandList().

shutdown

void shutdown()
shutdown this command. This is called on exit of the CommandDispatcher and allows you to do some cleanup (close connections, flush files..)


getShortDescription

String getShortDescription()
return a short string describing the purpose of the commands handled by this Command-implementation. This is the string listed in the bare 'help' overview (like 'describe a database object') Should contain no newline, no leading spaces.


getSynopsis

String getSynopsis(String cmd)
retuns a synopsis-string. The synopsis string returned should follow the following conventions:

Should contain no newline, no leading spaces. This synopsis is printed in the detailed help of a command or if the execute()-method returned a SYNTAX_ERROR.

Parameters:
cmd - the command the synopsis is for. This is one of the possible commands returned by getCommandList().

getLongDescription

String getLongDescription(String cmd)
returns a longer string describing this action. This should return a String describing details of the given command. This String should start with a TAB-character in each new line (the first line is a new line). The last line should not end with newline.

Parameters:
cmd - The command the long description is asked for. This is one of the possible commands returned by getCommandList().

setOptions

void setOptions(Options options)
Options are set, after the commandline has been parsed.

Parameters:
options -

registerOptions

void registerOptions(Options r)
This method is called before parsing the commandline. You can register command-specific options here.

Parameters:
r -

handleCommandline

void handleCommandline(CommandLine line)
After parsing the parameters, this method is called. there can be some default options left. These are set to the commands through this method. This is only for compatibility with the old commandline options, please use named options only!

Parameters:
line - TODO


? 1997..2006 Henner Zeller