Class NodeGroupIIAR

java.lang.Object
com.scivicslab.pojoactor.core.ActorRef<NodeGroupInterpreter>
com.scivicslab.pojoactor.workflow.IIActorRef<NodeGroupInterpreter>
com.scivicslab.actoriac.NodeGroupIIAR
All Implemented Interfaces:
com.scivicslab.pojoactor.core.CallableByActionName, AutoCloseable
public class NodeGroupIIAR extends com.scivicslab.pojoactor.workflow.IIActorRef<NodeGroupInterpreter>
Interpreter-interfaced actor reference for NodeGroupInterpreter instances.

This class provides a concrete implementation of IIActorRef specifically for NodeGroupInterpreter objects. It manages groups of infrastructure nodes and can apply actions to all nodes in a group using wildcard patterns.

NodeGroupInterpreter extends Interpreter, so this class can execute main workflows that orchestrate multiple nodes.

Supported actions:

Workflow actions (from Interpreter):

  • runWorkflow - Loads and runs a workflow file
  • readYaml - Reads a YAML workflow definition
  • runUntilEnd - Executes the workflow until completion

NodeGroup actions:

  • hasInventory - Returns true if inventory is loaded (for conditional branching)
  • createNodeActors - Creates child actors for all nodes in a specified group
  • apply - Applies an action to child actors matching a wildcard pattern
  • hasAccumulator - Returns true if accumulator exists (for idempotent workflows)
  • createAccumulator - Creates an accumulator for result collection
  • getAccumulatorSummary - Gets the collected results

Node Actor Hierarchy:

When createNodeActors is called, it creates a parent-child relationship:

NodeGroup (parent)
  ├─ node-web-01 (child NodeIIAR)
  ├─ node-web-02 (child NodeIIAR)
  └─ node-db-01 (child NodeIIAR)

Example YAML Workflow:

name: setup-nodegroup
steps:
  # Step 1: Create node actors
  - states: [0, 1]
    actions:
      - actor: nodeGroup
        method: createNodeActors
        arguments: ["web-servers"]

  # Step 2: Run workflow on all nodes (load and execute in one step)
  - states: [1, end]
    actions:
      - actor: nodeGroup
        method: apply
        arguments: ['{"actor": "node-*", "method": "runWorkflow", "arguments": ["deploy.yaml"]}']
