public class ProcessRunner extends java.lang.Object implements java.util.concurrent.Callable<ProcessRunnerResult>
Interrupting the thread in which a ProcessRunner
is running will
cause the destroy()
method to be called on the
Process
object of the operating system process. On a UNIX-like
operating system, this will likely result in the process being sent the
SIGTERM signal. (Unfortunately, the Java 7 API documentation does
not guarantee this behavior.) The process is expected to be responsive to
the SIGTERM signal and exit.
If the process creates child processes, it is up to the process to handle
what should happen to the child processes if it is destroyed via
Process.destroy()
. For example, if the process is sh
invoked with two arguments, -c and sleep 5, depending on
the implementation of the sh shell, the sleep 5 command
may result in a child process. If the sh process is destroyed and
the sleep 5 command resulted in a child process, the
sleep 5 child process may continue to run.
Better would be to invoke sh with the following two arguments: -c and exec sleep 5. The exec causes sleep 5 to replace the sh process so that there is only one process. However, in scenarios where the process needs to run with child processes, and they should die when the process is destroyed, the process will need to arrange for that to happen. For example, it might send each child process a SIGTERM signal.
Examples
Here's how to run the uptime program by creating a
ProcessRunner
instance:
ExecutorService service = null;
try {
service = Executors.newSingleThreadExecutor();
ProcessBuilder builder = new ProcessBuilder("uptime");
ProcessRunner runner = new ProcessRunner(builder);
Future<ProcessRunnerResult> future = service.submit(runner);
ProcessRunnerResult result = future.get();
} finally {
if (service != null) service.shutdownNow();
}
Here's how to run the same uptime program using one of the static convenience methods:
ProcessBuilder builder = new ProcessBuilder("uptime");
ProcessRunnerResult result = ProcessRunner.run(builder);
Here's how to run the same uptime program reading its standard output into an 80 byte fixed-size buffer:
ProcessBuilder builder = new ProcessBuilder("uptime");
InputStreamConsumerFactory factory;
factory = FixedSizeBufferInputStreamConsumer.newFactory(80);
ProcessRunnerResult result = ProcessRunner.run(builder, factory);
Constructor and Description |
---|
ProcessRunner(java.lang.ProcessBuilder builder)
Creates an instance with the specified builder and the default
standard-output and standard-error consumer factories that create
GrowingBufferInputStreamConsumer instances. |
ProcessRunner(java.lang.ProcessBuilder builder,
InputStreamConsumerFactory stdoutConsumerFactory)
Creates an instance with the specified builder and standard-output
consumer factory and the default standard-error consumer factory that
creates
GrowingBufferInputStreamConsumer instances. |
ProcessRunner(java.lang.ProcessBuilder builder,
InputStreamConsumerFactory stdoutConsumerFactory,
InputStreamConsumerFactory stderrConsumerFactory)
Creates an instance with the specified builder, standard-output consumer
factory, and standard-error consumer factory.
|
Modifier and Type | Method and Description |
---|---|
ProcessRunnerResult |
call()
Runs the process.
|
static ProcessRunnerResult |
run(java.lang.ProcessBuilder builder)
Creates and runs a
ProcessRunner with the specified builder, and
with the default standard-output consumer and standard-error consumer. |
static ProcessRunnerResult |
run(java.lang.ProcessBuilder builder,
InputStreamConsumerFactory stdoutConsumerFactory)
Creates and runs a
ProcessRunner with the specified builder and
standard-output consumer, and with the default standard-error consumer. |
static ProcessRunnerResult |
run(java.lang.ProcessBuilder builder,
InputStreamConsumerFactory stdoutConsumerFactory,
InputStreamConsumerFactory stderrConsumerFactory)
Creates and runs a
ProcessRunner with the specified builder,
standard-output consumer, and standard-error consumer. |
static ProcessRunnerResult |
run(java.lang.ProcessBuilder builder,
InputStreamConsumerFactory stdoutConsumerFactory,
InputStreamConsumerFactory stderrConsumerFactory,
long timeout,
java.util.concurrent.TimeUnit unit)
Creates and runs a
ProcessRunner with the specified builder,
standard-output consumer, standard-error consumer, and timeout. |
public ProcessRunner(java.lang.ProcessBuilder builder)
GrowingBufferInputStreamConsumer
instances.builder
- used to start the process when this class runspublic ProcessRunner(java.lang.ProcessBuilder builder, InputStreamConsumerFactory stdoutConsumerFactory)
GrowingBufferInputStreamConsumer
instances.builder
- used to start the process when this class runsstdoutConsumerFactory
- factory used to create the standard-output
consumer or null
to use the default factorypublic ProcessRunner(java.lang.ProcessBuilder builder, InputStreamConsumerFactory stdoutConsumerFactory, InputStreamConsumerFactory stderrConsumerFactory)
builder
- used to start the process when this class runsstdoutConsumerFactory
- factory used to create the standard-output
consumer or null
to use the default factorystderrConsumerFactory
- factory used to create the standard-error
consumer or null
to use the default factorypublic ProcessRunnerResult call()
call
in interface java.util.concurrent.Callable<ProcessRunnerResult>
public static ProcessRunnerResult run(java.lang.ProcessBuilder builder) throws java.lang.InterruptedException
ProcessRunner
with the specified builder, and
with the default standard-output consumer and standard-error consumer.builder
- used by the ProcessRunner
instance to start the
processProcessRunner
instancejava.lang.InterruptedException
- if the current thread is interrupted while
waiting for the ProcessRunner
to finishpublic static ProcessRunnerResult run(java.lang.ProcessBuilder builder, InputStreamConsumerFactory stdoutConsumerFactory) throws java.lang.InterruptedException
ProcessRunner
with the specified builder and
standard-output consumer, and with the default standard-error consumer.builder
- used by the ProcessRunner
instance to start the
processstdoutConsumerFactory
- factory used to create the standard-output
consumer or null
to use the default factoryProcessRunner
instancejava.lang.InterruptedException
- if the current thread is interrupted while
waiting for the ProcessRunner
to finishpublic static ProcessRunnerResult run(java.lang.ProcessBuilder builder, InputStreamConsumerFactory stdoutConsumerFactory, InputStreamConsumerFactory stderrConsumerFactory) throws java.lang.InterruptedException
ProcessRunner
with the specified builder,
standard-output consumer, and standard-error consumer.builder
- used by the ProcessRunner
instance to start the
processstdoutConsumerFactory
- factory used to create the standard-output
consumer or null
to use the default factorystderrConsumerFactory
- factory used to create the standard-error
consumer or null
to use the default factoryProcessRunner
instancejava.lang.InterruptedException
- if the current thread is interrupted while
waiting for the ProcessRunner
to finishpublic static ProcessRunnerResult run(java.lang.ProcessBuilder builder, InputStreamConsumerFactory stdoutConsumerFactory, InputStreamConsumerFactory stderrConsumerFactory, long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException, java.util.concurrent.TimeoutException
ProcessRunner
with the specified builder,
standard-output consumer, standard-error consumer, and timeout.builder
- used by the ProcessRunner
instance to start the
processstdoutConsumerFactory
- factory used to create the standard-output
consumer or null
to use the default factorystderrConsumerFactory
- factory used to create the standard-error
consumer or null
to use the default factorytimeout
- amount of time to wait for ProcessRunner
to
complete; 0 means wait foreverunit
- unit of timeout
parameterProcessRunner
instancejava.lang.InterruptedException
- if the current thread is interrupted while
waiting for the ProcessRunner
to finishjava.util.concurrent.TimeoutException
- if the ProcessRunner
has not finished
running within the specified timeout