<!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 Response
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/brian.stansberry">Brian Stansberry</a> in <i>JBoss AS7 Development</i> - <a href="http://community.jboss.org/docs/DOC-16354">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 is 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: arial,helvetica,sans-serif;"> the return value.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">For the format of the request, see <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-16336">this page</a>.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>See <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-16317">this page</a> for a more in depth example of using the native management API.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Simple Responses</h3><p><br/>Simple responses are provided by the following types of operations:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li>Non-composite operations that target a single server. (See below for more on composite operations).</li><li>Non-composite operations that target a DomainController or HostController and don't require the responder to apply the operation on multiple servers and aggregate their results (e.g. a simple read of a domain configuration property.)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The response will always include a simple boolean <span style="font-family: courier new,courier;">outcome</span> field, with one of three possible values:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">success</span> -- the operation executed successfully</li><li><span style="font-family: courier new,courier;">failed </span>-- the operation failed</li><li><span style="font-family: courier new,courier;">cancelled</span> -- the execution of the operation was cancelled. (This would be an unusual outcome for a simple operation which would generally very rapidly reach a point in its execution where it couldn't be cancelled.)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The other fields in the response will depend on whether the operation was sucessful.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The response for a failed operation:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "failure-description" => "[DOM-1234] Some failure message"
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A response for a successful operation will include an additional field:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><span style="font-family: courier new,courier;">result</span> -- the return value, or <span style="font-family: courier new,courier;">undefined</span> for void operations or those that return <span style="font-family: courier new,courier;">null</span></li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A non-void result:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "success",
    "result" => {
        "name" => "Brian",
        "age" => 22
    }
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A void result with a compensating operation:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "success",
    "result" => undefined
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">The response for a cancelled operation has no other fields:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "cancelled"
}
</code></pre><h3></h3><h3>Response Headers</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Besides the standard <span style="font-family: courier new,courier;">outcome</span>, <span style="font-family: courier new,courier;">result</span> and <span style="font-family: courier new,courier;">failure-description</span> fields described above, the response may also include various headers that provide more information about the affect of the operation or about the overall state of the server. The headers will be child element under a field named response-headers. For example:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "success",
    "result" => undefined,
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A response header is typically related to whether an operation could be applied to the targetted runtime without requiring a restart of some or all services, or even of the target process itself. Please see "Applying Updates to Runtime Services" on the <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-16317">Detyped Description of the AS 7 Management Model </a>wiki for a discussion of the basic concepts related to what happens if an operation requires a service restart to be applied.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The current possible response headers are:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li style="text-align: start;">operation-requires-reload -- boolean -- indicates that the specific operation that has generated this response requires a restart of all services in the process in order to take effect in the runtime. This would typically only have a value of 'true'; the absence of the header is the same as a value of 'false.'</li><li style="text-align: start;">operation-requires-restart -- boolean -- indicates that the specific operation that has generated this response requires a full process restart in order to take effect in the runtime. This would typically only have a value of 'true'; the absence of the header is the same as a value of 'false.'</li><li style="text-align: start;">process-state -- enumeration -- Provides information about the overall state of the target process. One of the following values:<ul><li style="text-align: start;">starting -- the process is starting</li><li style="text-align: start;">running -- the process is in a normal running state. The process-state header would typically not be seen with this value; the absence of the header is the same as a value of 'running'.</li><li style="text-align: start;">reload-required -- some operation (not necessarily this one) has executed that requires a restart of all services in order for a configuration change to take effect in the runtime.</li><li style="text-align: start;">restart-required -- some operation (not necessarily this one) has executed that requires a full process restart  in order for a configuration change to take effect in the runtime.</li><li style="text-align: start;">stopping -- the process is stopping</li></ul></li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Basic Composite Operation Responses</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A composite operation is one that incorporates more than one simple operation in a list and executes them atomically. See the "Composite Operations" section <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-16336">here</a> for more information.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Basic composite responses are provided by the following types of operations:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li>Composite operations that target a single server.</li><li>Composite operations that target a DomainController or HostController and don't require the responder to apply the operation on multiple servers and aggregate their results (e.g. a list of simple reads of domain configuration properties.)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The high level format of a basic composite operation response is largely the same as that of a simple operation response, although there is an important semantic difference. For a composite operation, the meaning of the <span style="font-family: courier new,courier;">outcome</span> flag is controlled by the value of the operation request's <span style="font-family: courier new,courier;">rollback-on-runtime-failure</span> header field. If that field was <span style="font-family: courier new,courier;">false</span> (default is <span style="font-family: courier new,courier;">true</span>), the outcome flag will be <span style="font-family: courier new,courier;">success</span> if <strong>any</strong> of the composite operation's steps was successful.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>What's distinctive about a composite operation response is the <span style="font-family: courier new,courier;">result</span> field. First, even if the operation was not successful, the <span style="font-family: courier new,courier;">result</span> field will usually be present. (It won't be present if there was some sort of immediate failure that prevented the responder from even attempting to execute the individual operations.)  Second, the content of the <span style="font-family: courier new,courier;">result</span> field will be a list. Each element in the list will record the result of the corresponding element in the <span style="font-family: courier new,courier;">steps<span style="font-family: arial,helvetica,sans-serif;"> field of the composite operation request. So each individual operation in the composite operation will have its result recorded.<br/></span></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">The individual operation results will have the same basic format as the simple operation results described above. However, there are some differences from the simple operation case when the individual operation's <span style="font-family: courier new,courier;">outcome</span> flag is <span style="font-family: courier new,courier;">failed</span>.  These relate to the fact in a composite operation, individual operations can be rolled back or not even attempted.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">If an individual operation was not even attempted (because the overall operation was cancelled or, more likely, a prior operation failed):</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "cancelled"
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>An individual operation that failed and was rolled back:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "failure-description" => "[DOM-1234] Some failure message",
    "rolled-back" => true
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>An individual operation that itself succeeded but was rolled back due to failure of another operation:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "result" => {
        "name" => "Brian",
        "age" => 22
    },
    "rolled-back" => true
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>An operation where the attempt at rollback was unsuccessful:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "failure-description" => "[DOM-1234] Some failure message",
    "rolled-back" => false,
    "rollback-failure-description" => "[DOM-9876] Some other failure message"
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">Here's an example of the response for a successful 2 step composite operation:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "success",
    "result" => [
        {
            "outcome" => "success",
            "result" => {
                "name" => "Brian",
                "age" => 22
            }
        },
        {
            "outcome" => "success",
            "result" => undefined
        }
    ]
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">And for a failed 3 step composite operation, where the first step succeeded and the second failed, triggering cancellation of the 3rd and rollback of the others:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "failure-description" => "[DOM-9999] Composite operation failed; see individual operation results for details",
    "result" => [
        {
            "outcome" => "failed",
            "result" => {
                "name" => "Brian",
                "age" => 22
            },
            "rolled-back" => true
        },
        {
            "outcome" => "failed",
            "failure-description" => "[DOM-1234] Some failure message",
            "rolled-back" => true
        },
        {
            "outcome" => "cancelled"
        }
    ]
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;"><br/></span></p><h3>Multi-Server Responses</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Multi-server responses are provided by operations that target a DomainController or HostController and require the responder to apply the operation on multiple servers and aggregate their results (e.g. nearly all domain or host configuration updates.)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Multi-server operations are executed in several stages.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>First, the operation may need to be applied against the authoritative configuration model maintained by the DomainController (for domain.xml confgurations) or a HostController (for a host.xml configuration). If there is a failure at this stage, the operation is automatically rolled back, with a response like this:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy">{</font>
    <font color="red">"outcome"</font> => <font color="red">"failed"</font>,
    <font color="red">"domain-failure-description"</font> => <font color="red">"[DOM-3333] Failed to apply X to the domain model"</font>
<font color="navy">}</font>
 
</code></pre><p>if the operation was addressed to the domain model, or like this:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "host-failure-description" => "[DOM-3334] Failed to apply Y to the host model"
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>if the operation was addressed to a host model.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If the operation was addressed to the domain model, in the next stage the DomainController will ask each HostController to apply it to its local copy of the domain model. If any HostController fails to do so, the DomainController will tell all HostControllers to revert the change, and it will revert the change locally as well. The response to the client will look like this:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy">{</font>
    <font color="red">"outcome"</font> => <font color="red">"failed"</font>,
    <font color="red">"host-failure-descriptions"</font> => <font color="navy">{</font>
        <font color="red">"hostA"</font> => <font color="red">"[DOM-3333] Failed to apply to the domain model"</font>,
        <font color="red">"hostB"</font> => <font color="red">"[DOM-3333] Failed to apply to the domain model"</font>
    <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If the preceding stages succeed, the operation will be pushed to all affected servers. If the operation is successful on all servers, the response will look like this (this operation has a void response, hence the <span style="font-family: courier new,courier;">result</span> for each server is <span style="font-family: courier new,courier;">undefined</span>):</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy">{</font>
    <font color="red">"outcome"</font> => <font color="red">"success"</font>,
    <font color="red">"server-groups"</font> => <font color="navy">{</font>
        <font color="red">"groupA"</font> => <font color="navy">{</font>
            <font color="red">"serverA-1"</font> => <font color="navy">{</font>
                <font color="red">"host"</font> => <font color="red">"host1"</font>,
                <font color="red">"response"</font> => <font color="navy">{</font>
                    <font color="red">"outcome"</font> => <font color="red">"success"</font>,
                    <font color="red">"result"</font> => undefined
                <font color="navy">}</font>
            <font color="navy">}</font>,
            <font color="red">"serverA-2"</font> => <font color="navy">{</font>
                <font color="red">"host"</font> => <font color="red">"host2"</font>,
                <font color="red">"response"</font> => <font color="navy">{</font>
                    <font color="red">"outcome"</font> => <font color="red">"success"</font>,
                    <font color="red">"result"</font> => undefined
                <font color="navy">}</font>
            <font color="navy">}</font>
        <font color="navy">}</font>,
        <font color="red">"groupB"</font> => <font color="navy">{</font>
            <font color="red">"serverB-1"</font> => <font color="navy">{</font>
                <font color="red">"host"</font> => <font color="red">"host1"</font>,
                <font color="red">"response"</font> => <font color="navy">{</font>
                    <font color="red">"outcome"</font> => <font color="red">"success"</font>,
                    <font color="red">"result"</font> => undefined
                <font color="navy">}</font>
            <font color="navy">}</font>,
            <font color="red">"serverB-2"</font> => <font color="navy">{</font>
                <font color="red">"host"</font> => <font color="red">"host2"</font>,
                <font color="red">"response"</font> => <font color="navy">{</font>
                    <font color="red">"outcome"</font> => <font color="red">"success"</font>,
                    <font color="red">"result"</font> => undefined
                <font color="navy">}</font>
            <font color="navy">}</font>
        <font color="navy">}</font>
    <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The operation need not succeed on all servers in order to get an <span style="font-family: courier new,courier;">"outcome" => "success" </span>result. All that is required is that it succeed on at least one server without the rollback policies in the rollout plan triggering a rollback on that server. (<em>TODO: consider something like <span style="font-family: courier new,courier;">"outcome" => "partial"</span> for this case, and for partially successful composite operations.</em>) An example response in such a situation would look like this:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "success",
    "server-groups" => {
        "groupA" => {
            "serverA-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            },
            "serverA-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            }
        },
        "groupB" => {
            "serverB-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-3" => {
                "host" => "host3",
                "response" => {
                    "outcome" => "failed",
                    "failure-description" => "[DOM-4556] Something didn't work right",
                    "rolled-back" => true
                }
            }
        }
    }
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Finally, if the operation fails or is rolled back on all servers, an example response would look like this:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">{
    "outcome" => "failed",
    "server-groups" => {
        "groupA" => {
            "serverA-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            },
            "serverA-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            }
        },
        "groupB" => {
            "serverB-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "failed",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "failed",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-3" => {
                "host" => "host3",
                "response" => {
                    "outcome" => "failed",
                    "failure-description" => "[DOM-4556] Something didn't work right",
                    "rolled-back" => true
                }
            }
        }
    }
}
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>TODO: discuss some nuances related to multi-server composite operations, particularly the fact that different items in the composite may execute on different sets of servers, or only on the DC or the HC.</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-16354">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>