uk.org.iscream.cms.util
Class Queue

java.lang.Object
  uk.org.iscream.cms.util.Queue

public class Queue

extends Object

A Queue class designed to operate in a multi-threaded environment, with added support for multiple "consumer" threads. Also offers blocking on the get() methods, which ensures the consumer waits until the queue actually contains some elements.

Version:

$Id: Queue.java,v 1.26 2003/02/05 14:27:59 tdb Exp $

Author:

$Author: tdb $

Field Summary

private int	_count A counter so we know how many data items have been passed through, for statistical purposes.
private LinkedList	_lists The LinkedLists of queues.
private int	_maxSize The maximum size of any Queue.
private String	_name This is the friendly identifier of the component this class is running in.
private QueueMonitor	_queueMon A reference to our QueueMonitor, if we have one.
private int	_removeAlgorithm The remove algorithm to use upon a Queue reaching it's maximum size.
static String[]	algorithms To allow opposite lookups.
static int	DROP Pass to constructor to drop the new item upon reaching the maximum Queue limit.
static int	FIRST Pass to constructor to remove the FIRST item from the Queue upon reaching the maximum limit.
static int	LAST Pass to constructor to remove the LAST item from the Queue upon reaching the maximum limit.
static int	RANDOM Pass to constructor to remove a RANDOM item from the Queue upon reaching the maximum limit.
static String	REVISION The current CVS revision of this class

Constructor Summary

Queue()
Constructs a Queue with no maximum size.

Queue(int maxSize, int removeAlgorithm)
Constructs a new Queue with a maximum size limit on any individual queue.

Method Summary

void	add(Object o) This method adds a given object to every queue.
void	clearQueue(int queue) This method erases the contents of a given queue.
int	elementCount() Returns the total numer of elements to have passed through this queue.
Object	get(int queue) This method returns an object from the front of a given queue.
int	getQueue() This method assigns a queue to a consumer.
int	queueSize(int queue) Returns the size of a given queue.
void	releaseQueue(int queue) This method releases a get() method that's currently waiting on an empty queue.
void	removeQueue(int queue) This method sets a entry to null in the list.
private void	removeQueueItem(LinkedList list) This method removes an item from a Queue, using a method requested at construction.
boolean	startMonitor(long interval, Queue destQueue, String name) Start a monitor on our own Queue.
boolean	startMonitor(long interval, String name) Start a monitor on our own Queue.
boolean	stopMonitor() Stop a monitor on our Queue if we have on running.
String	toString() Overrides the Object.toString() method to provide clean logging (every class should have this).
String	xmlStatus() This method returns an XML textual status of the queues.

Methods inherited from class java.lang.Object

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

Field Detail

REVISION

public static final String REVISION

The current CVS revision of this class

See Also:

Constant Field Values

RANDOM

public static final int RANDOM

Pass to constructor to remove a RANDOM item from the Queue upon reaching the maximum limit.

See Also:

Constant Field Values

FIRST

public static final int FIRST

Pass to constructor to remove the FIRST item from the Queue upon reaching the maximum limit.

See Also:

Constant Field Values

LAST

public static final int LAST

Pass to constructor to remove the LAST item from the Queue upon reaching the maximum limit.

See Also:

Constant Field Values

DROP

public static final int DROP

Pass to constructor to drop the new item upon reaching the maximum Queue limit.

See Also:

Constant Field Values

algorithms

public static final String[] algorithms

To allow opposite lookups.

_lists

private LinkedList _lists

The LinkedLists of queues.

_count

private int _count

A counter so we know how many data items have been passed through, for statistical purposes.

_queueMon

private QueueMonitor _queueMon

A reference to our QueueMonitor, if we have one.

_maxSize

private int _maxSize

The maximum size of any Queue.

_removeAlgorithm

private int _removeAlgorithm

The remove algorithm to use upon a Queue reaching it's maximum size.

_name

private String _name

