[jboss-dev-forums] [JBoss AS 7 Development] - CLI Batch Mode

[Alexey Loubyansky]

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

"CLI Batch Mode"

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

--------------------------------------------------------------
The batch mode allows one to group commands and operations and execute them together as an atomic unit, i.e., if at least one of the commands or operations fails, all the other successfully executed commands and operations in the batch are rolled back.

Not all of the commands can be added to a batch. E.g. commands like 'cd', 'ls', 'help', etc are not added to the batch since they don't translate into operation requests. These commands (if entered while in the batch mode) will be executed outside of the batch. Only the commands that translate into operation requests are allowed in the batch. The batch, actually, translates into a 'composite' operation request.

h2. Composing batches from scratch

Interactive mode begins with the +batch+ command.

[standalone at localhost:9999 /] batch
[standalone at localhost:9999 / #]



The '#' sign in the prompt indicates that the CLI is in the batch mode. Operations and commands like deploy, data-source, etc won't be executed as they are entered, instead they will be added to the current batch.

[standalone at localhost:9999 / #] deploy my.ear
#1 deploy my.ear
[standalone at localhost:9999 / #] data-source enable --name=ExampleDS
#2 data-source enable --name=ExampleDS
[standalone at localhost:9999 / #] /system-property=myprop:add(value=myvalue)
#3 /system-property=myprop:add(value=myvalue)
[standalone at localhost:9999 / #]



 But commands that don't translate into operation requests (or commands that are read-only) will be executed immediately, i.e. outside the batch. E.g.

[standalone at localhost:9999 / #] ls
extension               path                    subsystem               deployment              management-interfaces
interface               socket-binding-group
[standalone at localhost:9999 / #] cd subsystem=web
[standalone at localhost:9999 subsystem=web #] read-attribute default-virtual-server
default-host
[standalone at localhost:9999 subsystem=web #]


To see the list of the commands and operations in the current batch execute +list-batch+

[standalone at localhost:9999 / #] list-batch 
#1 deploy my.ear
#2 data-source enable --name=ExampleDS
#3 /system-property=myprop:add(value=myvalue)
[standalone at localhost:9999 / #]



Any line in the batch can be edited with +edit-batch-line+ command by providing the line number as the first argument and the edited command as the second one

[standalone at localhost:9999 / #] edit-batch-line 2 data-source disable --name=ExampleDS
#2 data-source disable --name=ExampleDS
[standalone at localhost:9999 / #]



If you want to re-order the lines in the batch you can do this using +move-batch-line+ by specifying the line number you want to move as the first argument and its new position as the second argument

[standalone at localhost:9999 / #] move-batch-line 3 1
[standalone at localhost:9999 / #] list-batch 
#1 /system-property=myprop:add(value=myvalue)
#2 deploy my.ear
#3 data-source disable --name=ExampleDS
[standalone at localhost:9999 / #]



A line can be removed using +remove-batch-line+ specifying the line number as the argument

[standalone at localhost:9999 / #] remove-batch-line 2
[standalone at localhost:9999 / #] list-batch 
#1 /system-property=myprop:add(value=myvalue)
#2 data-source disable --name=ExampleDS
[standalone at localhost:9999 / #]



You can postpone batch editing if suddenly you want to perform some other tasks outside the batch by executing +holdback-batch+

[standalone at localhost:9999 / #] holdback-batch 
[standalone at localhost:9999 /]



To return to the held back batch, just execute +batch+ command

[standalone at localhost:9999 /] batch 
Re-activated batch
#1 /system-property=myprop:add(value=myvalue)
#2 data-source disable --name=ExampleDS
[standalone at localhost:9999 / #]



Actually, it's possible to hold back more than one batch by specifying the name under which the batch should be saved (in runtime memory)

[standalone at localhost:9999 / #] holdback-batch mybatch
[standalone at localhost:9999 /]



Now, the batch is saved under the name 'mybatch'. To activate it, you now have to execute +batch mybatch+. Executing +batch+ without arguments will start a new batch.

[standalone at localhost:9999 /] batch
[standalone at localhost:9999 / #] deploy my.ear
#1 deploy my.ear
[standalone at localhost:9999 / #] holdback-batch 
[standalone at localhost:9999 /]


Now there are two batches held back. Too see the list of all the held back batches, execute +batch+ with +-l+ switch

[standalone at localhost:9999 /] batch -l
<unnamed>
mybatch
[standalone at localhost:9999 /]



The unnamed batch (there can be only one unnamed batch) is activated by executing +batch+ without arguments

[standalone at localhost:9999 /] batch 
Re-activated batch
#1 deploy my.ear
[standalone at localhost:9999 / #]



The currently active batch can be discarded by executing +discard-batch+

[standalone at localhost:9999 / #] discard-batch 
[standalone at localhost:9999 /] batch -l
mybatch
[standalone at localhost:9999 /]



Note, that after you re-activate your batch it is removed from the held back list and not associated with any name anymore. So, if you want to hold it back again, you will have to give it a new unique name or leave it unnamed.

Finally, to execute the currently active batch use +run-batch+ command. A successfully executed batch is automatically discarded and the CLI leaves the batch mode.

[standalone at localhost:9999 /] batch mybatch
Re-activated batch 'mybatch'
#1 /system-property=myprop:add(value=myvalue)
#2 data-source disable --name=ExampleDS
[standalone at localhost:9999 / #] run-batch 
The batch executed successfully
[standalone at localhost:9999 /] batch -l
[standalone at localhost:9999 /]


h2. 
h2. Executing batches stored in files

In case there is a set of commands and operations that peform a common task which could be executed frequently, they could be saved in a file which later could be specified as the argument to the +batch+ command. In this case the +batch+ command will start the batch mode and load the commands and operations from the specified file into the current batch. Now, you can edit the batch (edit, remove, add lines) and/or simply execute +run-batch+.

[standalone at localhost:9999 /] batch --file=myscript.txt
[standalone at localhost:9999 / #] list-batch 
#1 deploy my.ear
#2 data-source --name=ExampleDS --min-pool-size=5
[standalone at localhost:9999 / #] data-source --name=ExampleDS --max-pool-size=10
#3 data-source --name=ExampleDS --max-pool-size=10
[standalone at localhost:9999 / #] run-batch 
The batch executed successfully
[standalone at localhost:9999 /]


In case you don't need to modify the batch stored in the file, you can simply execute it by passing the file name as the argument to +run-batch+ without previously loading it using +batch.+
[standalone at localhost:9999 /] run-batch --file=myscript.txt
The batch executed successfully
[standalone at localhost:9999 /]


h2. Headers for batch request

+run-batch+ command accepts +--headers+ argument which can be used to attach operation headers to the composite operation request the batch translates to. Please, refer to the paragraph *Headers* on  https://community.jboss.org/docs/DOC-17599 The operation request format article to find out more about the supported headers and their syntax.

h2. Batches with properties

In case you need to parameterize your batches, you could use system properties. This is described in  https://community.jboss.org/docs/DOC-18726 System properties in command argument and operation parameter values.
--------------------------------------------------------------

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

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/20120718/a1b71124/attachment.html