Package org.apache.commons.exec

Class ExecuteWatchdog

  • All Implemented Interfaces:
    TimeoutObserver
    public class ExecuteWatchdog
extends java.lang.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.

    See Also:
    Executor, Watchdog

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static long INFINITE_TIMEOUT
      The marker for an infinite timeout

    • Constructor Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void checkException()
      This method will rethrow the exception that was possibly caught during the run of the process.
      void destroyProcess()
      Destroys the running process manually.
      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​(java.lang.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

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • INFINITE_TIMEOUT

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

    • Constructor Detail

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

      • start

        public void start​(java.lang.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:
        java.lang.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 java.lang.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:
        java.lang.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.