Package org.apache.commons.exec

# Class ExecuteWatchdog

java.lang.Object
org.apache.commons.exec.ExecuteWatchdog

All Implemented Interfaces:
  `TimeoutObserver`

public class ExecuteWatchdog extends Object implements 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:
  - `Executor`
  - `Watchdog`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `ExecuteWatchdog.Builder`
  Builds ExecuteWatchdog instances.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final long`
  `INFINITE_TIMEOUT`
  The marker for an infinite timeout.
  `static final Duration`
  `INFINITE_TIMEOUT_DURATION`
  The marker for an infinite timeout.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExecuteWatchdog(long timeoutMillis)`
  Deprecated.
  Use `ExecuteWatchdog.Builder.get()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ExecuteWatchdog.Builder`
  `builder()`
  Creates a new builder.
  `void`
  `checkException()`
  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`
  `destroyProcess()`
  Destroys the running process manually.
  `void`
  `failedToStart(Exception e)`
  Notification that starting the process failed.
  `boolean`
  `isWatching()`
  Indicates whether or not the watchdog is still monitoring the process.
  `boolean`
  `killedProcess()`
  Indicates whether the last process run was killed.
  `void`
  `start(Process processToMonitor)`
  Watches the given process and terminates it, if it runs for too long.
  `void`
  `stop()`
  Stops the watcher.
  `void`
  `timeoutOccured(Watchdog w)`
  Called after watchdog has finished.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### INFINITE_TIMEOUT

    public static final long INFINITE_TIMEOUT
    The marker for an infinite timeout.
    See Also:
      - Constant Field Values

  - ### INFINITE_TIMEOUT_DURATION

    public static final Duration INFINITE_TIMEOUT_DURATION
    The marker for an infinite timeout.

- ## Constructor Details

  - ### ExecuteWatchdog

    @Deprecated public ExecuteWatchdog(long timeoutMillis)
    Deprecated.
    Use `ExecuteWatchdog.Builder.get()`.
    Creates a new watchdog with a given timeout.
    Parameters:
      `timeoutMillis` - the timeout for the process in milliseconds. It must be greater than 0 or `INFINITE_TIMEOUT`.

- ## Method Details

  - ### builder

    public static ExecuteWatchdog.Builder builder()
    Creates a new builder.
    Returns:
      a new builder.
    Since:
      1.4.0

  - ### checkException

    public void checkException() throws Exception
    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.

  - ### failedToStart

    public void failedToStart(Exception e)
    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, otherwise `false`.

  - ### killedProcess

    public boolean killedProcess()
    Indicates whether the last process run was killed.
    Returns:
      `true` if the process was killed `false`.

  - ### start

    public void start(Process processToMonitor)
    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 be `null`.
    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

    public void timeoutOccured(Watchdog w)
    Called after watchdog has finished.
    Specified by:
      `timeoutOccured` in interface `TimeoutObserver`
    Parameters:
      `w` - the watchdog that timed out.