Class NodeInterpreter

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

This class extends Interpreter to provide workflow execution capabilities while delegating SSH operations to a wrapped Node instance.

This demonstrates the three-level architecture of actor-IaC:

  • Level 1 (POJO): Node - pure POJO with SSH functionality
  • Level 2 (Actor): ActorRef<Node> - actor wrapper for concurrent execution
  • Level 3 (Workflow): NodeInterpreter - workflow capabilities + IIActorRef wrapper

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

Author:
devteam@scivics-lab.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 final Set<String>
    changedDocuments
    Set of changed document names detected by workflow.
    private String
    currentVertexYaml
    The current vertex YAML snippet (first 10 lines) for accumulator reporting.
    private static final Logger
    logger
     
    private final Node
    node
    The wrapped Node POJO that handles actual SSH operations.
    private String
    overlayDir
    The overlay directory path for YAML overlay feature.

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

    code, currentState, currentVertexIndex, selfActorRef, system, workflowBaseDir

  • Constructor Summary

    Constructors
    Constructor
    Description
    NodeInterpreter(Node node, com.scivicslab.pojoactor.workflow.IIActorSystem system)
    Constructs a NodeInterpreter that wraps the specified Node.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addChangedDocument(String docName)
    Adds a document to the changed list (for testing or manual override).
    com.scivicslab.pojoactor.core.ActionResult
    buildChangedDocuments(String docListPath)
    Builds changed Docusaurus documents.
    private String
    checkGitStatus(Path docPath)
    Checks git status for a document directory.
    void
    clearChangedDocuments()
    Clears the changed documents list.
    com.scivicslab.pojoactor.core.ActionResult
    cloneChangedDocuments(String docListPath)
    Clones changed documents from git.
    com.scivicslab.pojoactor.core.ActionResult
    deployChangedDocuments(String docListPath)
    Copies changed document builds to public_html.
    com.scivicslab.pojoactor.core.ActionResult
    detectDocumentChanges(String docListPath)
    Detects changed documents and stores them in POJO state.
    Node.CommandResult
    executeCommand(String command)
    Executes a command on the remote node via SSH.
    Node.CommandResult
    executeSudoCommand(String command)
    Executes a command with sudo privileges on the remote node.
    Set<String>
    getChangedDocuments()
    Gets all changed document names.
    int
    getChangedDocumentsCount()
    Gets the number of changed documents.
    String
    getCurrentVertexYaml()
    Returns the current vertex YAML snippet for accumulator reporting.
    String
    getHostname()
    Gets the hostname of the node.
    Node
    getNode()
    Gets the wrapped Node instance.
    String
    getOverlayDir()
    Gets the overlay directory path.
    int
    getPort()
    Gets the SSH port.
    String
    getUser()
    Gets the username for SSH connections.
    boolean
    hasChangedDocuments()
    Checks if there are any changed documents to process.
    boolean
    isDocumentChanged(String docName)
    Checks if a specific document is in the changed list.
    protected void
    onEnterVertex(com.scivicslab.pojoactor.workflow.Vertex vertex)
    Hook called when entering a vertex during workflow execution.
    private String
    runGitCommand(Path workDir, String... command)
    Runs a git command and returns the output.
    com.scivicslab.pojoactor.core.ActionResult
    runWorkflow(String workflowFile, int maxIterations)
    Loads and runs a workflow file to completion with overlay support.
    void
    setOverlayDir(String overlayDir)
    Sets the overlay directory for YAML overlay feature.

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

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

    Methods inherited from class Object

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

  • Field Details

    • logger

      private static final Logger logger

    • node

      private final Node node
      The wrapped Node POJO that handles actual SSH operations.

    • overlayDir

      private String overlayDir
      The overlay directory path for YAML overlay feature.

    • currentVertexYaml

      private String currentVertexYaml
      The current vertex YAML snippet (first 10 lines) for accumulator reporting.

    • changedDocuments

      private final Set<String> changedDocuments
      Set of changed document names detected by workflow. This replaces the /tmp/changed_docs.txt file-based approach.

  • Constructor Details

    • NodeInterpreter

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

  • Method Details

    • executeCommand

      public Node.CommandResult executeCommand(String command) throws IOException
      Executes a command on the remote node via SSH.

      Delegates to the wrapped Node.executeCommand(String) method.

      Parameters:
      command - the command to execute
      Returns:
      the result of the command execution
      Throws:
      IOException - if SSH connection fails

    • executeSudoCommand

      public Node.CommandResult executeSudoCommand(String command) throws IOException
      Executes a command with sudo privileges on the remote node.

      Delegates to the wrapped Node.executeSudoCommand(String) method. Requires SUDO_PASSWORD environment variable to be set.

      Parameters:
      command - the command to execute with sudo
      Returns:
      the result of the command execution
      Throws:
      IOException - if SSH connection fails or SUDO_PASSWORD is not set

    • getHostname

      public String getHostname()
      Gets the hostname of the node.
      Returns:
      the hostname

    • getUser

      public String getUser()
      Gets the username for SSH connections.
      Returns:
      the username

    • getPort

      public int getPort()
      Gets the SSH port.
      Returns:
      the SSH port number

    • getNode

      public Node getNode()
      Gets the wrapped Node instance.

      This allows direct access to the underlying POJO when needed.

      Returns:
      the wrapped Node

    • setOverlayDir

      public void setOverlayDir(String overlayDir)
      Sets the overlay directory for YAML overlay feature.
      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

    • onEnterVertex

      protected void onEnterVertex(com.scivicslab.pojoactor.workflow.Vertex vertex)
      Hook called when entering a vertex during workflow execution.

      Displays the workflow name and first 10 lines of the vertex definition in YAML format using cowsay to provide visual separation between workflow steps.

      Overrides:
      onEnterVertex in class com.scivicslab.pojoactor.workflow.Interpreter
      Parameters:
      vertex - the vertex being entered

    • getCurrentVertexYaml

      public String getCurrentVertexYaml()
      Returns the current vertex YAML snippet for accumulator reporting.
      Returns:
      the first 10 lines of the current vertex in YAML format

    • runWorkflow

      public com.scivicslab.pojoactor.core.ActionResult runWorkflow(String workflowFile, int maxIterations)
      Loads and runs a workflow file to completion with overlay support.

      If overlayDir is set, the workflow is loaded with overlay applied. Variables defined in overlay-conf.yaml are substituted before execution.

      Overrides:
      runWorkflow in class com.scivicslab.pojoactor.workflow.Interpreter
      Parameters:
      workflowFile - the workflow file path (YAML or JSON)
      maxIterations - maximum number of state transitions allowed
      Returns:
      ActionResult with success=true if completed, false otherwise

    • detectDocumentChanges

      public com.scivicslab.pojoactor.core.ActionResult detectDocumentChanges(String docListPath) throws IOException
      Detects changed documents and stores them in POJO state.

      This method replaces the shell script that wrote to /tmp/changed_docs.txt. It reads the document list, checks git status for each, and stores changed document names in the changedDocuments set.

      Parameters:
      docListPath - path to the document list file
      Returns:
      ActionResult with detection summary
      Throws:
      IOException - if file operations fail

    • checkGitStatus

      private String checkGitStatus(Path docPath)
      Checks git status for a document directory.
      Parameters:
      docPath - path to the document directory
      Returns:
      status string like "[CHANGED]", "[UP-TO-DATE]", or "[UNKNOWN]"

    • runGitCommand

      private String runGitCommand(Path workDir, String... command)
      Runs a git command and returns the output.

    • isDocumentChanged

      public boolean isDocumentChanged(String docName)
      Checks if a specific document is in the changed list.
      Parameters:
      docName - the document name to check
      Returns:
      true if the document was detected as changed

    • getChangedDocumentsCount

      public int getChangedDocumentsCount()
      Gets the number of changed documents.
      Returns:
      the count of changed documents

    • getChangedDocuments

      public Set<String> getChangedDocuments()
      Gets all changed document names.
      Returns:
      unmodifiable set of changed document names

    • hasChangedDocuments

      public boolean hasChangedDocuments()
      Checks if there are any changed documents to process.
      Returns:
      true if at least one document needs processing

    • clearChangedDocuments

      public void clearChangedDocuments()
      Clears the changed documents list.

    • addChangedDocument

      public void addChangedDocument(String docName)
      Adds a document to the changed list (for testing or manual override).
      Parameters:
      docName - the document name to add

    • cloneChangedDocuments

      public com.scivicslab.pojoactor.core.ActionResult cloneChangedDocuments(String docListPath) throws IOException
      Clones changed documents from git.

      Only clones documents that are in the changedDocuments set. Removes existing directory and does fresh clone to avoid conflicts.

      Parameters:
      docListPath - path to the document list file
      Returns:
      ActionResult with clone summary
      Throws:
      IOException - if operations fail

    • buildChangedDocuments

      public com.scivicslab.pojoactor.core.ActionResult buildChangedDocuments(String docListPath) throws IOException
      Builds changed Docusaurus documents.

      Only builds documents that are in the changedDocuments set.

      Parameters:
      docListPath - path to the document list file
      Returns:
      ActionResult with build summary
      Throws:
      IOException - if operations fail

    • deployChangedDocuments

      public com.scivicslab.pojoactor.core.ActionResult deployChangedDocuments(String docListPath) throws IOException
      Copies changed document builds to public_html.

      Only copies documents that are in the changedDocuments set.

      Parameters:
      docListPath - path to the document list file
      Returns:
      ActionResult with copy summary
      Throws:
      IOException - if operations fail