org.opennms.bb.common.components
Class PCQueueLinkedList

java.lang.Object
  |
  +--org.opennms.bb.common.components.PCQueueLinkedList
All Implemented Interfaces:
PCQueue
Direct Known Subclasses:
EventListener.CheckQueue, EventPersistd.CheckQueue

public class PCQueueLinkedList
extends Object
implements PCQueue

The Linked list queue is a potentially infinite sized list of elements that follow producer/consumer rules. All elements are added and removed in a FIFO fashion, just like a standard queue. However, the queue is designed to be shared with one or more producers and one or more consumers.

Even though the queue is shared, the elements in the queue are not. If there are two consumers A and B and A removes an element from the queue. The next element removed by B will not be the same object as removed by A, but the object that was next in the queue.

Version:
$Revision: 1.9 $
Author:
Brian Weaver, OpenNMS

Field Summary
private  LinkedList m_elements
          The list of objects that are currently in the queue.
private  boolean m_isOpen
          If true then the queue is open and items may be written and read from the queue.
private  int m_maxSize
          The maximum number of elements that are allowed to exist in the queue.
private  List m_oneShotNotifyOnAdd
          The list of objects that should be notified when the next add call succeeds!
private  List m_oneShotNotifyOnRead
          The list of objects that should be notified when the next read call succeeds!
 
Constructor Summary
PCQueueLinkedList()
          Constructs a new linked list queue that adds and removes objects using the FIFO ordering.
PCQueueLinkedList(int size)
          Constructs the Producer/Consumer queue with the given size.
 
Method Summary
 void add(Object obj)
          Adds the specified object to the tail of the producer/consumer queue.
 void clear()
          Clears all the elements currently in the producer/consumer queue.
 void close()
          Close the current queue.
 int entries()
          Returns current number of entries in the queue.
 boolean isClosed()
          Returns true if the queue is closed.
 boolean isEmpty()
          This method is provided as a convience check to determine if the queue currently contains any elements.
 boolean isFull()
          This method is provided as a convience check to determine if the queue is currently full.
 boolean isOpen()
          Returns true if the queue is opened.
 void oneShotNotifyAllOnAdd(Object recipient)
          This method is designed to be used by classes that are waiting on new objects to be added to the queue.
 void oneShotNotifyAllOnRead(Object recipient)
          This method is designed to be used by classes that are waiting on objects to be read from a full queue.
 void open()
          Open the queue.
 Object read()
          Attempts to read the next object from the head of the producer/ consumer queue and return it to the caller.
 int size()
          Returns total capacity of the queue.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

m_maxSize

private int m_maxSize

The maximum number of elements that are allowed to exist in the queue. If items are attempted to be added after the number of queue items equal maxSize then each call is blocked until an item is removed.


m_isOpen

private boolean m_isOpen

If true then the queue is open and items may be written and read from the queue. If false then a QueueClosedException should be thrown by the method.


m_elements

private LinkedList m_elements

The list of objects that are currently in the queue.


m_oneShotNotifyOnAdd

private List m_oneShotNotifyOnAdd

The list of objects that should be notified when the next add call succeeds!


m_oneShotNotifyOnRead

private List m_oneShotNotifyOnRead

The list of objects that should be notified when the next read call succeeds!

Constructor Detail

PCQueueLinkedList

public PCQueueLinkedList()

Constructs a new linked list queue that adds and removes objects using the FIFO ordering. The default is to allow unlimited items in the list. Also, the queue is open by default.


PCQueueLinkedList

public PCQueueLinkedList(int size)
Constructs the Producer/Consumer queue with the given size. The size is fixed at construction time and cannot be changed.
Parameters:
size - The number of elements that may be placed into the queue before it blocks.
Throws:
IllegalArgumentException - Thrown if the size is invalid. This should only happen if the size is a negative number.
Method Detail

isOpen

public boolean isOpen()

Returns true if the queue is opened.

Specified by:
isOpen in interface PCQueue

isClosed

public boolean isClosed()

Returns true if the queue is closed.

Specified by:
isClosed in interface PCQueue

open

public void open()

Open the queue.

Specified by:
open in interface PCQueue

close

public void close()

Close the current queue.

Specified by:
close in interface PCQueue

