|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjcmdline.AbstractHandlerDecorator
public abstract class AbstractHandlerDecorator
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:
CmdLineHandler
argument or
create a CmdLineHandler
to which most method calls will be
delegated.
CmdLineHandler
along as an argument (
super(handler)
) as the first line of the constructor.
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:
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.
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; } }
System.exit()
or return its own
error, it should always return the parse error that was passed to it.
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 |
---|
protected AbstractHandlerDecorator(CmdLineHandler handler)
handler
- the CmdLineHandler to which most methods will be delegatedMethod Detail |
---|
public void addArg(Parameter<?> arg)
addArg
in interface CmdLineHandler
arg
- the new command line argument
java.lang.IllegalArgumentException
- if arg
is null.public void addOption(Parameter<?> opt)
addOption
in interface CmdLineHandler
opt
- the new command line option
java.lang.IllegalArgumentException
- if the tag associated with opt
has already been
defined for an option.public void exitUsageError(java.lang.String errMsg)
exitUsageError
in interface CmdLineHandler
errMsg
- the error messagepublic Parameter<?> getArg(java.lang.String tag)
tag
getArg
in interface CmdLineHandler
tag
- identifies the argument to be returned
tag
. If no matching
argument is found, null is returned.public java.util.List<Parameter<?>> getArgs()
getArgs
in interface CmdLineHandler
public java.lang.String getCmdDesc()
getCmdDesc
in interface CmdLineHandler
public java.lang.String getCmdName()
getCmdName
in interface CmdLineHandler
public boolean getDieOnParseError()
getDieOnParseError
in interface CmdLineHandler
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.parse()
public Parameter<?> getOption(java.lang.String tag)
tag
getOption
in interface CmdLineHandler
tag
- identifies the option to be returned
tag
public java.util.Collection<Parameter<?>> getOptions()
getOptions
in interface CmdLineHandler
public java.lang.String getParseError()
getParseError
in interface CmdLineHandler
setParseError()
public CmdLineParser getParser()
getParser
in interface CmdLineHandler
setParser()
public java.lang.String getUsage(boolean hidden)
getUsage
in interface CmdLineHandler
hidden
- indicates whether hidden options are to be included in the
usage.
public boolean parse(java.lang.String[] clargs)
parse
in interface CmdLineHandler
clargs
- command line arguments passed to the main() method of
CmdLineHandler's creating class.
dieOnParseError
is set to false
,
this method will return true if there are no parse errors. If
there are parse errors, false
is returned and an
appropriate error message may be obtained by calling
getParseError()
.public void setArgs(Parameter<?>[] args)
setArgs
in interface CmdLineHandler
args
- A Collection of Parameter
objects. This may be null if
the command accepts no command line arguments.public void setCmdDesc(java.lang.String cmdDesc)
setCmdDesc
in interface CmdLineHandler
cmdDesc
- a short description of the command's purpose
java.lang.IllegalArgumentException
- if cmdDesc
is null or of 0 length.public void setCmdName(java.lang.String cmdName)
setCmdName
in interface CmdLineHandler
cmdName
- the name of the command associated with this CmdLineHandler
java.lang.IllegalArgumentException
- if cmdName is null, or of 0 lengthpublic void setDieOnParseError(boolean val)
true
.
setDieOnParseError
in interface CmdLineHandler
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.parse()
public void setOptions(Parameter<?>[] options)
setOptions
in interface CmdLineHandler
options
- A Collection of Parameter
objects. This may be null if
the command accepts no command line options.public void setParseError(java.lang.String parseError)
setParseError
in interface CmdLineHandler
parseError
- the error message from the last call to parse()getParseError()
public void setParser(CmdLineParser parser)
setParser
in interface CmdLineHandler
parser
- the parser to be used to parse the command linegetParser()
protected Parameter<?>[] getCustomOptions()
setCustomOptions()
protected abstract boolean processParsedOptions(boolean parseStatus)
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.
true
if there were no problems concerning the custom
options, else false
. The return value from this
method will be returned from parse()
.protected void setCustomOptions(Parameter<?>[] customOptions)
customOptions
- options specific to a subclassgetCustomOptions()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |