Package org.apache.wiki

Class WatchDog

java.lang.Object
org.apache.wiki.WatchDog
public final class WatchDog extends Object
WatchDog is a general system watchdog. You can attach any Watchable or a Thread object to it, and it will notify you if a timeout has been exceeded.

The notification of the timeouts is done from a separate WatchDog thread, of which there is one per watched thread. This Thread is named 'WatchDog for XXX', where XXX is your Thread name.

The suggested method of obtaining a WatchDog is via the static factory method, since it will return you the correct watchdog for the current thread. However, we do not prevent you from creating your own watchdogs either.

If you create a WatchDog for a Thread, the WatchDog will figure out when the Thread is dead, and will stop itself accordingly. However, this object is not automatically released, so you might want to check it out after a while.

Since:
2.4.92

  • Constructor Details

    • WatchDog

      public WatchDog(Engine engine, Watchable watch)
      Creates a new WatchDog for a Watchable.
      Parameters:
      engine - The Engine.
      watch - A Watchable object.

    • WatchDog

      public WatchDog(Engine engine, Thread thread)
      Creates a new WatchDog for a Thread. The Thread is wrapped in a Watchable wrapper for this purpose.
      Parameters:
      engine - The Engine
      thread - A Thread for watching.

  • Method Details

    • getCurrentWatchDog

      public static WatchDog getCurrentWatchDog(Engine engine)
      Returns the current watchdog for the current thread. This is the preferred method of getting you a Watchdog, since it keeps an internal list of Watchdogs for you so that there won't be more than one watchdog per thread.
      Parameters:
      engine - The Engine to which the Watchdog should be bonded to.
      Returns:
      A usable WatchDog object.

    • enable

      public void enable()
      Can be used to enable the WatchDog. Will cause a new Thread to be created, if none was existing previously.

    • disable

      public void disable()
      Is used to disable a WatchDog. The watchdog thread is shut down and resources released.

    • enterState

      public void enterState(String state)
      Enters a watched state with no expectation of the expected completion time. In practice this method is used when you have no idea, but would like to figure out, e.g. via debugging, where exactly your Watchable is.
      Parameters:
      state - A free-form string description of your state.

    • enterState

      public void enterState(String state, int expectedCompletionTime)
      Enters a watched state which has an expected completion time. This is the main method for using the WatchDog. For example: WatchDog w = m_engine.getCurrentWatchDog(); w.enterState("Processing Foobar", 60); foobar(); w.exitState(); If the call to foobar() takes more than 60 seconds, you will receive an ERROR in the log stream.
      Parameters:
      state - A free-form string description of the state
      expectedCompletionTime - The timeout in seconds.

    • exitState

      public void exitState()
      Exits a state entered with enterState(). This method does not check that the state is correct, it'll just pop out whatever is on the top of the state stack.

    • exitState

      public void exitState(String state)
      Exits a particular state entered with enterState(). The state is checked against the current state, and if they do not match, an error is flagged.
      Parameters:
      state - The state you wish to exit.

    • isStateStackNotEmpty

      public boolean isStateStackNotEmpty()
      helper to see if the associated stateStack is not empty.
      Returns:
      true if not empty, false otherwise.

    • isWatchableAlive

      public boolean isWatchableAlive()
      helper to see if the associated watchable is alive.
      Returns:
      true if it's alive, false otherwise.

    • toString

      public String toString()
      Strictly for debugging/informative purposes.
      Overrides:
      toString in class Object
      Returns:
      Random ramblings.