State machine transition evaluator

The method "AcInstanceStateResolver.resolve" is used to validate an order (acDeployOrder, acLockOrder, acSubOrder) based of the current state (acDeployState, acLockState, acSubState, acStateChangeResult).

Describe the functionality "resolve" of the class "AcInstanceStateResolver" and how the functionality works.

The AcInstanceStateResolver.resolve method is the state machine transition evaluator for an Automation Composition Instance within the ACM runtime. Its primary function is to validate the immediate action (Order) to be executed by Participants, based on the current state of the Composition Instance and the “requested order” from the User.

It acts as a complex lookup table, or a state transition graph, to validate the consistency and legality of a requested state change before it is executed.

Functionality of AcInstanceStateResolver.resolve()

The function of resolve is to take a snapshot of the Automation Composition Instance's status and the command currently being processed, and return a single, definitive action string.

Input Parameters (The State and The Order):

The method takes seven parameters, which define the full context of a state transition:

1. Requested Orders (User/System Command):

   • acDeployOrder: The requested deployment action (DEPLOY, UNDEPLOY, MIGRATE, NONE).

   • acLockOrder: The requested locking action (LOCK, UNLOCK, NONE).

   • acSubOrder: The requested sub-state action (PREPARE, REVIEW, NONE).

2. Current States (Current Instance Status):

   • acDeployState: The current deployment state (UNDEPLOYED, DEPLOYED, DEPLOYING, etc.).

   • acLockState: The current lock state (LOCKED, UNLOCKED, NONE).

   • acSubState: The current sub-state (e.g., PREPARING, REVIEWING, NONE).

   • acStateChangeResult: The result of the last state change operation (NO_ERROR, FAILURE, TIMEOUT).

Output:

• Return Value: A single String representing the required next action, which corresponds to one of the input Orders (e.g., "DEPLOY", "LOCK", "UNDEPLOY", "PREPARE"), or the value "NONE" if the input combination is either illegal or implies that no further action is immediately needed.

How the Functionality Works

The AcInstanceStateResolver does not use traditional if/else logic. Instead, it uses a pre-built state definition map (StateDefinition) to perform a direct, composite lookup, which is a highly efficient and easily auditable way to manage complex state transitions.

1. State Definition Mapping

The core of the functionality is the StateDefinition class (implemented as a map):

• Composite Key Creation: The AcInstanceStateResolver initializes a graph object, which is a StateDefinition<String>. This object is populated at startup with all legal combinations of the seven input parameters mapped to a single output action.

  • The input parameters (Orders, States, and Result) are converted to their string names (e.g., DeployOrder.DEPLOY becomes "DEPLOY").

  • These seven strings are then concatenated into a single, unique key (e.g., "DEPLOY@NONE@NONE@UNDEPLOYED@NONE@NONE@NO_ERROR").

  • This long key maps directly to the desired output action string (e.g., "DEPLOY").

• The State Graph: The graph effectively represents the entire legal state transition diagram for an Automation Composition Instance.

2. The resolve() Execution Steps

The resolve method executes the following steps:

1. Default Handling: It ensures that no input parameter is null by assigning a default value if needed (e.g., DeployOrder.NONE, DeployState.UNDEPLOYED, StateChangeResult.NO_ERROR).

2. Composite Key Construction: It creates a string array containing the names of the seven contextual parameters:

   Java
   // Example Key Array: new String[] { deployOrder.name(), // e.g., "DEPLOY" lockOrder.name(), // e.g., "NONE" subOrder.name(), // e.g., "NONE" deployState.name(), // e.g., "UNDEPLOYED" lockState.name(), // e.g., "NONE" subState.name(), // e.g., "NONE" stateChangeResult.name() // e.g., "NO_ERROR" }

3. Graph Lookup: It performs a direct lookup in the pre-populated this.graph using the constructed array.

   Java
   return this.graph.get(new String[] {...});

4. Result:

   • Legal Transition: If the key exists in the map (a valid state and order combination), the associated action string (e.g., "DEPLOY") is returned.

   • Illegal/No-Op Transition: If the key is not found, the StateDefinition map returns its default value, which is implicitly "NONE", indicating that the requested command is either illegal given the current state or that the system should wait for a participant update.