add

public void add(Object obj)
         throws InterruptedException,
                QueueClosedException

Adds the specified object to the tail of the producer/consumer queue. If the queue is currently at it's predefined limit then the call blocks until there is room in the queue.

If the queue is closed while the thread is waiting to add the object then an exception is thrown. Likewise, if the adding thread is interruped then an exception is thrown by the add method.

Specified by:
add in interface PCQueue
Parameters:
obj - The object to be added to the queue.
Throws:
InterruptedException - Thrown if the adding thread is interrrupted prior to completing the addition of the object.
org.opennmms.bb.common.components.QueueClosedException - Thrown if the queue is closed before the object is added to the producer/consumer queue.

read

public Object read()
            throws InterruptedException,
                   QueueClosedException

Attempts to read the next object from the head of the producer/ consumer queue and return it to the caller. If there are no object in the queue currently then the call blocks until there is an object available.

If the queue is closed while the thread is waiting for an object then an exception is thrown. Likewise, if the reading thread is interrupted prior to reading an object then an exception is also thrown.

Specified by:
read in interface PCQueue
Returns:
The object to be recovered from the queue.
Throws:
InterruptedException - Thrown if the adding thread is interrrupted prior to completing the reading of an object.
org.opennmms.bb.common.components.QueueClosedException - Thrown if the queue is closed before the object is recovered from the producer/consumer queue.

clear

public void clear()

Clears all the elements currently in the producer/consumer queue.

Specified by:
clear in interface PCQueue

entries

public int entries()

Returns current number of entries in the queue.

Specified by:
entries in interface PCQueue

size

public int size()

Returns total capacity of the queue.

Specified by:
size in interface PCQueue

oneShotNotifyAllOnAdd

public void oneShotNotifyAllOnAdd(Object recipient)

This method is designed to be used by classes that are waiting on new objects to be added to the queue. When an object is added to the queue after this call, the recipient object will have its notifyAll method called. The recipient will only be notified once, all subsuquent adds to the queue will not cause the recipient to be signaled.

If a recipient needs to be called after each add then it must repeatly re-register after each notification, however this does not guarentee notification for each add. The one shot notification is designed to be used by classes that check check for elements and find the list empty, they then call wait() to pause until more elements are available.

Note: If the recipient is not well behavied and continues to hold its lock when the add method is called, it could cause a deadlock condition. Recipients must either unregister or release their lock to receive notifications. Care should be taken when using this method.

Specified by:
oneShotNotifyAllOnAdd in interface PCQueue
Parameters:
recipient - The object to be signaled when then next add succeeds.
Since:
1.5

oneShotNotifyAllOnRead

public void oneShotNotifyAllOnRead(Object recipient)

This method is designed to be used by classes that are waiting on objects to be read from a full queue. When an object is read from the queue after this call, the recipient object will have its notifyAll method called. The recipient will only be notified once, all subsuquent reads to the queue will not cause the recipient to be signaled.

If a recipient needs to be called after each read then it must repeatly re-register after each notification, however this does not guarentee notification for each read. The one shot notification is designed to be used by classes that check check for elements and find the list full, they then call wait() to pause until more elements are available.

Note: If the recipient is not well behavied and continues to hold its lock when the add method is called, it could cause a deadlock condition. Recipients must either unregister or release their lock to receive notifications. Care should be taken when using this method.

Specified by:
oneShotNotifyAllOnRead in interface PCQueue
Parameters:
recipient - The object to be signaled when then next read succeeds.
Since:
CVS Revision: 1.8

isEmpty

public boolean isEmpty()

This method is provided as a convience check to determine if the queue currently contains any elements. If the method returns true then there are no entries currently in the queue and a call to read will block until an object is added.

Specified by:
isEmpty in interface PCQueue
Returns:
True if there are no entries in the list.
Since:
1.7

isFull

public boolean isFull()

This method is provided as a convience check to determine if the queue is currently full. If the method returns true then there is no more room to place any elements and the next call to add will block until an object is removed.

If the PCQueue is not bounded then this method will always return false. To determine if the queue is bounded see the size method.

Specified by:
isFull in interface PCQueue
Returns:
True if there is no more room in the queue.
Since:
1.7
See Also:
size()