Package oracle.dbtools.plugin.api.cmdline

## Interface CommandProvider

-     public interface CommandProvider

  A service that provides a command line invocable operation. A `CommandProvider` implementation must enumerate the options and arguments the command accepts by annotating itself with the relevant `Command`, `Argument` and `Option` annotations.

  ### Automatic Command Line Parsing Example

       @Provides
       @Command(name = "echo", description = @TranslatableText(type = EchoMessages.class, id = EchoMessages.ECHO_COMMAND),
           arguments = { @Argument(type = String.class, name = "text",
               description = @TranslatableText(type = EchoMessages.class, id = EchoMessages.TEXT_ARGUMENT)) })
       class Echo implements CommandProvider {

         public void execute(final Map<String, Object> values) throws Exception {
           final String text = values.get("text");
           System.out.println(text);
         }
       }

  In the above example the `Command`, `TranslatableText` and `Argument` annotations are used to declaratively define how the command line arguments should be parsed.

  The `text` argument is parsed by the runtime and is passed an entry in the `Map` passed to the `execute(Map)` method.

  ### Manual Command Line Parsing Example

       @Provides
       @Command(name = "echo", description = @TranslatableText(type = EchoMessages.class, id = EchoMessages.ECHO_COMMAND),
           processArgs = true })
       class Echo implements CommandProvider {

         public int execute(final String...args) throws Exception {
           for ( String arg: args ) {
            System.out.print(arg);
            System.out.print(' ');
           }
           System.out.println();
           return 0;
         }
       }

  In the above example the command takes care of parsing the command line itself, in this case echoing each argument supplied
  Author:
    cdivilly

- - ### Method Summary

    All Methods Instance Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default int` | `execute​(java.lang.Iterable<java.lang.String> args)` | Execute the command, passing it the command line arguments to parse itself
    `default int` | `execute​(java.lang.String... args)` | Execute the command, passing it the command line arguments to parse itself
    `default void` | `execute​(java.util.Map<java.lang.String,​java.lang.Object> values)` | Execute the command

- - ### Method Detail

    - #### execute

          default void execute​(java.util.Map<java.lang.String,​java.lang.Object> values)
                        throws java.lang.Exception

      Execute the command
      Parameters:
        `values` - The values for the options and arguments of the command
      Throws:
        `java.lang.Exception` - if an error occurs during execution of the command

    - #### execute

          default int execute​(java.lang.String... args)
                       throws java.lang.Exception

      Execute the command, passing it the command line arguments to parse itself
      Parameters:
        `args` - The command line arguments to this command
      Returns:
        The exit status code for the command. If the command completes normally it must return zero, otherwise it must return a non zero value
      Throws:
        `java.lang.Exception` - if an error occurs during execution of the command
      See Also:
        `System.exit(int)`, `Runtime.exit(int)`

    - #### execute

          default int execute​(java.lang.Iterable<java.lang.String> args)
                       throws java.lang.Exception

      Execute the command, passing it the command line arguments to parse itself
      Parameters:
        `args` - The command line arguments to this command
      Returns:
        The exit status code for the command. If the command completes normally it must return zero, otherwise it must return a non zero value
      Throws:
        `java.lang.Exception` - if an error occurs during execution of the command
      Since:
        20.3.0
      See Also:
        `System.exit(int)`, `Runtime.exit(int)`