com.tangosol.util
Class Daemon

java.lang.Object
  com.tangosol.util.Base
      com.tangosol.util.Daemon

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

AsyncBinaryStore.QueueDaemon, LoadBalancer.SocketHandler, MulticastTest.Listener, ReadWriteBackingMap.ReadThread, ReadWriteBackingMap.WriteThread, TaskDaemon

public abstract class Daemon
extends Base
implements Runnable

A abstract Daemon thread handler. A sub-class need only provide an implementation of the run() method. When the Daemon is told to start, it will create a Java thread, which means that the number of Daemon instances within a system must be limited to a reasonable number. If an arbitrarily large number of conceptual daemons are necessary, consider using a TaskDaemon, which allows arbitrary tasks to be queued for execution. If thread pooling is desired, consider using a WorkManager implementation.

Author:

cp 2000.08.02, cp 2006.02.23 (Coherence 3.2) added restartability

Nested Class Summary

class

Daemon.DaemonWorker The sub-class of Thread that this Daemon uses as the actual thread of execution.

Constructor Summary

Daemon()
Default constructor.

Daemon(String sName)
Creates a Daemon with the specified name.

Daemon(String sName, int nPriority, boolean fStart)
Creates a Daemon with a specified name and priority.

Method Summary

protected void	changeState(int nState, Daemon.DaemonWorker worker) Change the state of the daemon.
protected void	configureWorker(Daemon.DaemonWorker worker) Configure a worker to use as a daemon.
protected String	getConfiguredName() Determine the configured name for the daemon.
protected int	getConfiguredPriority() Determine the configured priority for the daemon.
protected String	getDescription() Format the Daemon attributes into a String for inclusion in the String returned from the toString() method.
protected int	getState() Obtain the state of the daemon.
Thread	getThread() Accessor to obtain the Daemon thread object.
ClassLoader	getThreadContextClassLoader() Determine the configured context ClassLoader for the daemon thread.
Daemon.DaemonWorker	getWorker() Accessor to obtain the Daemon worker object.
protected Daemon.DaemonWorker	instantiateWorker() Instantiate a DaemonWorker that will be used as a daemon.
boolean	isOnWorkerThread() Indiciate if the current execution thread is a child of this daemon.
boolean	isRunning() Check if the daemon is running (has started and has not stopped).
boolean	isStopping() Check if the daemon is supposed to stop.
abstract void	run() The daemon's implementation method.
protected void	setConfiguredName(String sName) Configure the name for the daemon.
protected void	setConfiguredPriority(int nPriority) Configure the priority for the daemon.
void	setThreadContextClassLoader(ClassLoader loader) Configure the context ClassLoader for the daemon thread.
void	start() Performs a synchronized start of the thread if the thread is not already started.
void	stop() Request the daemon to stop.
protected static String	toStateString(int nState) Convert a state value to a human-readable String.
String	toString() Return a human-readable String representation of the Daemon.

Constructor Detail

Daemon

public Daemon()

Default constructor. Creates a Daemon using default settings. The daemon will not be automatically started.

Daemon

public Daemon(String sName)

Creates a Daemon with the specified name. The daemon will not be automatically started.

Parameters:

sName - the thread name (may be null)

Daemon

public Daemon(String sName,
              int nPriority,
              boolean fStart)

Creates a Daemon with a specified name and priority.

Warning: If the implementation class is a inner non-static class that refers to its outer object ("MyOuterClass.this"), do not use the auto-start option. The reason is that the run() method of the Daemon may be invoked on the new thread before the construction of the Daemon object itself unwinds, which means that the outer object reference will not have been set yet, causing an inexplicable NullPointerException.

Parameters:

sName - the thread name (may be null)

nPriority - the thread priority, between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY inclusive

fStart - pass true to auto-start the thread as part of its construction

Method Detail

run

public abstract void run()

The daemon's implementation method. Override this method to implement a daemon.

An example implementation is:

   while (!isStopping())
       {
       // do some processing
       // ...

       synchronized (this)
           {
           // wait for notification of more work
           wait();
           }
       }
 

Specified by:

run in interface Runnable

getThread

public Thread getThread()

Accessor to obtain the Daemon thread object.

The thread returned by this accessor will be null if the Daemon is stopped.

Returns:

the thread object

getWorker

public Daemon.DaemonWorker getWorker()

Accessor to obtain the Daemon worker object.

The worker returned by this accessor will be null if the Daemon is stopped.

Returns:

the worker object

start

public void start()

Performs a synchronized start of the thread if the thread is not already started. This means that when control returns to the caller of this method, that the thread has started. This method has no effect if the daemon thread is already running, even if it is in the process of stopping. Note that a daemon can be re-started once it has stopped.

isRunning

public boolean isRunning()

Check if the daemon is running (has started and has not stopped).

Returns:

true if and only if the daemon is running

stop

public void stop()

Request the daemon to stop. This method will only have an effect if the daemon sub-class respects the value returned from isStopping().

isStopping

public boolean isStopping()

Check if the daemon is supposed to stop. This method is primarily used by the daemon thread itself to check if it should stop processing.

Returns:

true if and only if the worker thread is no longer supposed to be running

isOnWorkerThread

public boolean isOnWorkerThread()

Indiciate if the current execution thread is a child of this daemon.

Returns:

true if the current thread is a child of the Daemon

getState

protected int getState()

Obtain the state of the daemon.

Returns:

one of the STATE_ enums

changeState

protected void changeState(int nState,
                           Daemon.DaemonWorker worker)

Change the state of the daemon.

Parameters:

nState - one of the STATE_ enums

worker - the new worker, if starting, otherwise the current worker

setConfiguredPriority

protected void setConfiguredPriority(int nPriority)

Configure the priority for the daemon.

Parameters:

nPriority - the thread priority for the daemon

getConfiguredPriority

protected int getConfiguredPriority()

Determine the configured priority for the daemon.

Returns:

the configured thread priority for the daemon

setConfiguredName

protected void setConfiguredName(String sName)

Configure the name for the daemon.

Parameters:

sName - the thread name for the daemon

getConfiguredName

protected String getConfiguredName()

Determine the configured name for the daemon.

Returns:

the configured thread name for the daemon

setThreadContextClassLoader

public void setThreadContextClassLoader(ClassLoader loader)

Configure the context ClassLoader for the daemon thread.

If the daemon thread is not currently running, the specified ClassLoader will be associated with the daemon thread when it is started (or restarted). Otherwise, setContextClassLoader will be called on the daemon thread object immediately as well as during subsequent restarts.

Parameters:

loader - the context ClassLoader for the daemon thread

getThreadContextClassLoader

public ClassLoader getThreadContextClassLoader()

Determine the configured context ClassLoader for the daemon thread.

Returns:

the configured context ClassLoader for the daemon thread

instantiateWorker

protected Daemon.DaemonWorker instantiateWorker()

Instantiate a DaemonWorker that will be used as a daemon.

Returns:

a new instance of DaemonWorker or a sub-class thereof

configureWorker

protected void configureWorker(Daemon.DaemonWorker worker)

Configure a worker to use as a daemon.

Parameters:

worker - the DaemonWorker to configure

toString

public String toString()

Return a human-readable String representation of the Daemon.

Returns:

a String describing the Daemon

getDescription

protected String getDescription()

Format the Daemon attributes into a String for inclusion in the String returned from the toString() method.

Returns:

a String listing the attributes of the Daemon

toStateString

protected static String toStateString(int nState)

Convert a state value to a human-readable String.

Parameters:

nState - a Daemon state, one of the STATE_* enums

Returns:

a human-readable name for the state