Package rife.bld.extension.tools

Class ProcessExecutor

java.lang.Object
rife.bld.extension.tools.ProcessExecutor
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.

Since:
1.0
Author:
Erik C. Thauvin

  • Field Details

  • Constructor Details

    • ProcessExecutor

      public ProcessExecutor()

  • Method Details

    • command

      public ProcessExecutor command(@NonNull 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
      Returns:
      this instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements

    • command

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

    • command

      public ProcessExecutor command(@NonNull 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
      Returns:
      this instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements

    • env

      public ProcessExecutor env(@NonNull String name, @NonNull 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(@NonNull 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.

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

    • timeout

      public ProcessExecutor timeout(int timeout)
      Configure the command timeout in seconds.
      Parameters:
      timeout - the timeout, must be greater than 0
      Returns:
      this instance
      Throws:
      IllegalArgumentException - if timeout is less than or equal to 0

    • timeout

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

    • workDir

      public ProcessExecutor workDir(@NonNull 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(@NonNull 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(@NonNull 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

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