Package com.seeq.utilities.process
Class ProcessSpawn
java.lang.Object
com.seeq.utilities.process.ProcessSpawn
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
A local facade to theStreamGobbler.LineReceivedCallback
class. -
Constructor Summary
ConstructorsConstructorDescriptionProcessSpawn
(String... command) Allocates a ProcessSpawn object and initializes it with the command and arguments specified.ProcessSpawn
(List<String> commandList) Allocates a ProcessSpawn object and initializes it with the command and arguments specified. -
Method Summary
Modifier and TypeMethodDescriptionAssembles a tree of running processes.command()
Returns the command that was passed in to the constructor.void
Kills the process forcibly.Returns the working directory for the spawned process.void
Sets the working directory for the spawned process.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.static long
Returns current process ID (PID).Returns the callback used to notify when error output is received.Returns the all text from the spawned process' error stream.int
Returns the exit code of the spawned process.Returns the input stream for the child process.Returns the callback used to notify when output is received.Returns the all text from the spawned process' output stream.getPid()
Returns the process identifier (PID) that can be used to kill the process.boolean
True if all output and error content should be captured in a string and accessible via the getOutputString() and getErrorString() accessors.boolean
Returns whether the process is running or not.static void
Kills all child processes of the current process recursively.void
killTree()
Terminates the spawned process and all child processessetCaptureTextEnabled
(boolean captureTextEnabled) Controls whether output and error content should be captured in a string and accessible via the getOutputString() and getErrorString() accessors.void
setErrorReceivedCallback
(ProcessSpawn.LineReceivedCallback errorReceivedCallback) Sets the callback used to notify when error output is received.setOutputReceivedCallback
(ProcessSpawn.LineReceivedCallback outputReceivedCallback) Sets the callback used to notify when output is received.setPrintToSystemOut
(Boolean printToSystemOut) setSimpleMode
(Boolean simpleMode) setUseCmdShell
(Boolean useCmdShell) void
start()
Spawns the process and begins processing output.void
waitFor()
Waits for process to terminate and all output streams to be closed.void
Waits for process to terminate and all output streams to be closed.
-
Constructor Details
-
ProcessSpawn
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
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
-
getUseCmdShell
-
setSimpleMode
-
setPrintToSystemOut
-
setUseCmdShell
-
command
Returns the command that was passed in to the constructor.- Returns:
- the command that was passed in to the constructor
-
directory
Sets the working directory for the spawned process.- Parameters:
directory
- the working directory for the spawned process
-
directory
Returns the working directory for the spawned process.- Returns:
- the working directory for the spawned process
-
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
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
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
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
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
Waits for process to terminate and all output streams to be closed.- Throws:
InterruptedException
- Method interrupted waiting for completion.TimeoutException
-
assembleProcessTree
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
Kills all child processes of the current process recursively.- Throws:
InterruptedException
- Method interrupted waiting for completion.IOException
- If an I/O error occurs.
-
killTree
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
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
Returns the all text from the spawned process' output stream.- Returns:
- the all text from the spawned process' output stream
-
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
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
Returns the callback used to notify when error output is received.- Returns:
- the callback used to notify when error output is received
-
setErrorReceivedCallback
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
-