Writing an ExCon command

The ExCon Receiver is a broker of commands that are request to be run by the Sender. And Sender is a command-line utility that you would interact with to run the commands.

In these examples that follow it will be assumed that your application also has the code to create the Receiver before registering these commands and to send it the go() message afterwards. This won't be repeated in each of the examples.

Standard Commands
ExCon comes prepackaged with several "standard commands".

rcvr.registerStandard();

This will add several commands to the "Sender menu" that perform functions like garbage collection, stack dumps, JVM termination and so on. All of the functions are pre-written as commands.

Writing your own Commands
Every command class must implement the ExCon interface called IExternalRequest. It requires a method called execute() that you must implement. It is the method that is called when the command is requested to be run. This is what the "Echo" command looks like.

package com.obdobion.ExCon.standard;
import org.apache.log4j.Logger;
import com.obdobion.ExCon.ClientCommand;
import com.obdobion.ExCon.IExternalRequest;

public class Echo implements IExternalRequest {

    static final private Logger logger = Logger.getLogger(Echo.class.getName());

    public String message;

    public Echo() {
    }

    public String execute(final ClientCommand cc) throws Exception {
        logger.info(message);
        return message;
    }
}

Echo is more of an interesting test class that a command that implements a real-world feature. But it serves the purpose here of showing off the framework of a command within ExCon.

The purpose of this command is the echo whatever you type in at the console back to the console. And also to write the same message to the log of your application. The execute() method returns a String value. It is the response given to the Sender and ultimately displayed on the console. That is true for all commands.

You may have wondered how the message to be echoed makes it from the command-line in the first place and into this Echo command. Argument does that part for us.

Writing Commands as Anonymous Inner Classes

Since commands have such a small "footprint" in your application you may not want to write classes for each of them. You can in-stream them by using inner classes.

Since this is an anonymous inner class it has to be used within the context of actually registering it. So this example shows the necessary surround code for the [Registering your Commands in Java] with the ExCon receiver. The parser definition is also shown as part of the registration process. This echo command requires a parser to get the "message" from the command-line into the command.

public class MyApplicationClass {
private void myRegistration() {
    rcvr.register("echo", new IExternalRequest() {

        public String message;

        public String execute(final ClientCommand cc) throws Exception {
              logger.info(message);
              return message;
        }
    }, new String[] {"-t String -k m --pos --var message --required"});
}}

This is very nearly the same as creating the class like the first example and registering it like this.

public class MyApplicationClass {
private void myRegistration() {
    rcvr.register(
        "echo", 
        new Echo(), 
        new String[] {"-t String -k m --pos --var message --required"});
}}

This command would be accessed from the command-line by its name "echo".

> xc echo 'Hello World'

< Hello World