org.apache.wiki

Class WatchDog

java.lang.Object

org.apache.wiki.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 and 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

Modifier and Type	Method and 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.