ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/experimental/server/Queue/Queue.java
(Generate patch)

Comparing experimental/server/Queue/Queue.java (file contents):
Revision 1.2 by tdb, Thu Dec 28 03:49:15 2000 UTC vs.
Revision 1.7 by tdb, Mon Feb 12 02:27:56 2001 UTC

# Line 1 | Line 1
1   //---PACKAGE DECLARATION---
2 + //package uk.ac.ukc.iscream.util;
3  
4   //---IMPORTS---
5   import java.util.LinkedList;
# Line 14 | Line 15 | import java.util.NoSuchElementException;
15   * @author  $Author$
16   * @version $Id$
17   */
18 < class Queue {
18 > public class Queue {
19  
20   //---FINAL ATTRIBUTES---
21  
# Line 25 | Line 26 | class Queue {
26      
27   //---STATIC METHODS---
28  
29 < //---CONSTRUCTORS---
30 <      
30 <    /**
31 <     * This constructor sets up a given number of queues, all of which
32 <     * will be populated with data using the add() method. It is very
33 <     * important that the correct number is given, otherwise redundant
34 <     * queues will build up with large amounts of data in them.
35 <     *
36 <     * @param consumers The number of queues to be created.
37 <     */
38 <    public Queue(int consumers) {
39 <        // constuct and initialise the queues
40 <        _lists = new LinkedList[consumers];
41 <        for(int i=0; i < _lists.length; i++) {
42 <            _lists[i] = new LinkedList();
43 <        }
44 <    }
45 <    
46 <    /**
47 <     * This constructor is intended for an environment with a single
48 <     * consumer. This should be used in conjunction with the no-args
49 <     * get() method.
50 <     */
51 <    public Queue() {
52 <        // call the proper constructor
53 <        this(1);
54 <    }
55 <    
29 > //---CONSTRUCTORS---  
30 >
31   //---PUBLIC METHODS---
32      
33      /**
# Line 62 | Line 37 | class Queue {
37       * @param o An Object to be added to the queues.
38       */
39      public void add(Object o) {
40 <        for(int i=0; i < _lists.length; i++) {
41 <            int s = _lists[i].size();
42 <            synchronized(this) {
43 <                // add() does the same thing, but this ensures behaviour
44 <                _lists[i].addLast(o);
45 <            }
46 <            // if the queue was empty before the add it is possible
72 <            // that a consumer is waiting... so we notify them
73 <            if (s == 0) {
74 <                synchronized(_lists[i]) {
75 <                    _lists[i].notifyAll();
40 >        for(int i=0; i < _lists.size(); i++) {
41 >            // skip over any gaps left in the list
42 >            if(_lists.get(i) != null) {
43 >                int s = ((LinkedList) _lists.get(i)).size();
44 >                synchronized(this) {
45 >                    // add() does the same thing, but this ensures behaviour
46 >                    ((LinkedList) _lists.get(i)).addLast(o);
47                  }
48 +                // if the queue was empty before the add it is possible
49 +                // that a consumer is waiting... so we notify them
50 +                if (s == 0) {
51 +                    synchronized(((LinkedList) _lists.get(i))) {
52 +                        ((LinkedList) _lists.get(i)).notifyAll();
53 +                    }
54 +                }
55              }
56          }
57          // we keep track of the total additions for the status() method
# Line 84 | Line 62 | class Queue {
62       * This method returns an object from the front of a given queue.
63       * It will block until data exists in the queue if required.
64       *
65 +     * @param The queue to retrieve data from.
66       * @return The object from the front of the queue.
67 +     * @throws InvalidQueueException if the queue does not exist.
68       */
69 <    public Object get(int queue) {
69 >    public Object get(int queue) throws InvalidQueueException {
70 >        // make sure queue exists
71 >        if (queue >= _lists.size() || _lists.get(queue) == null) {
72 >            throw new InvalidQueueException("Requested queue "+queue+" does not exist");
73 >        }
74          // block if the queue is empty
75 <        if (_lists[queue].size() == 0) {
76 <            synchronized(_lists[queue]) {
77 <                try { _lists[queue].wait(); } catch(Exception e) {}
75 >        if (((LinkedList) _lists.get(queue)).size() == 0) {
76 >            synchronized(((LinkedList) _lists.get(queue))) {
77 >                try { ((LinkedList) _lists.get(queue)).wait(); } catch(Exception e) {}
78              }
79          }
80          // get an item, it should never be null due to the blocking above
81          Object o = null;
82          synchronized(this) {
83              try {
84 <                o = _lists[queue].removeFirst();
84 >                o = ((LinkedList) _lists.get(queue)).removeFirst();
85              }
86              catch (NoSuchElementException e) {
87                  // This should never happen !
# Line 107 | Line 91 | class Queue {
91      }
92      
93      /**
94 <     * This method is intended for an environment where there is
95 <     * only a single consumer. It simply gets the item from the
96 <     * first (and presumably only) queue.
94 >     * This method releases a get() method that's currently
95 >     * waiting on an empty queue. This was designed for
96 >     * shutdown() type methods that may have problems closing
97 >     * if the thread of control is waiting on a queue.
98       *
99 <     * @return The object from the front of the queue.
99 >     * @param queue the queue to release.
100       */
101 <    public Object get() {
102 <        return get(0);
101 >    public void releaseQueue(int queue) {
102 >        synchronized(((LinkedList) _lists.get(queue))) {
103 >                ((LinkedList) _lists.get(queue)).notifyAll();
104 >        }
105      }
106 +
107 +    /**
108 +     * This method erases the contents of a given queue. This
109 +     * method should be used with care. It can only empty one
110 +     * internal queue, not all of them. This must be called
111 +     * multiple times to empty all queues.
112 +     *
113 +     * @param queue the queue to empty.
114 +     */
115 +    public void clearQueue(int queue) {
116 +        synchronized(this) {
117 +            ((LinkedList) _lists.get(queue)).clear();
118 +        }
119 +    }
120      
121      /**
122 <     * This method returns a textual status of the queues. It
123 <     * is merely for observation, and would most likely be used
124 <     * by a larger "monitoring" component. Information returned
125 <     * includes the current size of each queue, and the total
126 <     * items passed through.
122 >     * This method returns an XML textual status of the queues.
123 >     * It is merely for observation, and would most likely be
124 >     * used by a larger "monitoring" component. Information
125 >     * returned includes the current size of each queue, and
126 >     * the total items passed through.
127       *
128 <     * @return A String message containing status information.
128 >     * @return A String message containing status information in XML format
129       */
130 <    public String status() {
131 <        String status = "";
132 <        for(int i=0; i < _lists.length; i++) {
133 <            status += "Queue number "+i+" contains "+_lists[i].size()+" elements";
134 <            status += "\n";
130 >    public String xmlStatus() {
131 >        String status = "<queue ";
132 >        for(int i=0; i < _lists.size(); i++) {
133 >            // check for null entries
134 >            if(_lists.get(i) != null) {
135 >                status += "queue"+i+"=\""+((LinkedList) _lists.get(i)).size()+"\" ";
136 >            }
137 >            else {
138 >                status += "queue"+i+"=\"null\" ";
139 >            }
140          }
141 <        status += "A total of "+_count+" elements have been added to the queues";
141 >        status += "total=\""+_count+"\"></queue>";
142          return status;
143      }
144      
145      /**
146 +     * Returns the size of a given queue. A consumer can use
147 +     * this to see how big their queue is at any given time.
148 +     * they should use their queue number as the parameter.
149 +     *
150 +     * @param queue The queue number to query.
151 +     * @return the current size of the queue.
152 +     * @throws InvalidQueueException if the queue does not exist.
153 +     */
154 +    public int queueSize(int queue) throws InvalidQueueException {
155 +        if (queue >= _lists.size() || _lists.get(queue) == null) {
156 +            throw new InvalidQueueException("Requested queue "+queue+" does not exist");
157 +        }
158 +        return ((LinkedList) _lists.get(queue)).size();
159 +    }
160 +    
161 +    /**
162 +     * Returns the total numer of elements to have passed
163 +     * through this queue (ie. a counter on the add method).
164 +     *
165 +     * @return the element-ometer.
166 +     */
167 +    public int elementCount() {
168 +        return _count;
169 +    }
170 +    
171 +    /**
172       * This method assigns a queue to a consumer. The idea behind
173       * this is to ensure that only 1 consumer can be associated with
174       * a given queue, otherwise the whole "blocking" thing fails
175 <     * miserably.
175 >     * miserably. Queues are created upon requested.
176       *
177 +     * It is IMPORTANT that removeQueue() is used when the queue is
178 +     * no longer required.
179 +     *
180       * @return An integer to be passed to the get() method.
146     * @throws NoQueueException if there are no un-assigned queue's.
181       */
182 <    public int getQueue() throws NoQueueException {
183 <        if(_index < _lists.length) {
184 <            return _index++;
182 >    public int getQueue() {
183 >        int pos = -1;
184 >        for(int i=0; i < _lists.size(); i++) {
185 >            if(_lists.get(i) == null) {
186 >                // found a gap, re-use it
187 >                pos = i;
188 >                _lists.set(i, new LinkedList());
189 >            }
190          }
191 +        if(pos == -1) {
192 +            //we didn't find a gap, add at end
193 +            pos = _lists.size();
194 +            _lists.add(pos, new LinkedList());
195 +        }
196 +        return pos;
197 +    }
198 +    
199 +    /**
200 +     * This method sets a entry to null in the list. This ensures
201 +     * that it will no longer be added to after it is no longer
202 +     * required be a consumer.
203 +     *
204 +     * @param queue The integer identifier for the queue, given by getQueue().
205 +     */
206 +    public void removeQueue(int queue) {
207 +        _lists.set(queue, null);
208 +    }
209 +    
210 +    /**
211 +     * Start a monitor on our own Queue. This will log XML
212 +     * statistics about our Queue to a given Queue (could be
213 +     * the one being monitored).
214 +     *
215 +     * @param interval The long interval, in milliseconds, at which to take samples
216 +     * @param destQueue The queue to monitor to
217 +     * @param name A name to identify this Queue with
218 +     * @return whether we succeeded
219 +     */
220 +    public boolean startMonitor(long interval, Queue destQueue, String name) {
221 +        if(_queueMon == null) {
222 +            // start a monitor
223 +            _queueMon = new QueueMonitor(this, destQueue, interval, name);
224 +            _queueMon.start();
225 +            return true;
226 +        }
227          else {
228 <            throw new NoQueueException("Too many consumers, there are already "+_lists.length+" running");
228 >            // already have a monitor running
229 >            return false;
230          }
231      }
232 <
232 >    
233      /**
234 +     * Start a monitor on our own Queue. This will log XML
235 +     * statistics about our Queue to this Queue.
236 +     *
237 +     * @param interval The long interval, in milliseconds, at which to take samples
238 +     * @param name A name to identify this Queue with
239 +     * @return whether we succeeded
240 +     */
241 +    public boolean startMonitor(long interval, String name) {
242 +        return startMonitor(interval, this, name);
243 +    }
244 +    
245 +    /**
246 +     * Stop a monitor on our Queue if we have on running.
247 +     *
248 +     * @return whether we succeeded
249 +     */
250 +    public boolean stopMonitor() {
251 +        if(_queueMon != null) {
252 +            // stop a monitor
253 +            _queueMon.shutdown();
254 +            _queueMon = null;
255 +            return true;
256 +        }
257 +        else {
258 +            // no monitor running
259 +            return false;
260 +        }
261 +    }
262 +    
263 +    /**
264       * Overrides the {@link java.lang.Object#toString() Object.toString()}
265       * method to provide clean logging (every class should have this).
266       *
267       * This uses the uk.ac.ukc.iscream.util.FormatName class
268       * to format the toString()
269       *
270 <     * @return the name of this class and its CVS revision
270 >     * @return the name of this class and its CVS revision.
271       */
272 <    /*public String toString() {
272 >    public String toString() {
273          return FormatName.getName(
274              _name,
275              getClass().getName(),
276              REVISION);
277 <    }*/
277 >    }
278  
279   //---PRIVATE METHODS---
280  
# Line 177 | Line 283 | class Queue {
283   //---ATTRIBUTES---
284      
285      /**
286 <     * The array of lists, which the underlying queue data
181 <     * is stored in.
286 >     * The LinkedLists of queues.
287       */
288 <    private LinkedList[] _lists;
288 >    private LinkedList _lists = new LinkedList();
289      
290      /**
291       * A counter so we know how many data items have been
# Line 189 | Line 294 | class Queue {
294      private int _count = 0;
295      
296      /**
297 <     * An index of the next available queue. Used by the
193 <     * getQueue() method.
297 >     * A reference to our QueueMonitor, if we have one.
298       */
299 <    private int _index = 0;
300 <
299 >    private QueueMonitor _queueMon = null;
300 >    
301      /**
302       * This is the friendly identifier of the
303       * component this class is running in.
# Line 203 | Line 307 | class Queue {
307       * can be placed here.  This name could also
308       * be changed to null for utility classes.
309       */
310 <    //private String _name = <!THIS SHOULD CALL A STATIC NAME IN THE COMPONENT CLASS FOR THIS OBJECT!>;
207 <
208 <    /**
209 <     * This holds a reference to the
210 <     * system logger that is being used.
211 <     */
212 <    //private Logger _logger = ReferenceManager.getInstance().getLogger();
310 >    private String _name = null;
311  
312   //---STATIC ATTRIBUTES---
313  

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines