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:

  • Field Details

  • 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.