Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## things.common.commands
Class CommandRoot

    java.lang.Object
      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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Things.