org.opennms.bb.dp.common.components
Class PollerThread

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--org.opennms.bb.dp.common.components.PollerThread
All Implemented Interfaces:
Runnable
Direct Known Subclasses:
Actiond, ActiondEventListener, ActionLauncher, Capsd, CapsdReadManager, CapsdWriteManager, DBRunnableConsumerThread, Discovery, DiscPinger, DiscPingManager, DiscPingReplyReceiver, EventPersistd, IPGenerator, MonitorPinger, RunnableConsumerThread, TCPHandler, UDPHandler

public abstract class PollerThread
extends Thread

All the poller threads have to respond to start/stop and pause/resume commands and report their current status when queried. The PollerThread base class provides the default states and operations for transition between states. This allows derived classes to focus on extending the object to provide specific funtionality while maintaining consistant behavior in all derived objects.

It is important to note that the PollerThread class provides a highlevel design for how derived classes should behave. It is up to each designer of a derived class to ensure that a derived class functions properly within the semantics provided by the PollerThread class.

 Only the following state transitions are possible:

 STATUS_STARTING ---> STATUS_NORMAL

 STATUS_NORMAL   ---> STATUS_PAUSING
 STATUS_NORMAL   ---> STATUS_TERMINATING

 STATUS_PAUSING  ---> STATUS_PAUSED
 STATUS_PAUSING  ---> STATUS_RESUMING
 STATUS_PAUSING  ---> STATUS_TERMINATING

 STATUS_PAUSED   ---> STATUS_RESUMING
 STATUS_PAUSED   ---> STATUS_TERMINATING

 STATUS_RESUMING ---> STATUS_NORMAL
 STATUS_RESUMIMG ---> STATUS_PAUSING
 STATUS_RESUMING ---> STATUS_TERMINATING

 STATUS_TERMINATING ---> STATUS_SHUTDOWN
 

Version:
$Revision: 1.10 $
Author:
Sowmya, Brian Weaver, OpenNMS

Field Summary
private  int m_curOpStatus
          The current operation status of the thread.
static int STATUS_MASK
          The following mask is used to get/set the status of the poller thread.
static int STATUS_NORMAL
          Indicates that the thread has been started and is running normally.
static int STATUS_PAUSED
          Indicates that the thread has paused any processing and is waiting to resume or exit.
static int STATUS_PAUSING
          Indicates that the thread has been marked to be paused.
static int STATUS_RESUMING
          Indicates that the thread has be marked for resumption.
static int STATUS_SHUTDOWN
          The last act of an exiting thread should be to set the status to shutdown.
static int STATUS_STARTING
          This is the initial status of the thread object.
static int STATUS_TERMINATING
          The thread has been targeted for termination.
 
Fields inherited from class java.lang.Thread
contextClassLoader, daemon, eetop, group, inheritableThreadLocals, inheritedAccessControlContext, MAX_PRIORITY, MIN_PRIORITY, name, NORM_PRIORITY, priority, single_step, stillborn, stopThreadPermission, target, threadInitNumber, threadLocals, threadQ
 
Constructor Summary
protected PollerThread()
          Create a default poller thread with the operational status equal to STATUS_STARTING.
protected PollerThread(String name)
          Creates a new PollerThread.
protected PollerThread(ThreadGroup group, String name)
          Allocates a new PollerThread that is a member of the specified ThreadGroup.
 
Method Summary
protected  int getCtrlStatus()
          Returns the current control status for the poller thread.
 int getOpStatus()
          Returns the current operational status of the PollerThread as defined by the derived class.
 void pauseOperation()
          Sets the current operational status of the thread to STATUS_PAUSING.
static void pauseThread(PollerThread thr)
          The pauseThread operation thread calls the pauseOperation() method on the thread and then waits for it to reach a paused status.
 void resumeOperation()
          Sets the current operation status of the thread to STATUS_RESUMING.
static void resumeThread(PollerThread thr)
          The resumeThread operation thread calls the resumeOperation() method on the thread and then waits for it to reach a normal status.
protected  void setCtrlStatus(int status)
          Sets the lower bits of the status word to define the status of the derived class.
protected  void setOpStatus(int status)
          Use by derived classes to set the current operational status of the extend PollerThread.
protected  void setUserStatus(int status)
          Sets the upper bits of the status word to define the status of the derived class.
 void shutdown()
          Sets the current operational status of the thread to STATUS_TERMINATING.
static void shutdownThread(PollerThread thr)
          The shutdownThread operation thread calls the shutdown() method on the thread and then waits for it to reach a shutdown status.
 
Methods inherited from class java.lang.Thread
, activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, exit, getContextClassLoader, getName, getPriority, getThreadGroup, init, interrupt, interrupt0, interrupted, isAlive, isDaemon, isInterrupted, isInterrupted, join, join, join, nextThreadNum, registerNatives, resume, resume0, run, setContextClassLoader, setDaemon, setName, setPriority, setPriority0, sleep, sleep, start, stop, stop, stop0, suspend, suspend0, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

m_curOpStatus

private int m_curOpStatus

The current operation status of the thread. This status is updated by the derived class through a call to setOpStatus(). The actual value can be retreived via getOpStatus().


STATUS_STARTING

public static final int STATUS_STARTING

This is the initial status of the thread object. Indicates that the thread has be created, but that the start method has not yet been called. The status of the thread is only correct if derived classes actually set the status correctly.


STATUS_NORMAL

public static final int STATUS_NORMAL

Indicates that the thread has been started and is running normally.


