# Class Command

Object
Command

public final class Command extends Object
Command line interface for Apache SIS. The `main(String[])` method accepts the following actions:

> Supported command-line actions
> `help` | Show a help overview.
> `about` | Show information about Apache SIS and system configuration.
> `mime-type` | Show MIME type for the given file.
> `identifier` | Show identifiers for metadata and referencing systems in the given file.
> `metadata` | Show metadata information for the given file.
> `crs` | Show Coordinate Reference System information for the given file or code.
> `info` | Show resource-specific information (e.g., grid geometry).
> `transform` | Convert or transform coordinates from given source CRS to target CRS.
> `translate` | Rewrite a data file in another format.

Each command can accepts some of the following options:

> Supported command-line options
> `--sourceCRS` | The Coordinate Reference System of input data.
> `--targetCRS` | The Coordinate Reference System of output data.
> `--metadata` | Relative path to an auxiliary metadata file.
> `--format` | The output format: `xml`, `wkt`, `wkt1` or `text`.
> `--locale` | The locale to use for the console output.
> `--timezone` | The timezone for the dates printed to the console output.
> `--encoding` | The encoding to use for some text inputs and for console output.
> `--colors` | Whether colorized output shall be enabled.
> `--brief` | Whether the output should contain only brief information.
> `--verbose` | Whether the output should contain more detailed information.
> `--debug` | Prints full stack trace in case of failure.
> `--help` | Lists the options available for a specific command.

The `--locale`, `--timezone` and `--encoding` options apply to the command output sent to the standard output stream, but usually do not apply to the error messages sent to the standard error stream. The reason is that command output may be targeted to a client, while the error messages are usually for the operator.

## SIS installation on remote machines

Some sub-commands can operate on SIS installation on remote machines, provided that remote access has been enabled at the Java Virtual Machine startup time. See package javadoc for more information.

