<!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="http://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;">
Format of a Detyped Operation Request
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/bstansberry%40jboss.com">Brian Stansberry</a> in <i>JBoss AS7 Development</i> - <a href="http://community.jboss.org/docs/DOC-16336">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>The basic method a user of the AS 7 programmatic managment API would use it very simple:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>     <span style="font-family: courier new,courier;">ModelNode execute(ModelNode operation) throws CancellationException, IOException;</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>where the return value is the detyped representation of the response, and <span style="font-family: courier new,courier;">operation</span> is the detyped representation of the operating being invoked.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The purpose of this article is to document the structure of <span style="font-family: courier new,courier;">operation.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Simple Operations</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A text representation of simple operation would look like this:</p><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><pre class="jive-pre"><code class="jive-code">{
    "op" => "write-core-threads",
    "op-addr" => [
        ("profile" => "production"),
        ("subsystem" => "threads"),
        ("bounded-queue-thread-pool" => "pool1")
    ],
    "count" => 0,
    "per-cpu" => 20
}
</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><p>Java code to produce that output would be:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">ModelNode op = <font color="navy"><b>new</b></font> ModelNode();
op.get(<font color="red">"op"</font>).set(<font color="red">"setCoreThreads"</font>);
ModelNode addr = opB.get(<font color="red">"op-addr"</font>);
addr.add(<font color="red">"base"</font>, <font color="red">"domain"</font>);
addr.add(<font color="red">"profile"</font>, <font color="red">"production"</font>);
addr.add(<font color="red">"subsystem"</font>, <font color="red">"threads"</font>);
addr.add(<font color="red">"bounded-queue-thread-pool"</font>, <font color="red">"pool1"</font>);
op.get(<font color="red">"count"</font>).set(0);
op.get(<font color="red">"per-cpu"</font>).set(20);
 
