OperationModule

The OperationModule handles execution of Operations and Commands.

Operation

Operations are individual actions that are performed and have configurable settings that can be set through variables. All operations are referenced to by a string key. There are two kinds of operations, those that are hardcoded and those that are use-defined. User-defined operations are called procedures.

Hardcoded operations

Hardcoded operations perform unique and specific actions. They are basically implementations of the Operation interface. Implementations must be registered to the OperationModule. There is a list of default implementations available below.

Procedures

Procedures are user-defined operations that can be created from a YML file configuration. Procedures are a collection of one or more operations that can be executed in order, or through a series of if-else-then statements. Additionally variables can be defined that are passed on to the subsequent operations.

Creating procedures

Procedures are created by defining their configuration in a yml file, loading the file and passing it to the OperationFactory which can be retrieved from the OperationsModule. An example configuration is listed below, some individual parts are also explained below.

Creating Variables

Procedures start by creating Variables. Variables are mapped to settings declared inside operations. They are created inside a procedure and are passed along to any sub operations that are called. A variable consists of a key and a value. Keys are always string keys, values can either be empty or a string representation of the value that is required by the sub operations that will execute and use these variables. If a value is left empty it must either be specified by a parent operation executing this procedure, or the operation must allow that variable/setting to be optional. Type conversion happens through the ConversionModule and thus allows for a variety of string representations of the eventual type that is required, including data-paths.

Creating operation flow

A procedure can either execute one or more operations procedurally in order, or it can execute them based on a series of if-then-else statements. These if-then-else statements can be nested indefinitely to create elaborate conditionals.

Example configuration

Regular Procedure (operations are executed procedurally)

some-procedure-name:
   variables:
      variable-one: value-one
      variable-two: value-two
      variable-three: .some.path.to.value-three #data path notation, see DataPathModule
   operations: [operation-one, operation-two, operation-three, operation-four]

Conditional Procedure (operations are executed in the specified if-then-else order)

some-other-procedure-name:
   variables:
      variable-one: value-one
      variable-two: value-two
      variable-three: .some.path.to.value-three                #data path notation, see DataPathModule
   conditions:
      1:
         if: [operation-one, operation-two, operation-three]
         then: operation-four
         else: operation-five
      2:
         if: [operation-one, operation-two]
         then:
            if: [operation-one, operation-two]
            then: operation-five
            else:
               if: operation-four
               then: operation-six
      3:
         if: operation-three
         then: operation-four

Executing operations

Operations can be execute by getting the OperationExecutor from the OperationModule. Executing an operation consists of specifying the operation and optionally providing variables to be specified. The operation can be specified by referencing it’s class or it’s string key. Variables can be specified by passing a string-object map or by using a special syntax: key=value. To execute operations from user input a raw command can be passed that looks like this: ‘operation-name key1=value1 key2=value2 key3=value3 key4=value4 key5=value5’.

Commands

Executing operations through raw text is very cumbersome and lengthy. Because of this commands can be created that specify default variables for argument indices. An operation execution such as: ‘operation-name key1=value1 key2=value2 key3=value3 key4=value4 key5=value5’ will thus be able to look like: ‘command-name value1 value2 value3 value4 value5’. Missing arguments are automatically reported and users are able to query information on possible commands, their argument counts and suggested argument type. Arguments can also be set as optional.

Command configuration looks like this:

some-command:                                #This command is executed as: 'some-command   '
   operation: operation-name                 #This operation is executed when this command is called
   arguments:                                #Arguments are specified by the user and mapped to variables
      argument-one:
         variable: variable-one
         optional: false                     #default false is false, so can be left empty
      argument-two:
         variable: variable-two
         optional: false
      argument-three:
         variable: variable-three
         optional: true
      argument-four:
         variable: variable-four
         optional: true
   variables:                                #Variables can also be hardcoded. These are always passed to the operation as is. 
      somevar: someval
      othervar: otherval
   sub-commands:                             #This command is executed as: 'some-command some-sub-command  '
      some-sub-command:
         operation: the-operation
         arguments:
            arg1:
               variable: variable-one
            arg2:
               variable: variable-two
         sub-commands:                       #This command is executed as: 'some-command some-sub-sub-command '
            some-sub-sub-command:
               operation:
               arguments:
                  arg1:
                     variable: variable-one
      some-other-sub-command:                #This command is executed as: 'some-command some-other-sub-command' with no arguments
         operation: some-operation