CLI Batch Mode

Version 8

    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.

     

    Composing batches from scratch

     

    Interactive mode begins with the batch command.

     

    {code}[standalone@localhost:9999 /] batch

    [standalone@localhost:9999 / #]

    {code}

     

    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.

     

    {code}[standalone@localhost:9999 / #] deploy my.ear

    #1 deploy my.ear

    [standalone@localhost:9999 / #] data-source enable --name=ExampleDS

    #2 data-source enable --name=ExampleDS

    [standalone@localhost:9999 / #] /system-property=myprop:add(value=myvalue)

    #3 /system-property=myprop:add(value=myvalue)

    [standalone@localhost:9999 / #]

    {code}

     

    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.

     

    {code}[standalone@localhost:9999 / #] ls

    extension               path                    subsystem               deployment              management-interfaces

    interface               socket-binding-group

    [standalone@localhost:9999 / #] cd subsystem=web

    [standalone@localhost:9999 subsystem=web #] read-attribute default-virtual-server

    default-host

    [standalone@localhost:9999 subsystem=web #]

    {code}

     

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

     

    {code}[standalone@localhost:9999 / #] list-batch

    #1 deploy my.ear

    #2 data-source enable --name=ExampleDS

    #3 /system-property=myprop:add(value=myvalue)

    [standalone@localhost:9999 / #]

    {code}

     

    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

     

    {code}[standalone@localhost:9999 / #] edit-batch-line 2 data-source disable --name=ExampleDS

    #2 data-source disable --name=ExampleDS

    [standalone@localhost:9999 / #]

    {code}

     

    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

     

    {code}[standalone@localhost:9999 / #] move-batch-line 3 1

    [standalone@localhost:9999 / #] list-batch

    #1 /system-property=myprop:add(value=myvalue)

    #2 deploy my.ear

    #3 data-source disable --name=ExampleDS

    [standalone@localhost:9999 / #]

    {code}

     

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

     

    {code}[standalone@localhost:9999 / #] remove-batch-line 2

    [standalone@localhost:9999 / #] list-batch

    #1 /system-property=myprop:add(value=myvalue)

    #2 data-source disable --name=ExampleDS

    [standalone@localhost:9999 / #]

    {code}

     

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

     

    {code}[standalone@localhost:9999 / #] holdback-batch

    [standalone@localhost:9999 /]

    {code}

     

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

     

    {code}[standalone@localhost:9999 /] batch

    Re-activated batch

    #1 /system-property=myprop:add(value=myvalue)

    #2 data-source disable --name=ExampleDS

    [standalone@localhost:9999 / #]

    {code}

     

    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)

     

    {code}[standalone@localhost:9999 / #] holdback-batch mybatch

    [standalone@localhost:9999 /]

    {code}

     

    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.

     

    {code}[standalone@localhost:9999 /] batch

    [standalone@localhost:9999 / #] deploy my.ear

    #1 deploy my.ear

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

    [standalone@localhost:9999 /]

    {code}

     

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

     

    {code}[standalone@localhost:9999 /] batch -l

    <unnamed>

    mybatch

    [standalone@localhost:9999 /]

    {code}

     

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

     

    {code}[standalone@localhost:9999 /] batch

    Re-activated batch

    #1 deploy my.ear

    [standalone@localhost:9999 / #]

    {code}

     

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

     

    {code}[standalone@localhost:9999 / #] discard-batch

    [standalone@localhost:9999 /] batch -l

    mybatch

    [standalone@localhost:9999 /]

    {code}

     

    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.

     

    {code}[standalone@localhost:9999 /] batch mybatch

    Re-activated batch 'mybatch'

    #1 /system-property=myprop:add(value=myvalue)

    #2 data-source disable --name=ExampleDS

    [standalone@localhost:9999 / #] run-batch

    The batch executed successfully

    [standalone@localhost:9999 /] batch -l

    [standalone@localhost:9999 /]

    {code}

    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.

     

    {code}[standalone@localhost:9999 /] batch --file=myscript.txt

    [standalone@localhost:9999 / #] list-batch

    #1 deploy my.ear

    #2 data-source --name=ExampleDS --min-pool-size=5

    [standalone@localhost:9999 / #] data-source --name=ExampleDS --max-pool-size=10

    #3 data-source --name=ExampleDS --max-pool-size=10

    [standalone@localhost:9999 / #] run-batch

    The batch executed successfully

    [standalone@localhost:9999 /]{code}

     

    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.

    {code}[standalone@localhost:9999 /] run-batch --file=myscript.txt

    The batch executed successfully

    [standalone@localhost:9999 /]{code}

     

    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 The operation request format article to find out more about the supported headers and their syntax.

     

    Batches with properties

     

    In case you need to parameterize your batches, you could use system properties. This is described in System properties in command argument and operation parameter values.