Package org.apache.sis.console
Class CommandRunner
java.lang.Object
org.apache.sis.console.CommandRunner
- Direct Known Subclasses:
AboutCommand
,FormattedOutputCommand
,HelpCommand
,MimeTypeCommand
Base class of all sub-commands.
A subclasses is initialized by the
Command
constructor,
then the run()
method is invoked by Command.run()
.- Since:
- 0.3
- Version:
- 0.8
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final boolean
true
if colors can be applied for ANSI X3.64 compliant terminal.protected final String
The name of this command, as specified by the user on the command-line.protected final boolean
true
for printing the full stack trace in case of failure.protected final Charset
The encoding specified by the"--encoding"
option.protected final PrintWriter
Error stream to the console.Any remaining parameters that are not command name or option.(package private) static CommandRunner
The instance, used byResourcesDownloader
only.protected final Locale
The locale specified by the"--locale"
option.The command-line options allowed by this sub-command, together with their values.protected final PrintWriter
Output stream to the console.(package private) final StringBuffer
(package private) static final String
Special value forarguments[commandIndex]
meaning that this sub-command is created for JUnit test purpose.protected final TimeZone
The locale specified by the"--timezone"
option.The set of legal options for this command. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
CommandRunner
(int commandIndex, String[] arguments, EnumSet<Option> validOptions) Creates a new sub-command with the given command-line arguments.(package private)
CommandRunner
(CommandRunner parent) Copies the configuration of the given sub-command. -
Method Summary
Modifier and TypeMethodDescription(package private) final void
canNotOpen
(int fileIndex, Exception e) Prints the "Cannot open …" error message followed by the message in the given exception.(package private) final void
Prints the given error message followed by the message in the given exception.(package private) final boolean
hasContradictoryOptions
(Option... exclusive) Checks if the user-provided options contains mutually exclusive options.(package private) final boolean
hasUnexpectedFileCount
(int min, int max) Checks the size of thefiles
list.protected void
Shows the help instructions for a specific command.abstract int
run()
Executes the sub-command.(package private) final boolean
Returnstrue
if the command should use the standard input.
-
Field Details
-
TEST
Special value forarguments[commandIndex]
meaning that this sub-command is created for JUnit test purpose.- See Also:
-
instance
The instance, used byResourcesDownloader
only. We use this static field as a workaround for the fact thatResourcesDownloader
is not instantiated by us, so we cannot pass theCommandRunner
instance to its constructor. -
commandName
The name of this command, as specified by the user on the command-line. May contain a mix of lower-case and upper-case letters if the user specified the command that way. -
validOptions
The set of legal options for this command.- See Also:
-
options
The command-line options allowed by this sub-command, together with their values. -
locale
The locale specified by the"--locale"
option. If no such option was provided, then this field is set to the default locale. -
timezone
The locale specified by the"--timezone"
option. If no such option was provided, then this field is set to the default timezone. -
encoding
The encoding specified by the"--encoding"
option. If no such option was provided, then this field is set to the default charset. -
colors
protected final boolean colorstrue
if colors can be applied for ANSI X3.64 compliant terminal. This is the value specified by the--colors
arguments if present, or a value inferred from the system otherwise. -
debug
protected final boolean debugtrue
for printing the full stack trace in case of failure. -
out
Output stream to the console. This output stream uses the encoding specified by the"--encoding"
argument, if presents. -
err
Error stream to the console. This stream always uses the locale encoding, since its output will typically be sent to the console even if the user redirected the standard output to a file. -
outputBuffer
The buffer whereout
anderr
output are sent, ornull
if none. This is non-null only during JUnit tests.- See Also:
-
files
Any remaining parameters that are not command name or option. They are typically file names, but can occasionally be other types like URL.
-
-
Constructor Details
-
CommandRunner
CommandRunner(CommandRunner parent) Copies the configuration of the given sub-command. This constructor is used only when a command needs to delegates part of its work to another command. -
CommandRunner
protected CommandRunner(int commandIndex, String[] arguments, EnumSet<Option> validOptions) throws InvalidOptionException Creates a new sub-command with the given command-line arguments. Thearguments
array is the same array than the one given to themain(String[])
method. The argument at indexcommandIndex
is the name of this command, and will be ignored except for the special "TEST" value which is used only at JUnit testing time.- Parameters:
commandIndex
- index of thearguments
element containing the sub-command name, or -1 if none.arguments
- the command-line arguments provided by the user.validOptions
- the command-line options allowed by this sub-command.- Throws:
InvalidOptionException
- if an illegal option has been provided, or the option has an illegal value.
-
-
Method Details
-
hasContradictoryOptions
Checks if the user-provided options contains mutually exclusive options. If an inconsistency is found, then this method prints an error message toerr
and returnstrue
.An example of a pair of mutually exclusive options is
--brief
and--verbose
.- Parameters:
exclusive
- pairs of mutually exclusive options.- Returns:
true
if two mutually exclusive options exist.
-
hasUnexpectedFileCount
final boolean hasUnexpectedFileCount(int min, int max) Checks the size of thefiles
list. If the list has an unexpected size, then this method prints an error message toerr
and returnstrue
.- Parameters:
min
- minimal number of files.max
- maximum number of files.- Returns:
true
if the list size is not in the expected bounds.
-
useStandardInput
final boolean useStandardInput()Returnstrue
if the command should use the standard input. -
canNotOpen
Prints the "Cannot open …" error message followed by the message in the given exception.- Parameters:
fileIndex
- index in thefiles
list of the file that cannot be opened.e
- the exception which occurred.
-
error
Prints the given error message followed by the message in the given exception.- Parameters:
message
- the message to print before the exception, ornull
.e
- the exception which occurred.
-
help
Shows the help instructions for a specific command. This method is invoked instead ofrun()
if the the user provided the--help
option. The default implementation builds a description from the texts associated to the givenresourceKey
in various resource bundles provided in thissis-console
module. Subclasses can override if needed.- Parameters:
resourceKey
- the key for the resource to print. This is usuallycommandName
in lower-cases.- Throws:
IOException
- should never happen, because we are writing to aPrintWriter
.
-
run
Executes the sub-command.- Returns:
- 0 on success, or an exit code if the command failed for a reason other than an uncaught Java exception.
- Throws:
Exception
- if an error occurred while executing the sub-command.
-