Class ProcessExecutor
- java.lang.Object
-
- org.zeroturnaround.exec.ProcessExecutor
-
public class ProcessExecutor extends java.lang.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 aFuture
(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
, Usestreams(ExecuteStreamHandler)
,redirectOutput(OutputStream)
, or any of theredirectOutputAs*
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.
- See Also:
ProcessResult
-
-
Field Summary
Fields Modifier and Type Field Description private java.util.Set<java.lang.Integer>
allowedExitValues
Set of accepted exit codes ornull
if all exit codes are allowed.private java.lang.ProcessBuilder
builder
Process builder used by this executor.private java.lang.Long
closeTimeout
Timeout for closing process' standard streams.private java.util.concurrent.TimeUnit
closeTimeoutUnit
static java.lang.Integer[]
DEFAULT_EXIT_VALUES
static boolean
DEFAULT_REDIRECT_ERROR_STREAM
private java.util.Map<java.lang.String,java.lang.String>
environment
Environment variables which are added (removed in case ofnull
values) to the process being started.private static boolean
IS_OS_WINDOWS
private CompositeProcessListener
listeners
Process event handlers.private static org.slf4j.Logger
log
private MessageLogger
messageLogger
Helper for logging messages about starting and waiting for the processes.private static java.lang.Integer
NORMAL_EXIT_VALUE
private boolean
readOutput
true
if the process output should be read to a buffer and returned byProcessResult.output()
.private ProcessStopper
stopper
Helper for stopping the process in case of timeout or cancellation.private ExecuteStreamHandler
streams
Process stream Handler (copied from Commons Exec library).private java.lang.Long
timeout
Timeout for running a process.private java.util.concurrent.TimeUnit
timeoutUnit
-
Constructor Summary
Constructors Constructor Description ProcessExecutor()
Creates newProcessExecutor
instance.ProcessExecutor(java.lang.Iterable<java.lang.String> command)
Creates newProcessExecutor
instance for the given program and its arguments.ProcessExecutor(java.lang.String... command)
Creates newProcessExecutor
instance for the given program and its arguments.ProcessExecutor(java.util.List<java.lang.String> command)
Creates newProcessExecutor
instance for the given program and its arguments.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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.private void
applyEnvironment()
void
checkExitValue(ProcessResult result)
Check the exit value of given process result.ProcessExecutor
clearListeners()
Unregister all existing process event handlers.ProcessExecutor
closeTimeout(long timeout, java.util.concurrent.TimeUnit unit)
Sets a timeout for closing standard streams of the process being executed.ProcessExecutor
command(java.lang.Iterable<java.lang.String> command)
Sets the program and its arguments which are being executed.ProcessExecutor
command(java.lang.String... command)
Sets the program and its arguments which are being executed.ProcessExecutor
command(java.util.List<java.lang.String> command)
Sets the program and its arguments which are being executed.ProcessExecutor
commandSplit(java.lang.String commandWithArgs)
Splits string by spaces and passes it tocommand(String...)
NB: this method do not handle whitespace escaping,"mkdir new\ folder"
would be interpreted as{"mkdir", "new\", "folder"}
command.ProcessExecutor
debug()
Deprecated.ProcessExecutor
debug(java.lang.String name)
Deprecated.ProcessExecutor
debug(org.slf4j.Logger log)
Deprecated.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(java.io.File directory)
Sets this working directory for the process being executed.ProcessExecutor
environment(java.lang.String name, java.lang.String value)
Adds a single additional environment variable for the process being executed.ProcessExecutor
environment(java.util.Map<java.lang.String,java.lang.String> env)
Adds additional environment variables for the process being executed.ProcessResult
execute()
Executes the sub process.ProcessResult
executeNoTimeout()
Executes the sub process.ProcessExecutor
exitValue(java.lang.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 only0
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(java.lang.Integer... exitValues)
Sets the allowed exit values for the process being executed.private static java.util.List<java.lang.String>
fixArguments(java.util.List<java.lang.String> command)
Fixes the command line arguments on Windows by replacing empty arguments with""
.private ProcessAttributes
getAttributes()
Capture a snapshot of this process executor's main state.private org.slf4j.Logger
getCallerLogger(java.lang.String name)
Creates aLogger
for theProcessExecutor
's caller class.java.util.List<java.lang.String>
getCommand()
Returns this process executor's operating system program and arguments.java.io.File
getDirectory()
Returns this process executor's working directory.java.util.Map<java.lang.String,java.lang.String>
getEnvironment()
Returns this process executor's additional environment variables.private java.lang.String
getExecutingErrorMessage()
private java.lang.String
getExecutingLogMessage()
private java.lang.String
getExecutingMessageParams()
private static java.lang.Integer
getExitCodeOrNull(java.lang.Process process)
private static java.lang.String
getUnitsAsString(long d, java.util.concurrent.TimeUnit unit)
ProcessExecutor
info()
Deprecated.ProcessExecutor
info(java.lang.String name)
Deprecated.ProcessExecutor
info(org.slf4j.Logger log)
Deprecated.private java.lang.Process
invokeStart()
protected <T> java.util.concurrent.Future<T>
invokeSubmit(java.util.concurrent.ExecutorService executor, java.util.concurrent.Callable<T> task)
Override this to customize how the waiting task is started in the background.ProcessExecutor
listener(ProcessListener listener)
Unregister all existing process event handlers and register new one.protected java.util.concurrent.ExecutorService
newExecutor(java.lang.String processName)
private java.util.concurrent.ExecutorService
newExecutor(WaitForProcess task)
private ProcessCloser
newProcessCloser(ExecuteStreamHandler streams)
private java.util.concurrent.TimeoutException
newTimeoutException(long timeout, java.util.concurrent.TimeUnit unit, WaitForProcess task)
PumpStreamHandler
pumps()
ProcessExecutor
readOutput(boolean readOutput)
Sets this process executor'sreadOutput
property.ProcessExecutor
redirectError(java.io.OutputStream output)
Redirects the process' error stream to given output stream.ProcessExecutor
redirectErrorAlsoTo(java.io.OutputStream output)
Redirects the process' error stream also to a given output stream.private static PumpStreamHandler
redirectErrorAlsoTo(PumpStreamHandler pumps, java.io.OutputStream output)
Redirects the process' error stream also to a given output stream.ProcessExecutor
redirectErrorAsDebug()
Deprecated.ProcessExecutor
redirectErrorAsDebug(java.lang.String name)
Deprecated.ProcessExecutor
redirectErrorAsDebug(org.slf4j.Logger log)
Deprecated.ProcessExecutor
redirectErrorAsInfo()
Deprecated.ProcessExecutor
redirectErrorAsInfo(java.lang.String name)
Deprecated.ProcessExecutor
redirectErrorAsInfo(org.slf4j.Logger log)
Deprecated.ProcessExecutor
redirectErrorStream(boolean redirectErrorStream)
Sets this process executor'sredirectErrorStream
property.ProcessExecutor
redirectInput(java.io.InputStream input)
Sets the input stream to redirect to the process' input stream.ProcessExecutor
redirectOutput(java.io.OutputStream output)
Redirects the process' output stream to given output stream.ProcessExecutor
redirectOutputAlsoTo(java.io.OutputStream output)
Redirects the process' output stream also to a given output stream.private static PumpStreamHandler
redirectOutputAlsoTo(PumpStreamHandler pumps, java.io.OutputStream output)
Redirects the process' output stream also to a given output stream.ProcessExecutor
redirectOutputAsDebug()
Deprecated.ProcessExecutor
redirectOutputAsDebug(java.lang.String name)
Deprecated.ProcessExecutor
redirectOutputAsDebug(org.slf4j.Logger log)
Deprecated.ProcessExecutor
redirectOutputAsInfo()
Deprecated.ProcessExecutor
redirectOutputAsInfo(java.lang.String name)
Deprecated.ProcessExecutor
redirectOutputAsInfo(org.slf4j.Logger log)
Deprecated.ProcessExecutor
removeListener(ProcessListener listener)
Unregister existing process event handler.ProcessExecutor
removeListeners(java.lang.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.protected WaitForProcess
startInternal()
Start the process and its stream handlers.private WaitForProcess
startInternal(java.lang.Process process, ProcessAttributes attributes, ExecuteStreamHandler streams, java.io.ByteArrayOutputStream out)
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, java.util.concurrent.TimeUnit unit)
Sets a timeout for the process being executed.private void
validateStreams(ExecuteStreamHandler streams, boolean readOutput)
Validates that ifreadOutput
istrue
the output could be read with the givenExecuteStreamHandler
instance.private ProcessResult
waitFor(WaitForProcess task)
Wait until the process stops, a timeout occurs and the caller thread gets interrupted.protected <T> java.util.concurrent.Callable<T>
wrapTask(java.util.concurrent.Callable<T> task)
Override this to customize how the background task is created.
-
-
-
Field Detail
-
log
private static final org.slf4j.Logger log
-
IS_OS_WINDOWS
private static final boolean IS_OS_WINDOWS
-
DEFAULT_EXIT_VALUES
public static final java.lang.Integer[] DEFAULT_EXIT_VALUES
-
NORMAL_EXIT_VALUE
private static final java.lang.Integer NORMAL_EXIT_VALUE
-
DEFAULT_REDIRECT_ERROR_STREAM
public static final boolean DEFAULT_REDIRECT_ERROR_STREAM
- See Also:
- Constant Field Values
-
builder
private final java.lang.ProcessBuilder builder
Process builder used by this executor.
-
environment
private final java.util.Map<java.lang.String,java.lang.String> environment
Environment variables which are added (removed in case ofnull
values) to the process being started.
-
allowedExitValues
private java.util.Set<java.lang.Integer> allowedExitValues
Set of accepted exit codes ornull
if all exit codes are allowed.
-
timeout
private java.lang.Long timeout
Timeout for running a process. If the process is running too long aTimeoutException
is thrown and the process is destroyed.
-
timeoutUnit
private java.util.concurrent.TimeUnit timeoutUnit
-
stopper
private ProcessStopper stopper
Helper for stopping the process in case of timeout or cancellation.
-
streams
private ExecuteStreamHandler streams
Process stream Handler (copied from Commons Exec library). Ifnull
streams are not handled.
-
closeTimeout
private java.lang.Long closeTimeout
Timeout for closing process' standard streams. In case this timeout is reached we just log a warning but don't throw an error.
-
closeTimeoutUnit
private java.util.concurrent.TimeUnit closeTimeoutUnit
-
readOutput
private boolean readOutput
true
if the process output should be read to a buffer and returned byProcessResult.output()
.
-
listeners
private final CompositeProcessListener listeners
Process event handlers.
-
messageLogger
private MessageLogger messageLogger
Helper for logging messages about starting and waiting for the processes.
-
-
Constructor Detail
-
ProcessExecutor
public ProcessExecutor()
Creates newProcessExecutor
instance.
-
ProcessExecutor
public ProcessExecutor(java.util.List<java.lang.String> command)
Creates newProcessExecutor
instance for the given program and its arguments.- Parameters:
command
- The list containing the program and its arguments.
-
ProcessExecutor
public ProcessExecutor(java.lang.String... command)
Creates newProcessExecutor
instance for the given program and its arguments.- Parameters:
command
- A string array containing the program and its arguments.
-
ProcessExecutor
public ProcessExecutor(java.lang.Iterable<java.lang.String> command)
Creates newProcessExecutor
instance for the given program and its arguments.- Parameters:
command
- The iterable containing the program and its arguments.- Since:
- 1.8
-
-
Method Detail
-
getCommand
public java.util.List<java.lang.String> getCommand()
Returns this process executor's operating system program and arguments. The returned list is a copy.- Returns:
- this process executor's program and its arguments (not
null
).
-
command
public ProcessExecutor command(java.util.List<java.lang.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(java.lang.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(java.lang.Iterable<java.lang.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(java.lang.String commandWithArgs)
Splits string by spaces and passes it tocommand(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.
-
getDirectory
public java.io.File getDirectory()
Returns this process executor's working directory. Subprocesses subsequently started by this object will use this as their working directory. The returned value may benull
-- this means to use the working directory of the current Java process, usually the directory named by the system propertyuser.dir
, as the working directory of the child process.- Returns:
- this process executor's working directory
-
directory
public ProcessExecutor directory(java.io.File directory)
Sets this working directory for the process being executed. The argument may benull
-- this means to use the working directory of the current Java process, usually the directory named by the system propertyuser.dir
, as the working directory of the child process.- Parameters:
directory
- The new working directory- Returns:
- This process executor.
-
getEnvironment
public java.util.Map<java.lang.String,java.lang.String> getEnvironment()
Returns this process executor's additional environment variables. The returned value is not a copy.- Returns:
- this process executor's environment variables (not
null
).
-
environment
public ProcessExecutor environment(java.util.Map<java.lang.String,java.lang.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(java.lang.String name, java.lang.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'sredirectErrorStream
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 istrue
.- 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 only0
as the exit value for the process being executed.- Returns:
- This process executor.
-
exitValue
public ProcessExecutor exitValue(java.lang.Integer exitValue)
Sets the allowed exit value for the process being executed.- Parameters:
exitValue
- single exit value ornull
if all exit values are allowed.- Returns:
- This process executor.
-
exitValues
public ProcessExecutor exitValues(java.lang.Integer... exitValues)
Sets the allowed exit values for the process being executed.- Parameters:
exitValues
- set of exit values ornull
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 ornull
if all exit values are allowed.- Returns:
- This process executor.
-
timeout
public ProcessExecutor timeout(long timeout, java.util.concurrent.TimeUnit unit)
Sets a timeout for the process being executed. When this timeout is reached aTimeoutException
is thrown and the process is destroyed. This only applies toexecute
methods notstart
methods.- Parameters:
timeout
- timeout for running a process.unit
- the time unit of the timeout- 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 invokesProcess.destroy()
.- Parameters:
stopper
- helper for stopping the process (null
meansNopProcessStopper
- 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.- Parameters:
streams
- the stream handler- Returns:
- This process executor.
-
closeTimeout
public ProcessExecutor closeTimeout(long timeout, java.util.concurrent.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.unit
- the time unit of the timeout- Returns:
- This process executor.
-
redirectInput
public ProcessExecutor redirectInput(java.io.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(java.io.OutputStream output)
Redirects the process' output stream to given output stream. If this method is invoked multiple times each call overwrites the previous. UseredirectOutputAlsoTo(OutputStream)
if you want to redirect the output to multiple streams.- Parameters:
output
- output stream where the process output is redirected to (null
meansNullOutputStream
which acts like a/dev/null
).- Returns:
- This process executor.
-
redirectError
public ProcessExecutor redirectError(java.io.OutputStream output)
Redirects the process' error stream to given output stream. If this method is invoked multiple times each call overwrites the previous. UseredirectErrorAlsoTo(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
meansNullOutputStream
which acts like a/dev/null
).- Returns:
- This process executor.
-
redirectOutputAlsoTo
public ProcessExecutor redirectOutputAlsoTo(java.io.OutputStream output)
Redirects the process' output stream also to a given output stream. This method can be used to redirect output to multiple streams.- Parameters:
output
- the stream to redirect this output to- Returns:
- This process executor.
-
redirectErrorAlsoTo
public ProcessExecutor redirectErrorAlsoTo(java.io.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.
- Parameters:
output
- the output stream to redirect the error stream to- Returns:
- This process executor.
-
pumps
public PumpStreamHandler pumps()
- Returns:
- current PumpStreamHandler (maybe
null
). - Throws:
java.lang.IllegalStateException
- if the current stream handler is not an instance ofPumpStreamHandler
.- See Also:
streams()
-
redirectOutputAlsoTo
private static PumpStreamHandler redirectOutputAlsoTo(PumpStreamHandler pumps, java.io.OutputStream output)
Redirects the process' output stream also to a given output stream.- Returns:
- new stream handler created.
-
redirectErrorAlsoTo
private static PumpStreamHandler redirectErrorAlsoTo(PumpStreamHandler pumps, java.io.OutputStream output)
Redirects the process' error stream also to a given output stream.- Returns:
- new stream handler created.
-
readOutput
public ProcessExecutor readOutput(boolean readOutput)
Sets this process executor'sreadOutput
property.If this property is
true
, the process output should be read to a buffer and returned byProcessResult.output()
. The initial value isfalse
.- Parameters:
readOutput
- The new property value- Returns:
- This process executor.
-
validateStreams
private void validateStreams(ExecuteStreamHandler streams, boolean readOutput)
Validates that ifreadOutput
istrue
the output could be read with the givenExecuteStreamHandler
instance.
-
info
public ProcessExecutor info(org.slf4j.Logger log)
Deprecated.Logs the process' output to a givenLogger
withinfo
level.- Parameters:
log
- the logger to process the output to- Returns:
- This process executor.
-
debug
public ProcessExecutor debug(org.slf4j.Logger log)
Deprecated.Logs the process' output to a givenLogger
withdebug
level.- Parameters:
log
- the logger to process the output to- Returns:
- This process executor.
-
info
public ProcessExecutor info(java.lang.String name)
Deprecated.Logs the process' output to aLogger
with given name usinginfo
level.- Parameters:
name
- the name of the logger to process the output to- Returns:
- This process executor.
-
debug
public ProcessExecutor debug(java.lang.String name)
Deprecated.Logs the process' output to aLogger
with given name usingdebug
level.- Parameters:
name
- the name of the logger to process the output to- Returns:
- This process executor.
-
info
public ProcessExecutor info()
Deprecated.Logs the process' output to aLogger
of the caller class usinginfo
level.- Returns:
- This process executor.
-
debug
public ProcessExecutor debug()
Deprecated.Logs the process' output to aLogger
of the caller class usingdebug
level.- Returns:
- This process executor.
-
redirectOutputAsInfo
public ProcessExecutor redirectOutputAsInfo(org.slf4j.Logger log)
Deprecated.Logs the process' output to a givenLogger
withinfo
level.- Parameters:
log
- the logger to output the message to- Returns:
- This process executor.
-
redirectOutputAsDebug
public ProcessExecutor redirectOutputAsDebug(org.slf4j.Logger log)
Deprecated.Logs the process' output to a givenLogger
withdebug
level.- Parameters:
log
- the logger to output the message to- Returns:
- This process executor.
-
redirectOutputAsInfo
public ProcessExecutor redirectOutputAsInfo(java.lang.String name)
Deprecated.Logs the process' output to aLogger
with given name usinginfo
level.- Parameters:
name
- the name of the logger to log to- Returns:
- This process executor.
-
redirectOutputAsDebug
public ProcessExecutor redirectOutputAsDebug(java.lang.String name)
Deprecated.Logs the process' output to aLogger
with given name usingdebug
level.- Parameters:
name
- the name of the logger to process output to- Returns:
- This process executor.
-
redirectOutputAsInfo
public ProcessExecutor redirectOutputAsInfo()
Deprecated.Logs the process' output to aLogger
of the caller class usinginfo
level.- Returns:
- This process executor.
-
redirectOutputAsDebug
public ProcessExecutor redirectOutputAsDebug()
Deprecated.Logs the process' output to aLogger
of the caller class usingdebug
level.- Returns:
- This process executor.
-
redirectErrorAsInfo
public ProcessExecutor redirectErrorAsInfo(org.slf4j.Logger log)
Deprecated.Logs the process' error to a givenLogger
withinfo
level.- Parameters:
log
- the logger to process output to- Returns:
- This process executor.
-
redirectErrorAsDebug
public ProcessExecutor redirectErrorAsDebug(org.slf4j.Logger log)
Deprecated.Logs the process' error to a givenLogger
withdebug
level.- Parameters:
log
- the logger to process the error to- Returns:
- This process executor.
-
redirectErrorAsInfo
public ProcessExecutor redirectErrorAsInfo(java.lang.String name)
Deprecated.Logs the process' error to aLogger
with given name usinginfo
level.- Parameters:
name
- the name of the logger to process the error to- Returns:
- This process executor.
-
redirectErrorAsDebug
public ProcessExecutor redirectErrorAsDebug(java.lang.String name)
Deprecated.Logs the process' error to aLogger
with given name usingdebug
level.- Parameters:
name
- the name of the logger to process the error to- Returns:
- This process executor.
-
redirectErrorAsInfo
public ProcessExecutor redirectErrorAsInfo()
Deprecated.Logs the process' error to aLogger
of the caller class usinginfo
level.- Returns:
- This process executor.
-
redirectErrorAsDebug
public ProcessExecutor redirectErrorAsDebug()
Deprecated.Logs the process' error to aLogger
of the caller class usingdebug
level.- Returns:
- This process executor.
-
getCallerLogger
private org.slf4j.Logger getCallerLogger(java.lang.String name)
Creates aLogger
for theProcessExecutor
's caller class.- Parameters:
name
- name of the logger.- Returns:
- SLF4J Logger instance.
-
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 (notnull
).- 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. UseaddDestroyer(ProcessDestroyer)
to keep the existing ones.- Parameters:
destroyer
- helper for destroying all processes on certain event such as VM exit (maybenull
).- 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 (maybenull
).- 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(java.lang.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 defaultMessageLoggers.DEBUG
is used. However if someone is executing a process every secondMessageLoggers.TRACE
may be used e.g.- Parameters:
messageLogger
- message logger for certain level.- Returns:
- This process executor.
-
execute
public ProcessResult execute() throws java.io.IOException, java.lang.InterruptedException, java.util.concurrent.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:
java.io.IOException
- an error occurred when process was started or stopped.java.lang.InterruptedException
- this thread was interrupted.java.util.concurrent.TimeoutException
- timeout set bytimeout(long, TimeUnit)
was reached.InvalidExitValueException
- if invalid exit value was returned (@seeexitValues(Integer...)
).
-
executeNoTimeout
public ProcessResult executeNoTimeout() throws java.io.IOException, java.lang.InterruptedException, InvalidExitValueException
Executes the sub process. This method waits until the process exits. Value passed totimeout(long, TimeUnit)
is ignored (useexecute()
for timeout).- Returns:
- exit code of the finished process.
- Throws:
java.io.IOException
- an error occurred when process was started or stopped.java.lang.InterruptedException
- this thread was interrupted.InvalidExitValueException
- if invalid exit value was returned (@seeexitValues(Integer...)
).
-
checkExitValue
public void checkExitValue(ProcessResult result) throws InvalidExitValueException
Check the exit value of given process result. This can be used by unit tests.- Parameters:
result
- process result which maybe constructed by a unit test.- Throws:
InvalidExitValueException
- if the given exit value was rejected.
-
start
public StartedProcess start() throws java.io.IOException
Start the sub process. This method does not wait until the process exits. Value passed totimeout(long, TimeUnit)
is ignored. UseFuture.get()
to wait for the process to finish. Invokefuture.cancel(true);
to destroy the process.- Returns:
- Future representing the exit value of the finished process.
- Throws:
java.io.IOException
- an error occurred when process was started.
-
startInternal
protected final WaitForProcess startInternal() throws java.io.IOException
Start the process and its stream handlers.- Returns:
- process the started process.
- Throws:
java.io.IOException
- the process or its stream handlers couldn't start (in the latter case we also destroy the process).
-
getAttributes
private ProcessAttributes getAttributes()
Capture a snapshot of this process executor's main state.
-
invokeStart
private java.lang.Process invokeStart() throws java.io.IOException
- Throws:
java.io.IOException
-
getExecutingLogMessage
private java.lang.String getExecutingLogMessage()
-
getExecutingErrorMessage
private java.lang.String getExecutingErrorMessage()
-
getExecutingMessageParams
private java.lang.String getExecutingMessageParams()
-
startInternal
private WaitForProcess startInternal(java.lang.Process process, ProcessAttributes attributes, ExecuteStreamHandler streams, java.io.ByteArrayOutputStream out) throws java.io.IOException
- Throws:
java.io.IOException
-
newProcessCloser
private ProcessCloser newProcessCloser(ExecuteStreamHandler streams)
-
waitFor
private ProcessResult waitFor(WaitForProcess task) throws java.io.IOException, java.lang.InterruptedException, java.util.concurrent.TimeoutException
Wait until the process stops, a timeout occurs and the caller thread gets interrupted. In the latter cases the process gets destroyed as well.- Throws:
java.io.IOException
java.lang.InterruptedException
java.util.concurrent.TimeoutException
-
newExecutor
private java.util.concurrent.ExecutorService newExecutor(WaitForProcess task)
-
newExecutor
protected java.util.concurrent.ExecutorService newExecutor(java.lang.String processName)
-
invokeSubmit
protected <T> java.util.concurrent.Future<T> invokeSubmit(java.util.concurrent.ExecutorService executor, java.util.concurrent.Callable<T> task)
Override this to customize how the waiting task is started in the background.- Type Parameters:
T
- the type of the task- Parameters:
executor
- the executor service to submit the task ontask
- the task to be submitted- Returns:
- the future of the task
-
wrapTask
protected <T> java.util.concurrent.Callable<T> wrapTask(java.util.concurrent.Callable<T> task)
Override this to customize how the background task is created.- Type Parameters:
T
- the type of the Task- Parameters:
task
- the Task to be wrapped- Returns:
- the wrapped task
-
newTimeoutException
private java.util.concurrent.TimeoutException newTimeoutException(long timeout, java.util.concurrent.TimeUnit unit, WaitForProcess task)
-
getUnitsAsString
private static java.lang.String getUnitsAsString(long d, java.util.concurrent.TimeUnit unit)
-
getExitCodeOrNull
private static java.lang.Integer getExitCodeOrNull(java.lang.Process process)
-
applyEnvironment
private void applyEnvironment()
-
fixArguments
private static java.util.List<java.lang.String> fixArguments(java.util.List<java.lang.String> command)
Fixes the command line arguments on Windows by replacing empty arguments with""
. Otherwise these arguments would be just skipped.
-
-