To develop console commands in more convenient and safer manner than with PluggableCommands, use AnnotatedCommands abstract class and its supplementary annotations.

Register Annotated commands either:

• as a service using BundleContext or
• using the register() method, which is available from the class

Analogically, unregister them using:

• close() method or
• ServiceRegistration.unregister()

The following specifics should be noted when creating AnnotatedCommands:

• When extending the class, the super constructor can be used to initialize with the appropriate group name, help message and BundleContext object. More parameters, for example for services, which are used from within the commands, can be added manually in the extending class’s constructor.

  public AnnotatedCommands(BundleContext bc, String name, String help)

• Commands, which are methods inside the extended abstract class, can be implemented using the @Command annotation. It automatically takes the method name as a command name. Further fields that can be added in this annotation, are:

      /**

       * The name of the commands. If not specified it default to the method name.

       */

      String name() default ""; // defaults to method name

      

      /**

       * User friendly description of the commands.

       */

      String description();

      

      /**

       * Optional command aliases.

       */

      String[] aliases() default {};

•     Parameters of the command should be specified either with:
  • @Argument annotation, which is dependent on the order of arguments, for example:

      >go 1 2 3

  In this case 1, 2 and 3 are arguments

  • @Option annotation which is given using an explicit marker, for example:

      >go –t 1 –h 2 –e 3

  In this case 1, 2 and 3 are options to the three parameters –t, -h, and –e

  You can use a combination of both, for example:
  >go 1 –t 2 2 3 –n 15

  In this case 1, 2, 3 are arguments, and options are –t = 2 , and –n = 15

•     Arguments have the following additional specifics:

        /**

         * Specifies the description of the argument.

         *

         */

      String description();

        

        /**

         * Specifies if the parameter is required or not. Usually all arguments are required. However

         * the command-line parser allows you to define the last parameters as optional. Still there is a

         * limitation that you cannot define an optional parameter and then, after it, a required one.

         *

         *

         * @return if the parameter is required.

         */

      boolean required() default true;

•     Options also have some additional specifics:

        /**

         * This specifies the name of the option. It is usually "h" or "help", "f" or "filter" .. etc.

         *

         * <p>When invoked from the command line the options is prefixed with a dash. E.g:

         * "-h" or "-help".

         *

         * <p>The command line parser will look for arguments like the one above and consider the next argument to

         * be the value of this optional parameter.

         *

         * <p>If the type of the optional parameter is boolean, then the name of the option must not be

         * followed by any additional argument.

         */

      String name();

      

        /**

         * Specifies the description of the option.

         */

      String description();

      

        /**

         * The default value of the option, when the command-line parameter is missing.

         *

         * {@link Resolver#NIL} can be used to indicate <code>null</code> as value.

         */

      String[] def();

Here is an example of a command that prints “Hello World!”, followed by its two arguments:

• a required String
• an optional character array

and then its two options:

• a String with a default value of “123”,
• an int array with default value int[1,3]:

@Command(

aliases = {

      "hw", "hello"

  },

name = "helloworld",

description = "Prints hello world!")

public void helloworld(

@Argument(description = "first arg", required = true) String arg1,

@Argument(description = "second arg", required = false) char[] arg2,

@Option(def = "123", description = "first option", name = "o") String opt1,

@Option(def = {

          "1", "3"

}, description = "second option", name = "i") int[] opt2) {

    println("Hello World!");

    println("Arguments:");

    println("Arg1:" + arg1);

    print("Arg2:");

    for (char arg : arg2) {

        print(arg + ", ");

    }

    println("");

    println("Options:");

    println("opt1:" + opt1);

    print("opt2:");

    for (int i : opt2) {

        print(i + ", ");

    }

}

The invocation of the command in the runtime is as follows (assuming ‘groupname’ is our used group name from within the AnnotatedCommands extension constructor) :

groupname>$helloworld String1 a b c -o String2 -i 2 -i 3 -i 4

Hello World!

Arguments:

Arg1:String1

Arg2:a, b, c ,

Options:

opt1:String2

opt2:2, 3, 4,

The aliases can also be used to call the command – instead of “helloworld” we could have written “hw” and “hello”.

Here we have an example of arguments and options which are collections. How to specify them is described in Supplying Arrays and Collections as Options.