System.out.println(op);
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The order in which the items appear in the request is not relevant. The required elements are:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">op</span> -- String -- The name of the operation being invoked.</li><li><span style="font-family: courier new,courier;">op-addr</span> -- the address of the managed resource against which the request should be executed.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The other key/value pairs are parameter names and their values. The names and values should match what is specified in the operation's <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-16317">description</a>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Parameters may have any name, except for <span style="font-family: courier new,courier;">op</span>, <span style="font-family: courier new,courier;">op-addr</span> and <span style="font-family: courier new,courier;">rollout-plan</span>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Composite Operations</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The root resource managed by a (Domain|Host|Server)Controller will expose an operation named "composite".   This operation executes a list of other operations as a (semi-)atomic unit.  The structure of the request for the "composite" operations has the same fundamental structure as a simple operation (operation name, address, params as key value pairs.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre ___default_attr="plain" class="jive_text_macro jive_macro_code"><pre class="jive-pre"><code class="jive-code">{
    "op" => "composite",
    "op-addr" => [],
    "steps" => [
         {
              "op" => "write-core-threads",
              "op-addr" => [
                   ("profile" => "production"),
                   ("subsystem" => "threads"),
                   ("bounded-queue-thread-pool" => "pool1")
              ],
              "count" => 0,
              "per-cpu" => 20
         },
         {
              "op" => "write-core-threads",
              "op-addr" => [
                   ("profile" => "production"),
                   ("subsystem" => "threads"),
                   ("bounded-queue-thread-pool" => "pool2")
              ],
              "count" => 5,
              "per-cpu" => 10
         }
    ],
    "rollback-on-runtime-failure" => false
}
</code></pre>
<br/><br/><br/><br/><br/></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The "composite" operation takes two parameters:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">steps</span> -- a list, where each item in the list has the same structure as a simple operation request. In the example above each of the two steps is modifying the thread pool configuration for a different pool. There need not be any particular relationship between the steps.</li><li><span style="font-family: courier new,courier;">rollback-on-runtime-failure</span> -- boolean, optional, defaults to <span style="font-family: courier new,courier;">true</span>. Whether steps that successfully execute should be reverted if other steps fail at runtime. Note that if any steps modify the persistent configuration, and any of those steps fail, all steps will be reverted. Partial/incomplete changes to the persistent configuration are not allowed. So, this flag only deals with what happens if there is a problem applying an operation to the running state of a server (e.g. actually increasing the size of a runtime thread pool.)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Operations with a Rollout Plan</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Operations targetted at domain or host level resources can potentially impact multiple servers. Such operations can include a "rollout plan" detailing the sequence in which the operation should be applied to servers as well as policies for detailing whether the operation should be reverted if it fails to execute successfully on some servers.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If the operation includes a rollout plan, the structure is as follows:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre ___default_attr="plain" class="jive_text_macro jive_macro_code"><p><span style="font-family: courier new,courier;">{</span></p><p><span style="font-family: courier new,courier;">    "op" => "write-core-threads",</span></p><p><span style="font-family: courier new,courier;">    "op-addr" => [</span></p><p><span style="font-family: courier new,courier;">        ("profile" => "production"),</span></p><p><span style="font-family: courier new,courier;">        ("subsystem" => "threads"),</span></p><p><span style="font-family: courier new,courier;">        ("bounded-queue-thread-pool" => "pool1")</span></p><p><span style="font-family: courier new,courier;">    ],</span></p><p><span style="font-family: courier new,courier;">    "count" => 0,</span></p><p><span style="font-family: courier new,courier;">    "per-cpu" => 20,</span></p><p><span style="font-family: courier new,courier;">    "rollout-plan" => {</span></p><p><span style="font-family: courier new,courier;">        "in-series" => [</span></p><p><span style="font-family: courier new,courier;">            {</span></p><p><span style="font-family: courier new,courier;">                "concurrent-groups" => {</span></p><p><span style="font-family: courier new,courier;">                    "groupA" => {</span></p><p><span style="font-family: courier new,courier;">                        "rolling-to-servers" => true,</span></p><p><span style="font-family: courier new,courier;">                        "max-failure-percentage" => 20</span></p><p><span style="font-family: courier new,courier;">                    },</span></p><p><span style="font-family: courier new,courier;">                    "groupB" => undefined</span></p><p><span style="font-family: courier new,courier;">                },</span></p><p><span style="font-family: courier new,courier;">                "server-group" => {"groupC" => {</span></p><p><span style="font-family: courier new,courier;">                        "rolling-to-servers" => false,</span></p><p><span style="font-family: courier new,courier;">                        "max-failed-servers" => 1</span></p><p><span style="font-family: courier new,courier;">                    }}</span></p><p><span style="font-family: courier new,courier;">            },</span></p><p><span style="font-family: courier new,courier;">            {"server-group" => {"groupC" => undefined}},</span></p><p><span style="font-family: courier new,courier;">            {"concurrent-groups" => {</span></p><p><span style="font-family: courier new,courier;">                    "groupD" => {</span></p><p><span style="font-family: courier new,courier;">                        "rolling-to-servers" => true,</span></p><p><span style="font-family: courier new,courier;">                        "max-failure-percentage" => 20</span></p><p><span style="font-family: courier new,courier;">                    },</span></p><p><span style="font-family: courier new,courier;">                    "groupE" => undefined</span></p><p><span style="font-family: courier new,courier;">                }}</span></p><p><span style="font-family: courier new,courier;">        ]</span></p><p><span style="font-family: courier new,courier;">    }, <br/></span></p><p><span style="font-family: courier new,courier;">    "rollback-across-groups" => true</span></p><p><span style="font-family: courier new,courier;">}</span></p></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>As you can see, the rollout plan is simply another structure at the same level as op, op-addr and the operation parameters. The root node of the structure allows two children:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">in-series</span> -- a list -- A list of steps that are to be performed in series, with each step reaching completion before the next step is executed. Each step involves the application of the operation to the servers in one or more server groups. See below for details on each element in the list.<span style="font-family: courier new,courier;"> </span></li><li><span style="font-family: courier new,courier;">rollback-across-groups<span style="font-family: arial,helvetica,sans-serif;"> -- boolean -- </span></span>indicates whether the need to rollback the operation on all the servers in one server group should trigger a rollback across all the server groups. This is an optional setting, and defaults to <span style="font-family: courier new,courier;">false</span>.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Each element in the list under the in-series node must have one or the other of the following structures:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">concurrent-groups</span> -- a map of server group names to policies controlling how the operation should be applied to that server group. For each server group in the map, the operation may be applied concurrently. See below for details on the per-server-group policy configuration.</li><li><span style="font-family: courier new,courier;">server-group</span> -- a single key/value mapping of a server group name to a policy controlling how the operation should be applied to that server group. See below for details on the policy configuration. <em>(Note: there is no difference in plan execution between this and a "concurrent-groups" map with a single entry.)</em></li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The policy controlling how the operation is applied to the servers within a server group has the following elements, each of which is optional:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">rolling-to-servers</span> -- boolean -- If true, the operation will be applied to each server in the group in series. If false or not specified, the operation will be applied to the servers in the group concurrently.</li><li><span style="font-family: courier new,courier;">max-failed-servers</span> -- int -- Maximum number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is zero; i.e. failure on any server triggers rollback across the group.</li><li><span style="font-family: courier new,courier;">max-failure-percentage</span> -- int between 0 and 100 -- Maximum percentage of the total number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is zero; i.e. failure on any server triggers rollback across the group.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If both <span style="font-family: courier new,courier;">max-failed-servers<span style="font-family: arial,helvetica,sans-serif;"> and </span></span><span style="font-family: courier new,courier;">max-failure-percentage<span style="font-family: arial,helvetica,sans-serif;"> are set to non-zero values, </span></span><span style="font-family: courier new,courier;">max-failure-percentage </span><span style="font-family: arial,helvetica,sans-serif;">takes precedence.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">Looking at the (contrived) example, application of the operation to the servers in the domain would be done in 3 phases. If the policy for any server group triggers a rollback of the operation across the server group, all other server groups will be rolled back as well. The 3 phases are:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ol><li><span style="font-family: arial,helvetica,sans-serif;">Server groups groupA and groupB will have the operation applied concurrently. The operation will be applied to the servers in groupA in series, while all servers in groupB will handle the operation concurrently. If more than 20% of the servers in groupA fail to apply the operation, it will be rolled back across that group. If any servers in groupB fail to apply the operation it will be rolled back across that group.</span></li><li><span style="font-family: arial,helvetica,sans-serif;">Once all servers in groupA and groupB are complete, the operation will be applied to the servers in groupC. Those servers will handle the operation concurrently. If more than one server in groupC fails </span><span style="font-family: arial,helvetica,sans-serif;">to apply the operation it will be rolled back across that group.</span></li><li><span style="font-family: arial,helvetica,sans-serif;">Once all servers in groupC are complete, s</span><span style="font-family: arial,helvetica,sans-serif;">erver groups groupD and groupE will have the operation applied concurrently. </span><span style="font-family: arial,helvetica,sans-serif;">The operation will be applied to the servers in groupD in series, while all servers in groupE will handle the operation concurrently. If more than 20% of the servers in groupD fail to apply the operation, it will be rolled back across that group. If any servers in groupE fail to apply the operation it will be rolled back across that group.</span></li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">See also <a class="jive-link-external-small" href="https://issues.jboss.org/browse/JBAS-8795">JBAS-8795</a> for a suggestion on additional rollout plan capabilities.<br/></span></p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-16336">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss AS7 Development at <a href="http://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>