Stored commands for CLI

Version 13

    Analysis

    Summary

    It has been identified a need to capture a set of commands in order to address 2 use cases:

    1) Capture a set of commands in order to create a re-usable named command for this set of commands

    2) Capture a set of commands and export it into a script file.

     

    Requirements

    This feature is controlled by a new command "commands record". Once typed, every command/operation typed is executed and is "recorded". The CLI prompt turn to display the "REC" characters.

    At some point one can stop the recording by calling "commands stop-record". The prompt comes back to what it was prior to start recoding. If no command has been recorded, the recording session is left without any side effect. This command has 2 possible options:

    - In order to export the commands to a file, use the option "--export=<file path>". If relative, the script is generated in the current working dir.

    - In order to create a named command, use the option "--store=<command name> {--transient}". The named command and the associated set of commands are stored in a cli owned file. By default the command will be persisted. If no name more export file is provided, the CLI will store the list of commands in a stored command named "stored-cmd-<random num>".

    In order to not persist the command use the option -- transient

    A recording can be trashed by using the --discard option.

    The options --export and --store can be used all together to both export and create a stored command.

    The list of currently stored commands/operations is displayed when calling "commands list-recorded"

    - It can be useful to remove a command from the recording (wrong syntax, wrong command, ...). This can be achieved with the commands "commands rewind-record". It will remove from the recording session the last executed command.

    Design Notes

    Stored command persistency

     

    Commands are stored in the file JBOSS_HOME/bin/cli-stored-commands.xml

    This file is read at CLI start time and is updated each time a new stored command is persisted. If no such file exists when saving command, the command will be not persisted.

    CLI must preserve the XML content and comments but is free to reformat the file. Command/operation can be wrapped in CDATA element if required. Commands persisted by the CLI are wrapped in CDATA element.

     

    XML extract:

    <cli-stored-commands>

       <stored-command name={command name}>

        <command><![CDATA[cmd1]]></command>

        <command><cmd2></command>

        ...

       </stored-command>

       ...

    </cli-stored-commands>

     

    Stored command usage

     

    Stored commands are exposed by CLI completion. They are called like any other CLI commands. A stored command has no options.

     

    Exported file

     

    This generated file contains the list of commands that have been recorded. It can then be used when launching the CLI using the --file option.

     

    Special case for invalid command or command that fails

     

    When a command fails (due to parsing or execution), it is still recorded. We can imagine cases where the context is not right at record time but would become valid when the stored command will be executed.

    General

    Product Issue(s)

    https://issues.jboss.org/browse/EAP7-745

     

    Upstream Issue(s)

    [WFCORE-3235] CLI command recorder - JBoss Issue Tracker

     

    Developer Contacts

    Jean-François Denise (jdenise@redhat.com)