SINCE 3.4

Overview

A Talon XVM has the ability to discover annotated 'Command' methods provided by an application. Such commands can be invoked remotely by tools in an out of band fashion with an application's message driven event handlers to perform administrative functions. The command framework is designed to work in the context of command line tools, guis or for administrative applications. A command method is identified by annotating it with a @Command annotation, and its parameters are exposed by annotating its parameters with either @Option or @Argument annotations which allows commands to be invoked by passing the arguments in a command line format. 

Annotating Command methods

At its simplest, a method that is composed of primitive arguments needs only to be annotated with a Command annotation to expose it as a command that can be invoked remotely. 

The above method can than be invoked via the Robin api as: 

... the command name is identified by the name of the method and each parameter in the signature is treated as an argument to the command. 

@Command 

Above we gave a simple example of using the Command annotation to identify a command. The command can be further described by using the following command annotation elements

@Argument

The @Argument annotation can be applied to method parameters to describe and constrain arguments.

Below is an example of how an Argument annotation may be used:

@Option

The @Option annotation can be applied to method parameters. An Option differs from an argument in that it is invoked using a command line switch. Options are useful in cases where a command method signature needs to be changed as scripts written against the old command signature will continue to function.  

Below is an example of how an Argument annotation may be used:

Special Handling for boolean options

Special parsing is done for boolean options. If a boolean option is specified on the command line with no following value, then it is parsed as if a value of true were specified. The following two invocations are thus equivalent:

The second command invocation above implicitly indicates a value of true and this would hold even when the Option's defaultValue="false". The defaultValue specified in the annotation is only used If the option switch is omitted altogether.

Supported Types for Options, Arguments And Return values:

The following types are returned when describing the command usage. In Json they are represented as the name from the enumeration below. The expectation is that tools will use this options in forms. 

Command Discovery

The above command could then be discovered as follows:

Robin API

Robin Command Line Tool

Usage

listAppCommands
  This lists the commands available for an app
Usage:
  listAppCommands [-h] [-u] <xvmName> <appName> [<filter>] 
       [<-h|--help> Displays this help message (default='false')]
       [<-u|--usage> Flag that can be specified to additionally show usage
           for the commands. (default='false')]
       xvmName: The name of the XVM in which the app is running
       appName: The name of the app on which to list commands
       [filter: Optionally can be specified to list only commands that
           contain this filter in their name. '*' indicates that all commands
           should be displayed default='*']

Command Invocation

Robin API

The command above can be invoked programmatically using a Robin Controller:

Robin Script

Robin Command Line Tool

Escaping

Commands are invoked on the server using a command line style interface in which parameters are passed to the command being executing as option or argument token separated by one or more whitespace characters. The rules for escaping are straightforward:

• To pass a string with whitespace as a single token it must be wrapped in quotes for example "My Text" so that the parser can tell that it is one argument rather than two arguments. 
  • Quotes within a quoted string must be escaped, so to represent an argument "My Text" with the surrounding quotes being passed in the parameter escaped quotes must be used: "\"My Text\""
• Because the command parser treats any token starting with '-' as an option negative leading dash characters must be escaped by prefixing them with a '\', for example \-3.1456.

The following simple command serves to demonstrate when escaping is necessary. This command prints a given line to either System.err or System.out:

Passing A String with Spaces 
 

The above will result in the following being printed to System.out in the App:

My String

Passing A String with Quotes 

Note that below we escape the quote characters within the quoted string:

All of the above will result in the following being printed to System.error in the App (with the quotes preserved). Not that in the java case that the extra escapes are needed to escape the '\' character. 

ERROR [0]: "My Error"

Passing Argument Starting With A Dash

Note that below we escape the quote characters within the quoted string:

All of the above will result in the following being printed to System.error in the App (with the quotes preserved)

ERROR[-10]: --BAD_TIMES--

Examples

A Fully Annotated Command

Usage as Printed By SrvMonUtil

testCommand
A command that exercises all of the invocation APIs
 Usage:
  testCommand -b -c -n -i -l -f -d -s -m -e <aByteArgument> <aCharArgument> <aShortArgument> <aIntArgument> <aLongArgument> <aFloatArgument> <aDoubleArgument> <aStringArgument> <aCurrencyArgument> <aEnumArgument> 
       <-b|--byteOption> <1|0,> Tests a byte Option default='0'
       <-c|--charOption> <a,|b|c> Tests a char Option default='b'
       <-n|--shortOption> <300|399,> Tests a short Option default='399'
       <-i|--intOption> <200000|20000,> Tests a int Option default='200000'
       <-l|--longOption> <100000000,|2000000000> Tests a long Option
           default='100000000'
       <-f|--floatOption> <0.0,|-2.0> Tests a float Option default='0.0'
       <-d|--doubleOption> <0.0,|1.2> Tests a double Option default='1.2'
       <-s|--stringOption> <Bar|Foo,> Tests a String Option default='Foo'
       <-m|--currencyOption> <JPY|USD,> Tests a Currency Option
           default='JPY'
       <-e|--enumOption> Tests a Enum Option default='PrettyPrint'
       [aByteArgument: <1|0,> Tests a byte Arguement default='0']
       [aCharArgument: <a,|b|c> Tests a char Arguement default='a']
       [aShortArgument: <300|399,> Tests a short Arguement default='300']
       [aIntArgument: <200000|20000,> Tests a int Arguement
           default='200000']
       [aLongArgument: <100000000,|2000000000> Tests a long Arguement
           default='100000000']
       [aFloatArgument: <0.0,|-2.01> Tests a float Arguement
           default='-2.01']
       [aDoubleArgument: <0.0,|1.2> Tests a double Arguement default='0.0']
       [aStringArgument: <Bar|Foo,> Tests a String Arguement default='Foo']
       [aCurrencyArgument: <JPY|USD,> Tests a Currency Arguement
           default='USD']
       [aEnumArgument: Tests a Enum Arguement default='Minimal']

Json Command Description: