Package org.apache.sis.console

Class CommandRunner

java.lang.Object
org.apache.sis.console.CommandRunner
Direct Known Subclasses:
AboutCommand, FormattedOutputCommand, HelpCommand, MimeTypeCommand
abstract class CommandRunner extends Object
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

    Fields
    Modifier and Type
    Field
    Description
    protected final boolean
    colors
    true if colors can be applied for ANSI X3.64 compliant terminal.
    protected final String
    commandName
    The name of this command, as specified by the user on the command-line.
    protected final boolean
    debug
    true for printing the full stack trace in case of failure.
    protected final Charset
    encoding
    The encoding specified by the "--encoding" option.
    protected final PrintWriter
    err
    Error stream to the console.
    protected final List<String>
    files
    Any remaining parameters that are not command name or option.
    (package private) static CommandRunner
    instance
    The instance, used by ResourcesDownloader only.
    protected final Locale
    locale
    The locale specified by the "--locale" option.
    protected final EnumMap<Option,String>
    options
    The command-line options allowed by this sub-command, together with their values.
    protected final PrintWriter
    out
    Output stream to the console.
    (package private) final StringBuffer
    outputBuffer
    The buffer where out and err output are sent, or null if none.
    (package private) static final String
    TEST
    Special value for arguments[commandIndex] meaning that this sub-command is created for JUnit test purpose.
    protected final TimeZone
    timezone
    The locale specified by the "--timezone" option.
    private final EnumSet<Option>
    validOptions
    The set of legal options for this command.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    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 Type
    Method
    Description
    (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
    error(String message, Exception e)
    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 the files list.
    protected void
    help(String resourceKey)
    Shows the help instructions for a specific command.
    abstract int
    run()
    Executes the sub-command.
    (package private) final boolean
    useStandardInput()
    Returns true if the command should use the standard input.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • TEST

      static final String TEST
      Special value for arguments[commandIndex] meaning that this sub-command is created for JUnit test purpose.
      See Also:

    • instance

      static CommandRunner instance
      The instance, used by ResourcesDownloader only. We use this static field as a workaround for the fact that ResourcesDownloader is not instantiated by us, so we cannot pass the CommandRunner instance to its constructor.

    • commandName

      protected final String 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

      private final EnumSet<Option> validOptions
      The set of legal options for this command.
      See Also:

    • options

      protected final EnumMap<Option,String> options
      The command-line options allowed by this sub-command, together with their values.

    • locale

      protected final Locale locale
      The locale specified by the "--locale" option. If no such option was provided, then this field is set to the default locale.

    • timezone

      protected final TimeZone timezone
      The locale specified by the "--timezone" option. If no such option was provided, then this field is set to the default timezone.

    • encoding

      protected final Charset 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 colors
      true 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 debug
      true for printing the full stack trace in case of failure.

    • out

      protected final PrintWriter out
      Output stream to the console. This output stream uses the encoding specified by the "--encoding" argument, if presents.

    • err

      protected final PrintWriter 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

      final StringBuffer outputBuffer
      The buffer where out and err output are sent, or null if none. This is non-null only during JUnit tests.
      See Also:

    • files

      protected final List<String> 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. The arguments array is the same array than the one given to the main(String[]) method. The argument at index commandIndex 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 the arguments 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

      final boolean hasContradictoryOptions(Option... exclusive)
      Checks if the user-provided options contains mutually exclusive options. If an inconsistency is found, then this method prints an error message to err and returns true.

      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 the files list. If the list has an unexpected size, then this method prints an error message to err and returns true.
      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()
      Returns true if the command should use the standard input.

    • canNotOpen

      final void canNotOpen(int fileIndex, Exception e)
      Prints the "Cannot open …" error message followed by the message in the given exception.
      Parameters:
      fileIndex - index in the files list of the file that cannot be opened.
      e - the exception which occurred.

    • error

      final void error(String message, Exception e)
      Prints the given error message followed by the message in the given exception.
      Parameters:
      message - the message to print before the exception, or null.
      e - the exception which occurred.

    • help

      protected void help(String resourceKey) throws IOException
      Shows the help instructions for a specific command. This method is invoked instead of run() if the the user provided the --help option. The default implementation builds a description from the texts associated to the given resourceKey in various resource bundles provided in this sis-console module. Subclasses can override if needed.
      Parameters:
      resourceKey - the key for the resource to print. This is usually commandName in lower-cases.
      Throws:
      IOException - should never happen, because we are writing to a PrintWriter.

    • run

      public abstract int run() throws Exception
      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.