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 Summary

Constructors
Constructor
Description
`WatchDog(Engine engine, 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
Description
`void`
`disable()`
Is used to disable a WatchDog.
`void`
`enable()`
Can be used to enable the WatchDog.
`void`
`enterState(String state)`
Enters a watched state with no expectation of the expected completion time.
`void`
`enterState(String state, int expectedCompletionTime)`
Enters a watched state which has an expected completion time.
`void`
`exitState()`
Exits a state entered with enterState().
`void`
`exitState(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.
`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 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.