Class Node

java.lang.Object
com.scivicslab.actoriac.Node
public class Node extends Object
Represents a single node in the infrastructure as a pure POJO.

This is a pure POJO class that provides SSH-based command execution capabilities. It has NO dependency on ActorSystem or workflow components.

Three Levels of Usage

Level 1: Pure POJO (Synchronous)

Node node = new Node("192.168.1.1", "admin");
CommandResult result = node.executeCommand("show version");
System.out.println(result.getStdout());

Level 2: Actor-based (Asynchronous, Parallel)

ActorSystem system = new ActorSystem("iac", 4);
ActorRef<Node> nodeActor = system.actorOf("node1", node);
CompletableFuture<CommandResult> future = nodeActor.ask(n -> n.executeCommand("show version"));

Level 3: Workflow-based (YAML/JSON/XML)

// Use NodeInterpreter instead for workflow capabilities
NodeInterpreter nodeInterpreter = new NodeInterpreter(node, system);
IIActorRef<NodeInterpreter> nodeActor = new IIActorRef<>("node1", nodeInterpreter, system);

Uses ssh-agent for SSH key authentication. Make sure ssh-agent is running and your SSH key is added before using this class.

Author:
devteam@scivicslab.com

  • Field Details

  • Constructor Details

    • Node

      public Node(String hostname, String user, int port)
      Constructs a Node with the specified connection parameters (POJO constructor).
      Parameters:
      hostname - the hostname or IP address of the node
      user - the SSH username
      port - the SSH port (typically 22)

    • Node

      public Node(String hostname, String user, int port, boolean localMode)
      Constructs a Node with the specified connection parameters and local mode.
      Parameters:
      hostname - the hostname or IP address of the node
      user - the SSH username
      port - the SSH port (typically 22)
      localMode - if true, execute commands locally instead of via SSH

    • Node

      public Node(String hostname, String user, int port, boolean localMode, String password)
      Constructs a Node with all connection parameters including password.
      Parameters:
      hostname - the hostname or IP address of the node
      user - the SSH username
      port - the SSH port (typically 22)
      localMode - if true, execute commands locally instead of via SSH
      password - the SSH password (null to use ssh-agent key authentication)

    • Node

      public Node(String hostname, String user)
      Constructs a Node with default port 22 (POJO constructor).
      Parameters:
      hostname - the hostname or IP address of the node
      user - the SSH username

  • Method Details

    • isLocalMode

      public boolean isLocalMode()
      Checks if this node is in local execution mode.
      Returns:
      true if commands are executed locally, false for SSH

    • executeCommand

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

      If localMode is true, executes the command locally using ProcessBuilder. Otherwise, executes via SSH using JSch.

      Parameters:
      command - the command to execute
      Returns:
      the execution result containing stdout, stderr, and exit code
      Throws:
      IOException - if command execution fails

    • executeCommand

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

      If localMode is true, executes the command locally using ProcessBuilder. Otherwise, executes via SSH using JSch.

      The callback receives stdout and stderr lines as they are produced, enabling real-time forwarding to accumulators.

      Parameters:
      command - the command to execute
      callback - the callback for real-time output (may be null)
      Returns:
      the execution result containing stdout, stderr, and exit code
      Throws:
      IOException - if command execution fails

    • executeLocalCommand

      private Node.CommandResult executeLocalCommand(String command, Node.OutputCallback callback) throws IOException
      Executes a command locally using ProcessBuilder with real-time streaming.

      Output is streamed via callback (if provided) in real-time as it becomes available, while also being captured for the CommandResult.

      Parameters:
      command - the command to execute
      callback - the callback for real-time output (may be null)
      Returns:
      the execution result
      Throws:
      IOException - if command execution fails

    • executeRemoteCommand

      private Node.CommandResult executeRemoteCommand(String command, Node.OutputCallback callback) throws IOException
      Executes a command on the remote node via SSH using JSch with real-time streaming.

      Output is streamed via callback (if provided) in real-time as it becomes available, while also being captured for the CommandResult.

      Parameters:
      command - the command to execute
      callback - the callback for real-time output (may be null)
      Returns:
      the execution result containing stdout, stderr, and exit code
      Throws:
      IOException - if SSH connection or command execution fails

    • executeSudoCommand

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

      Reads the sudo password from the SUDO_PASSWORD environment variable. If the environment variable is not set, throws an IOException.

      Multi-line scripts are properly handled by wrapping them in bash -c.

      Parameters:
      command - the command to execute with sudo
      Returns:
      the execution result containing stdout, stderr, and exit code
      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.

      Reads the sudo password from the SUDO_PASSWORD environment variable. If the environment variable is not set, throws an IOException.

      Multi-line scripts are properly handled by wrapping them in bash -c.

      Parameters:
      command - the command to execute with sudo
      callback - the callback for real-time output (may be null)
      Returns:
      the execution result containing stdout, stderr, and exit code
      Throws:
      IOException - if SSH connection fails or SUDO_PASSWORD is not set

    • createSession

      private com.jcraft.jsch.Session createSession() throws com.jcraft.jsch.JSchException, IOException
      Creates a JSch SSH session with configured credentials. Supports ProxyJump for connections through a jump host.
      Returns:
      configured but not yet connected Session
      Throws:
      com.jcraft.jsch.JSchException - if session creation fails
      IOException - if SSH key file operations fail

    • setupAuthentication

      private void setupAuthentication(com.jcraft.jsch.JSch jsch, String identityFileFromConfig) throws IOException, com.jcraft.jsch.JSchException
      Sets up authentication for JSch.
      Throws:
      IOException
      com.jcraft.jsch.JSchException

    • createSessionViaProxyJump

      private com.jcraft.jsch.Session createSessionViaProxyJump(com.jcraft.jsch.JSch jsch, String proxyJump, String targetUser, String targetHost, int targetPort) throws com.jcraft.jsch.JSchException, IOException
      Creates a session through a jump host using ProxyJump. Format: user@host or user@host:port
      Throws:
      com.jcraft.jsch.JSchException
      IOException

    • cleanup

      public void cleanup()
      Cleans up resources used by this Node. Closes any open jump host sessions.

    • getHostname

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

    • getUser

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

    • getPort

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

    • toString

      public String toString()
      Overrides:
      toString in class Object