<!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;">
created 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.</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 explain 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) {
            // one of the commands 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>  </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 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 handle 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 handle 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>  </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 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 operation request can be executed using handle 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>