jcmdline
Class AbstractHandlerDecorator

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

• With regard to the subclass constructor(s):
  • All constructors should accept a CmdLineHandler argument or create a CmdLineHandler to which most method calls will be delegated.
  • They should include a call to this class's constructor, passing their contained CmdLineHandler along as an argument ( super(handler)) as the first line of the constructor.
  • In the constructor of the subclass, call setCustomOptions, specifying the options supported by the subclass. This ensures that the options are added to the contained handler, and that they will be restored should setOptions() be called on the contained handler.
• Implement the processParsedOptions() method. This method will be called after the command line has been parsed by the contained handler. It is in this method that a subclass should do its option processing.

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:

• This method may never be reached. If the dieOnParseError option is set true for the contained CmdLineHandler (which it is by default), a parse error will cause the program to exit before calling any processParsedOptions() methods.
• If this method post-processes its option value and finds it to be in error, it should either call exitUsageError() or return false, as appropriate based on the value returned by getDieOnParseError(). For example:

      if ((errorMsg = postProcess(myOpt.getValue()) != null) {
          // oops - have an error condition
          if (getDieOnParseError()) {
              exitUsageError(errorMsg);
          } else {
              return false;
          }
      }
   

• If this method does not call System.exit() or return its own error, it should always return the parse error that was passed to it.

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()