@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.
|
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 writer 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.
|
java.io.PrintStream |
getOut()
Retrieves the print writer 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.
|
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 getMaxTrailingArguments()
getTrailingArgumentsPlaceholder()
method to
return a non-null
value.public java.lang.String getTrailingArgumentsPlaceholder()
null
if trailing
arguments are not supported.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.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()
@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()
@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.