Class ProcessSpawn

java.lang.Object
com.seeq.utilities.process.ProcessSpawn

public class ProcessSpawn extends Object
Creates and manages processes in a more robust manner than Java's ProcessBuilder by itself. It correctly processes output and error streams so that it gathers all the text on separate threads and makes it available to the caller. It utilizes a somewhat complex scheme to launch a child proxy process that captures a process identifier (PID) that can be used to kill the spawned process forcefully. There is otherwise no easy way to do this in Java.
  • Constructor Details

    • ProcessSpawn

      public ProcessSpawn(String... command)
      Allocates a ProcessSpawn object and initializes it with the command and arguments specified.
      Parameters:
      command - The executable should be the first parameter, and the arguments for the executable should be the second, third, fourth etc.
    • ProcessSpawn

      public ProcessSpawn(List<String> commandList)
      Allocates a ProcessSpawn object and initializes it with the command and arguments specified.
      Parameters:
      commandList - The executable should be the first array member, and the arguments for the executable should be the second, third, fourth etc.
  • Method Details

    • getSimpleMode

      public Boolean getSimpleMode()
    • getUseCmdShell

      public Boolean getUseCmdShell()
    • setSimpleMode

      public ProcessSpawn setSimpleMode(Boolean simpleMode)
    • setPrintToSystemOut

      public ProcessSpawn setPrintToSystemOut(Boolean printToSystemOut)
    • setUseCmdShell

      public ProcessSpawn setUseCmdShell(Boolean useCmdShell)
    • command

      public List<String> command()
      Returns the command that was passed in to the constructor.
      Returns:
      the command that was passed in to the constructor
    • directory

      public void directory(File directory)
      Sets the working directory for the spawned process.
      Parameters:
      directory - the working directory for the spawned process
    • directory

      public File directory()
      Returns the working directory for the spawned process.
      Returns:
      the working directory for the spawned process
    • environment

      public Map<String,String> environment()
      Returns the environment for the spawned process, which is a map where the key is the environment variable name and the value is its value.
      Returns:
      the spawned process builder's environment
    • getPid

      public Long getPid()
      Returns the process identifier (PID) that can be used to kill the process. This is only available when simple mode is false.
      Returns:
      the process identifier (PID)
    • getInputStream

      public OutputStream getInputStream()
      Returns the input stream for the child process. Note that it is technically an instance of the OutputStream class, because you write to it from the parent process.
      Returns:
      the input stream for the child process
    • start

      public void start() throws IOException
      Spawns the process and begins processing output. If simple mode is false, this function will not exit until the process identifier (PID) for the child process has been captured.
      Throws:
      IOException - when process cannot be spawned
    • waitFor

      public void waitFor() throws InterruptedException
      Waits for process to terminate and all output streams to be closed.
      Throws:
      InterruptedException - Method interrupted waiting for completion.
    • destroyForcibly

      public void destroyForcibly()
      Kills the process forcibly. The process represented by this Process object is forcibly terminated.
    • waitFor

      public void waitFor(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException
      Waits for process to terminate and all output streams to be closed.
      Throws:
      InterruptedException - Method interrupted waiting for completion.
      TimeoutException
    • assembleProcessTree

      public static Map<Long,Long> assembleProcessTree() throws InterruptedException, IOException
      Assembles a tree of running processes. This function is unreliable under Windows!
      Returns:
      pid vs ppid map.
      Throws:
      InterruptedException - Method interrupted waiting for completion.
      IOException - If an I/O error occurs.
    • killAllChildProcesses

      public static void killAllChildProcesses() throws IOException, InterruptedException
      Kills all child processes of the current process recursively.
      Throws:
      InterruptedException - Method interrupted waiting for completion.
      IOException - If an I/O error occurs.
    • killTree

      public void killTree() throws IOException, InterruptedException
      Terminates the spawned process and all child processes
      Throws:
      InterruptedException - Method interrupted waiting for completion.
      IOException - If an I/O error occurs.
    • isCaptureTextEnabled

      public boolean isCaptureTextEnabled()
      True if all output and error content should be captured in a string and accessible via the getOutputString() and getErrorString() accessors.
      Returns:
      true if output and error content is being captured
    • setCaptureTextEnabled

      public ProcessSpawn setCaptureTextEnabled(boolean captureTextEnabled)
      Controls whether output and error content should be captured in a string and accessible via the getOutputString() and getErrorString() accessors. WARNING: Setting this to true can significantly affect performance and memory usage if the child process produces significant output.
      Parameters:
      captureTextEnabled - true if output and error content should be captured
    • getOutputString

      public String getOutputString()
      Returns the all text from the spawned process' output stream.
      Returns:
      the all text from the spawned process' output stream
    • getErrorString

      public String getErrorString()
      Returns the all text from the spawned process' error stream.
      Returns:
      the all text from the spawned process' error stream
    • getExitValue

      public int getExitValue()
      Returns the exit code of the spawned process.
      Returns:
      the exit code of the spawned process
    • getOutputReceivedCallback

      public ProcessSpawn.LineReceivedCallback getOutputReceivedCallback()
      Returns the callback used to notify when output is received.
      Returns:
      the callback used to notify when output is received
    • setOutputReceivedCallback

      public ProcessSpawn setOutputReceivedCallback(ProcessSpawn.LineReceivedCallback outputReceivedCallback)
      Sets the callback used to notify when output is received.
      Parameters:
      outputReceivedCallback - the callback used to notify when output is received
    • getErrorReceivedCallback

      public ProcessSpawn.LineReceivedCallback getErrorReceivedCallback()
      Returns the callback used to notify when error output is received.
      Returns:
      the callback used to notify when error output is received
    • setErrorReceivedCallback

      public void setErrorReceivedCallback(ProcessSpawn.LineReceivedCallback errorReceivedCallback)
      Sets the callback used to notify when error output is received.
      Parameters:
      errorReceivedCallback - the callback used to notify when error output is received
    • isRunning

      public boolean isRunning()
      Returns whether the process is running or not.
      Returns:
      whether the process is running.
    • getCurrentPid

      public static long getCurrentPid()
      Returns current process ID (PID). Not guaranteed to work on all operating systems, but it works on Windows, Linux and OSX. Note: There is no way to get code coverage stats on this because it is executing as part of a child process. So this will show up as red in EclEmma.
      Returns:
      process ID