org.josef.util

Class CQueue<E>

java.lang.Object

org.josef.util.CQueue<E>

Type Parameters:

E - The type of elements to add and serve from the queue.

@ThreadSafety(level=THREAD_SAFE,
              doc="By Design")
 @Status(stage=PRODUCTION,
        unitTests=COMPLETE)
public class CQueue<E>
extends Object

Abstraction of a queue.
This class simulates elements in a queue waiting to be served. This class is designed to be used with multiple producers and consumers that simultaneously add elements to the queue and serve elements from the queue.
Note: This class used to be based upon ArrayBlockingQueue but this resulted in dead locks. It turns out that this class is difficult to use in combination with synchronized methods. Still: When you don't need the extra functionality in this class, directly use an ArrayBlockingQueue. The extra functionality includes: Gathering statistical information plus a standard way to close a queue.

Version:

1.1 $Revision: 6488 $

Author:

Kees Schotanus

Constructor Summary

Constructors

Constructor and Description
CQueue(int capacity) Creates a queue with the supplied maximum capacity.

Method Summary

Modifier and Type	Method and Description
void	add(E element) Adds the supplied element to the end of the queue.
void	close() Closes the queue.
int	getMaximumUsedCapacity() Gets the maximum used capacity of this CQueue (this equals the maximum number of elements that have been waiting to be served).
E	serve() Serve an element waiting in the queue.
String	toString() Creates a String representation of this CQueue.

Methods inherited from class java.lang.Object

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

Constructor Detail

CQueue

public CQueue(int capacity)

Creates a queue with the supplied maximum capacity.

Parameters:

capacity - The maximum capacity of this CQueue.

Throws:

IllegalArgumentException - When the supplied maximum capacity is less than one.

Method Detail

getMaximumUsedCapacity

public int getMaximumUsedCapacity()

Gets the maximum used capacity of this CQueue (this equals the maximum number of elements that have been waiting to be served).
Used to determine a good maximum capacity of this CQueue.
When the maximum used capacity is far less than the maximum capacity it might be a good idea to create this CQueue with a smaller capacity in order to conserve memory.
When the maximum used capacity equals the maximum capacity it might be a good idea to create this CQueue with a larger capacity for better performance.

Returns:

The maximum used capacity of this CQueue.

add

public void add(E element)

Adds the supplied element to the end of the queue. Pre condition: The queue should not have been closed.

Parameters:

element - Element to be added to the queue.

Throws:

IllegalStateException - When the queue is closed.

NullPointerException - When the supplied element is null.

serve

public E serve()

Serve an element waiting in the queue.
This works on a first come, first served basis.

Returns:

The first element in the queue or null when the queue is empty and closed.

close

public void close()

Closes the queue.
A closed queue does not accept new elements anymore, but it will serve the elements that already were present in the queue.

toString

public String toString()

Creates a String representation of this CQueue.
The returned String will only contain capacity/size information, thus no information about individual elements in this CQueue.

Overrides:

toString in class Object

Returns:

A String representation of this CQueue.