[jboss-dev-forums] [JBoss AS 7 Development] - JBoss AS7 Command-line Operation Request Format

[Alexey Loubyansky]

Alexey Loubyansky [https://community.jboss.org/people/aloubyansky] modified the document:

"JBoss AS7 Command-line Operation Request Format"

To view the document, visit: https://community.jboss.org/docs/DOC-17599

--------------------------------------------------------------
For the definition and description of the AS7 management operation request, please, refer to the  https://community.jboss.org/docs/DOC-16336 Format of a detyped operation request.

This article describes only the format of the operation request in the command-line interface, which is

[node_path] : operation_name [parameter_list] [header_list]

node_path := node_type=node_name (, node_type=node_name)*
parameter_list := '(' parameter_name=parameter_value (,parameter_name=parameter_value)* ')'
header_list := {header (;header)*}



As you can see, all the parts except the +operation_name+ preceded with ':' are optional.

h3. Address (node path)

+node_path+ represents the address of the target resource (or the node) against which the operation should be invoked. It consists of +node_type=node_name+ pairs separated by a comma:

node_type=node_name (, node_type=node_name)*


 E.g.

+/subsystem=datasources+

or

+/subsystem=datasources/data-source=ExampleDS+

etc.


h3. Operation

The operation consists of an operation name and an optional list of parameters. The operation name is always preceded by a colon. The colon serves as a separator between the +node_path+ and the operation. Even if the +node_path+ is empty, the colon is still required. This is also how an operation is different from a command (commands are not preceded with a colon).

The parameter list, if present, is surrounded with parentheses and consists of +parameter_name=parameter_value+ pairs separated by commas:

:operation-name ['(' [name=value [, name=value]*] ')']


E.g.

+:shutdown+
+:shutdown()+
+:shutdown(restart=true)+
+/subsystem=datasources/data-source=ExampleDS:write-attribute(name=min-pool-size,value=5)+


h3. Headers

For the list of supported headers and their descriptions, please, refer to the section *Operation headers* of the  https://community.jboss.org/docs/DOC-16336 Format of a detyped operation request.
This article only describes the format of headers in CLI.

header (;header)*


If present, the header list is surrounded with curly braces. The headers in the list are separated by a semicolon. The syntax of headers may vary. Simple headers follow +header_name=header_value+ format. But there are also headers (like rollout plans) that require a more complex custom expression. Here is an example of an operation with simple headers:

+:write-attribute(name=my-attr,value=my-value){allow-resource-service-restart=true;rollback-on-runtime-failure=false}+


h3. Rollout plans

For the definition and explanation of what rollout plans are and for, please, refer to the section *Operations with a Rollout Plan* of the  https://community.jboss.org/docs/DOC-16336 Format of a detyped operation request.

This article only describes the CLI format of a rollout plan which is


rollout (id=plan_id | server_group_list) [rollback-across-groups]

server_group_list := server_group [ (sequence_separator | concurrent_separator) server_group ]
sequence_separator := ','
concurrent_separator := '^'
server_group := server_group_name [group_policy_list]
group_policy_list := '(' policy_property_name=policy_property_value (, policy_property_name=policy_property_value)* ')'
policy_property_name := 'rolling-to-servers' | 'max-failed-servers' | 'max-failure-percentage'



The value of +policy_property_value+ depends on the property. It can be a boolean, an integer, etc. You can fine the definition and description of each of the policy properties in 
the section *Operations with a Rollout Plan* of the  https://community.jboss.org/docs/DOC-16336 Format of a detyped operation request.

Rollout plans can potentially be long and complex. There is a possibility, though, to store them as part of the domain management model and then later be referenced from commands and operations using their name (or id in the definition above).
Stored rollout plans are managed (added, modified, removed) with the +rollout-plan+ command. E.g.

[domain at localhost:9999 /] rollout-plan add --name=my-plan --content={rollout main-server-group^other-server-group}


adds a simple concurrent rollout plan.

In the management model, rollout plans are stored under

/management-client-content=rollout-plans/rollout-plan=


which exists only in the domain mode.

Here are a few examples.

Rollout the operation in sequence first to main-server-group than the other-server-group:

:write-attribute(name=my-attr,value=my-value){rollout main-server-group,other-server-group}


Rollout the operation concurrently to main-server-group and the other-server-group:

:write-attribute(name=my-attr,value=my-value){rollout main-server-group^other-server-group}


Rollout the operation in sequence to groupA, concurrently to groupB and groupC and then to groupD using the specified policies and rollback across all the groups in case of a failure.

:write-attribute(name=my-attr,value=my-value){rollout groupA, groupB(max-failed-servers=1) ^ groupC(max-failure-percentage=10), groupD(max-failed-servers=2, rolling-to-servers=true) rollback-across-groups}


An example of using a stored rollout plan


rollout-plan add --name=my-plan --content={rollout main-server-group^other-server-group}
:write-attribute(name=my-attr,value=my-value){rollout id=my-plan}



h4. Headers in commands

Headers are also allowed for the commands that translate into operation requests. Those commands accept argument +--headers+ the value of which is header-list defined above. I.e. the syntax for headers for operations and commands is exactly the same, e.g.

+data-source --profile=default --name=ExampleDS --min-pool-size=5 --headers={rollout groupA, groupB(max-failed-servers=1) ^ groupC(max-failure-percentage=10), groupD(max-failed-servers=2, rolling-to-servers=true) rollback-across-groups}+
--------------------------------------------------------------

Comment by going to Community
[https://community.jboss.org/docs/DOC-17599]

Create a new document in JBoss AS 7 Development at Community
[https://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-dev-forums/attachments/20120302/c4f01edb/attachment.html