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:

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. 

Valid Arguments and Options types:

• boolean or Boolean
• byte or Byte
• char or Char
• short or Short
• int or Integer
• long or Long
• float or Float
• double or Double
• date or Date
• String
• Enumerations (converted to/from a String when sent over the wire). 

Valid return types

All of the support argument types above and void. 

Registering Command Handlers with the runtime.

@AppCommandHandlerContainersAccessor

Any @Command annotated method in the main application class will be discovered by a Talon XVM. If additional classes in your application contain configured fields or methods, they can be exposed to the server using the @AppCommandHandlerContainersAccessor annotation which should add all objects that should be introspected for command handlers. 

Example:

Configuration Discovery in Hornet

For Topic Oriented Applications, any @Managed object will be introspected for @Command methods. See ManagedObjectLocator. The DefaultManagedObjectLocator for Hornet calls TopicOrientedApplication.addAppCommandHandlerContainers(Set), so unless your application provides its own managed object locator, additional configured containers can be added by overriding addConfiguredContainers():

Invoking Annotated Commands

Annotated command handlers can be discovered and invoked by deployment tools such as Robin and Lumino via admin connections made to the XVM in which the application is running. 

Examples / Appendix

A Fully Annotated Command

The below command handler exercises all of the 

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: