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
• getSessionId - Gets the current session ID for log queries

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@scivicslab.com

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	NodeGroupIIAR.VerifyResult	Helper class to hold verification results for a step.

Field Summary

Fields

Modifier and Type	Field	Description
private String	currentWorkflowPath	Current workflow file path being executed.
(package private) Logger	logger

Fields inherited from class com.scivicslab.pojoactor.core.ActorRef

actorName, actorSystem, object

Constructor Summary

Constructors

Constructor	Description
NodeGroupIIAR(String actorName, NodeGroupInterpreter object)	Constructs a new NodeGroupIIAR with the specified actor name and nodeGroupInterpreter object.
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.

Method Summary

Modifier and Type	Method	Description
private com.scivicslab.pojoactor.core.ActionResult	apply(String actionDef)	Applies an action to multiple actors matching a pattern in parallel.
com.scivicslab.pojoactor.core.ActionResult	applyAction(String args)	Applies an action to child actors matching a wildcard pattern.
private int	countOccurrences(String text, String sub)	Counts occurrences of a substring in a string.
com.scivicslab.pojoactor.core.ActionResult	createAccumulator(String args)	Creates an accumulator (no-op, kept for backward compatibility).
private void	createNodeActors(String groupName)	Creates child node actors for all nodes in the specified group.
com.scivicslab.pojoactor.core.ActionResult	createNodeActorsAction(String args)	Creates child actors for all nodes in a specified group.
com.scivicslab.pojoactor.core.ActionResult	doNothing(String args)	Does nothing, returns the argument as result.
com.scivicslab.pojoactor.core.ActionResult	execCode(String args)	Executes the current step code.
private List<String>	executeCommandOnAllNodes(String command)	Executes a single command on all child node actors.
com.scivicslab.pojoactor.core.ActionResult	executeCommandOnAllNodesAction(String args)	Executes a command on all child node actors.
private String	extractSingleArgument(String arg)	Extracts a single argument from JSON array format.
private void	extractSpecialInfo(String message, NodeGroupIIAR.VerifyResult result)	Extracts special information from log messages (like document count, cluster health).
private List<com.scivicslab.pojoactor.workflow.IIActorRef<?>>	findMatchingChildActors(String pattern)	Finds child actors matching a wildcard pattern.
private String	formatStatus(NodeGroupIIAR.VerifyResult result)	Formats the status string for a verification result.
private com.scivicslab.pojoactor.core.ActionResult	getAccumulatorSummary()	Gets the summary from the output multiplexer.
com.scivicslab.pojoactor.core.ActionResult	getAccumulatorSummaryAction(String args)	Gets the summary from the output multiplexer.
private String	getFirst(String args)
com.scivicslab.pojoactor.core.ActionResult	getSessionId(String args)	Gets the current session ID.
com.scivicslab.pojoactor.core.ActionResult	getWorkflowPath(String args)	Gets the current workflow file path.
com.scivicslab.pojoactor.core.ActionResult	hasAccumulator(String args)	Checks if accumulator exists.
com.scivicslab.pojoactor.core.ActionResult	hasInventory(String args)	Checks if inventory is loaded.
private int	parseMaxIterations(String arg, int defaultValue)
com.scivicslab.pojoactor.core.ActionResult	printJson(String args)	Outputs JSON State at the given path in pretty JSON format via outputMultiplexer.
private com.scivicslab.pojoactor.core.ActionResult	printSessionSummary()	Prints a summary of the current session's verification results.
com.scivicslab.pojoactor.core.ActionResult	printSessionSummaryAction(String args)	Prints a summary of the current session's verification results.
com.scivicslab.pojoactor.core.ActionResult	printYaml(String args)	Outputs JSON State at the given path in YAML format via outputMultiplexer.
com.scivicslab.pojoactor.core.ActionResult	readYaml(String args)	Reads a YAML workflow definition.
com.scivicslab.pojoactor.core.ActionResult	runUntilEnd(String args)	Runs the workflow until completion.
com.scivicslab.pojoactor.core.ActionResult	runWorkflow(String args)	Loads and runs a workflow file.
private void	sendToMultiplexer(String formatted)	Sends formatted output to the outputMultiplexer, line by line.

Methods inherited from class com.scivicslab.pojoactor.workflow.IIActorRef

callByActionName, hasAnnotatedAction, invokeAnnotatedAction, parseFirstArgument

Methods inherited from class com.scivicslab.pojoactor.core.ActorRef

ask, ask, askNow, clearJsonState, clearPendingMessages, close, createChild, expandVariables, getJsonBoolean, getJsonInt, getJsonString, getJsonString, getLastResult, getName, getNamesOfChildren, getParentName, hasJson, hasJsonState, initLogger, isAlive, json, putJson, setLastResult, setParentName, system, tell, tell, tellNow, toStringOfJson, toStringOfYaml

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

