Brian Stansberry [
http://community.jboss.org/people/bstansberry%40jboss.com] modified the
document:
"Format of a Detyped Operation Response"
To view the document, visit:
http://community.jboss.org/docs/DOC-16354
--------------------------------------------------------------
+*Note: this document is a draft meant to spark discussion, and its content may undergo
significant change*+
The basic method a user of the AS 7 programmatic managment API would use is very simple:
ModelNode execute(ModelNode operation) throws CancellationException, IOException;
where the return value is the detyped representation of the response, and operation is the
detyped representation of the operating being invoked.
The purpose of this article is to document the structure of the return value.
For the format of the request, see this page (
http://community.jboss.org/docs/DOC-16336).
h3. Simple Responses
Simple responses are provided by the following types of operations:
* Non-composite operations that target a single server. (See below for more on composite
operations).
* 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.)
The response will always include a simple boolean outcome field, with one of three
possible values:
* success -- the operation executed successfully
* failed -- the operation failed
* cancelled -- 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.)
The other fields in the response will depend on whether the operation was sucessful.
The response for a failed operation:
{
"outcome" => "failed",
"failure-description" => "[DOM-1234] Some failure message"
}
A response for a successful operation will include two fields:
* result -- the return value, or undefined for void operations or those that return null
* compensating-op -- a complex structure in the format of an operation request
(
http://community.jboss.org/docs/DOC-16336) that the caller could use to reverse the
affect of the operation. May be undefined if no compensating operation is available.
A non-void result with no compensating op available:
{
"outcome" => "success",
"result" => {
"name" => "Brian",
"age" => 22
},
"compensating-op" => undefined
}
A void result with a compensating op:
{
"outcome" => "success",
"result" => undefined,
"compensating-op" => {
"op" => "write-core-threads",
"op-addr" => [
("profile" => "production"),
("subsystem" => "threads"),
("bounded-queue-thread-pool" => "pool1")
],
"count" => 5,
"per-cpu" => 5
}
}
The response for a cancelled operation has no other fields:
{
"outcome" => "cancelled"
}
h3.
h3. Basic Composite Operation Responses
A composite operation is one that incorporates more than one simple operation in a list
and executes them atomically. See the "Composite Operations" section
http://community.jboss.org/docs/DOC-16336 here for more information.
Basic composite responses are provided by the following types of operations:
* Composite operations that target a single server.
* 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.)
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 outcome flag is controlled by the value of the
operation request's rollback-on-runtime-failure field. If that field was false
(default is true), the outcome flag will be success if *any* of the composite
operation's steps was successful.
What's distinctive about a composite operation response is the result field. First,
even if the operation was not successful, the result 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 result field will be a list. Each element in the list will record the result of the
corresponding element in the steps field of the composite operation request. So each
individual operation in the composite operation will have its result recorded.
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 outcome flag is failed. These relate to the fact
in a composite operation, individual operations can be rolled back or not even attempted.
If an individual operation was not even attempted (because the overall operation was
cancelled or, more likely, a prior operation failed):
{
"outcome" => "cancelled"
}
An individual operation that failed and was rolled back:
{
"outcome" => "failed",
"failure-description" => "[DOM-1234] Some failure message",
"rolled-back" => true
}
An individual operation that itself succeeded but was rolled back due to failure of
another operation:
{
"outcome" => "failed",
"result" => {
"name" => "Brian",
"age" => 22
},
"rolled-back" => true
}
An operation where the attempt at rollback was unsuccessful:
{
"outcome" => "failed",
"failure-description" => "[DOM-1234] Some failure message",
"rolled-back" => false,
"rollback-failure-description" => "[DOM-9876] Some other failure
message"
}
Here's an example of the response for a successful 2 step composite operation:
{
"outcome" => "success",
"result" => [
{
"outcome" => "success",
"result" => {
"name" => "Brian",
"age" => 22
},
"compensating-op" => undefined
},
{
"outcome" => "success",
"result" => undefined,
"compensating-op" => {
"op" => "write-core-threads",
"op-addr" => [
("profile" => "production"),
("subsystem" => "threads"),
("bounded-queue-thread-pool" => "pool1")
],
"count" => 5,
"per-cpu" => 5
}
}
],
"compensating-op" => {
"op" => "composite",
"op-addr" => [],
"steps" => [{
"op" => "write-core-threads",
"op-addr" => [
("profile" => "production"),
("subsystem" => "threads"),
("bounded-queue-thread-pool" => "pool1")
],
"count" => 5,
"per-cpu" => 5
}]
}
}
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:
{
"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"
}
]
}
h3. Multi-Server Responses
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.)
+Details coming this evening...+
--------------------------------------------------------------
Comment by going to Community
[
http://community.jboss.org/docs/DOC-16354]
Create a new document in JBoss AS7 Development at Community
[
http://community.jboss.org/choose-container!input.jspa?contentType=102&am...]