org.sadun.util.watchdog
Class WatchDog

java.lang.Object
  java.lang.Thread
      org.sadun.util.watchdog.WatchDog

All Implemented Interfaces:

java.lang.Runnable, Terminable

public abstract class WatchDog

extends java.lang.Thread

implements Terminable

A WatchDog thread, which periodically executes some checking action.

The thread is a daemon, therefore will exit when there are no more non-daemon threads running.

Event listeners (implementing the WatchDog.Listenerinterface can be registered and will be notfied of failures or the impossibility to execute a check.

The check is executed synchronously, so if one listener blocks, the others will be blocked as well.

The default check period is set to 5 minutes. The property org.sadun.pool.connection.watchdog.sleeptime can be set to a numeric (long) value to change this.

Synchronous vs. Asynchronous mode

Version 1.0 notified all the listeners synchronously, that is, the method calls of the WatchDog.Listenerinterface happened in the same thread as the thread running WatchDog itself. This implied that if a listener performed a heavy operation or crashed, the following listeners and the watchdog itself where blocked.

Version 1.1 is retrofitted with an aysnchronous listening mode (optional) to allow for complex or unreliable listeners. No changes are required to external code.

The default mode is still synchronous, so existing code behaviour is unchanged. To change the synchronicity mode, either use the new constructoror invoke setSynchronous(boolean)before starting the watchdog.

If the asynchronous mode is selected at construction, listeners notifications will be decoupled from the WatchDog thread itself. Therefore, if a listener blocks, the watchdog thread will not block (see Aysnchronous listening framework for further information).

Asynchronous mode uses more system resources.

Version:

1.1

Author:

Cristiano Sadun

Nested Class Summary

static class	WatchDog.BaseListener A base implementation of WatchDog.Listener which invokes checkFailed() also when a check is impossible.
static interface	WatchDog.Listener The event listening interface for WatchDogevents.

Field Summary

static long

DEFAULT_SLEEP_TIME

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

protected	WatchDog() Create a watchdog with the default check period time.
protected	WatchDog(java.lang.String name) Create a watchdog with the default check period time.
protected	WatchDog(java.lang.String name, long checkPeriodTime) Create a watchdog with the given check period, in milliseconds.
protected	WatchDog(java.lang.String name, long checkPeriodTime, boolean synchronous) Create a watchdog with the given check period, in milliseconds.

Method Summary

void	addListener(WatchDog.Listener l) Add a watchdog listener to the listener set.
void	dispose() Disposes of any resource allocated by the watchdog.
protected abstract java.lang.Throwable	doCheck(java.lang.Object obj) Perform the required check.
void	finalize() The class finalizer.
long	getCheckPeriodTime() Return the amount of time the watchdog waits between each check.
protected java.lang.Object	getObjectToCheck() This method can be implemented by subclasses if the checking action implies one or more objects.
boolean	isRemoveFailedListeners() Return true if listeners that fail are removed from the listener set (in synchronous mode).
boolean	isShuttingDown() See org.sadun.util.Terminable.isShuttingDown().
boolean	isStartBySleeping() Return true if the watchdog goes immediatly to sleep on startup
boolean	isSynchronous() Return the synchronicity mode (see class comment).
void	removeListener(WatchDog.Listener l) Remove a watchdog listener from the listeners set.
void	removeaAllListeners()
void	run() Run the watching loop, until the thread is either shut downor the last running thread.
void	setCheckPeriodTime(long checkPeriodTime) Set the amount of time the watchdog waits between each check.
void	setRemoveFailedListeners(boolean removeFailedListeners) Set wether or not listeners that fail are removed from the listener set (in synchronous mode).
void	setStartBySleeping(boolean startBySleeping)
void	setSynchronous(boolean v) Set the synchronicity mode (see class comment).
void	shutdown() Shut down the watchdog thread.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SLEEP_TIME

public static final long DEFAULT_SLEEP_TIME

See Also:

Constant Field Values

Constructor Detail

WatchDog

protected WatchDog(java.lang.String name,
                   long checkPeriodTime)

Create a watchdog with the given check period, in milliseconds.

The watchdog is created in synchronus mode - i.e. a blocking listener will block the WatchDog thread itself.

Parameters:

name - the name of the WatchDog thread

checkPeriodTime - the amount of time the watchdog waits between each check.

WatchDog

protected WatchDog(java.lang.String name,
                   long checkPeriodTime,
                   boolean synchronous)

Create a watchdog with the given check period, in milliseconds.

The watchdog can be created in either synchronous or asynchronous mode.

In the former case, listeners are invoked in the WatchDog thread - and if they block, the WatchDog thread will block; in the latter case, listeners execution is decoupled from the WatchDog thread.

Asynchronous mode requires is heavier and requires more resources.

Parameters:

name - the name of the WatchDog thread

checkPeriodTime - the amount of time the watchdog waits between each check.

synchronous - if true, synchronous mode is selected, else asynchronous.

WatchDog

protected WatchDog(java.lang.String name)

Create a watchdog with the default check period time.

WatchDog

protected WatchDog()

Create a watchdog with the default check period time.

Method Detail

run

public void run()

Run the watching loop, until the thread is either shut downor the last running thread.

Specified by:

run in interface java.lang.Runnable

getObjectToCheck

protected java.lang.Object getObjectToCheck()

This method can be implemented by subclasses if the checking action implies one or more objects. The default implemntation returns null .

Returns:

the object subject to the checking action.

doCheck

protected abstract java.lang.Throwable doCheck(java.lang.Object obj)
                                        throws WatchDogException

Perform the required check. This method must return a Throwable object if the check fails, and raise a WatchDogExceptionif the check proves impossible.

In either case, the currently registered listeners will be notified of the failure.

Parameters:

obj - the object subject to the check, or null if the check does not depend on any specific object.

Returns:

a Throwable object, if the check fails

Throws:

WatchDogException - if the check is impossible

isShuttingDown

public boolean isShuttingDown()

See org.sadun.util.Terminable.isShuttingDown().

Specified by:

isShuttingDown in interface Terminable

Returns:

true if a shutdown has been requested

See Also:

Terminable.isShuttingDown()

shutdown

public void shutdown()

Shut down the watchdog thread. See org.sadun.util.Terminable.shutdown().

Specified by:

shutdown in interface Terminable

See Also:

Terminable.shutdown()

addListener

public void addListener(WatchDog.Listener l)

Add a watchdog listener to the listener set.

Parameters:

l - the listener to add

removeListener

public void removeListener(WatchDog.Listener l)

Remove a watchdog listener from the listeners set.

Parameters:

l - the listener to remove

removeaAllListeners

public void removeaAllListeners()

getCheckPeriodTime

public long getCheckPeriodTime()

Return the amount of time the watchdog waits between each check.

Returns:

the amount of time the watchdog waits between each check.

setCheckPeriodTime

public void setCheckPeriodTime(long checkPeriodTime)

Set the amount of time the watchdog waits between each check.

Parameters:

checkPeriodTime - the amount of time the watchdog waits between each check.

isSynchronous

public boolean isSynchronous()

Return the synchronicity mode (see class comment).

Returns:

the synchronicity mode (see class comment).

setSynchronous

public void setSynchronous(boolean v)

Set the synchronicity mode (see class comment).

Parameters:

v - if true, the mode is "synchronous" (see class comment).

isStartBySleeping

public boolean isStartBySleeping()

Return true if the watchdog goes immediatly to sleep on startup

Returns:

true if the watchdog goes immediatly to sleep on startup

setStartBySleeping

public void setStartBySleeping(boolean startBySleeping)

Parameters:

startBySleeping - The startBySleeping to set.

isRemoveFailedListeners

public boolean isRemoveFailedListeners()

Return true if listeners that fail are removed from the listener set (in synchronous mode).

Returns:

true if listeners that fail are removed from the listener set (in synchronous mode).

setRemoveFailedListeners

public void setRemoveFailedListeners(boolean removeFailedListeners)

Set wether or not listeners that fail are removed from the listener set (in synchronous mode).

Parameters:

removeFailedListeners - if true, listeners that fail are removed from the listener set (in synchronous mode).

dispose

public void dispose()

Disposes of any resource allocated by the watchdog. This implementation does not do anything.

finalize

public void finalize()

The class finalizer. This implementation invokes dispose().