Package com.scivicslab.turingworkflow.plugins.ssh

Class NodeInterpreter

java.lang.Object
com.scivicslab.turingworkflow.workflow.Interpreter
com.scivicslab.turingworkflow.plugins.ssh.NodeInterpreter
public class NodeInterpreter extends com.scivicslab.turingworkflow.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:

  • 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.

Since:
2.0.0
Author:
devteam@scivicslab.com

  • Nested Class Summary

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

    com.scivicslab.turingworkflow.workflow.Interpreter.ActionFailureListener, com.scivicslab.turingworkflow.workflow.Interpreter.BreakpointListener, com.scivicslab.turingworkflow.workflow.Interpreter.Builder

  • Field Summary

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

    code, currentState, currentTransitionIndex, paused, selfActorRef, stopRequested, system, workflowBaseDir

  • Constructor Summary

    Constructors
    Constructor
    Description
    NodeInterpreter(Node node, com.scivicslab.turingworkflow.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.
    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
    executeCommand(String command, Node.OutputCallback callback)
    Executes a command on the remote node via SSH with real-time output callback.
    Node.CommandResult
    executeSudoCommand(String command)
    Executes a command with sudo privileges on the remote node.
    Node.CommandResult
    executeSudoCommand(String command, Node.OutputCallback callback)
    Executes a command with sudo privileges on the remote node with real-time output callback.
    WorkflowStreamingAccumulator
    getAccumulator()
    Gets the WorkflowStreamingAccumulator for cowsay display.
    Set<String>
    getChangedDocuments()
    Gets all changed document names.
    int
    getChangedDocumentsCount()
    Gets the number of changed documents.
    String
    getCurrentTransitionYaml()
    Returns the current transition 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
    onEnterTransition(com.scivicslab.turingworkflow.workflow.Transition transition)
    Hook called when entering a transition during workflow execution.
    protected void
    onExitTransition(com.scivicslab.turingworkflow.workflow.Transition transition, boolean success, com.scivicslab.pojoactor.core.ActionResult result)
    Hook called after a transition completes (success or failure).
    com.scivicslab.pojoactor.core.ActionResult
    runWorkflow(String workflowFile, int maxIterations)
    Loads and runs a workflow file to completion with overlay support.
    void
    setAccumulator(WorkflowStreamingAccumulator accumulator)
    Sets the WorkflowStreamingAccumulator for cowsay display.
    void
    setOverlayDir(String overlayDir)
    Sets the overlay directory for YAML overlay feature.

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

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

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • NodeInterpreter

      public NodeInterpreter(Node node, com.scivicslab.turingworkflow.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

    • executeCommand

      public Node.CommandResult executeCommand(String command, Node.OutputCallback callback) throws IOException
      Executes a command on the remote node via SSH with real-time output callback.

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

      Parameters:
      command - the command to execute
      callback - the callback for real-time output (may be null)
      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

    • executeSudoCommand

      public Node.CommandResult executeSudoCommand(String command, Node.OutputCallback callback) throws IOException
      Executes a command with sudo privileges on the remote node with real-time output callback.

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

      Parameters:
      command - the command to execute with sudo
      callback - the callback for real-time output (may be null)
      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

    • setAccumulator

      public void setAccumulator(WorkflowStreamingAccumulator accumulator)
      Sets the WorkflowStreamingAccumulator for cowsay display.
      Parameters:
      accumulator - the accumulator to use for cowsay display

    • getAccumulator

      public WorkflowStreamingAccumulator getAccumulator()
      Gets the WorkflowStreamingAccumulator for cowsay display.
      Returns:
      the cowsay accumulator, or null if not set

    • onEnterTransition

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

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

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

    • onExitTransition

      protected void onExitTransition(com.scivicslab.turingworkflow.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 outputMultiplexer for workflow execution reporting.

      Overrides:
      onExitTransition in class com.scivicslab.turingworkflow.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

    • getCurrentTransitionYaml

      public String getCurrentTransitionYaml()
      Returns the current transition YAML snippet for accumulator reporting.
      Returns:
      the first 10 lines of the current transition 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.turingworkflow.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

    • 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