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.1 by tdb, Thu Dec 28 00:58:43 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;
6		import java.util.NoSuchElementException;
7	+	//import uk.ac.ukc.iscream.util.*;
8
9	<	class Queue {
9	>	/**
10	>	* A Queue class designed to operate in a multi-threaded environment, with
11	>	* added support for multiple "consumer" threads. Also offers blocking on
12	>	* the get() methods, which ensures the consumer waits until the queue
13	>	* actually contains some elements.
14	>	*
15	>	* @author  $Author$
16	>	* @version $Id$
17	>	*/
18	>	public class Queue {
19	>
20	>	//---FINAL ATTRIBUTES---
21	>
22	>	/**
23	>	* The current CVS revision of this class
24	>	*/
25	>	public static final String REVISION = "$Revision$";
26
27	<	public Queue() {
28	<	// Possible use this method instead ?
29	<	//_list = Collections.synchronizedList(new LinkedList(...));
30	<	_list = new LinkedList();
31	<	}
27	>	//---STATIC METHODS---
28	>
29	>	//---CONSTRUCTORS---
30	>
31	>	//---PUBLIC METHODS---
32
33	<	public synchronized void add(Object o) {
34	<	int s = _list.size();
35	<	// add() does the same thing, but this ensures behaviour
36	<	_list.addLast(o);
37	<	if (s == 0) {
38	<	notifyAll();
33	>	/**
34	>	* This method adds a given object to every queue. It will notify
35	>	* any waiting consumers (on an empty queue) during this process.
36	>	*
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.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
58		_count++;
59		}
60
61	<	public synchronized Object get() {
62	<	if (_list.size() == 0) {
63	<	try { wait(); } catch(Exception e) {}
61	>	/**
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) 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 (((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	<	try {
83	<	o = _list.removeFirst();
82	>	synchronized(this) {
83	>	try {
84	>	o = ((LinkedList) _lists.get(queue)).removeFirst();
85	>	}
86	>	catch (NoSuchElementException e) {
87	>	// This should never happen !
88	>	}
89		}
30	–	catch (NoSuchElementException e) {
31	–	// no element... null already... so just leave
32	–	}
90		return o;
91		}
92
93	<	public String status() {
94	<	String status = "";
95	<	status += "Current queue size = "+_list.size();
96	<	status += "\n";
97	<	status += "Queue-ometer = "+_count;
93	>	/**
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	>	* @param queue the queue to release.
100	>	*/
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 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 in XML format
129	>	*/
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 += "total=\""+_count+"\"></queue>";
142		return status;
143		}
144
145	<	private LinkedList _list;
146	<	private int _count;
147	<	}
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. 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.
181	>	*/
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	>	// already have a monitor running
229	>	return false;
230	>	}
231	>	}
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.
271	>	*/
272	>	public String toString() {
273	>	return FormatName.getName(
274	>	_name,
275	>	getClass().getName(),
276	>	REVISION);
277	>	}
278	>
279	>	//---PRIVATE METHODS---
280	>
281	>	//---ACCESSOR/MUTATOR METHODS---
282	>
283	>	//---ATTRIBUTES---
284	>
285	>	/**
286	>	* The LinkedLists of queues.
287	>	*/
288	>	private LinkedList _lists = new LinkedList();
289	>
290	>	/**
291	>	* A counter so we know how many data items have been
292	>	* passed through, for statistical purposes.
293	>	*/
294	>	private int _count = 0;
295	>
296	>	/**
297	>	* A reference to our QueueMonitor, if we have one.
298	>	*/
299	>	private QueueMonitor _queueMon = null;
300	>
301	>	/**
302	>	* This is the friendly identifier of the
303	>	* component this class is running in.
304	>	* eg, a Filter may be called "filter1",
305	>	* If this class does not have an owning
306	>	* component,  a name from the configuration
307	>	* can be placed here.  This name could also
308	>	* be changed to null for utility classes.
309	>	*/
310	>	private String _name = null;
311	>
312	>	//---STATIC ATTRIBUTES---
313	>
314	>	}

Diff Legend

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