...
| Status | ||||
|---|---|---|---|---|
|
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.
...
| Note |
|---|
Because command handlers are not executed on the application's business logic thread they are not allowed to touch application state. In general applications that intend to pass values back to command handlers should do so through member variables that are not part of the applications HA state that are declare as volatile. Alternatively, a command handler may inject a message into the application to perform logic that works with application state, but this is considered advanced usage as doing so is not a fault tolerant and blurs the lines between application and administrative traffic. |
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 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
| Parameter | Type | Description | Default |
|---|---|---|---|
| aliases | String [] | Returns the aliases used to invoke this command. This can be useful in cases where a command's | none |
| description | String | A description of the command. This is used by tools to expose usage information for the command. It is a good idea to provide a description on commands as it provides tools with the ability to provide | none |
| name | String | Returns the name of the command. If this parameter is omitted on an annotated Method then the name will default to the method name. | none |
| parseOptions | boolean | Whether or not the command parser should attempt to parse options or if this command is | true |
@Argument
The @Argument annotation can be applied to method parameters to describe and constrain arguments.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
@Command(name = "resetOrderStats",
description="Resets the number of orders processed")
public int resetOrdersProcessed(@Option(shortForm = 'v', longForm ="verbose", defaultValue="false")
boolean verbose,
@Argument(name = "newOrderProcessingCount", position=1)
long newNumOrdersProcessed) |
@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.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
@Command(name = "resetOrderStats",
description="Resets the number of orders processed")
public int resetOrdersProcessed(@Option(shortForm = 'v', longForm ="verbose", defaultValue="false")
boolean verbose,
@Argument(name = "newOrderProcessingCount", position=1)
long newNumOrdersProcessed) |
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.
...
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@Command methods, they can be exposed to the Talon server using the @AppCommandHandlerContainersAccessor annotation which should add all objects that should be introspected for command handlers.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
@AppHAPolicy(HAPolicy.EventSourcing)
public static class MyApp {
MyOtherClass someOtherClass = new MyOtherClass();
@AppCommandHandlerContainersAccessor
public void getCommandHandlers(Set<Object> containers) {
containers.add(someOtherClass );
}
}
class MyOtherClass {
volatile int count = 0;
MyOtherClass() {
}
@Command(name = "getCount",
description="Returns a counter value")
public int getCount() {
return count;
}
} |
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():
| Code Block | ||||
|---|---|---|---|---|
| ||||
@AppHAPolicy(HAPolicy.EventSourcing)
public static class MyApp {
MyOtherClass someOtherClass = new MyOtherClass();
@Override
public void addAppCommandHandlerContainers(Set<Object> containers) {
containers.add(someOtherClass );
}
}
class MyOtherClass {
volatile int count = 0;
MyOtherClass() {
}
@Command(name = "getCount",
description="Returns a counter value")
public int getCount() {
return count;
}
} |
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
| Code Block | ||||
|---|---|---|---|---|
| ||||
@Command(name = "testCommand", aliases = { "TestCommandAlias" }, description = "A command that exercises all of the invocation APIs")
public String testCommand(@Option(shortForm = 'b', longForm = "byteOption", required = true, description = "A byte Option", validOptions = { "0,", "1" }, defaultValue = "0") byte aByteOption,
@Option(shortForm = 'c', longForm = "charOption", required = true, description = "A char Option", validOptions = { "a,", "b", "c" }, defaultValue = "b") char aCharOption,
@Option(shortForm = 'n', longForm = "shortOption", required = true, description = "A short Option", validOptions = { "399,", "300" }, defaultValue = "399") short aShortOption,
@Option(shortForm = 'i', longForm = "intOption", required = true, description = "An int Option", validOptions = { "20000,", "200000" }, defaultValue = "200000") int aIntOption,
@Option(shortForm = 'l', longForm = "longOption", required = true, description = "A long Option", validOptions = { "100000000,", "2000000000" }, defaultValue = "100000000") long aLongOption,
@Option(shortForm = 'f', longForm = "floatOption", required = true, description = "A float Option", validOptions = { "0.0,", "-2.0" }, defaultValue = "0.0") float aFloatOption,
@Option(shortForm = 'd', longForm = "doubleOption", required = true, description = "A double Option", validOptions = { "0.0,", "1.2" }, defaultValue = "1.2") double aDoubleOption,
@Option(shortForm = 's', longForm = "stringOption", required = true, description = "A String Option", validOptions = { "Foo,", "Bar" }, defaultValue = "Foo") String aStringOption,
@Option(shortForm = 'm', longForm = "currencyOption", required = true, description = "A Currency Option", validOptions = { "USD,", "JPY" }, defaultValue = "JPY") Currency aCurrencyOption,
@Option(shortForm = 'e', longForm = "enumOption", required = true, description = "An Enum Option", defaultValue = "PrettyPrint") JsonPrettyPrintStyle aEnumOption,
@Argument(position = 1, required = true, name = "aByteArgument", description = "A byte Arguement", validOptions = { "0,", "1" }, defaultValue = "0") byte aByteArgument,
@Argument(position = 2, required = true, name = "aCharArgument", description = "A char Arguement", validOptions = { "a,", "b", "c" }, defaultValue = "a") char aCharArgument,
@Argument(position = 3, required = true, name = "aShortArgument", description = "A short Arguement", validOptions = { "399,", "300" }, defaultValue = "300") short aShortArgument,
@Argument(position = 4, required = true, name = "aIntArgument", description = "An int Arguement", validOptions = { "20000,", "200000" }, defaultValue = "200000") int aIntArgument,
@Argument(position = 5, required = true, name = "aLongArgument", description = "A long Arguement", validOptions = { "100000000,", "2000000000" }, defaultValue = "100000000") long aLongArgument,
@Argument(position = 6, required = true, name = "aFloatArgument", description = "A float Arguement", validOptions = { "0.0,", "-2.01" }, defaultValue = "-2.01") float aFloatArgument,
@Argument(position = 7, required = true, name = "aDoubleArgument", description = "A double Arguement", validOptions = { "0.0,", "1.2" }, defaultValue = "0.0") double aDoubleArgument,
@Argument(position = 8, required = true, name = "aStringArgument", description = "A String Arguement", validOptions = { "Foo,", "Bar" }, defaultValue = "Foo") String aStringArgument,
@Argument(position = 9, required = true, name = "aCurrencyArgument", description = "A Currency Arguement", validOptions = { "USD,", "JPY" }, defaultValue = "USD") Currency aCurrencyArgument,
@Argument(position = 10, required = true, name = "aEnumArgument", description = "An Enum Arguement", defaultValue = "Minimal") JsonPrettyPrintStyle aEnumArgument) throws Exception {
return "Received Arguments: " + Arrays.asList(new Object[] {
aByteOption,
aCharOption,
aShortOption,
aIntOption,
aLongOption,
aFloatOption,
aDoubleOption,
aStringOption,
aCurrencyOption,
aEnumOption,
aByteArgument,
aCharArgument,
aShortArgument,
aIntArgument,
aLongArgument,
aFloatArgument,
aDoubleArgument,
aStringArgument,
aCurrencyArgument,
aEnumArgument }).toString();
} |
Usage as Printed By SrvMonUtil
| No Format |
|---|
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:
| Code Block | ||
|---|---|---|
| ||
"name": "testCommand",
"aliases": [
"TestCommandAlias"
],
"description": "A command that exercises all of the invocation APIs",
"additionalArguments": false,
"arguments": [
{
"position": 1,
"required": true,
"type": "BYTE",
"name": "aByteArgument",
"defaultValue": "0",
"validValues": [
"1",
"0,"
],
"description": "Tests a byte Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 2,
"required": true,
"type": "CHAR",
"name": "aCharArgument",
"defaultValue": "a",
"validValues": [
"a,",
"b",
"c"
],
"description": "Tests a char Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 3,
"required": true,
"type": "SHORT",
"name": "aShortArgument",
"defaultValue": "300",
"validValues": [
"300",
"399,"
],
"description": "Tests a short Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 4,
"required": true,
"type": "INT",
"name": "aIntArgument",
"defaultValue": "200000",
"validValues": [
"200000",
"20000,"
],
"description": "Tests a int Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 5,
"required": true,
"type": "LONG",
"name": "aLongArgument",
"defaultValue": "100000000",
"validValues": [
"100000000,",
"2000000000"
],
"description": "Tests a long Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 6,
"required": true,
"type": "FLOAT",
"name": "aFloatArgument",
"defaultValue": "-2.01",
"validValues": [
"0.0,",
"-2.01"
],
"description": "Tests a float Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 7,
"required": true,
"type": "DOUBLE",
"name": "aDoubleArgument",
"defaultValue": "0.0",
"validValues": [
"0.0,",
"1.2"
],
"description": "Tests a double Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 8,
"required": true,
"type": "STRING",
"name": "aStringArgument",
"defaultValue": "Foo",
"validValues": [
"Bar",
"Foo,"
],
"description": "Tests a String Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 9,
"required": true,
"type": "STRING",
"name": "aCurrencyArgument",
"defaultValue": "USD",
"validValues": [
"JPY",
"USD,"
],
"description": "Tests a Currency Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"position": 10,
"required": true,
"type": "STRING",
"name": "aEnumArgument",
"defaultValue": "Minimal",
"description": "Tests a Enum Arguement",
"_xFieldBitmask_": [
0
],
"xRogType": 0
}
],
"options": [
{
"shortForm": "b",
"required": true,
"type": "BYTE",
"longForm": "byteOption",
"defaultValue": "0",
"validValues": [
"1",
"0,"
],
"description": "Tests a byte Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "c",
"required": true,
"type": "CHAR",
"longForm": "charOption",
"defaultValue": "b",
"validValues": [
"a,",
"b",
"c"
],
"description": "Tests a char Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "n",
"required": true,
"type": "SHORT",
"longForm": "shortOption",
"defaultValue": "399",
"validValues": [
"300",
"399,"
],
"description": "Tests a short Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "i",
"required": true,
"type": "INT",
"longForm": "intOption",
"defaultValue": "200000",
"validValues": [
"200000",
"20000,"
],
"description": "Tests a int Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "l",
"required": true,
"type": "LONG",
"longForm": "longOption",
"defaultValue": "100000000",
"validValues": [
"100000000,",
"2000000000"
],
"description": "Tests a long Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "f",
"required": true,
"type": "FLOAT",
"longForm": "floatOption",
"defaultValue": "0.0",
"validValues": [
"0.0,",
"-2.0"
],
"description": "Tests a float Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "d",
"required": true,
"type": "DOUBLE",
"longForm": "doubleOption",
"defaultValue": "1.2",
"validValues": [
"0.0,",
"1.2"
],
"description": "Tests a double Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "s",
"required": true,
"type": "STRING",
"longForm": "stringOption",
"defaultValue": "Foo",
"validValues": [
"Bar",
"Foo,"
],
"description": "Tests a String Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "m",
"required": true,
"type": "STRING",
"longForm": "currencyOption",
"defaultValue": "JPY",
"validValues": [
"JPY",
"USD,"
],
"description": "Tests a Currency Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
},
{
"shortForm": "e",
"required": true,
"type": "STRING",
"longForm": "enumOption",
"defaultValue": "PrettyPrint",
"description": "Tests a Enum Option",
"_xFieldBitmask_": [
0
],
"xRogType": 0
}
],
"returnType": "VOID",
"_xFieldBitmask_": [
0
],
"xRogType": 0
} |
...