Package org.apache.commons.exec
Class ExecuteWatchdog
java.lang.Object
org.apache.commons.exec.ExecuteWatchdog
- All Implemented Interfaces:
TimeoutObserver
Destroys a process running for too long. For example:
ExecuteWatchdog watchdog = ExecuteWatchdog.builder().setTimeout(Duration.ofSeconds(30)).get(); Executor executor = DefaultExecutor.builder().setExecuteStreamHandler(new PumpStreamHandler()).get(); executor.setWatchdog(watchdog); int exitValue = executor.execute(myCommandLine); if (executor.isFailure(exitValue) && watchdog.killedProcess()) { // it was killed on purpose by the watchdog }
When starting an asynchronous process than 'ExecuteWatchdog' is the keeper of the process handle. In some cases it is useful not to define a timeout (and
pass INFINITE_TIMEOUT_DURATION
) and to kill the process explicitly using destroyProcess()
.
Please note that ExecuteWatchdog is processed asynchronously, e.g. it might be still attached to a process even after the
DefaultExecutor.execute(CommandLine)
or a variation has returned.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Builds ExecuteWatchdog instances. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Exception
Exception that might be thrown during the process execution.private final boolean
Is a user-supplied timeout in use.static final long
The marker for an infinite timeout.static final Duration
The marker for an infinite timeout.private boolean
Say whether or not the process was killed due to running overtime.private Process
The process to execute and watch for duration.private boolean
Indicates that the process is verified as startedprivate final ThreadFactory
The thread factory.private boolean
Say whether or not the watchdog is currently monitoring a process.private final Watchdog
Will tell us whether timeout has occurred. -
Constructor Summary
ConstructorsModifierConstructorDescriptionExecuteWatchdog
(long timeoutMillis) Deprecated.private
ExecuteWatchdog
(ThreadFactory threadFactory, Duration timeout) Creates a new watchdog with a given timeout. -
Method Summary
Modifier and TypeMethodDescriptionstatic ExecuteWatchdog.Builder
builder()
Creates a new builder.void
This method will rethrow the exception that was possibly caught during the run of the process.protected void
cleanUp()
reset the monitor flag and the process.void
Destroys the running process manually.private void
Ensures that the process is started or not already terminated so we do not race with asynch executionor hang forever.void
Notification that starting the process failed.boolean
Indicates whether or not the watchdog is still monitoring the process.boolean
Indicates whether the last process run was killed.(package private) void
void
Watches the given process and terminates it, if it runs for too long.void
stop()
Stops the watcher.void
Called after watchdog has finished.
-
Field Details
-
INFINITE_TIMEOUT
public static final long INFINITE_TIMEOUTThe marker for an infinite timeout.- See Also:
-
INFINITE_TIMEOUT_DURATION
The marker for an infinite timeout. -
process
The process to execute and watch for duration. -
hasWatchdog
private final boolean hasWatchdogIs a user-supplied timeout in use. -
watch
private boolean watchSay whether or not the watchdog is currently monitoring a process. -
caught
Exception that might be thrown during the process execution. -
killedProcess
private boolean killedProcessSay whether or not the process was killed due to running overtime. -
watchdog
Will tell us whether timeout has occurred. -
processStarted
private volatile boolean processStartedIndicates that the process is verified as started -
threadFactory
The thread factory.
-
-
Constructor Details
-
ExecuteWatchdog
Deprecated.Creates a new watchdog with a given timeout.- Parameters:
timeoutMillis
- the timeout for the process in milliseconds. It must be greater than 0 orINFINITE_TIMEOUT
.
-
ExecuteWatchdog
Creates a new watchdog with a given timeout.- Parameters:
threadFactory
- the thread factory.timeout
- the timeout Duration for the process. It must be greater than 0 orINFINITE_TIMEOUT_DURATION
.
-
-
Method Details
-
builder
Creates a new builder.- Returns:
- a new builder.
- Since:
- 1.4.0
-
checkException
This method will rethrow the exception that was possibly caught during the run of the process. It will only remains valid once the process has been terminated either by 'error', timeout or manual intervention. Information will be discarded once a new process is ran.- Throws:
Exception
- a wrapped exception over the one that was silently swallowed and stored during the process run.
-
cleanUp
protected void cleanUp()reset the monitor flag and the process. -
destroyProcess
public void destroyProcess()Destroys the running process manually. -
ensureStarted
private void ensureStarted()Ensures that the process is started or not already terminated so we do not race with asynch executionor hang forever. The caller of this method must be holding the lock on this. -
failedToStart
Notification that starting the process failed.- Parameters:
e
- the offending exception.
-
isWatching
public boolean isWatching()Indicates whether or not the watchdog is still monitoring the process.- Returns:
true
if the process is still running, otherwisefalse
.
-
killedProcess
public boolean killedProcess()Indicates whether the last process run was killed.- Returns:
true
if the process was killedfalse
.
-
setProcessNotStarted
void setProcessNotStarted() -
start
Watches the given process and terminates it, if it runs for too long. All information from the previous run are reset.- Parameters:
processToMonitor
- the process to monitor. It cannot benull
.- Throws:
IllegalStateException
- if a process is still being monitored.
-
stop
public void stop()Stops the watcher. It will notify all threads possibly waiting on this object. -
timeoutOccured
Called after watchdog has finished.- Specified by:
timeoutOccured
in interfaceTimeoutObserver
- Parameters:
w
- the watchdog that timed out.
-
ExecuteWatchdog.Builder.get()
.