|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjcmdline.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 |
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 |
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 |
protected void setCustomOptions(Parameter[] customOptions)
customOptions
- options specific to a subclassgetCustomOptions()
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()
.public 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 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 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 setParser(CmdLineParser parser)
setParser
in interface CmdLineHandler
parser
- the parser to be used to parse the command linegetParser()
public CmdLineParser getParser()
getParser
in interface CmdLineHandler
setParser()
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 addArg(Parameter arg)
addArg
in interface CmdLineHandler
arg
- the new command line argument
java.lang.IllegalArgumentException
- if arg
is null.public java.util.List getArgs()
getArgs
in interface CmdLineHandler
public 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 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 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 java.util.Collection getOptions()
getOptions
in interface CmdLineHandler
public Parameter getOption(java.lang.String tag)
tag
getOption
in interface CmdLineHandler
tag
- identifies the option to be returned
tag
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 java.lang.String getCmdDesc()
getCmdDesc
in interface CmdLineHandler
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 java.lang.String getCmdName()
getCmdName
in interface CmdLineHandler
public java.lang.String getUsage(boolean hidden)
getUsage
in interface CmdLineHandler
hidden
- indicates whether hidden options are to be included
in the usage.
public void setParseError(java.lang.String parseError)
setParseError
in interface CmdLineHandler
parseError
- the error message from the last call to parse()getParseError()
public java.lang.String getParseError()
getParseError
in interface CmdLineHandler
setParseError()
public void exitUsageError(java.lang.String errMsg)
exitUsageError
in interface CmdLineHandler
errMsg
- the error message
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |