Package rife.bld.extension.tools

Class ProcessExecutor

java.lang.Object
rife.bld.extension.tools.ProcessExecutor
@NullMarked public class ProcessExecutor extends Object
Generic process executor with timeout, I/O control, and output capture.

Framework-agnostic utility that can be composed by any extension. Handles process tree cleanup and stream management for Windows compatibility.

This class is not thread-safe. Configure and execute from a single thread.

Since:
1.0
Author:
Erik C. Thauvin

  • Field Details

    • DEFAULT_TIMEOUT_SECONDS

      public static final long DEFAULT_TIMEOUT_SECONDS
      Default timeout in seconds.
      See Also:

  • Constructor Details

    • ProcessExecutor

      public ProcessExecutor()

  • Method Details

    • command

      public ProcessExecutor command(String... args)
      Sets the command and arguments to be executed, replacing any previously configured command.
      Parameters:
      args - one or more arguments, must not be null or contain null/empty elements. The first element must be a non-blank program name.
      Returns:
      this instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null/empty elements.

    • command

      public List<String> command()
      Returns the mutable command and arguments list.
      Returns:
      the command list, never null

    • command

      public ProcessExecutor command(Collection<String> args)
      Sets the command and arguments to be executed, replacing any previously configured command.
      Parameters:
      args - the list of arguments, must not be null or contain null/empty elements. The first element must be a non-blank program name.
      Returns:
      this instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null/empty elements

    • env

      public ProcessExecutor env(String name, String value)
      Adds an environment variable for the command.
      Parameters:
      name - the variable name, must not be null
      value - the variable value, must not be null
      Returns:
      this instance
      Throws:
      NullPointerException - if name or value is null

    • env

      public ProcessExecutor env(Map<String,String> vars)
      Adds environment variables for the command.
      Parameters:
      vars - the map of environment variables, must not be null
      Returns:
      this instance
      Throws:
      NullPointerException - if vars is null

    • env

      public Map<String,String> env()
      Returns the mutable environment variables map.
      Returns:
      the environment map, never null

    • execute

      public ProcessExecutor.ProcessResult execute() throws IOException, InterruptedException
      Executes the command and returns the result.
      Returns:
      the process result containing exit code and captured output
      Throws:
      IOException - if the process cannot be started
      InterruptedException - if the thread is interrupted while waiting
      IllegalStateException - if no command is set, the working directory is invalid, or both inheritIO() and outputConsumer(Consumer) are configured

    • inheritIO

      public ProcessExecutor inheritIO(boolean inheritIO)
      Configures whether the child process should inherit the I/O streams of the current JVM.

      When true, the child process uses the same stdin, stdout, and stderr as the current Java process. Output is not captured; ProcessExecutor.ProcessResult.output() will return an empty string in this mode.

      When false (the default), stdout and stderr are merged and captured. Stdin receives EOF.

      Cannot be used with outputConsumer(Consumer).

      Parameters:
      inheritIO - true to inherit I/O, false to capture output
      Returns:
      this instance

    • inheritIO

      public boolean inheritIO()
      Returns whether the child process inherits the I/O streams of the current JVM.
      Returns:
      true if I/O is inherited, false if output is captured

    • outputConsumer

      public ProcessExecutor outputConsumer(Consumer<String> consumer)
      Sets a consumer to receive output lines as they arrive.

      Only effective when inheritIO() is false. The consumer is called from a background thread. Setting this implies output should be captured, not inherited.

      Exceptions thrown by the consumer are silently ignored to protect the output reader thread. Ensure the consumer handles its own errors if reliable delivery is required.

      Parameters:
      consumer - the output consumer, or null to disable
      Returns:
      this instance

    • timeout

      public ProcessExecutor timeout(long timeout)
      Configure the command timeout in seconds.

      Use a negative value to disable the timeout and wait indefinitely.

      A value of 0 is invalid as it would cause the process to fail immediately if not completed instantly.

      Default: DEFAULT_TIMEOUT_SECONDS

      Parameters:
      timeout - the timeout in seconds; use negative value for no timeout
      Returns:
      this instance
      Throws:
      IllegalArgumentException - if timeout is 0

    • timeout

      public long timeout()
      Returns the command timeout in seconds.
      Returns:
      the timeout

    • workDir

      public ProcessExecutor workDir(File dir)
      Configures the working directory.
      Parameters:
      dir - the directory, must not be null
      Returns:
      this instance
      Throws:
      NullPointerException - if dir is null

    • workDir

      public ProcessExecutor workDir(Path dir)
      Configures the working directory.
      Parameters:
      dir - the directory, must not be null
      Returns:
      this instance
      Throws:
      NullPointerException - if dir is null

    • workDir

      public ProcessExecutor workDir(String dir)
      Configures the working directory.
      Parameters:
      dir - the directory path, must not be null or empty
      Returns:
      this instance
      Throws:
      IllegalArgumentException - if dir is null or empty

    • workDir

      public @Nullable File workDir()
      Returns the working directory.
      Returns:
      the directory, or null if not set