things.common.commands
Class CommandRoot

java.lang.Object
  extended by things.common.commands.CommandRoot

public abstract class CommandRoot
extends java.lang.Object

Command root for all the commands.

It will automatically expect a root directory as the first entity (#0). This one is reserved. You can have scripts or wrappers obfuscate it if none of your commands care about it.

Version:
1.0

Version History

 EPG - Initial - 1 NOV 01
 EPG - Welded more tightly into the system, inclufing logging. - 10 AUG 06
 
Author:
Erich P. Gatejen

Field Summary
 ThingsPropertyReaderToolkit configProps
          Configuration properties, if provided.
 ThingsPropertyView configPropsView
          Configuration properties from a writable view, if provided.
 Logger defaultLogger
          A default logger.
static int ENTITY_ROOT_DIRECTORY
          Built-in entities.
static int OPTION_HELP1
           
static int OPTION_HELP2
           
static int OPTION_VERBOSE
          Built-in options.
 ThingsPropertyReaderToolkit valueProps
          Value properties, if provided.
 ThingsPropertyView valuePropsView
          Value properties from a writable view, if provided.
static java.lang.String VALUES_CONFIGURATION
          Build-in values
static java.lang.String VALUES_VALUES
           
 
Constructor Summary
CommandRoot()
          The constructor.
 
Method Summary
protected abstract  void declare()
          Declare usage.
protected  void declareEntities(int name, java.lang.String helpText, boolean isRequired)
          Declare an entity.
protected  void declareOption(int option, java.lang.String helpText)
          Declare an option.
protected  void declareValues(java.lang.String name, java.lang.String helpText, boolean isRequired)
          Declare a value.
protected  void ERROR(java.lang.String message)
          Raise an error and let the command root render it to the user.
protected  void ERROR(java.lang.String message, java.lang.Throwable t)
          Raise an error and let the command root render it to the user.
 java.io.PrintWriter getConsole()
          Get the console print writer.
 java.lang.String getEntity(int item)
          Get an entity (numbered parameter).
 java.lang.String getEntityRequired(int item, java.lang.String message)
          Get an entity (numbered parameter).
protected  java.lang.String getFooter()
          OVERRIDE IF YOU WANT TO PROVIDE PARAMETER INFORMATION to the command help.
protected  java.lang.String getHeader()
          OVERRIDE IF YOU WANT TO PROVIDE MORE INFO in the help about what the command does.
protected abstract  java.lang.String getName()
          Get the command name.
protected abstract  java.lang.String getToken()
          Get the command token.
 java.lang.String getValue(java.lang.String name)
          Get a value.
 void mainEntry(java.lang.String[] args)
          A main entry for the command.
protected  int numberOfEntites()
          Get the number of entities.
protected  int numberOfValues()
          Get the number of values.
 boolean optionIsSet(int character)
          Convenience to check if an option is set.
abstract  void run()
          Run the command.
protected  void suppressListingRootInstallEntity()
          When called during declaration, any subsequent list or help will not show the install root entity.
 void usage()
          Print the usage (help).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OPTION_VERBOSE

public static final int OPTION_VERBOSE
Built-in options.

See Also:
Constant Field Values

OPTION_HELP1

public static final int OPTION_HELP1
See Also:
Constant Field Values

OPTION_HELP2

public static final int OPTION_HELP2
See Also:
Constant Field Values

VALUES_CONFIGURATION

public static final java.lang.String VALUES_CONFIGURATION
Build-in values

See Also:
Constant Field Values

VALUES_VALUES

public static final java.lang.String VALUES_VALUES
See Also:
Constant Field Values

ENTITY_ROOT_DIRECTORY

public static final int ENTITY_ROOT_DIRECTORY
Built-in entities.

See Also:
Constant Field Values

configProps

public ThingsPropertyReaderToolkit configProps
Configuration properties, if provided. Not all commands need them. They can be load from a file with the -configs option.


valueProps

public ThingsPropertyReaderToolkit valueProps
Value properties, if provided. Not all commands need them. They can be load from a file with the -values option.


valuePropsView

public ThingsPropertyView valuePropsView
Value properties from a writable view, if provided. Not all commands need them. They can be load from a file with the -values option.


configPropsView

public ThingsPropertyView configPropsView
Configuration properties from a writable view, if provided. Not all commands need them. They can be load from a file with the -values option.


defaultLogger

public Logger defaultLogger
A default logger. It'll be set during startup, but if you are brave, overwrite it.

Constructor Detail

CommandRoot

public CommandRoot()
            throws java.lang.Throwable
The constructor. It will declare the command, so be ready for exceptions if done wrong.

Throws:
java.lang.Throwable
Method Detail

declare

protected abstract void declare()
                         throws java.lang.Throwable
Declare usage. Gives the subclass a chance to declare values and options.

Throws:
java.lang.Throwable

run

public abstract void run()
                  throws java.lang.Throwable
Run the command. The implementation should NOT persist any state! It's up the the creator to decide if to keep the command object around. Any exception that finds its way out will be stopped and logged. Obviously, ThingsExceptions will provide richer detail than plain Exceptions.

Throws:
java.lang.Throwable

getName

protected abstract java.lang.String getName()
Get the command name. This is how the subclass defines the name (which is mostly used in the help).

Returns:
the name.

getToken

protected abstract java.lang.String getToken()
Get the command token. This is a short token that will head each log line.

Returns:
the token.

getHeader

protected java.lang.String getHeader()
OVERRIDE IF YOU WANT TO PROVIDE MORE INFO in the help about what the command does. Return null is you don't want to print a header.

Returns:
The header or null.

getFooter

protected java.lang.String getFooter()
OVERRIDE IF YOU WANT TO PROVIDE PARAMETER INFORMATION to the command help. Return null is you don't want to print a footer.

Returns:
a string that is the footer.

declareOption

protected void declareOption(int option,
                             java.lang.String helpText)
                      throws java.lang.Throwable
Declare an option. (they are always optional).

Parameters:
option - The character for the option.
helpText - The help text.
Throws:
java.lang.Throwable - Most likely a ThingsException if parameters are bad or if the option was already declared.

declareValues

protected void declareValues(java.lang.String name,
                             java.lang.String helpText,
                             boolean isRequired)
                      throws java.lang.Throwable
Declare a value.

Parameters:
name - The option name. Not case sensitive. Internally, they are normalized to lower case.
helpText - The help text.
isRequired - is it required? false means it is optional.
Throws:
java.lang.Throwable - Most likely a ThingsException if parameters are bad or if the option was already declared.
See Also:
ThingsException

declareEntities

protected void declareEntities(int name,
                               java.lang.String helpText,
                               boolean isRequired)
                        throws java.lang.Throwable
Declare an entity. These MUST be done sequentially by item number, starting with 1 (0 is reserved by the system for the install root). If you declare them out of numeric order, like 1-2-4-3, or have gaps, like 1-2-3-5, you will get an exception. I'm just being a pain here. :6)

Parameters:
name - The option name. Not case sensitive. Internally, they are normalized to lower case.
helpText - The help text.
isRequired - is it required? false means it is optional.
Throws:
java.lang.Throwable - Most likely a ThingsException if parameters are bad or if the option was already declared.
See Also:
ThingsException

suppressListingRootInstallEntity

protected void suppressListingRootInstallEntity()
When called during declaration, any subsequent list or help will not show the install root entity.


ERROR

protected void ERROR(java.lang.String message)
              throws java.lang.Throwable
Raise an error and let the command root render it to the user.

Parameters:
message - the error
Throws:
java.lang.Throwable

ERROR

protected void ERROR(java.lang.String message,
                     java.lang.Throwable t)
              throws java.lang.Throwable
Raise an error and let the command root render it to the user.

Parameters:
message - the error
t - the causing exception.
Throws:
java.lang.Throwable

numberOfEntites

protected int numberOfEntites()
Get the number of entities. Besides the number you declare, there is always the root (0) entity.

Returns:
the total number of entities (including the root).

numberOfValues

protected int numberOfValues()
Get the number of values.

Returns:
the total number of values.

mainEntry

public void mainEntry(java.lang.String[] args)
A main entry for the command. The subclass should call this right from static main.

This will not throw any exceptions.

Parameters:
args - The command line arguments. What's passed from main() works dandy.

usage

public void usage()
Print the usage (help).

The formats:

   aaa           - REQUIRED, AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
                   AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
   b             - BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
                   BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
   cccccccccccc  - OPTIONAL, CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
                   CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC

"   %-3s           - %-8s, %-71s"
"                   %-81s"
"   %c             - %-81s"
"                   %-81s"
"   %-12s  - %-8s, %-71s"
"                   %-81s"


getConsole

public java.io.PrintWriter getConsole()
Get the console print writer.

Returns:
the console print writer.

getEntity

public java.lang.String getEntity(int item)
                           throws ThingsException
Get an entity (numbered parameter). If it isn't present and it is REQUIRED, it will throw a CommandException with the numeric COMMANDLINE_ERROR_MISSING_REQUIRED. If it isn't present and isn't required, it will return a null.

Parameters:
item - The item number.
Returns:
The value of the parameter.
Throws:
ThingsException

getEntityRequired

public java.lang.String getEntityRequired(int item,
                                          java.lang.String message)
                                   throws ThingsException
Get an entity (numbered parameter). If it isn't present it is assumed to be required, and it will throw a CommandException with the numeric COMMANDLINE_ERROR_MISSING_REQUIRED.

Parameters:
item - The item number.
message - The entity name or description. It's used if an error occurs.
Returns:
The value of the parameter.
Throws:
ThingsException

getValue

public java.lang.String getValue(java.lang.String name)
                          throws ThingsException
Get a value. If it isn't present and it is REQUIRED, it will throw a CommandException with the numeric COMMANDLINE_ERROR_MISSING_REQUIRED. If it isn't present and isn't required, it will return a null.

Parameters:
name - The item name.
Returns:
The value of the parameter.
Throws:
ThingsException

optionIsSet

public boolean optionIsSet(int character)
Convenience to check if an option is set. Return true if it is. This method is a pass-through to the currentLine.

Parameters:
character -
Returns:
true if it is set, otherwise false


Things.