Since:
  0.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `INVALID_ARGUMENT_EXIT_CODE`
  The code given to `System​.exit(int)` when the program failed because of an illegal user argument.
  `static final int`
  `INVALID_COMMAND_EXIT_CODE`
  The code given to `System​.exit(int)` when the program failed because of a unknown sub-command.
  `static final int`
  `INVALID_OPTION_EXIT_CODE`
  The code given to `System​.exit(int)` when the program failed because of a unknown option.
  `static final int`
  `IO_EXCEPTION_EXIT_CODE`
  The code given to `System​.exit(int)` when the program failed because of an `IOException`.
  `static final int`
  `OTHER_ERROR_EXIT_CODE`
  The code given to `System​.exit(int)` when the program failed for a reason other than the ones enumerated in the above constants.
  `static final int`
  `SQL_EXCEPTION_EXIT_CODE`
  The code given to `System​.exit(int)` when the program failed because of an `SQLException`.
  `static final int`
  `UNKNOWN_STORAGE_EXIT_CODE`
  The code given to `System​.exit(int)` when a file given in argument uses an unknown file format.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Command(Object[] args)`
  Creates a new command for the given arguments.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `configureLogging()`
  Loads the logging configuration file if not already done, then configures the monoline formatter.
  `static int`
  `exitCodeFor(Throwable cause)`
  Returns the exit code for the given exception, or 0 if unknown.
  `static void`
  `main(String[] args)`
  Prints the information to the standard output stream.
  `int`
  `run()`
  Runs the command.
  `PrintWriter`
  `writer(boolean error)`
  Returns the writer where this command sends its output.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### INVALID_COMMAND_EXIT_CODE

    public static final int INVALID_COMMAND_EXIT_CODE
    The code given to `System​.exit(int)` when the program failed because of a unknown sub-command.
    See Also:
      - Constant Field Values

  - ### INVALID_OPTION_EXIT_CODE

    public static final int INVALID_OPTION_EXIT_CODE
    The code given to `System​.exit(int)` when the program failed because of a unknown option. The set of valid options depend on the sub-command to execute.
    See Also:
      - Constant Field Values

  - ### INVALID_ARGUMENT_EXIT_CODE

    public static final int INVALID_ARGUMENT_EXIT_CODE
    The code given to `System​.exit(int)` when the program failed because of an illegal user argument. The user arguments are everything which is not a command name or an option. They are typically file names, but can occasionally be other types like URL.
    See Also:
      - Constant Field Values

  - ### UNKNOWN_STORAGE_EXIT_CODE

    public static final int UNKNOWN_STORAGE_EXIT_CODE
    The code given to `System​.exit(int)` when a file given in argument uses an unknown file format.
    See Also:
      - Constant Field Values

  - ### IO_EXCEPTION_EXIT_CODE

    public static final int IO_EXCEPTION_EXIT_CODE
    The code given to `System​.exit(int)` when the program failed because of an `IOException`.
    See Also:
      - Constant Field Values

  - ### SQL_EXCEPTION_EXIT_CODE

    public static final int SQL_EXCEPTION_EXIT_CODE
    The code given to `System​.exit(int)` when the program failed because of an `SQLException`.
    See Also:
      - Constant Field Values

  - ### OTHER_ERROR_EXIT_CODE

    public static final int OTHER_ERROR_EXIT_CODE
    The code given to `System​.exit(int)` when the program failed for a reason other than the ones enumerated in the above constants.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Command

    public Command(Object[] args) throws InvalidCommandException, InvalidOptionException
    Creates a new command for the given arguments. The first value in the given array which is not an option is taken as the command name. All other values are options or filenames.

    Arguments should be instances of `String`, except the arguments for input or output files which can be any types accepted by `StorageConnector`. This includes, for example, `String`, `File`, `Path`, `URL`, etc.

    Parameters:
      `args` - the command-line arguments.
    Throws:
      `InvalidCommandException` - if an invalid command has been given.
      `InvalidOptionException` - if the given arguments contain an invalid option.

- ## Method Details

  - ### configureLogging

    public static void configureLogging()
    Loads the logging configuration file if not already done, then configures the monoline formatter. This method performs two main tasks:
    1. If the "java.util.logging.config.file" is not set, then try to set it to `$SIS_HOME/conf/logging​.properties` and load that file.
    2. If the `"derby​.stream​.error​.file"` system property is not defined, then try to set it to `$SIS_HOME/log/derby​.log`.
    3. If the configuration file declares `MonolineFormatter` as the console formatter, ensures that the formatter is loaded and resets its colors depending on whether X364 seems to be supported.
    This method can be invoked at initialization time, such as the beginning of `main(…)` static method.
    Since:
      1.5
    See Also:
      - `MonolineFormatter​.install()`

  - ### writer

    public PrintWriter writer(boolean error)
    Returns the writer where this command sends its output.
    Parameters:
      `error` - `true` for the error stream, or `false` for the standard output stream.
    Returns:
      the stream where this command sends it output.
    Since:
      1.5

  - ### run

    public int run() throws Exception
    Runs the command. If an exception occurs, then the exception message is sent to the error output stream before to be thrown. Callers can map the exception to a system exit code by the `exitCodeFor(Throwable)` method.
    Returns:
      0 on success, or an exit code if the command failed for a reason other than a Java exception.
    Throws:
      `Exception` - if an error occurred during the command execution. This is typically, but not limited, to `IOException`, `SQLException`, `DataStoreException` or `TransformException`.

  - ### exitCodeFor

    public static int exitCodeFor(Throwable cause)
    Returns the exit code for the given exception, or 0 if unknown. This method iterates through the causes until an exception matching a `*_EXIT_CODE` constant is found.
    Parameters:
      `cause` - the exception for which to get the exit code.
    Returns:
      the exit code as one of the `*_EXIT_CODE` constant, or `OTHER_ERROR_EXIT_CODE` if unknown.

  - ### main

    public static void main(String[] args)
    Prints the information to the standard output stream.
    Parameters:
      `args` - command-line options.