Author:
devteam@scivics-lab.com

  • Field Details

  • Constructor Details

    • NodeGroupIIAR

      public NodeGroupIIAR(String actorName, NodeGroupInterpreter object)
      Constructs a new NodeGroupIIAR with the specified actor name and nodeGroupInterpreter object.
      Parameters:
      actorName - the name of this actor
      object - the NodeGroupInterpreter instance managed by this actor reference

    • NodeGroupIIAR

      public NodeGroupIIAR(String actorName, NodeGroupInterpreter object, com.scivicslab.pojoactor.workflow.IIActorSystem system)
      Constructs a new NodeGroupIIAR with the specified actor name, nodeGroupInterpreter object, and actor system.
      Parameters:
      actorName - the name of this actor
      object - the NodeGroupInterpreter instance managed by this actor reference
      system - the actor system managing this actor

  • Method Details

    • callByActionName

      public com.scivicslab.pojoactor.core.ActionResult callByActionName(String actionName, String arg)
      Invokes an action on the node group by name with the given arguments.

      This method dispatches to specialized handler methods based on the action type:

      Specified by:
      callByActionName in interface com.scivicslab.pojoactor.core.CallableByActionName
      Specified by:
      callByActionName in class com.scivicslab.pojoactor.workflow.IIActorRef<NodeGroupInterpreter>
      Parameters:
      actionName - the name of the action to execute
      arg - the argument string (JSON array format)
      Returns:
      an ActionResult indicating success or failure with a message

    • handleWorkflowAction

      private com.scivicslab.pojoactor.core.ActionResult handleWorkflowAction(String actionName, String arg) throws InterruptedException, ExecutionException
      Handles workflow-related actions (from Interpreter).
      Parameters:
      actionName - the action name
      arg - the argument string
      Returns:
      ActionResult if handled, null if not a workflow action
      Throws:
      InterruptedException
      ExecutionException

    • handleNodeGroupAction

      private com.scivicslab.pojoactor.core.ActionResult handleNodeGroupAction(String actionName, String arg) throws InterruptedException, ExecutionException
      Handles NodeGroup-specific actions.
      Parameters:
      actionName - the action name
      arg - the argument string
      Returns:
      ActionResult if handled, null if not a NodeGroup action
      Throws:
      InterruptedException
      ExecutionException

    • handleReadYaml

      private com.scivicslab.pojoactor.core.ActionResult handleReadYaml(String arg) throws InterruptedException, ExecutionException
      Throws:
      InterruptedException
      ExecutionException

    • parseMaxIterations

      private int parseMaxIterations(String arg, int defaultValue)

    • createNodeActors

      private void createNodeActors(String groupName)
      Creates child node actors for all nodes in the specified group.

      This method creates Node POJOs using the NodeGroup's inventory, wraps each in a NodeInterpreter (for workflow capabilities), then wraps in a NodeIIAR, and registers them as children of this actor using the parent-child relationship mechanism.

      Special handling for "local" group: creates a localhost node without requiring an inventory file. This is useful for development and testing.

      Parameters:
      groupName - the name of the group from the inventory file, or "local" for localhost

    • apply

      private com.scivicslab.pojoactor.core.ActionResult apply(String actionDef)
      Applies an action to child actors matching a wildcard pattern.

      This method parses an action definition JSON and executes the specified method on all child actors whose names match the pattern.

      Action definition format:

      {
  "actor": "node-*",           // Wildcard pattern for actor names
  "method": "executeCommand",  // Method to call
  "arguments": ["ls -la"]      // Arguments (optional)
}

      Supported wildcard patterns:

      • * - Matches all child actors
      • node-* - Matches actors starting with "node-"
      • *-web - Matches actors ending with "-web"
      Parameters:
      actionDef - JSON string defining the action to apply
      Returns:
      ActionResult indicating success or failure

    • findMatchingChildActors

      private List<com.scivicslab.pojoactor.workflow.IIActorRef<?>> findMatchingChildActors(String pattern)
      Finds child actors matching a wildcard pattern.
      Parameters:
      pattern - the wildcard pattern (e.g., "node-*", "*-web", "*")
      Returns:
      list of matching child actors

    • executeCommandOnAllNodes

      private List<String> executeCommandOnAllNodes(String command) throws ExecutionException, InterruptedException
      Executes a single command on all child node actors.
      Parameters:
      command - the command to execute
      Returns:
      list of results from each node
      Throws:
      ExecutionException - if command execution fails
      InterruptedException - if the operation is interrupted

    • extractSingleArgument

      private String extractSingleArgument(String arg)
      Extracts a single argument from JSON array format.
      Parameters:
      arg - the JSON array argument string
      Returns:
      the extracted argument

    • createAccumulator

      private void createAccumulator(String type)
      Creates an accumulator as a child actor.

      If a log store is configured in the NodeGroupInterpreter, creates a LoggingAccumulatorIIAR that also writes to the H2 database.

      Parameters:
      type - the accumulator type ("streaming", "buffered", "table", "json")

    • getAccumulatorSummary

      private com.scivicslab.pojoactor.core.ActionResult getAccumulatorSummary()
      Gets the summary from the accumulator.
      Returns:
      ActionResult with the summary or error

    • printSessionSummary

      private com.scivicslab.pojoactor.core.ActionResult printSessionSummary()
      Prints a summary of the current session's verification results.

      Groups results by vertex name (step) and displays a formatted table.

      Returns:
      ActionResult with success status and summary text

    • formatStatus

      private String formatStatus(NodeGroupIIAR.VerifyResult result)
      Formats the status string for a verification result.

    • extractSpecialInfo

      private void extractSpecialInfo(String message, NodeGroupIIAR.VerifyResult result)
      Extracts special information from log messages (like document count, cluster health).

    • countOccurrences

      private int countOccurrences(String text, String sub)
      Counts occurrences of a substring in a string.