jcmdline
Class AbstractHandlerDecorator

java.lang.Object
  extended by jcmdline.AbstractHandlerDecorator
All Implemented Interfaces:
CmdLineHandler
Direct Known Subclasses:
DefaultCmdLineHandler, HelpCmdLineHandler, LoggerCmdLineHandler, VersionCmdLineHandler

public abstract class AbstractHandlerDecorator
extends java.lang.Object
implements CmdLineHandler

An abstract class implementing the Decorator design pattern for decoration of CmdLineHandler subclasses. This class implements all methods of the CmdLineHandler interface by delegating them to a contained instance of CmdLineHandler. The intended use for this class is specification and implementation of a command option that can be reused, and can be used in series with others of the same ilk. More information on CmdLineHandlers and decorator classes can be found in the jcmdline User Guide.

Subclassing this Class

In order to subclass this class, do the following:

An example of a subclass follows (note that, but for the lack of additional constructors, this is basically how the VersionCmdLineHandler is implemented).
 public class VersionCmdLineHandler extends AbstractHandlerDecorator {
 
        private BooleanParam versionOpt;
        private String version;
 
        public MyCmdLineHandler(String version, CmdLineHandler handler) {
                super(handler);
                if (version == null || version.length() == 0) {
                        throw new IllegalArgumentException("version must be specified");
                }
                this.version = version;
                versionOpt = new BooleanParam(Strings.get("version"), Strings
                                .get("displays the version and exits"));
                versionOpt.setIgnoreRequired(true);
                setCustomOptions(new Parameter[] { versionOpt });
        }
 
        protected boolean processParsedOptions(boolean parseOk) {
                if (parseOk) {
                        if (versionOpt.isTrue()) {
                                System.out.println(version);
                                System.exit(0);
                        }
                }
                return parseOk;
        }
 }
 

A Note on Option Processing

CmdLineHandler decorator classes are particularly useful for options that perform a task and call System.exit(), such as -help or -version options. Options such as these should have the ignoreRequired attribute set to true. If not, and the command has required parameters, the option will never be accepted unless the required parameters are also specified.

Notes on the processParsedOptions() method

The following should be kept in mind when coding the processParsedOptions() method:

Version:
jcmdline Rel. 2.0.0 $Id: AbstractHandlerDecorator.java,v 1.2 2002/12/07 14:22:06 lglawrence Exp $
Author:
Lynne Lawrence

Constructor Summary
protected AbstractHandlerDecorator(CmdLineHandler handler)
          constructor
 
Method Summary
 void addArg(Parameter<?> arg)
          Adds a command line arguement.
 void addOption(Parameter<?> opt)
          Adds a command line option.
 void exitUsageError(java.lang.String errMsg)
          Prints the usage, followed by the specified error message, to stderr and exits the program with exit status = 1.
 Parameter<?> getArg(java.lang.String tag)
          gets the argument specified by tag
 java.util.List<Parameter<?>> getArgs()
          gets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command
 java.lang.String getCmdDesc()
          gets a description of the command's purpose
 java.lang.String getCmdName()
          gets the value of the command name associated with this CmdLineHandler
protected  Parameter<?>[] getCustomOptions()
          Gets options specific to a subclass.
 boolean getDieOnParseError()
          Gets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message).
 Parameter<?> getOption(java.lang.String tag)
          gets the option specified by tag
 java.util.Collection<Parameter<?>> getOptions()
          gets the value of the options associated with the command
 java.lang.String getParseError()
          Gets the error message from the last call to parse().
 CmdLineParser getParser()
          Gets the parser to be used to parse the command line.
 java.lang.String getUsage(boolean hidden)
          Gets the usage statement associated with the command.
 boolean parse(java.lang.String[] clargs)
          parse the specified command line arguments
protected abstract  boolean processParsedOptions(boolean parseStatus)
          Called from the parse() method after the command line has been parsed.
 void setArgs(Parameter<?>[] args)
          sets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command
 void setCmdDesc(java.lang.String cmdDesc)
          sets a description of the command's purpose
 void setCmdName(java.lang.String cmdName)
          sets the value of the command name associated with this CmdLineHandler
protected  void setCustomOptions(Parameter<?>[] customOptions)
          Sets options specific to a subclass.
 void setDieOnParseError(boolean val)
          Sets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message).
 void setOptions(Parameter<?>[] options)
          Sets the value of the options associated with the command
 void setParseError(java.lang.String parseError)
          Sets the error message from the last call to parse().
 void setParser(CmdLineParser parser)
          Sets the parser to be used to parse the command line.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractHandlerDecorator

protected AbstractHandlerDecorator(CmdLineHandler handler)
constructor

Parameters:
handler - the CmdLineHandler to which most methods will be delegated
Method Detail

addArg

public void addArg(Parameter<?> arg)
Adds a command line arguement.

Specified by:
addArg in interface CmdLineHandler
Parameters:
arg - the new command line argument
Throws:
java.lang.IllegalArgumentException - if arg is null.

addOption

public void addOption(Parameter<?> opt)
Adds a command line option. If an option with same tag has already been added to this CmdLineHandler, this new option will override the old.

Specified by:
addOption in interface CmdLineHandler
Parameters:
opt - the new command line option
Throws:
java.lang.IllegalArgumentException - if the tag associated with opt has already been defined for an option.

exitUsageError

public void exitUsageError(java.lang.String errMsg)
Prints the usage, followed by the specified error message, to stderr and exits the program with exit status = 1. The error message will be prefaced with 'ERROR: '. This method does not return - it exits the program with an exit status of 1.

Specified by:
exitUsageError in interface CmdLineHandler
Parameters:
errMsg - the error message

