(Since JBoss AS 7.1.1)

This article describes how to start a CLI session to execute commands and operations from a Java application or to simply leverage the functionality implemented in the CLI to, e.g., only translate commands and operations from their string form into DMR operation requests and execute them using another client.

Example

Here is a simple example (which is explained in detail below) that takes a snapshot of the current server's configuration (the operation :take-snapshot) and then deploys myapp.ear (command deploy). These two actions were chosen just as an example of an operation and a command.

{code}
        // Initialize the CLI context
        final CommandContext ctx;
        try {
            ctx = CommandContextFactory.getInstance().newCommandContext();
        } catch(CliInitializationException e) {
            throw new IllegalStateException("Failed to initialize CLI context", e);
        }
 
        try {
            // connect to the server controller
            ctx.connectController();
 
            // execute commands and operations
            ctx.handle(":take-snapshot");
            ctx.handle("deploy myapp.ear");
        } catch (CommandLineException e) {
            // the operation or the command has failed
        } finally {
            // terminate the session and
            // close the connection to the controller
            ctx.terminateSession();
        } 
{code}

Starting a CLI session

The main interface, which represents a CLI session, is org.jboss.as.cli.CommandContext. This interface declares methods to connect to the server's controller, execute commands and operations and much more. So, the first step to start a CLI session is to obtain an instance of this interface. The simplest way to do it is

{code}
        final CommandContext ctx;
        try {
            ctx = org.jboss.as.cli.CommandContextFactory.getInstance().newCommandContext();
        } catch (CliInitializationException e) {
            // handle the exception
        }
{code}

There are a few other versions of the newCommandContext() that accept username and password, default controller host and port, in case you need to change the default values.

Connecting to the controller

Normally, the next step will be to connect to the server controller. This can be done by invoking one of the connectController() methods.  E.g. the following method will attempt to connect using the default host and port (which is localhost:9999 or the ones provided at the CommandContext construction time).

{code}ctx.connectionController();{code}

If the target controller is not at the default host and port, the host and port can be specified

{code}ctx.connectController(host, port);{code}

Both of these methods throw an instance of org.jboss.as.cli.CommandLineException in case the connection failed.

Executing commands and operations

Another way to connect to the controller would be to simply execute the connect command. Like any other CLI command or an operation, it can be executed using void handle(String line) method

{code}
    try {
        ctx.handle("connect");
    } catch(CommandLineException e) {
        // command failed
    } 
{code}

The handle method throws an instance of CommandLineException in case the command or the operation fails. If you are not interested in catching exceptions, there is void handleSafe(String line) method, which actually invokes the handle method but catches CommandLineException, logs it and sets the context's error code to a non-zero value which can be checked after the method has returned.

{code}
    ctx.handleSafe("connect");
    if(ctx.getExitCode != 0) {
        // connect failed
    } 
{code}

The exit code is reset automatically to zero before each command or an operation is executed.

Now, when the connection is established, any CLI command or an operation request can be executed using handle or handleSafe method. E.g.

{code}
    ctx.handleSafe(":take-snapshot");  // an example of an operation
    ctx.handleSafe("deploy myapp.ear");  // an example of a command 
{code}

Building and executing DMR requests

In case you want to execute DMR requests yourself, you can use the CommandContext to translate commands and operations to DMR requests. E.g.

{code}
        ModelNode deployRequest;
        try {
            ModelNode deployRequest = ctx.buildRequest("deploy myapp.ear");
        } catch (CommandFormatException e) {
            // there was a problem building a DMR request
        } 
{code}

Then you can execute DMR requests using the context's controller client, e.g.

{code}
        ModelControllerClient client = ctx.getModelControllerClient();
        if(client != null) {
            try {
                client.execute(deployRequest);
            } catch (IOException e) {
                // client failed to execute the request
            }
        } else {
            // the client is not available, meaning the connection to the controller
            // has not been established, which means ctx.connectController(...)
            // or ctx.handle("connect") haven't been executed before
        }
{code}