Package org.apache.wiki

Class WatchDog

  • public final class WatchDog
extends java.lang.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 Summary

      Constructors 
      Constructor Description
      WatchDog​(Engine engine, java.lang.Thread thread)
      Creates a new WatchDog for a Thread.
      WatchDog​(Engine engine, Watchable watch)
      Creates a new WatchDog for a Watchable.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void disable()
      Is used to disable a WatchDog.
      void enable()
      Can be used to enable the WatchDog.
      void enterState​(java.lang.String state)
      Enters a watched state with no expectation of the expected completion time.
      void enterState​(java.lang.String state, int expectedCompletionTime)
      Enters a watched state which has an expected completion time.
      void exitState()
      Exits a state entered with enterState().
      void exitState​(java.lang.String state)
      Exits a particular state entered with enterState().
      static WatchDog getCurrentWatchDog​(Engine engine)
      Returns the current watchdog for the current thread.
      boolean isStateStackNotEmpty()
      helper to see if the associated stateStack is not empty.
      boolean isWatchableAlive()
      helper to see if the associated watchable is alive.
      java.lang.String toString()
      Strictly for debugging/informative purposes.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • 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,
                java.lang.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 Detail

      • 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​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.String toString()
        Strictly for debugging/informative purposes.
        Overrides:
        toString in class java.lang.Object
        Returns:
        Random ramblings.