Class NodeGroupInterpreter

java.lang.Object
com.scivicslab.pojoactor.workflow.Interpreter
com.scivicslab.actoriac.NodeGroupInterpreter
public class NodeGroupInterpreter extends com.scivicslab.pojoactor.workflow.Interpreter
Level 3 wrapper that adds workflow capabilities to a NodeGroup POJO.

This class extends Interpreter to provide workflow execution capabilities while delegating node group operations to a wrapped NodeGroup instance.

This follows the same three-level architecture as NodeInterpreter:

  • Level 1 (POJO): NodeGroup - pure POJO with inventory management
  • Level 2 (Actor): ActorRef<NodeGroup> - actor wrapper for concurrent execution
  • Level 3 (Workflow): NodeGroupInterpreter - workflow capabilities + IIActorRef wrapper

Design principle: NodeGroup remains a pure POJO, independent of ActorSystem. NodeGroupInterpreter wraps NodeGroup to add workflow capabilities without modifying the NodeGroup class.

Author:
devteam@scivicslab.com

  • Nested Class Summary

    Nested classes/interfaces inherited from class com.scivicslab.pojoactor.workflow.Interpreter

    com.scivicslab.pojoactor.workflow.Interpreter.Builder

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private IaCStreamingAccumulator
    accumulator
    IaCStreamingAccumulator for displaying workflow steps with cowsay ASCII art.
    private ExecutorService
    dbExecutor
    Dedicated executor service for DB writes.
    private DistributedLogStore
    logStore
    Direct reference to the log store for synchronous read operations.
    private com.scivicslab.pojoactor.core.ActorRef<DistributedLogStore>
    logStoreActor
    Actor reference for the distributed log store.
    private final NodeGroup
    nodeGroup
    The wrapped NodeGroup POJO that handles inventory and node creation.
    private String
    overlayDir
    The overlay directory path for YAML overlay feature.
    private long
    sessionId
    Session ID for the current workflow execution.
    private boolean
    verbose
    Verbose output flag.

    Fields inherited from class com.scivicslab.pojoactor.workflow.Interpreter

    code, currentState, currentTransitionIndex, logger, selfActorRef, system, workflowBaseDir

  • Constructor Summary

    Constructors
    Constructor
    Description
    NodeGroupInterpreter(NodeGroup nodeGroup, com.scivicslab.pojoactor.workflow.IIActorSystem system)
    Constructs a NodeGroupInterpreter that wraps the specified NodeGroup.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<Node>
    createLocalNode()
    Creates a single Node for localhost execution.
    List<Node>
    createNodesForGroup(String groupName)
    Creates Node objects for all hosts in the specified group.
    IaCStreamingAccumulator
    getAccumulator()
    Gets the IaCStreamingAccumulator for displaying workflow steps.
    ExecutorService
    getDbExecutor()
    Gets the DB executor service.
    InventoryParser.Inventory
    getInventory()
    Gets the inventory object.
    DistributedLogStore
    getLogStore()
    Gets the log store for direct read operations.
    com.scivicslab.pojoactor.core.ActorRef<DistributedLogStore>
    getLogStoreActor()
    Gets the log store actor for async write operations.
    NodeGroup
    getNodeGroup()
    Gets the wrapped NodeGroup instance.
    String
    getOverlayDir()
    Gets the overlay directory path.
    long
    getSessionId()
    Gets the session ID.
    private String
    getTransitionNote(com.scivicslab.pojoactor.workflow.Transition transition)
    transitionのnoteを取得する。60文字または最初の行までに制限。 noteがない場合は空文字列を返す。
    boolean
    isVerbose()
    Checks if verbose mode is enabled.
    protected void
    onEnterTransition(com.scivicslab.pojoactor.workflow.Transition transition)
    Hook called when entering a transition during workflow execution.
    protected void
    onExitTransition(com.scivicslab.pojoactor.workflow.Transition transition, boolean success, com.scivicslab.pojoactor.core.ActionResult result)
    Hook called after a transition completes (success or failure).
    void
    setAccumulator(IaCStreamingAccumulator accumulator)
    Sets the IaCStreamingAccumulator for displaying workflow steps.
    void
    setLogStore(DistributedLogStore logStore, com.scivicslab.pojoactor.core.ActorRef<DistributedLogStore> logStoreActor, ExecutorService dbExecutor, long sessionId)
    Sets the distributed log store for structured logging.
    void
    setOverlayDir(String overlayDir)
    Sets the overlay directory for YAML overlay feature.
    void
    setVerbose(boolean verbose)
    Sets verbose mode for detailed output.

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

    action, addToAccumulator, addToAccumulator, apply, call, execCode, findMatchingActors, findMatchingChildActors, findNextMatchingTransition, generateChildName, getCode, getCurrentState, getCurrentTransitionIndex, getToState, getWorkflowBaseDir, hasCodeLoaded, loadWorkflowFromClasspath, matchesCurrentState, matchesStatePattern, readJson, readXml, readYaml, readYaml, readYaml, removeChildActor, reset, runUntilEnd, runUntilEnd, runWorkflow, runWorkflow, setCode, setSelfActorRef, setWorkflowBaseDir, transitionTo

    Methods inherited from class Object

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

  • Field Details

    • nodeGroup

      private final NodeGroup nodeGroup
      The wrapped NodeGroup POJO that handles inventory and node creation.

    • overlayDir

      private String overlayDir
      The overlay directory path for YAML overlay feature. When set, workflows are loaded with overlay applied.

    • verbose

      private boolean verbose
      Verbose output flag. When true, displays full YAML for each transition instead of truncated version.

    • accumulator

      private IaCStreamingAccumulator accumulator
      IaCStreamingAccumulator for displaying workflow steps with cowsay ASCII art. When set, workflow step transitions are displayed using this accumulator.

    • logStoreActor

      private com.scivicslab.pojoactor.core.ActorRef<DistributedLogStore> logStoreActor
      Actor reference for the distributed log store. Used to send log messages asynchronously to avoid blocking workflow execution.

    • logStore

      private DistributedLogStore logStore
      Direct reference to the log store for synchronous read operations. Reads don't need to go through the actor since they don't need serialization.

    • dbExecutor

      private ExecutorService dbExecutor
      Dedicated executor service for DB writes. Should be a single-threaded pool to ensure serialized writes.

    • sessionId

      private long sessionId
      Session ID for the current workflow execution.

  • Constructor Details

    • NodeGroupInterpreter

      public NodeGroupInterpreter(NodeGroup nodeGroup, com.scivicslab.pojoactor.workflow.IIActorSystem system)
      Constructs a NodeGroupInterpreter that wraps the specified NodeGroup.
      Parameters:
      nodeGroup - the NodeGroup instance to wrap
      system - the actor system for workflow execution

  • Method Details

    • createNodesForGroup

      public List<Node> createNodesForGroup(String groupName)
      Creates Node objects for all hosts in the specified group.

      Delegates to the wrapped NodeGroup.createNodesForGroup(String) method.

      Parameters:
      groupName - the name of the group from the inventory file
      Returns:
      the list of created Node objects

    • createLocalNode

      public List<Node> createLocalNode()
      Creates a single Node for localhost execution.

      Delegates to the wrapped NodeGroup.createLocalNode() method.

      Returns:
      a list containing a single localhost Node

    • getInventory

      public InventoryParser.Inventory getInventory()
      Gets the inventory object.
      Returns:
      the loaded inventory, or null if not loaded

    • getNodeGroup

      public NodeGroup getNodeGroup()
      Gets the wrapped NodeGroup instance.

      This allows direct access to the underlying POJO when needed.

      Returns:
      the wrapped NodeGroup

    • setOverlayDir

      public void setOverlayDir(String overlayDir)
      Sets the overlay directory for YAML overlay feature.

      When an overlay directory is set, workflows will be loaded with overlay applied, allowing environment-specific configuration.

      Parameters:
      overlayDir - the path to the overlay directory containing overlay-conf.yaml

    • getOverlayDir

      public String getOverlayDir()
      Gets the overlay directory path.
      Returns:
      the overlay directory path, or null if not set

    • setVerbose

      public void setVerbose(boolean verbose)
      Sets verbose mode for detailed output.

      When enabled, displays full YAML for each transition in cowsay output instead of the truncated version.

      Parameters:
      verbose - true to enable verbose output

    • isVerbose

      public boolean isVerbose()
      Checks if verbose mode is enabled.
      Returns:
      true if verbose mode is enabled

    • setAccumulator

      public void setAccumulator(IaCStreamingAccumulator accumulator)
      Sets the IaCStreamingAccumulator for displaying workflow steps.

      When set, workflow step transitions are displayed using cowsay ASCII art via this accumulator. The accumulator's cowfile setting determines which character is used.

      Parameters:
      accumulator - the accumulator to use for cowsay display

    • getAccumulator

      public IaCStreamingAccumulator getAccumulator()
      Gets the IaCStreamingAccumulator for displaying workflow steps.
      Returns:
      the cowsay accumulator, or null if not set

    • setLogStore

      public void setLogStore(DistributedLogStore logStore, com.scivicslab.pojoactor.core.ActorRef<DistributedLogStore> logStoreActor, ExecutorService dbExecutor, long sessionId)
      Sets the distributed log store for structured logging.

      Database writes are performed asynchronously via the logStore actor using the dedicated dbExecutor to avoid blocking workflow execution. Direct reads can use the logStore reference directly.

      Parameters:
      logStore - the log store instance (for direct reads)
      logStoreActor - the actor reference for the log store (for async writes)
      dbExecutor - the dedicated executor service for DB writes
      sessionId - the session ID for this execution

    • getLogStore

      public DistributedLogStore getLogStore()
      Gets the log store for direct read operations.
      Returns:
      the log store, or null if not set

    • getLogStoreActor

      public com.scivicslab.pojoactor.core.ActorRef<DistributedLogStore> getLogStoreActor()
      Gets the log store actor for async write operations.
      Returns:
      the log store actor, or null if not set

    • getDbExecutor

      public ExecutorService getDbExecutor()
      Gets the DB executor service.
      Returns:
      the DB executor service, or null if not set

    • getSessionId

      public long getSessionId()
      Gets the session ID.
      Returns:
      the session ID, or -1 if not set

    • onEnterTransition

      protected void onEnterTransition(com.scivicslab.pojoactor.workflow.Transition transition)
      Hook called when entering a transition during workflow execution.

      Displays the workflow name and transition definition using cowsay. In normal mode, shows first 10 lines. In verbose mode, shows the full YAML after the cowsay output.

      Overrides:
      onEnterTransition in class com.scivicslab.pojoactor.workflow.Interpreter
      Parameters:
      transition - the transition being entered

    • onExitTransition

      protected void onExitTransition(com.scivicslab.pojoactor.workflow.Transition transition, boolean success, com.scivicslab.pojoactor.core.ActionResult result)
      Hook called after a transition completes (success or failure).

      Logs the transition result to the distributed log store for workflow execution reporting.

      Overrides:
      onExitTransition in class com.scivicslab.pojoactor.workflow.Interpreter
      Parameters:
      transition - the transition that was attempted
      success - true if the transition succeeded, false if it failed
      result - the ActionResult from executing the transition's actions

    • getTransitionNote

      private String getTransitionNote(com.scivicslab.pojoactor.workflow.Transition transition)
      transitionのnoteを取得する。60文字または最初の行までに制限。 noteがない場合は空文字列を返す。