--- projects/cms/source/util/uk/org/iscream/cms/util/Queue.java	2001/01/30 02:12:23	1.8
+++ projects/cms/source/util/uk/org/iscream/cms/util/Queue.java	2002/05/18 18:16:03	1.24
@@ -1,10 +1,30 @@
+/* 
+ * i-scream central monitoring system
+ * Copyright (C) 2000-2002 i-scream
+ * 
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+ */
+
 //---PACKAGE DECLARATION---
-package uk.ac.ukc.iscream.util;
+package uk.org.iscream.cms.server.util;
 
 //---IMPORTS---
 import java.util.LinkedList;
 import java.util.NoSuchElementException;
-import uk.ac.ukc.iscream.util.*;
+import java.util.Random;
+import uk.org.iscream.cms.server.util.*;
 
 /**
  * A Queue class designed to operate in a multi-threaded environment, with
@@ -13,7 +33,7 @@ import uk.ac.ukc.iscream.util.*;
  * actually contains some elements.
  *
  * @author  $Author: tdb $
- * @version $Id: Queue.java,v 1.8 2001/01/30 02:12:23 tdb Exp $
+ * @version $Id: Queue.java,v 1.24 2002/05/18 18:16:03 tdb Exp $
  */
 public class Queue {
 
@@ -22,11 +42,64 @@ public class Queue {
     /**
      * The current CVS revision of this class
      */
-    public static final String REVISION = "$Revision: 1.8 $";
+    public static final String REVISION = "$Revision: 1.24 $";
     
+    /**
+     * 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;
+    
+    /**
+     * To allow opposite lookups.
+     */
+    public static final String[] algorithms = {"RANDOM", "FIRST", "LAST", "DROP"};
+    
 //---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,17 +113,27 @@ public class Queue {
         for(int i=0; i < _lists.size(); i++) {
             // skip over any gaps left in the list
             if(_lists.get(i) != null) {
-                int s = ((LinkedList) _lists.get(i)).size();
-                synchronized(this) {
-                    // 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) {
-                    synchronized(((LinkedList) _lists.get(i))) {
-                        ((LinkedList) _lists.get(i)).notifyAll();
+                synchronized(((LinkedList) _lists.get(i))) {
+                    // get size before adding to the Queue
+                    int s = ((LinkedList) _lists.get(i)).size();
+                    // 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
+                        //synchronized(((LinkedList) _lists.get(i))) {
+                            ((LinkedList) _lists.get(i)).notifyAll();
+                        //}
+                    }
                 }
             }
         }
@@ -72,8 +155,8 @@ public class Queue {
             throw new InvalidQueueException("Requested queue "+queue+" does not exist");
         }
         // block if the queue is empty
-        if (((LinkedList) _lists.get(queue)).size() == 0) {
-            synchronized(((LinkedList) _lists.get(queue))) {
+        synchronized(((LinkedList) _lists.get(queue))) {
+            if (((LinkedList) _lists.get(queue)).size() == 0) {
                 try { ((LinkedList) _lists.get(queue)).wait(); } catch(Exception e) {}
             }
         }
@@ -119,28 +202,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 = "<queue ";
         for(int i=0; i < _lists.size(); i++) {
             // check for null entries
             if(_lists.get(i) != null) {
-                status += "Queue number "+i+" contains "+((LinkedList) _lists.get(i)).size()+" elements";
-                status += "\n";
+                status += "queue"+i+"=\""+((LinkedList) _lists.get(i)).size()+"\" ";
             }
             else {
-                status += "Slot number "+i+" is currently empty";
-                status += "\n";
+                status += "queue"+i+"=\"[deleted]\" ";
             }
         }
-        status += "A total of "+_count+" elements have been added to the queues";
+        status += "total=\""+_count+"\"";
+        if(_maxSize != -1) {
+            status += " maxSize=\""+_maxSize+"\"";
+        }
+        status += "></queue>";
         return status;
     }
     
@@ -162,7 +247,8 @@ public class Queue {
     
     /**
      * Returns the total numer of elements to have passed
-     * through this queue (ie. a counter on the add method).
+     * through this queue. This is essentially a counter
+     * on the add method.
      *
      * @return the element-ometer.
      */
@@ -181,7 +267,7 @@ public class Queue {
      *
      * @return An integer to be passed to the get() method.
      */
-    public int getQueue() {
+    public synchronized int getQueue() {
         int pos = -1;
         for(int i=0; i < _lists.size(); i++) {
             if(_lists.get(i) == null) {
@@ -205,15 +291,68 @@ public class Queue {
      *
      * @param queue The integer identifier for the queue, given by getQueue().
      */
-    public void removeQueue(int queue) {
+    public synchronized void removeQueue(int queue) {
         _lists.set(queue, null);
     }
     
     /**
+     * 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
+     * This uses the uk.org.iscream.cms.server.util.FormatName class
      * to format the toString()
      *
      * @return the name of this class and its CVS revision.
@@ -226,7 +365,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---
@@ -241,6 +411,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