<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="https://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
JBoss AS7 Command-line public API
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="https://community.jboss.org/people/aloubyansky">Alexey Loubyansky</a> in <i>JBoss AS 7 Development</i> - <a href="https://community.jboss.org/docs/DOC-17597">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>(Since JBoss AS 7.1.1)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>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.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Example</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Here is a simple example (which is explained in detail below) that takes a snapshot of the current server's configuration (the operation <em>:take-snapshot</em>) and then deploys myapp.ear (command <em>deploy</em>). These two actions were chosen just as an example of an operation and a command.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-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></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Starting a CLI session</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The main interface, which represents a CLI session, is <em>org.jboss.as.cli.CommandContext</em>. 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</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">
        final CommandContext ctx;
        try {
            ctx = org.jboss.as.cli.CommandContextFactory.getInstance().newCommandContext();
        } catch (CliInitializationException e) {
            // handle the exception
        }
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>There are a few other versions of the <em>newCommandContext()</em> that accept username and password, default controller host and port, in case you need to change the default values.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Connecting to the controller</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Normally, the next step will be to connect to the server controller. This can be done by invoking one of the <em>connectController()</em> 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 <em>CommandContext</em> construction time).</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">ctx.connectionController();</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If the target controller is not at the default host and port, the host and port can be specified</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">ctx.connectController(host, port);</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Both of these methods throw an instance of <em>org.jboss.as.cli.CommandLineException</em> in case the connection failed.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Executing commands and operations</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Another way to connect to the controller would be to simply execute the <em>connect</em> command. Like any other CLI command or an operation, it can be executed using <em>void handle(String line)</em> method</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">
    try {
        ctx.handle("connect");
    } catch(CommandLineException e) {
        // command failed
    }
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The <em>handle</em> method throws an instance of <em>CommandLineException</em> in case the command or the operation fails. If you are not interested in catching exceptions, there is <em>void handleSafe(String line)</em> method, which actually invokes the <em>handle</em> method but catches <em>CommandLineException</em>, logs it and sets the context's error code to a non-zero value which can be checked after the method has returned.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">
    ctx.handleSafe("connect");
    if(ctx.getExitCode != 0) {
        // connect failed
    }
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The exit code is reset automatically to zero before each command or an operation is executed.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Now, when the connection is established, any CLI command or an operation request can be executed using <em>handle</em> or <em>handleSafe</em> method. E.g.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">
    ctx.handleSafe(":take-snapshot");  // an example of an operation
    ctx.handleSafe("deploy myapp.ear");  // an example of a command
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Building and executing DMR requests</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In case you want to execute DMR requests yourself, you can use the <em>CommandContext</em> to translate commands and operations to DMR requests. E.g. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">
        ModelNode deployRequest;
        try {
            ModelNode deployRequest = ctx.buildRequest("deploy myapp.ear");
        } catch (CommandFormatException e) {
            // there was a problem building a DMR request
        }
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Then you can execute DMR requests using the context's controller client, e.g.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-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></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="https://community.jboss.org/docs/DOC-17597">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss AS 7 Development at <a href="https://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>