Registering your Commands in Java

This is an example of the registerStandard() method to use as a discussion vehicle.

    public Receiver registerStandard() throws ParseException, IOException {
        ClientCommand cc;

        register(cc = createCommand("Garbage Collection", 
            "gc",  
            new GC()));
        cc.setTimeoutMS(60000);

        register(cc = createCommand("Echo to log",  
            "echo",  
            new Echo(),  
            "-tStr -p -km --var message --req"));
        cc.setTimeoutMS(100);

        register(cc = createCommand("Application Shutdown",  
            "kill",  
            new Kill(),
            "-tint -p -kexitCode --var exitCode --list 0 9 --def 0", 
            "-tbool -kc confirm --req"));
        cc.setTimeoutMS(60000);

        return this;
    }

The essential difference in the registration of these three commands is the complexity of the parse. It goes from no parse, to a one argument parse, and finally a parser with two arguments.

When a command is registered with the ExCon Receiver it is wrapped in an instance of a ClientCommand. You can interact a bit with the wrapper before you register it. But to do that you must create it separately from the registration. The registration method allows you to provide all of the details for registration. But the preferred means of registering is to first create the wrapper (ClientCommand) and then register the wrapper.

Creating the ClientCommand

There are 4 parameters that you can provide when creating the command wrapper (ClientCommand).

Title

final String title,

The title is displayed when the console-user uses the "help" command. A list of all commands is presented by cmdName and title. The title is optional but very helpful to the user.

e.g.: "Stack trace" is a title for the "Dump" command.

# xc help
=========================================================
Help Table of Contents  (case does not matter)
=========================================================
Dump                - Stack trace
Echo                - Echo to log
GC                  - Garbage Collection
Kill                - Application Shutdown

Command Name

final String cmdName,

The cmdName is how the command is requested. When it is requested the case does not matter so you can specify the command's name with upper and lower case letters for readability. This is required.

The command entitled "Garbage Collection" can be executed with the lowercase "gc".

# xc gc
free memory before(842,515,184) after(879,780,512) reclaimed(37,265,328)

Instance of the Command Class

final IExternalRequest cmd,

Create a new instance of your command class for this parameter. This is required. This specific instance of the command will be used each time the command is requested. So it must be re-entrant; reset all of the variables when exiting the command so that the next command can have a clean slate to work with.

Arguments to the Command

final String... parserDef

An Argument parser to move values from the command-line into the variables in your command. This is optional. But it is necessary if your command has parameters that must be resolved.

Parameters to The Registration Method

The same method parameters are available for the registration method as those that are available for the createCommand method. This is a convenience when you don't need direct access to the wrapped command (ClientCommand).

Although the code, similar to the example at the top of this page, is simpler, it does not allow access to the command wrapper.

public Receiver registerStandard() throws ParseException, IOException {  

    register("Garbage Collection",  
        "gc",  
        new GC());  

    register("Echo to log",  
        "echo",  
        new Echo(),  
        "-tStr -p -km --var message --req");  

    register("Application Shutdown",  
        "kill",  
        new Kill(),  
        "-tint -p -kexitCode --var exitCode --list 0 9 --def 0",  
        "-tbool -kc confirm --req");  

    return this;  
}

Interacting with the ClientCommand

Limiting the milliseconds in which the command can run.

cc.setTimeoutMS(long timeoutMS);

This limits the wall-clock time that a command can run before it is interrupted.