org.zeroturnaround.exec
Class ProcessExecutor

java.lang.Object
  org.zeroturnaround.exec.ProcessExecutor

public class ProcessExecutor
extends Object

Helper for executing sub processes.

It's implemented as a wrapper of ProcessBuilder complementing it with additional features such as:

• Handling process streams (copied from Commons Exec library).
• Destroying process on VM exit (copied from Commons Exec library).
• Checking process exit code.
• Setting a timeout for running the process and automatically stopping it in case of timeout.
• Either waiting for the process to finish (execute()) or returning a Future (start().
• Reading the process output stream into a buffer (readOutput(boolean), ProcessResult).

The default configuration for executing a process is following:

• Process is not automatically destroyed on VM exit.
• Error stream is redirected to its output stream. Use redirectErrorStream(boolean) to override it.
• Output stream is pumped to a NullOutputStream, Use streams(ExecuteStreamHandler), redirectOutput(OutputStream), or any of the redirectOutputAs* methods.to override it.
• Any exit code is allowed. Use exitValues(Integer...) to override it.
• In case of timeout or cancellation Process.destroy() is invoked.

Author:

Rein Raudjärv

See Also:

ProcessResult

Field Summary

static Integer[]	DEFAULT_EXIT_VALUES
static boolean	DEFAULT_REDIRECT_ERROR_STREAM

Constructor Summary

ProcessExecutor()
Creates new ProcessExecutor instance.

ProcessExecutor(Iterable<String> command)
Creates new ProcessExecutor instance for the given program and its arguments.

ProcessExecutor(List<String> command)
Creates new ProcessExecutor instance for the given program and its arguments.

ProcessExecutor(String... command)
Creates new ProcessExecutor instance for the given program and its arguments.

Method Summary

ProcessExecutor	addDestroyer(ProcessDestroyer destroyer) Adds a process destroyer to be notified when the process starts and stops.
ProcessExecutor	addListener(ProcessListener listener) Register new process event handler.
ProcessExecutor	clearListeners() Unregister all existing process event handlers.
ProcessExecutor	closeTimeout(long timeout, TimeUnit unit) Sets a timeout for closing standard streams of the process being executed.
ProcessExecutor	command(Iterable<String> command) Sets the program and its arguments which are being executed.
ProcessExecutor	command(List<String> command) Sets the program and its arguments which are being executed.
ProcessExecutor	command(String... command) Sets the program and its arguments which are being executed.
ProcessExecutor	commandSplit(String commandWithArgs) Splits string by spaces and passes it to command(String...) NB: this method do not handle whitespace escaping, "mkdir new\ folder" would be interpreted as {"mkdir", "new\", "folder"} command.
ProcessExecutor	debug() Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	debug(org.slf4j.Logger log) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	debug(String name) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	destroyer(ProcessDestroyer destroyer) Sets the process destroyer to be notified when the process starts and stops.
ProcessExecutor	destroyOnExit() Sets the started process to be destroyed on VM exit (shutdown hooks are executed).
ProcessExecutor	directory(File directory) Sets this working directory for the process being executed.
ProcessExecutor	environment(Map<String,String> env) Adds additional environment variables for the process being executed.
ProcessExecutor	environment(String name, String value) Adds a single additional environment variable for the process being executed.
ProcessResult	execute() Executes the sub process.
ProcessResult	executeNoTimeout() Executes the sub process.
ProcessExecutor	exitValue(Integer exitValue) Sets the allowed exit value for the process being executed.
ProcessExecutor	exitValueAny() Allows any exit value for the process being executed.
ProcessExecutor	exitValueNormal() Allows only 0 as the exit value for the process being executed.
ProcessExecutor	exitValues(int[] exitValues) Sets the allowed exit values for the process being executed.
ProcessExecutor	exitValues(Integer... exitValues) Sets the allowed exit values for the process being executed.
ProcessExecutor	info() Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	info(org.slf4j.Logger log) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	info(String name) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	listener(ProcessListener listener) Unregister all existing process event handlers and register new one.
PumpStreamHandler	pumps()
ProcessExecutor	readOutput(boolean readOutput) Sets this process executor's readOutput property.
ProcessExecutor	redirectError(OutputStream output) Redirects the process' error stream to given output stream.
ProcessExecutor	redirectErrorAlsoTo(OutputStream output) Redirects the process' error stream also to a given output stream.
ProcessExecutor	redirectErrorAsDebug() Deprecated. use redirectError(OutputStream) and Slf4jStream
ProcessExecutor	redirectErrorAsDebug(org.slf4j.Logger log) Deprecated. use redirectError(OutputStream) and Slf4jStream
ProcessExecutor	redirectErrorAsDebug(String name) Deprecated. use redirectError(OutputStream) and Slf4jStream
ProcessExecutor	redirectErrorAsInfo() Deprecated. use redirectError(OutputStream) and Slf4jStream
ProcessExecutor	redirectErrorAsInfo(org.slf4j.Logger log) Deprecated. use redirectError(OutputStream) and Slf4jStream
ProcessExecutor	redirectErrorAsInfo(String name) Deprecated. use redirectError(OutputStream) and Slf4jStream
ProcessExecutor	redirectErrorStream(boolean redirectErrorStream) Sets this process executor's redirectErrorStream property.
ProcessExecutor	redirectInput(InputStream input) Sets the input stream to redirect to the process' input stream.
ProcessExecutor	redirectOutput(OutputStream output) Redirects the process' output stream to given output stream.
ProcessExecutor	redirectOutputAlsoTo(OutputStream output) Redirects the process' output stream also to a given output stream.
ProcessExecutor	redirectOutputAsDebug() Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	redirectOutputAsDebug(org.slf4j.Logger log) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	redirectOutputAsDebug(String name) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	redirectOutputAsInfo() Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	redirectOutputAsInfo(org.slf4j.Logger log) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	redirectOutputAsInfo(String name) Deprecated. use redirectOutput(OutputStream) and Slf4jStream
ProcessExecutor	removeListener(ProcessListener listener) Unregister existing process event handler.
ProcessExecutor	removeListeners(Class<? extends ProcessListener> listenerType) Unregister existing process event handlers of given type or its sub-types.
ProcessExecutor	setMessageLogger(MessageLogger messageLogger) Changes how most common messages about starting and waiting for processes are actually logged.
StartedProcess	start() Start the sub process.
ProcessExecutor	stopper(ProcessStopper stopper) Sets the helper for stopping the process in case of timeout or cancellation.
ExecuteStreamHandler	streams()
ProcessExecutor	streams(ExecuteStreamHandler streams) Sets a stream handler for the process being executed.
ProcessExecutor	timeout(long timeout, TimeUnit unit) Sets a timeout for the process being executed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_EXIT_VALUES

public static final Integer[] DEFAULT_EXIT_VALUES

DEFAULT_REDIRECT_ERROR_STREAM

public static final boolean DEFAULT_REDIRECT_ERROR_STREAM

See Also:

Constant Field Values

Constructor Detail

ProcessExecutor

public ProcessExecutor()

Creates new ProcessExecutor instance.

ProcessExecutor

public ProcessExecutor(List<String> command)

Creates new ProcessExecutor instance for the given program and its arguments.

Parameters:

command - The list containing the program and its arguments.

ProcessExecutor

public ProcessExecutor(String... command)

Creates new ProcessExecutor instance for the given program and its arguments.

Parameters:

command - A string array containing the program and its arguments.

ProcessExecutor

public ProcessExecutor(Iterable<String> command)

Creates new ProcessExecutor instance for the given program and its arguments.

Parameters:

command - The iterable containing the program and its arguments.

Since:

1.8

Method Detail

command

public ProcessExecutor command(List<String> command)

Sets the program and its arguments which are being executed.

Parameters:

command - The list containing the program and its arguments.

Returns:

This process executor.

command

public ProcessExecutor command(String... command)

Sets the program and its arguments which are being executed.

Parameters:

command - A string array containing the program and its arguments.

Returns:

This process executor.

command

public ProcessExecutor command(Iterable<String> command)

Sets the program and its arguments which are being executed.

Parameters:

command - The iterable containing the program and its arguments.

Returns:

This process executor.

Since:

1.8

commandSplit

public ProcessExecutor commandSplit(String commandWithArgs)

Splits string by spaces and passes it to command(String...)
NB: this method do not handle whitespace escaping, "mkdir new\ folder" would be interpreted as {"mkdir", "new\", "folder"} command.

Parameters:

commandWithArgs - A string array containing the program and its arguments.

Returns:

This process executor.

directory

public ProcessExecutor directory(File directory)

Sets this working directory for the process being executed. The argument may be null -- this means to use the working directory of the current Java process, usually the directory named by the system property user.dir, as the working directory of the child process.

Parameters:

directory - The new working directory

Returns:

This process executor.

environment

public ProcessExecutor environment(Map<String,String> env)

Adds additional environment variables for the process being executed.

Parameters:

env - environment variables added to the process being executed.

Returns:

This process executor.

environment

public ProcessExecutor environment(String name,
                                   String value)

Adds a single additional environment variable for the process being executed.

Parameters:

name - name of the environment variable added to the process being executed.

value - value of the environment variable added to the process being executed.

Returns:

This process executor.

Since:

1.7

redirectErrorStream

public ProcessExecutor redirectErrorStream(boolean redirectErrorStream)

Sets this process executor's redirectErrorStream property.

If this property is true, then any error output generated by subprocesses will be merged with the standard output. This makes it easier to correlate error messages with the corresponding output. The initial value is true.

Parameters:

redirectErrorStream - The new property value

Returns:

This process executor.

exitValueAny

public ProcessExecutor exitValueAny()

Allows any exit value for the process being executed.

Returns:

This process executor.

exitValueNormal

public ProcessExecutor exitValueNormal()

Allows only 0 as the exit value for the process being executed.

Returns:

This process executor.

exitValue

public ProcessExecutor exitValue(Integer exitValue)

Sets the allowed exit value for the process being executed.

Parameters:

exitValue - single exit value or null if all exit values are allowed.

Returns:

This process executor.

exitValues

public ProcessExecutor exitValues(Integer... exitValues)

Sets the allowed exit values for the process being executed.

Parameters:

exitValues - set of exit values or null if all exit values are allowed.

Returns:

This process executor.

exitValues

public ProcessExecutor exitValues(int[] exitValues)

Sets the allowed exit values for the process being executed.

Parameters:

exitValues - set of exit values or null if all exit values are allowed.

Returns:

This process executor.

timeout

public ProcessExecutor timeout(long timeout,
                               TimeUnit unit)

Sets a timeout for the process being executed. When this timeout is reached a TimeoutException is thrown and the process is destroyed. This only applies to execute methods not start methods.

Parameters:

timeout - timeout for running a process.

Returns:

This process executor.

stopper

public ProcessExecutor stopper(ProcessStopper stopper)

Sets the helper for stopping the process in case of timeout or cancellation.

By default DestroyProcessStopper is used which just invokes Process.destroy().

Parameters:

stopper - helper for stopping the process (null means NopProcessStopper - process is not stopped).

Returns:

This process executor.

streams

public ExecuteStreamHandler streams()

Returns:

current stream handler for the process being executed.

streams

public ProcessExecutor streams(ExecuteStreamHandler streams)

Sets a stream handler for the process being executed. This will overwrite any stream redirection that was previously set to use the provided handler.

Returns:

This process executor.

closeTimeout

public ProcessExecutor closeTimeout(long timeout,
                                    TimeUnit unit)

Sets a timeout for closing standard streams of the process being executed. When this timeout is reached we log a warning but consider that the process has finished. We also flush the streams so that all output read so far is available.

This can be used on Windows in case a process exits quickly but closing the streams blocks forever.

Closing timeout must fit into the general execution timeout (see timeout(long, TimeUnit)). By default there's no closing timeout.

Parameters:

timeout - timeout for closing streams of a process.

Returns:

This process executor.

redirectInput

public ProcessExecutor redirectInput(InputStream input)

Sets the input stream to redirect to the process' input stream. If this method is invoked multiple times each call overwrites the previous.

Parameters:

input - input stream that will be written to the process input stream (null means nothing will be written to the process input stream).

Returns:

This process executor.

redirectOutput

public ProcessExecutor redirectOutput(OutputStream output)

Redirects the process' output stream to given output stream. If this method is invoked multiple times each call overwrites the previous. Use redirectOutputAlsoTo(OutputStream) if you want to redirect the output to multiple streams.

Parameters:

output - output stream where the process output is redirected to (null means NullOutputStream which acts like a /dev/null).

Returns:

This process executor.

redirectError

public ProcessExecutor redirectError(OutputStream output)

Redirects the process' error stream to given output stream. If this method is invoked multiple times each call overwrites the previous. Use redirectErrorAlsoTo(OutputStream) if you want to redirect the error to multiple streams.

Calling this method automatically disables merging the process error stream to its output stream.

Parameters:

output - output stream where the process error is redirected to (null means NullOutputStream which acts like a /dev/null).

Returns:

This process executor.

redirectOutputAlsoTo

public ProcessExecutor redirectOutputAlsoTo(OutputStream output)

Redirects the process' output stream also to a given output stream. This method can be used to redirect output to multiple streams.

Returns:

This process executor.

redirectErrorAlsoTo

public ProcessExecutor redirectErrorAlsoTo(OutputStream output)

Redirects the process' error stream also to a given output stream. This method can be used to redirect error to multiple streams.

Calling this method automatically disables merging the process error stream to its output stream.

Returns:

This process executor.

pumps

public PumpStreamHandler pumps()

Returns:

current PumpStreamHandler (maybe null).

Throws:

IllegalStateException - if the current stream handler is not an instance of PumpStreamHandler.

See Also:

streams()

readOutput

public ProcessExecutor readOutput(boolean readOutput)

Sets this process executor's readOutput property.

If this property is true, the process output should be read to a buffer and returned by ProcessResult.output(). The initial value is false.

Parameters:

readOutput - The new property value

Returns:

This process executor.

info

public ProcessExecutor info(org.slf4j.Logger log)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a given Logger with info level.

Returns:

This process executor.

debug

public ProcessExecutor debug(org.slf4j.Logger log)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a given Logger with debug level.

Returns:

This process executor.

info

public ProcessExecutor info(String name)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger with given name using info level.

Returns:

This process executor.

debug

public ProcessExecutor debug(String name)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger with given name using debug level.

Returns:

This process executor.

info

public ProcessExecutor info()

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger of the caller class using info level.

Returns:

This process executor.

debug

public ProcessExecutor debug()

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger of the caller class using debug level.

Returns:

This process executor.

redirectOutputAsInfo

public ProcessExecutor redirectOutputAsInfo(org.slf4j.Logger log)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a given Logger with info level.

Returns:

This process executor.

redirectOutputAsDebug

public ProcessExecutor redirectOutputAsDebug(org.slf4j.Logger log)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a given Logger with debug level.

Returns:

This process executor.

redirectOutputAsInfo

public ProcessExecutor redirectOutputAsInfo(String name)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger with given name using info level.

Returns:

This process executor.

redirectOutputAsDebug

public ProcessExecutor redirectOutputAsDebug(String name)

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger with given name using debug level.

Returns:

This process executor.

redirectOutputAsInfo

public ProcessExecutor redirectOutputAsInfo()

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger of the caller class using info level.

Returns:

This process executor.

redirectOutputAsDebug

public ProcessExecutor redirectOutputAsDebug()

Deprecated. use redirectOutput(OutputStream) and Slf4jStream

Logs the process' output to a Logger of the caller class using debug level.

Returns:

This process executor.

redirectErrorAsInfo

public ProcessExecutor redirectErrorAsInfo(org.slf4j.Logger log)

Deprecated. use redirectError(OutputStream) and Slf4jStream

Logs the process' error to a given Logger with info level.

Returns:

This process executor.

redirectErrorAsDebug

public ProcessExecutor redirectErrorAsDebug(org.slf4j.Logger log)

Deprecated. use redirectError(OutputStream) and Slf4jStream

Logs the process' error to a given Logger with debug level.

Returns:

This process executor.

redirectErrorAsInfo

public ProcessExecutor redirectErrorAsInfo(String name)

Deprecated. use redirectError(OutputStream) and Slf4jStream

Logs the process' error to a Logger with given name using info level.

Returns:

This process executor.

redirectErrorAsDebug

public ProcessExecutor redirectErrorAsDebug(String name)

Deprecated. use redirectError(OutputStream) and Slf4jStream

Logs the process' error to a Logger with given name using debug level.

Returns:

This process executor.

redirectErrorAsInfo

public ProcessExecutor redirectErrorAsInfo()

Deprecated. use redirectError(OutputStream) and Slf4jStream

Logs the process' error to a Logger of the caller class using info level.

Returns:

This process executor.

redirectErrorAsDebug

public ProcessExecutor redirectErrorAsDebug()

Deprecated. use redirectError(OutputStream) and Slf4jStream

Logs the process' error to a Logger of the caller class using debug level.

Returns:

This process executor.

addDestroyer

public ProcessExecutor addDestroyer(ProcessDestroyer destroyer)

Adds a process destroyer to be notified when the process starts and stops.

Parameters:

destroyer - helper for destroying all processes on certain event such as VM exit (not null).

Returns:

This process executor.

destroyer

public ProcessExecutor destroyer(ProcessDestroyer destroyer)

Sets the process destroyer to be notified when the process starts and stops.

This methods always removes any other ProcessDestroyer registered. Use addDestroyer(ProcessDestroyer) to keep the existing ones.

Parameters:

destroyer - helper for destroying all processes on certain event such as VM exit (maybe null).

Returns:

This process executor.

destroyOnExit

public ProcessExecutor destroyOnExit()

Sets the started process to be destroyed on VM exit (shutdown hooks are executed). If this VM gets killed the started process may not get destroyed.

To undo this command call destroyer(null).

Returns:

This process executor.

listener

public ProcessExecutor listener(ProcessListener listener)

Unregister all existing process event handlers and register new one.

Parameters:

listener - process event handler to be set (maybe null).

Returns:

This process executor.

addListener

public ProcessExecutor addListener(ProcessListener listener)

Register new process event handler.

Parameters:

listener - process event handler to be added.

Returns:

This process executor.

removeListener

public ProcessExecutor removeListener(ProcessListener listener)

Unregister existing process event handler.

Parameters:

listener - process event handler to be removed.

Returns:

This process executor.

removeListeners

public ProcessExecutor removeListeners(Class<? extends ProcessListener> listenerType)

Unregister existing process event handlers of given type or its sub-types.

Parameters:

listenerType - process event handler type.

Returns:

This process executor.

clearListeners

public ProcessExecutor clearListeners()

Unregister all existing process event handlers.

Returns:

This process executor.

setMessageLogger

public ProcessExecutor setMessageLogger(MessageLogger messageLogger)

Changes how most common messages about starting and waiting for processes are actually logged. By default MessageLoggers.DEBUG is used. However if someone is executing a process every second MessageLoggers.TRACE may be used e.g.

Parameters:

messageLogger - message logger for certain level.

Returns:

This process executor.

execute

public ProcessResult execute()
                      throws IOException,
                             InterruptedException,
                             TimeoutException,
                             InvalidExitValueException

Executes the sub process. This method waits until the process exits, a timeout occurs or the caller thread gets interrupted. In the latter cases the process gets destroyed as well.

Returns:

exit code of the finished process.

Throws:

IOException - an error occurred when process was started or stopped.

InterruptedException - this thread was interrupted.

TimeoutException - timeout set by timeout(long, TimeUnit) was reached.

InvalidExitValueException - if invalid exit value was returned (@see exitValues(Integer...)).

executeNoTimeout

public ProcessResult executeNoTimeout()
                               throws IOException,
                                      InterruptedException,
                                      InvalidExitValueException

Executes the sub process. This method waits until the process exits. Value passed to timeout(long, TimeUnit) is ignored (use execute() for timeout).

Returns:

exit code of the finished process.

Throws:

IOException - an error occurred when process was started or stopped.

InterruptedException - this thread was interrupted.

InvalidExitValueException - if invalid exit value was returned (@see exitValues(Integer...)).

start

public StartedProcess start()
                     throws IOException

Start the sub process. This method does not wait until the process exits. Value passed to timeout(long, TimeUnit) is ignored. Use Future.get() to wait for the process to finish. Invoke future.cancel(true); to destroy the process.

Returns:

Future representing the exit value of the finished process.

Throws:

IOException - an error occurred when process was started.