ViewVC Help

View File | Revision Log | Show Annotations | Revision Graph | Root Listing

root/i-scream/experimental/server/Queue/Queue.java

Comparing experimental/server/Queue/Queue.java (file contents):
Revision 1.4 by tdb, Thu Jan 18 22:08:07 2001 UTC vs.
Revision 1.9 by tdb, Thu Mar 1 03:04:28 2001 UTC

#	Line 1 | Line 1
1		//---PACKAGE DECLARATION---
2	<	package uk.ac.ukc.iscream.util;
2	>	//package uk.ac.ukc.iscream.util;
3
4		//---IMPORTS---
5		import java.util.LinkedList;
6		import java.util.NoSuchElementException;
7	<	import uk.ac.ukc.iscream.util.*;
7	>	import java.util.Random;
8	>	//import uk.ac.ukc.iscream.util.*;
9
10		/**
11		* A Queue class designed to operate in a multi-threaded environment, with
#	Line 24 | Line 25 | public class Queue {
25		*/
26		public static final String REVISION = "$Revision$";
27
28	+	/**
29	+	* Pass to constructor to remove a RANDOM item from
30	+	* the Queue upon reaching the maximum limit.
31	+	*/
32	+	public static final int RANDOM = 0;
33	+
34	+	/**
35	+	* Pass to constructor to remove the FIRST item from
36	+	* the Queue upon reaching the maximum limit.
37	+	*/
38	+	public static final int FIRST = 1;
39	+
40	+	/**
41	+	* Pass to constructor to remove the LAST item from
42	+	* the Queue upon reaching the maximum limit.
43	+	*/
44	+	public static final int LAST = 2;
45	+
46	+	/**
47	+	* Pass to constructor to drop the new item upon reaching
48	+	* the maximum Queue limit.
49	+	*/
50	+	public static final int DROP = 3;
51	+
52		//---STATIC METHODS---
53
54		//---CONSTRUCTORS---
55	+
56	+	/**
57	+	* Constructs a new Queue with a maximum size limit on
58	+	* any individual queue. This should be used to stop
59	+	* conditions where the Queue cannot be guaranteed to
60	+	* be emptied as quick as it's filled.
61	+	*
62	+	* An algorithm will be used to remove data when new data
63	+	* arrives. There may be choices of algorithms later on.
64	+	*
65	+	* @param maxSize the upper limit for a queue
66	+	* @param removeAlgorithm the remove algorithm to use upon reaching the maxSize
67	+	*/
68	+	public Queue(int maxSize, int removeAlgorithm) {
69	+	_maxSize = maxSize;
70	+	_removeAlgorithm = removeAlgorithm;
71	+	}
72	+
73	+	/**
74	+	* Constructs a Queue with no maximum size.
75	+	*/
76	+	public Queue() {
77	+	_maxSize = -1;
78	+	}
79
80		//---PUBLIC METHODS---
81
#	Line 40 | Line 89 | public class Queue {
89		for(int i=0; i < _lists.size(); i++) {
90		// skip over any gaps left in the list
91		if(_lists.get(i) != null) {
92	+	// get size before adding to the Queue
93		int s = ((LinkedList) _lists.get(i)).size();
94	<	synchronized(this) {
95	<	// add() does the same thing, but this ensures behaviour
96	<	((LinkedList) _lists.get(i)).addLast(o);
94	>	// check whether we need to remove an item from the current Queue
95	>	if(_maxSize!=-1 && s==_maxSize && _removeAlgorithm!=DROP) {
96	>	// we need to remove an item
97	>	removeQueueItem((LinkedList) _lists.get(i));
98		}
99	+	// check if we should add (not if Queue full, and using DROP algorithm)
100	+	if(!(s==_maxSize && _removeAlgorithm==DROP)) {
101	+	// add the next item, ensuring we lock
102	+	synchronized(this) {
103	+	// LinkedList.add() does the same thing, but this ensures behaviour
104	+	((LinkedList) _lists.get(i)).addLast(o);
105	+	}
106	+	}
107		// if the queue was empty before the add it is possible
108		// that a consumer is waiting... so we notify them
109		if (s == 0) {
#	Line 62 | Line 121 | public class Queue {
121		* This method returns an object from the front of a given queue.
122		* It will block until data exists in the queue if required.
123		*
124	+	* @param The queue to retrieve data from.
125		* @return The object from the front of the queue.
126		* @throws InvalidQueueException if the queue does not exist.
127		*/
#	Line 88 | Line 148 | public class Queue {
148		}
149		return o;
150		}
151	<
151	>
152		/**
153	<	* This method returns a textual status of the queues. It
154	<	* is merely for observation, and would most likely be used
155	<	* by a larger "monitoring" component. Information returned
156	<	* includes the current size of each queue, and the total
97	<	* items passed through.
153	>	* This method releases a get() method that's currently
154	>	* waiting on an empty queue. This was designed for
155	>	* shutdown() type methods that may have problems closing
156	>	* if the thread of control is waiting on a queue.
157		*
158	<	* @return A String message containing status information.
158	>	* @param queue the queue to release.
159		*/
160	<	public String status() {
161	<	String status = "";
160	>	public void releaseQueue(int queue) {
161	>	synchronized(((LinkedList) _lists.get(queue))) {
162	>	((LinkedList) _lists.get(queue)).notifyAll();
163	>	}
164	>	}
165	>
166	>	/**
167	>	* This method erases the contents of a given queue. This
168	>	* method should be used with care. It can only empty one
169	>	* internal queue, not all of them. This must be called
170	>	* multiple times to empty all queues.
171	>	*
172	>	* @param queue the queue to empty.
173	>	*/
174	>	public void clearQueue(int queue) {
175	>	synchronized(this) {
176	>	((LinkedList) _lists.get(queue)).clear();
177	>	}
178	>	}
179	>
180	>	/**
181	>	* This method returns an XML textual status of the queues.
182	>	* It is merely for observation, and would most likely be
183	>	* used by a larger "monitoring" component. Information
184	>	* returned includes the current size of each queue, and
185	>	* the total items passed through.
186	>	*
187	>	* @return A String message containing status information in XML format
188	>	*/
189	>	public String xmlStatus() {
190	>	String status = "<queue ";
191		for(int i=0; i < _lists.size(); i++) {
192		// check for null entries
193		if(_lists.get(i) != null) {
194	<	status += "Queue number "+i+" contains "+((LinkedList) _lists.get(i)).size()+" elements";
107	<	status += "\n";
194	>	status += "queue"+i+"=\""+((LinkedList) _lists.get(i)).size()+"\" ";
195		}
196		else {
197	<	status += "Slot number "+i+" is currently empty";
111	<	status += "\n";
197	>	status += "queue"+i+"=\"[deleted]\" ";
198		}
199		}
200	<	status += "A total of "+_count+" elements have been added to the queues";
200	>	status += "total=\""+_count+"\"";
201	>	if(_maxSize != -1) {
202	>	status += " maxSize=\""+_maxSize+"\"";
203	>	}
204	>	status += "></queue>";
205		return status;
206		}
207
#	Line 122 | Line 212 | public class Queue {
212		*
213		* @param queue The queue number to query.
214		* @return the current size of the queue.
215	+	* @throws InvalidQueueException if the queue does not exist.
216		*/
217		public int queueSize(int queue) throws InvalidQueueException {
218	<	if (queue >= _lists.size() || _lists.get(queue) == null) {
218	>	if (queue >= _lists.size() || _lists.get(queue) == null) {
219		throw new InvalidQueueException("Requested queue "+queue+" does not exist");
220		}
221	<	return ((LinkedList) _lists.get(queue)).size();
221	>	return ((LinkedList) _lists.get(queue)).size();
222		}
223
224		/**
225		* Returns the total numer of elements to have passed
226		* through this queue (ie. a counter on the add method).
227		*
228	<	* @return the element-ometer
228	>	* @return the element-ometer.
229		*/
230		public int elementCount() {
231	<	return _count;
231	>	return _count;
232		}
233
234		/**
#	Line 180 | Line 271 | public class Queue {
271		}
272
273		/**
274	+	* Start a monitor on our own Queue. This will log XML
275	+	* statistics about our Queue to a given Queue (could be
276	+	* the one being monitored).
277	+	*
278	+	* @param interval The long interval, in milliseconds, at which to take samples
279	+	* @param destQueue The queue to monitor to
280	+	* @param name A name to identify this Queue with
281	+	* @return whether we succeeded
282	+	*/
283	+	public boolean startMonitor(long interval, Queue destQueue, String name) {
284	+	if(_queueMon == null) {
285	+	// start a monitor
286	+	_queueMon = new QueueMonitor(this, destQueue, interval, name);
287	+	_queueMon.start();
288	+	return true;
289	+	}
290	+	else {
291	+	// already have a monitor running
292	+	return false;
293	+	}
294	+	}
295	+
296	+	/**
297	+	* Start a monitor on our own Queue. This will log XML
298	+	* statistics about our Queue to this Queue.
299	+	*
300	+	* @param interval The long interval, in milliseconds, at which to take samples
301	+	* @param name A name to identify this Queue with
302	+	* @return whether we succeeded
303	+	*/
304	+	public boolean startMonitor(long interval, String name) {
305	+	return startMonitor(interval, this, name);
306	+	}
307	+
308	+	/**
309	+	* Stop a monitor on our Queue if we have on running.
310	+	*
311	+	* @return whether we succeeded
312	+	*/
313	+	public boolean stopMonitor() {
314	+	if(_queueMon != null) {
315	+	// stop a monitor
316	+	_queueMon.shutdown();
317	+	_queueMon = null;
318	+	return true;
319	+	}
320	+	else {
321	+	// no monitor running
322	+	return false;
323	+	}
324	+	}
325	+
326	+	/**
327		* Overrides the {@link java.lang.Object#toString() Object.toString()}
328		* method to provide clean logging (every class should have this).
329		*
330		* This uses the uk.ac.ukc.iscream.util.FormatName class
331		* to format the toString()
332		*
333	<	* @return the name of this class and its CVS revision
333	>	* @return the name of this class and its CVS revision.
334		*/
335		public String toString() {
336		return FormatName.getName(
#	Line 196 | Line 340 | public class Queue {
340		}
341
342		//---PRIVATE METHODS---
343	<
343	>
344	>	/**
345	>	* This method removes an item from a Queue, using a method
346	>	* requested at construction.
347	>	*
348	>	* @param list The LinkedList from which to remove an item.
349	>	*/
350	>	private void removeQueueItem(LinkedList list) {
351	>	// look at our algorithm
352	>	// remove a random item from the list
353	>	if(_removeAlgorithm==RANDOM) {
354	>	// new Random, with a good seed
355	>	Random rand = new Random(System.currentTimeMillis());
356	>	int i = rand.nextInt(_maxSize);
357	>	synchronized(this) {
358	>	list.remove(i);
359	>	}
360	>	}
361	>	// remove the first item from the list
362	>	else if(_removeAlgorithm==FIRST) {
363	>	synchronized(this) {
364	>	list.removeFirst();
365	>	}
366	>	}
367	>	// remove the last item from the list
368	>	else if(_removeAlgorithm==LAST) {
369	>	synchronized(this) {
370	>	list.removeLast();
371	>	}
372	>	}
373	>	}
374	>
375		//---ACCESSOR/MUTATOR METHODS---
376
377		//---ATTRIBUTES---
#	Line 211 | Line 386 | public class Queue {
386		* passed through, for statistical purposes.
387		*/
388		private int _count = 0;
389	+
390	+	/**
391	+	* A reference to our QueueMonitor, if we have one.
392	+	*/
393	+	private QueueMonitor _queueMon = null;
394	+
395	+	/**
396	+	* The maximum size of any Queue.
397	+	*/
398	+	private int _maxSize = -1;
399	+
400	+	/**
401	+	* The remove algorithm to use upon a Queue reaching
402	+	* it's maximum size.
403	+	*/
404	+	private int _removeAlgorithm = -1;
405
406		/**
407		* This is the friendly identifier of the

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines