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@scivics-lab.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

    • executeLocalCommand

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

      Output is streamed to System.out/System.err in real-time as it becomes available, while also being captured for the CommandResult.

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

    • executeRemoteCommand

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

      Output is streamed to System.out/System.err in real-time as it becomes available, while also being captured for the CommandResult.

      Parameters:
      command - the command to execute
      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

    • 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