--- projects/cms/source/util/uk/org/iscream/cms/util/Queue.java 2001/01/30 01:56:28 1.7 +++ projects/cms/source/util/uk/org/iscream/cms/util/Queue.java 2001/03/01 01:05:49 1.14 @@ -4,6 +4,7 @@ package uk.ac.ukc.iscream.util; //---IMPORTS--- import java.util.LinkedList; import java.util.NoSuchElementException; +import java.util.Random; import uk.ac.ukc.iscream.util.*; /** @@ -13,7 +14,7 @@ import uk.ac.ukc.iscream.util.*; * actually contains some elements. * * @author $Author: tdb $ - * @version $Id: Queue.java,v 1.7 2001/01/30 01:56:28 tdb Exp $ + * @version $Id: Queue.java,v 1.14 2001/03/01 01:05:49 tdb Exp $ */ public class Queue { @@ -22,11 +23,59 @@ public class Queue { /** * The current CVS revision of this class */ - public static final String REVISION = "$Revision: 1.7 $"; + public static final String REVISION = "$Revision: 1.14 $"; + /** + * Pass to constructor to remove a RANDOM item from + * the Queue upon reaching the maximum limit. + */ + public static final int RANDOM = 0; + + /** + * Pass to constructor to remove the FIRST item from + * the Queue upon reaching the maximum limit. + */ + public static final int FIRST = 1; + + /** + * Pass to constructor to remove the LAST item from + * the Queue upon reaching the maximum limit. + */ + public static final int LAST = 2; + + /** + * Pass to constructor to drop the new item upon reaching + * the maximum Queue limit. + */ + public static final int DROP = 3; + //---STATIC METHODS--- //---CONSTRUCTORS--- + + /** + * 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. + * + * @param maxSize the upper limit for a queue + * @param removeAlgorithm the remove algorithm to use upon reaching the maxSize + */ + public Queue(int maxSize, int removeAlgorithm) { + _maxSize = maxSize; + _removeAlgorithm = removeAlgorithm; + } + + /** + * Constructs a Queue with no maximum size. + */ + public Queue() { + _maxSize = -1; + } //---PUBLIC METHODS--- @@ -40,11 +89,21 @@ public class Queue { for(int i=0; i < _lists.size(); i++) { // skip over any gaps left in the list if(_lists.get(i) != null) { + // get size before adding to the Queue int s = ((LinkedList) _lists.get(i)).size(); - synchronized(this) { - // add() does the same thing, but this ensures behaviour - ((LinkedList) _lists.get(i)).addLast(o); + // check whether we need to remove an item from the current Queue + if(_maxSize!=-1 && s==_maxSize && _removeAlgorithm!=DROP) { + // we need to remove an item + removeQueueItem((LinkedList) _lists.get(i)); } + // check if we should add (not if Queue full, and using DROP algorithm) + if(!(s==_maxSize && _removeAlgorithm==DROP)) { + // add the next item, ensuring we lock + synchronized(this) { + // LinkedList.add() does the same thing, but this ensures behaviour + ((LinkedList) _lists.get(i)).addLast(o); + } + } // if the queue was empty before the add it is possible // that a consumer is waiting... so we notify them if (s == 0) { @@ -62,6 +121,7 @@ public class Queue { * This method returns an object from the front of a given queue. * It will block until data exists in the queue if required. * + * @param The queue to retrieve data from. * @return The object from the front of the queue. * @throws InvalidQueueException if the queue does not exist. */ @@ -95,7 +155,7 @@ public class Queue { * shutdown() type methods that may have problems closing * if the thread of control is waiting on a queue. * - * @param queue the queue to release + * @param queue the queue to release. */ public void releaseQueue(int queue) { synchronized(((LinkedList) _lists.get(queue))) { @@ -118,28 +178,30 @@ public class Queue { } /** - * This method returns a 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. + * 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. * - * @return A String message containing status information. + * @return A String message containing status information in XML format */ - public String status() { - String status = ""; + public String xmlStatus() { + String status = "= _lists.size() || _lists.get(queue) == null) { @@ -162,7 +225,7 @@ public class Queue { * Returns the total numer of elements to have passed * through this queue (ie. a counter on the add method). * - * @return the element-ometer + * @return the element-ometer. */ public int elementCount() { return _count; @@ -208,13 +271,66 @@ public class Queue { } /** + * 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). + * + * @param interval The long interval, in milliseconds, at which to take samples + * @param destQueue The queue to monitor to + * @param name A name to identify this Queue with + * @return whether we succeeded + */ + public boolean startMonitor(long interval, Queue destQueue, String name) { + if(_queueMon == null) { + // start a monitor + _queueMon = new QueueMonitor(this, destQueue, interval, name); + _queueMon.start(); + return true; + } + else { + // already have a monitor running + return false; + } + } + + /** + * Start a monitor on our own Queue. This will log XML + * statistics about our Queue to this Queue. + * + * @param interval The long interval, in milliseconds, at which to take samples + * @param name A name to identify this Queue with + * @return whether we succeeded + */ + public boolean startMonitor(long interval, String name) { + return startMonitor(interval, this, name); + } + + /** + * Stop a monitor on our Queue if we have on running. + * + * @return whether we succeeded + */ + public boolean stopMonitor() { + if(_queueMon != null) { + // stop a monitor + _queueMon.shutdown(); + _queueMon = null; + return true; + } + else { + // no monitor running + return false; + } + } + + /** * Overrides the {@link java.lang.Object#toString() Object.toString()} * method to provide clean logging (every class should have this). * * This uses the uk.ac.ukc.iscream.util.FormatName class * to format the toString() * - * @return the name of this class and its CVS revision + * @return the name of this class and its CVS revision. */ public String toString() { return FormatName.getName( @@ -224,7 +340,38 @@ public class Queue { } //---PRIVATE METHODS--- - + + /** + * This method removes an item from a Queue, using a method + * requested at construction. + * + * @param list The LinkedList from which to remove an item. + */ + private void removeQueueItem(LinkedList list) { + // look at our algorithm + // remove a random item from the list + if(_removeAlgorithm==RANDOM) { + // new Random, with a good seed + Random rand = new Random(System.currentTimeMillis()); + int i = rand.nextInt(_maxSize); + synchronized(this) { + list.remove(i); + } + } + // remove the first item from the list + else if(_removeAlgorithm==FIRST) { + synchronized(this) { + list.removeFirst(); + } + } + // remove the last item from the list + else if(_removeAlgorithm==LAST) { + synchronized(this) { + list.removeLast(); + } + } + } + //---ACCESSOR/MUTATOR METHODS--- //---ATTRIBUTES--- @@ -239,6 +386,22 @@ public class Queue { * passed through, for statistical purposes. */ private int _count = 0; + + /** + * A reference to our QueueMonitor, if we have one. + */ + private QueueMonitor _queueMon = null; + + /** + * The maximum size of any Queue. + */ + private int _maxSize = -1; + + /** + * The remove algorithm to use upon a Queue reaching + * it's maximum size. + */ + private int _removeAlgorithm = -1; /** * This is the friendly identifier of the