@Extensible @ThreadSafety(level=INTERFACE_NOT_THREADSAFE) public abstract class CommandLineTool extends java.lang.Object
main
method that creates an
instance of a CommandLineTool
and should invoke the
runTool(java.lang.String...)
method with the provided arguments. For
example:
public class ExampleCommandLineTool extends CommandLineTool { public static void main(String[] args) { ExampleCommandLineTool tool = new ExampleCommandLineTool(); ResultCode resultCode = tool.runTool(args); if (resultCode != ResultCode.SUCCESS) { System.exit(resultCode.intValue()); } | public ExampleCommandLineTool() { super(System.out, System.err); } // The rest of the tool implementation goes here. ... }.
out(Object...)
and err(Object...)
methods may be invoked
concurrently by any number of threads.Constructor and Description |
---|
CommandLineTool(java.io.OutputStream outStream,
java.io.OutputStream errStream)
Creates a new instance of this command-line tool with the provided
information.
|
Modifier and Type | Method and Description |
---|---|
abstract void |
addToolArguments(ArgumentParser parser)
Adds the command-line arguments supported for use with this tool to the
provided argument parser.
|
ArgumentParser |
createArgumentParser()
Creates a parser that can be used to to parse arguments accepted by
this tool.
|
boolean |
defaultsToInteractiveMode()
Indicates whether this tool defaults to launching in interactive mode if
the tool is invoked without any command-line arguments.
|
void |
doExtendedArgumentValidation()
Performs any necessary processing that should be done to ensure that the
provided set of command-line arguments were valid.
|
protected void |
doShutdownHookProcessing(ResultCode resultCode)
Performs any processing that may be needed when the JVM is shutting down,
whether because tool processing has completed or because it has been
interrupted (e.g., by a kill or break signal).
|
abstract ResultCode |
doToolProcessing()
Performs the core set of processing for this tool.
|
void |
err(java.lang.Object... msg)
Writes the provided message to the standard error stream for this tool.
|
java.io.PrintStream |
getErr()
Retrieves the print stream that will be used for standard error.
|
java.util.LinkedHashMap<java.lang.String[],java.lang.String> |
getExampleUsages()
Retrieves a set of information that may be used to generate example usage
information.
|
int |
getMaxTrailingArguments()
Retrieves the maximum number of unnamed trailing arguments that may be
provided for this tool.
|
int |
getMinTrailingArguments()
Retrieves the minimum number of unnamed trailing arguments that must be
provided for this tool.
|
java.io.PrintStream |
getOriginalErr()
Retrieves the print stream that may be used to write to the original
standard error.
|
java.io.PrintStream |
getOriginalOut()
Retrieves the print stream that may be used to write to the original
standard output.
|
java.io.PrintStream |
getOut()
Retrieves the print stream that will be used for standard output.
|
abstract java.lang.String |
getToolDescription()
Retrieves a human-readable description for this tool.
|
abstract java.lang.String |
getToolName()
Retrieves the name of this tool.
|
java.lang.String |
getToolVersion()
Retrieves a version string for this tool, if available.
|
java.lang.String |
getTrailingArgumentsPlaceholder()
Retrieves a placeholder string that should be used for trailing arguments
in the usage information for this tool.
|
void |
out(java.lang.Object... msg)
Writes the provided message to the standard output stream for this tool.
|
protected boolean |
registerShutdownHook()
Indicates whether this tool should register a shutdown hook with the JVM.
|
ResultCode |
runTool(java.lang.String... args)
Performs all processing for this command-line tool.
|
boolean |
supportsInteractiveMode()
Indicates whether this tool should provide support for an interactive mode,
in which the tool offers a mode in which the arguments can be provided in
a text-driven menu rather than requiring them to be given on the command
line.
|
protected boolean |
supportsOutputFile()
Indicates whether this tool should provide arguments for redirecting output
to a file.
|
boolean |
supportsPropertiesFile()
Indicates whether this tool supports the use of a properties file for
specifying default values for arguments that aren't specified on the
command line.
|
void |
wrapErr(int indent,
int wrapColumn,
java.lang.Object... msg)
Writes the provided message to the standard error stream for this tool,
optionally wrapping and/or indenting the text in the process.
|
void |
wrapOut(int indent,
int wrapColumn,
java.lang.Object... msg)
Writes the provided message to the standard output stream for this tool,
optionally wrapping and/or indenting the text in the process.
|
public CommandLineTool(java.io.OutputStream outStream, java.io.OutputStream errStream)
outStream
- The output stream to use for standard output. It may be
System.out
for the JVM's default standard output
stream, null
if no output should be generated,
or a custom output stream if the output should be sent
to an alternate location.errStream
- The output stream to use for standard error. It may be
System.err
for the JVM's default standard error
stream, null
if no output should be generated,
or a custom output stream if the output should be sent
to an alternate location.public final ResultCode runTool(java.lang.String... args)
addToolArguments(com.unboundid.util.args.ArgumentParser)
method.doExtendedArgumentValidation()
method.doToolProcessing()
method to do the appropriate
work for this tool.args
- The command-line arguments provided to this program.ResultCode.SUCCESS
if the tool completed its work
successfully, or some other result if a problem occurred.public abstract java.lang.String getToolName()
public abstract java.lang.String getToolDescription()
public java.lang.String getToolVersion()
null
if none is
available.public int getMinTrailingArguments()
getMaxTrailingArguments()
arguments to return nonzero values, and it must also override the
getTrailingArgumentsPlaceholder()
method to return a
non-null
value.public int getMaxTrailingArguments()
getTrailingArgumentsPlaceholder()
method to
return a non-null
value.public java.lang.String getTrailingArgumentsPlaceholder()
null
if trailing
arguments are not supported.public boolean supportsInteractiveMode()
defaultsToInteractiveMode()
returns true
, then
interactive mode may be invoked by simply launching the tool without any
arguments.true
if this tool supports interactive mode, or
false
if not.public boolean defaultsToInteractiveMode()
supportsInteractiveMode()
returns true
.true
if this tool defaults to using interactive mode if
launched without any command-line arguments, or false
if
not.public boolean supportsPropertiesFile()
true
if this tool supports the use of a properties file
for specifying default values for arguments that aren't specified
on the command line, or false
if not.protected boolean supportsOutputFile()
true
, then the tool will offer
an "--outputFile" argument that will specify the path to a file to which
all standard output and standard error content will be written, and it will
also offer a "--teeToStandardOut" argument that can only be used if the
"--outputFile" argument is present and will cause all output to be written
to both the specified output file and to standard output.true
if this tool should provide arguments for redirecting
output to a file, or false
if not.public final ArgumentParser createArgumentParser() throws ArgumentException
ArgumentException
- If there was a problem initializing the
parser for this tool.public abstract void addToolArguments(ArgumentParser parser) throws ArgumentException
parser
- The argument parser to which the arguments are to be added.ArgumentException
- If a problem occurs while adding any of the
tool-specific arguments to the provided
argument parser.public void doExtendedArgumentValidation() throws ArgumentException
doToolProcessing()
method is invoked.
Note that if the tool supports interactive mode, then this method may be
invoked multiple times to allow the user to interactively fix validation
errors.ArgumentException
- If there was a problem with the command-line
arguments provided to this program.public abstract ResultCode doToolProcessing()
protected boolean registerShutdownHook()
System.exit()
or Runtime.exit()
is called.System.halt()
or
Runtime.halt()
methods).
true
, then the
doShutdownHookProcessing(ResultCode)
method should also be
overridden to contain the logic that will be invoked when the JVM is
shutting down in a manner that calls shutdown hooks.true
if this tool should register a shutdown hook, or
false
if not.protected void doShutdownHookProcessing(ResultCode resultCode)
java.lang.Runtime.addShutdownHook
method for recommendations and
restrictions about writing shutdown hooks.resultCode
- The result code returned by the tool. It may be
null
if the tool was interrupted before it
completed processing.@ThreadSafety(level=METHOD_THREADSAFE) public java.util.LinkedHashMap<java.lang.String[],java.lang.String> getExampleUsages()
null
or empty if no example usage
information is available.public final java.io.PrintStream getOut()
public final java.io.PrintStream getOriginalOut()
@ThreadSafety(level=METHOD_THREADSAFE) public final void out(java.lang.Object... msg)
msg
- The message components that will be written to the standard
output stream. They will be concatenated together on the same
line, and that line will be followed by an end-of-line
sequence.@ThreadSafety(level=METHOD_THREADSAFE) public final void wrapOut(int indent, int wrapColumn, java.lang.Object... msg)
indent
- The number of spaces each line should be indented. A
value less than or equal to zero indicates that no
indent should be used.wrapColumn
- The column at which to wrap long lines. A value less
than or equal to two indicates that no wrapping should
be performed. If both an indent and a wrap column are
to be used, then the wrap column must be greater than
the indent.msg
- The message components that will be written to the
standard output stream. They will be concatenated
together on the same line, and that line will be
followed by an end-of-line sequence.public final java.io.PrintStream getErr()
public final java.io.PrintStream getOriginalErr()
@ThreadSafety(level=METHOD_THREADSAFE) public final void err(java.lang.Object... msg)
msg
- The message components that will be written to the standard
error stream. They will be concatenated together on the same
line, and that line will be followed by an end-of-line
sequence.@ThreadSafety(level=METHOD_THREADSAFE) public final void wrapErr(int indent, int wrapColumn, java.lang.Object... msg)
indent
- The number of spaces each line should be indented. A
value less than or equal to zero indicates that no
indent should be used.wrapColumn
- The column at which to wrap long lines. A value less
than or equal to two indicates that no wrapping should
be performed. If both an indent and a wrap column are
to be used, then the wrap column must be greater than
the indent.msg
- The message components that will be written to the
standard output stream. They will be concatenated
together on the same line, and that line will be
followed by an end-of-line sequence.