logger

Logger logger

currentWorkflowPath

private String currentWorkflowPath

Current workflow file path being executed.

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

execCode

public com.scivicslab.pojoactor.core.ActionResult execCode(String args)

Executes the current step code.

Parameters:

args - the argument string (not used)

Returns:

ActionResult indicating success or failure

runUntilEnd

public com.scivicslab.pojoactor.core.ActionResult runUntilEnd(String args)

Runs the workflow until completion.

Parameters:

args - the argument string (optional max iterations)

Returns:

ActionResult indicating success or failure

runWorkflow

public com.scivicslab.pojoactor.core.ActionResult runWorkflow(String args)

Loads and runs a workflow file.

Parameters:

args - JSON array with workflow file path and optional max iterations

Returns:

ActionResult indicating success or failure

readYaml

public com.scivicslab.pojoactor.core.ActionResult readYaml(String args)

Reads a YAML workflow definition.

Parameters:

args - JSON array with file path

Returns:

ActionResult indicating success or failure

hasInventory

public com.scivicslab.pojoactor.core.ActionResult hasInventory(String args)

Checks if inventory is loaded.

Parameters:

args - the argument string (not used)

Returns:

ActionResult with true if inventory exists

createNodeActorsAction

public com.scivicslab.pojoactor.core.ActionResult createNodeActorsAction(String args)

Creates child actors for all nodes in a specified group.

Parameters:

args - JSON array with group name

Returns:

ActionResult indicating success or failure

applyAction

public com.scivicslab.pojoactor.core.ActionResult applyAction(String args)

Applies an action to child actors matching a wildcard pattern.

Parameters:

args - JSON object defining the action to apply

Returns:

ActionResult indicating success or failure

executeCommandOnAllNodesAction

public com.scivicslab.pojoactor.core.ActionResult executeCommandOnAllNodesAction(String args)

Executes a command on all child node actors.

Parameters:

args - JSON array with command

Returns:

ActionResult with execution results

hasAccumulator

public com.scivicslab.pojoactor.core.ActionResult hasAccumulator(String args)

Checks if accumulator exists.

Parameters:

args - the argument string (not used)

Returns:

ActionResult with true if accumulator exists

createAccumulator

public com.scivicslab.pojoactor.core.ActionResult createAccumulator(String args)

Creates an accumulator (no-op, kept for backward compatibility).

Parameters:

args - the argument string (not used)

Returns:

ActionResult with success

getAccumulatorSummaryAction

public com.scivicslab.pojoactor.core.ActionResult getAccumulatorSummaryAction(String args)

Gets the summary from the output multiplexer.

Parameters:

args - the argument string (not used)

Returns:

ActionResult with the summary

printSessionSummaryAction

public com.scivicslab.pojoactor.core.ActionResult printSessionSummaryAction(String args)

Prints a summary of the current session's verification results.

Parameters:

args - the argument string (not used)

Returns:

ActionResult with the summary

getSessionId

public com.scivicslab.pojoactor.core.ActionResult getSessionId(String args)

Gets the current session ID.

Parameters:

args - the argument string (not used)

Returns:

ActionResult with the session ID

getWorkflowPath

public com.scivicslab.pojoactor.core.ActionResult getWorkflowPath(String args)

Gets the current workflow file path.

Parameters:

args - the argument string (not used)

Returns:

ActionResult with the workflow path

doNothing

public com.scivicslab.pojoactor.core.ActionResult doNothing(String args)

Does nothing, returns the argument as result.

Parameters:

args - the argument string

Returns:

ActionResult with the argument

printJson

public com.scivicslab.pojoactor.core.ActionResult printJson(String args)

Outputs JSON State at the given path in pretty JSON format via outputMultiplexer.

Parameters:

args - the path to output (from JSON array)

Returns:

ActionResult with the formatted JSON

printYaml

public com.scivicslab.pojoactor.core.ActionResult printYaml(String args)

Outputs JSON State at the given path in YAML format via outputMultiplexer.

Parameters:

args - the path to output (from JSON array)

Returns:

ActionResult with the formatted YAML

sendToMultiplexer

private void sendToMultiplexer(String formatted)

Sends formatted output to the outputMultiplexer, line by line.

parseMaxIterations

private int parseMaxIterations(String arg,
 int defaultValue)

getFirst

private String getFirst(String args)

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 multiple actors matching a pattern in parallel.

This method executes the specified action on all matching actors asynchronously and in parallel, then waits for all executions to complete before returning. This provides significant performance benefits when executing actions on many nodes.

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

getAccumulatorSummary

private com.scivicslab.pojoactor.core.ActionResult getAccumulatorSummary()

Gets the summary from the output multiplexer.

Retrieves the multiplexer actor from ActorSystem by name ("outputMultiplexer") and calls its getSummary action.

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 label (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.