This is the friendly identifier of the component this class is running in. eg, a Filter may be called "filter1", If this class does not have an owning component, a name from the configuration can be placed here. This name could also be changed to null for utility classes.

Constructor Detail

Queue

public Queue(int maxSize,
             int removeAlgorithm)

Constructs a new Queue with a maximum size limit on any individual queue. This should be used to stop conditions where the Queue cannot be guaranteed to be emptied as quick as it's filled. An algorithm will be used to remove data when new data arrives. There may be choices of algorithms later on.

Parameters:

maxSize - the upper limit for a queue

removeAlgorithm - the remove algorithm to use upon reaching the maxSize

Queue

public Queue()

Constructs a Queue with no maximum size.

Method Detail

add

public void add(Object o)

This method adds a given object to every queue. It will notify any waiting consumers (on an empty queue) during this process.

Parameters:

o - An Object to be added to the queues.

get

public Object get(int queue)
           throws InvalidQueueException

This method returns an object from the front of a given queue. It will block until data exists in the queue if required.

Returns:

The object from the front of the queue.

Throws:

InvalidQueueException - if the queue does not exist.

releaseQueue

public void releaseQueue(int queue)

This method releases a get() method that's currently waiting on an empty queue. This was designed for shutdown() type methods that may have problems closing if the thread of control is waiting on a queue.

Parameters:

queue - the queue to release.

clearQueue

public void clearQueue(int queue)

This method erases the contents of a given queue. This method should be used with care. It can only empty one internal queue, not all of them. This must be called multiple times to empty all queues.

Parameters:

queue - the queue to empty.

xmlStatus

public String xmlStatus()

This method returns an XML textual status of the queues. It is merely for observation, and would most likely be used by a larger "monitoring" component. Information returned includes the current size of each queue, and the total items passed through.

Returns:

A String message containing status information in XML format

queueSize

public int queueSize(int queue)
              throws InvalidQueueException

Returns the size of a given queue. A consumer can use this to see how big their queue is at any given time. they should use their queue number as the parameter.

Parameters:

queue - The queue number to query.

Returns:

the current size of the queue.

Throws:

InvalidQueueException - if the queue does not exist.

elementCount

public int elementCount()

Returns the total numer of elements to have passed through this queue. This is essentially a counter on the add method.

Returns:

the element-ometer.

getQueue

public int getQueue()

This method assigns a queue to a consumer. The idea behind this is to ensure that only 1 consumer can be associated with a given queue, otherwise the whole "blocking" thing fails miserably. Queues are created upon requested. It is IMPORTANT that removeQueue() is used when the queue is no longer required.

Returns:

An integer to be passed to the get() method.

removeQueue

public void removeQueue(int queue)

This method sets a entry to null in the list. This ensures that it will no longer be added to after it is no longer required be a consumer.

Parameters:

queue - The integer identifier for the queue, given by getQueue().

startMonitor

public boolean startMonitor(long interval,
                            Queue destQueue,
                            String name)

Start a monitor on our own Queue. This will log XML statistics about our Queue to a given Queue (could be the one being monitored).

Parameters:

interval - The long interval, in milliseconds, at which to take samples

destQueue - The queue to monitor to

name - A name to identify this Queue with

Returns:

whether we succeeded

startMonitor

public boolean startMonitor(long interval,
                            String name)

Start a monitor on our own Queue. This will log XML statistics about our Queue to this Queue.

Parameters:

interval - The long interval, in milliseconds, at which to take samples

name - A name to identify this Queue with

Returns:

whether we succeeded

stopMonitor

public boolean stopMonitor()

Stop a monitor on our Queue if we have on running.

Returns:

whether we succeeded

toString

public String toString()

Overrides the Object.toString() method to provide clean logging (every class should have this). This uses the uk.org.iscream.cms.server.util.FormatName class to format the toString()

Returns:

the name of this class and its CVS revision.

removeQueueItem

private void removeQueueItem(LinkedList list)

This method removes an item from a Queue, using a method requested at construction.

Parameters:

list - The LinkedList from which to remove an item.