--- 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/02/12 02:21:45	1.9
@@ -13,7 +13,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.9 2001/02/12 02:21:45 tdb Exp $
  */
 public class Queue {
 
@@ -22,7 +22,7 @@ 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.9 $";
     
 //---STATIC METHODS---
 
@@ -62,6 +62,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 +96,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 +119,26 @@ 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+"=\"null\" ";
             }
         }
-        status += "A total of "+_count+" elements have been added to the queues";
+        status += "total=\""+_count+"\"></queue>";
         return status;
     }
     
@@ -150,6 +149,7 @@ public class Queue {
      *
      * @param queue The queue number to query.
      * @return the current size of the queue.
+     * @throws InvalidQueueException if the queue does not exist.
      */
     public int queueSize(int queue) throws InvalidQueueException {
         if (queue >= _lists.size() || _lists.get(queue) == null) {
@@ -162,7 +162,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 +208,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(
@@ -239,6 +292,11 @@ 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;
     
     /**
      * This is the friendly identifier of the