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 = new ExecuteWatchdog(30000);
 Executer exec = new Executer(myloghandler, watchdog);
 exec.setCommandLine(mycmdline);
 int exitvalue = exec.execute();
 if (Execute.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') 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 has returned.

Version:
$Id: ExecuteWatchdog.java 1612032 2014-07-20 06:30:44Z ggregory $
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private Exception
    caught
    Exception that might be thrown during the process execution.
    private final boolean
    hasWatchdog
    Is a user-supplied timeout in use
    static final long
    INFINITE_TIMEOUT
    The marker for an infinite timeout
    private boolean
    killedProcess
    Say whether or not the process was killed due to running overtime.
    private Process
    process
    The process to execute and watch for duration.
    private boolean
    processStarted
    Indicates that the process is verified as started
    private boolean
    watch
    Say whether or not the watchdog is currently monitoring a process.
    private final Watchdog
    watchdog
    Will tell us whether timeout has occurred.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ExecuteWatchdog(long timeout)
    Creates a new watchdog with a given timeout.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    private void
    ensureStarted()
    Ensures that the process is started, so we do not race with asynch execution.
    boolean
    isWatching()
    Indicates whether or not the watchdog is still monitoring the process.
    boolean
    killedProcess()
    Indicates whether the last process run was killed.
    (package private) void
    setProcessNotStarted()
     
    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:

    • process

      private Process process
      The process to execute and watch for duration.

    • hasWatchdog

      private final boolean hasWatchdog
      Is a user-supplied timeout in use

    • watch

      private boolean watch
      Say whether or not the watchdog is currently monitoring a process.

    • caught

      private Exception caught
      Exception that might be thrown during the process execution.

    • killedProcess

      private boolean killedProcess
      Say whether or not the process was killed due to running overtime.

    • watchdog

      private final Watchdog watchdog
      Will tell us whether timeout has occurred.

    • processStarted

      private volatile boolean processStarted
      Indicates that the process is verified as started

  • Constructor Details

    • ExecuteWatchdog

      public ExecuteWatchdog(long timeout)
      Creates a new watchdog with a given timeout.
      Parameters:
      timeout - the timeout for the process in milliseconds. It must be greater than 0 or 'INFINITE_TIMEOUT'

  • Method Details

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

    • destroyProcess

      public void destroyProcess()
      Destroys the running process manually.

    • timeoutOccured

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

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

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

    • cleanUp

      protected void cleanUp()
      reset the monitor flag and the process.

    • setProcessNotStarted

      void setProcessNotStarted()

    • ensureStarted

      private void ensureStarted()
      Ensures that the process is started, so we do not race with asynch execution. The caller of this method must be holding the lock on this