getArg

public Parameter<?> getArg(java.lang.String tag)
gets the argument specified by tag

Specified by:
getArg in interface CmdLineHandler
Parameters:
tag - identifies the argument to be returned
Returns:
The argument associated with tag. If no matching argument is found, null is returned.

getArgs

public java.util.List<Parameter<?>> getArgs()
gets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command

Specified by:
getArgs in interface CmdLineHandler
Returns:
the command's options

getCmdDesc

public java.lang.String getCmdDesc()
gets a description of the command's purpose

Specified by:
getCmdDesc in interface CmdLineHandler
Returns:
the command's description

getCmdName

public java.lang.String getCmdName()
gets the value of the command name associated with this CmdLineHandler

Specified by:
getCmdName in interface CmdLineHandler
Returns:
the command name

getDieOnParseError

public boolean getDieOnParseError()
Gets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message).

Specified by:
getDieOnParseError in interface CmdLineHandler
Returns:
true (the default) if the parse method should call System.exit() in case of a parse error, false if parse() should return to the user for error processing.
See Also:
parse()

getOption

public Parameter<?> getOption(java.lang.String tag)
gets the option specified by tag

Specified by:
getOption in interface CmdLineHandler
Parameters:
tag - identifies the option to be returned
Returns:
the option associated with tag

getOptions

public java.util.Collection<Parameter<?>> getOptions()
gets the value of the options associated with the command

Specified by:
getOptions in interface CmdLineHandler
Returns:
the command's options

getParseError

public java.lang.String getParseError()
Gets the error message from the last call to parse().

Specified by:
getParseError in interface CmdLineHandler
Returns:
the error message from the last call to parse()
See Also:
setParseError()

getParser

public CmdLineParser getParser()
Gets the parser to be used to parse the command line.

Specified by:
getParser in interface CmdLineHandler
Returns:
the parser to be used to parse the command line
See Also:
setParser()

getUsage

public java.lang.String getUsage(boolean hidden)
Gets the usage statement associated with the command.

Specified by:
getUsage in interface CmdLineHandler
Parameters:
hidden - indicates whether hidden options are to be included in the usage.
Returns:
the usage statement associated with the command

parse

public boolean parse(java.lang.String[] clargs)
parse the specified command line arguments

Specified by:
parse in interface CmdLineHandler
Parameters:
clargs - command line arguments passed to the main() method of CmdLineHandler's creating class.
Returns:
This method will exit, rather than returning, if one of the following conditions is met:
  • -h, or -h!, or -?, are amongst the command line arguments - the appropriate information is displayed on stdout, and the program exits with status 0.
  • OR, dieOnParseError is set to true AND:
    • a command line argument is incorrectly specified - an error message is displayed and the program exits with status 1.
    • a required command line argument is missing - an error message is displayed and the program exits with status 1.
If dieOnParseError is set to false, this method will return true if there are no parse errors. If there are parse errors, falseis returned and an appropriate error message may be obtained by calling getParseError().

setArgs

public void setArgs(Parameter<?>[] args)
sets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command

Specified by:
setArgs in interface CmdLineHandler
Parameters:
args - A Collection of Parameter objects. This may be null if the command accepts no command line arguments.

setCmdDesc

public void setCmdDesc(java.lang.String cmdDesc)
sets a description of the command's purpose

Specified by:
setCmdDesc in interface CmdLineHandler
Parameters:
cmdDesc - a short description of the command's purpose
Throws:
java.lang.IllegalArgumentException - if cmdDesc is null or of 0 length.

setCmdName

public void setCmdName(java.lang.String cmdName)
sets the value of the command name associated with this CmdLineHandler

Specified by:
setCmdName in interface CmdLineHandler
Parameters:
cmdName - the name of the command associated with this CmdLineHandler
Throws:
java.lang.IllegalArgumentException - if cmdName is null, or of 0 length

setDieOnParseError

public void setDieOnParseError(boolean val)
Sets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message). This flag defaults to true.

Specified by:
setDieOnParseError in interface CmdLineHandler
Parameters:
val - true (the default) if the parse method should call System.exit() in case of a parse error, false if parse() should return to the user for error processing.
See Also:
parse()

setOptions

public void setOptions(Parameter<?>[] options)
Sets the value of the options associated with the command

Specified by:
setOptions in interface CmdLineHandler
Parameters:
options - A Collection of Parameter objects. This may be null if the command accepts no command line options.

setParseError

public void setParseError(java.lang.String parseError)
Sets the error message from the last call to parse().

Specified by:
setParseError in interface CmdLineHandler
Parameters:
parseError - the error message from the last call to parse()
See Also:
getParseError()

setParser

public void setParser(CmdLineParser parser)
Sets the parser to be used to parse the command line.

Specified by:
setParser in interface CmdLineHandler
Parameters:
parser - the parser to be used to parse the command line
See Also:
getParser()

getCustomOptions

protected Parameter<?>[] getCustomOptions()
Gets options specific to a subclass.

Returns:
options specific to a subclass
See Also:
setCustomOptions()

processParsedOptions

protected abstract boolean processParsedOptions(boolean parseStatus)
Called from the parse() method after the command line has been parsed. This is where a subclass performs processing specific to its custom options.

Parameters:
parseStatus - the results of the parse() call. Note that if dieOnParseError is set, or some other AbstractHandlerDecorator exits first, this method may never be called.
Returns:
true if there were no problems concerning the custom options, else false. The return value from this method will be returned from parse().

setCustomOptions

protected void setCustomOptions(Parameter<?>[] customOptions)
Sets options specific to a subclass.

Parameters:
customOptions - options specific to a subclass
See Also:
getCustomOptions()