systemic.sif.sifcommon.subscriber.queue
Class SubscriberQueue<T extends BaseMessage>

java.lang.Object
  extended by systemic.sif.sifcommon.subscriber.queue.SubscriberQueue<T>

public class SubscriberQueue<T extends BaseMessage>
extends java.lang.Object

This class encapsulates a standard BlockingQueue from the java.util.concurrent package. It only gives access to the blocking put() and take() method. This is the desired behaviour for agents that allow for multi-threaded subscribers that must follow the producer-consumer design pattern. A further advantage of encapsulating the lower level blocking queue is that further functionality can be provided to this SubscriberQueue queue such a 'persistence', notification etc. without the need of changes in the classes that use this SubscriberQueue class.

Note:
At this point in time the persistence functionality is not yet implemented. This might be a future feature. This means if the system should go down, the messages currently held in the queue are lost. One needs to carefully analyse what capacity of the subscriber queue shall be as this is the maximum number of lost messages in case of a system failure.

Author:
Joerg Huber

Constructor Summary
SubscriberQueue(int capacity, java.lang.String queueID, java.lang.String workingDir)
          This initialises the Subscriber Queue for use in multi-threaded environment.
 
Method Summary
 T blockingPull()
          This method returns the next available message from the queue.
 void blockingPush(T subscriberMsg)
          This method attempts to put a SubscriberMessage on to the SubscriberQueue.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SubscriberQueue

public SubscriberQueue(int capacity,
                       java.lang.String queueID,
                       java.lang.String workingDir)
This initialises the Subscriber Queue for use in multi-threaded environment.

Parameters:
capacity - The max capacity of elements that can be held by this queue. Generally that should be a low number but theoretically can be any number.
queueID - A unique name representing this queue. This ID should not contain any white spaces. In fact all white spaces will be removed from this value. Once persistence is implemented this name will be used as part of the persistence store identification.
workingDir - This is a directory that might be used for temporary or permanent storage once persistence is implemented. This should point to a valid directory that will be created if it doesn't exist.
Method Detail

blockingPush

public void blockingPush(T subscriberMsg)
This method attempts to put a SubscriberMessage on to the SubscriberQueue. If the capacity of the queue is below the threshold defined in the constructor then the subscriberMsg is put on the queue immediately. If the queue is full this method blocks indefinitely until a 'slot' becomes available (ie. the size of the queue falls below the capacity defined in the constructor). This means a consumer has taken a element off the queue.

Parameters:
subscriberMsg - The element to be put on the queue.

blockingPull

public T blockingPull()
This method returns the next available message from the queue. If a message is available this method returns immediatley with the message. If no message is available then this method will block until a message is available (blockingPush() has been called by some thread).

Returns:
A message of the defined type.