STATUS_PAUSING

public static final int STATUS_PAUSING

Indicates that the thread has been marked to be paused. The thread may not yet have actually reached a paused state.


STATUS_PAUSED

public static final int STATUS_PAUSED

Indicates that the thread has paused any processing and is waiting to resume or exit.


STATUS_RESUMING

public static final int STATUS_RESUMING

Indicates that the thread has be marked for resumption. The thread may be in the process of restarting paused work.


STATUS_TERMINATING

public static final int STATUS_TERMINATING

The thread has been targeted for termination. The thread should exit as soon as it has performed any required cleanup.


STATUS_SHUTDOWN

public static final int STATUS_SHUTDOWN

The last act of an exiting thread should be to set the status to shutdown. This is the final state of the actual object after the thread has exited.


STATUS_MASK

public static final int STATUS_MASK

The following mask is used to get/set the status of the poller thread. When a status change occurs the lower 8-bits of the status word are the only parts of the status to be changed. It is up to the derived class to change the upper 24 bits of status information.

Constructor Detail

PollerThread

protected PollerThread()

Create a default poller thread with the operational status equal to STATUS_STARTING.

See Also:
Thread.Thread()

PollerThread

protected PollerThread(String name)

Creates a new PollerThread. The name of the thread is equal to name.

Parameters:
name - The name of the new thread.
See Also:
Thread.Thread(java.lang.String)

PollerThread

protected PollerThread(ThreadGroup group,
                       String name)

Allocates a new PollerThread that is a member of the specified ThreadGroup. The initial status of the thread is STATUS_STARTING.

Parameters:
group - The owning ThreadGroup.
name - The name of the new thread.
See Also:
Thread.Thread(java.lang.ThreadGroup, java.lang.String), ThreadGroup
Method Detail

setCtrlStatus

protected void setCtrlStatus(int status)

Sets the lower bits of the status word to define the status of the derived class.

Parameters:
status - The status for the lower bits.

setUserStatus

protected void setUserStatus(int status)

Sets the upper bits of the status word to define the status of the derived class.

Parameters:
status - The status for the upper bits.

getCtrlStatus

protected int getCtrlStatus()

Returns the current control status for the poller thread.

Returns:
The current status of the poller thread.

setOpStatus

protected void setOpStatus(int status)

Use by derived classes to set the current operational status of the extend PollerThread.

Parameters:
status - The new status of the thread.
See Also:
STATUS_STARTING, STATUS_NORMAL, STATUS_PAUSING, STATUS_PAUSED, STATUS_RESUMING, STATUS_TERMINATING, STATUS_SHUTDOWN

getOpStatus

public int getOpStatus()

Returns the current operational status of the PollerThread as defined by the derived class.

Returns:
The current operation status of the thread.
See Also:
STATUS_STARTING, STATUS_NORMAL, STATUS_PAUSING, STATUS_PAUSED, STATUS_RESUMING, STATUS_TERMINATING, STATUS_SHUTDOWN

shutdown

public void shutdown()

Sets the current operational status of the thread to STATUS_TERMINATING. Once the status is set the Thread's notifyAll() method is invoked to inform all waiters.

See Also:
STATUS_TERMINATING, Object.notifyAll()

pauseOperation

public void pauseOperation()

Sets the current operational status of the thread to STATUS_PAUSING. The status of the thread must be either STATUS_NORMAL or STATUS_RESUMING for the status change to occur. If the status change occurs then the thread's notifyAll() is called after changing the status.

It is the derived class' responsibility to actually transition the object from an STATUS_PAUSING to an actual STATUS_PAUSED status when the object reflects the appropiate status.

See Also:
Object.notifyAll(), STATUS_NORMAL, STATUS_RESUMING, STATUS_PAUSING

resumeOperation

public void resumeOperation()

Sets the current operation status of the thread to STATUS_RESUMING. It is up to the derived thread to update the status from STATUS_RESUMING to STATUS_NORMAL after restaring operations. The status will only be change if the current status is one of STATUS_PAUSED or STATUS_PAUSING. Any other status will cause the status change to fail.

If the status is changed then the method notifyAll() to signal the status change.

See Also:
Object.notifyAll(), STATUS_PAUSED, STATUS_PAUSING, STATUS_RESUMING

pauseThread

public static void pauseThread(PollerThread thr)
                        throws InterruptedException

The pauseThread operation thread calls the pauseOperation() method on the thread and then waits for it to reach a paused status. If the thread is in an illegal state (terminated || shutdown) then an exception will be thrown.

Parameters:
thr - The thread to pause.
Throws:
InterruptedException - Thrown if the calling thread is interrupted by another caller.
IllegalThreadStateException - Thrown if the thread to be stopped is in an illegal state.

resumeThread

public static void resumeThread(PollerThread thr)
                         throws InterruptedException

The resumeThread operation thread calls the resumeOperation() method on the thread and then waits for it to reach a normal status. If the thread is in an illegal state (terminated || shutdown) then an exception will be thrown.

Parameters:
thr - The thread to resume.
Throws:
InterruptedException - Thrown if the calling thread is interrupted by another caller.
IllegalThreadStateException - Thrown if the thread to be stopped is in an illegal state.

shutdownThread

public static void shutdownThread(PollerThread thr)
                           throws InterruptedException

The shutdownThread operation thread calls the shutdown() method on the thread and then waits for it to reach a shutdown status.

Parameters:
thr - The thread to shutdown.
Throws:
InterruptedException - Thrown if the calling thread is interrupted by another caller.