cms/util/Queue.java

//---PACKAGE DECLARATION---
package uk.ac.ukc.iscream.util;

//---IMPORTS---
import java.util.LinkedList;
import java.util.NoSuchElementException;
import uk.ac.ukc.iscream.util.*;

/**
 * A Queue class designed to operate in a multi-threaded environment, with
 * added support for multiple "consumer" threads. Also offers blocking on
 * the get() methods, which ensures the consumer waits until the queue
 * actually contains some elements.
 *
 * @author  $Author: tdb1 $
 * @version $Id: Queue.java,v 1.7 2001/01/30 01:56:28 tdb1 Exp $
 */
public class Queue {

//---FINAL ATTRIBUTES---

    /**
     * The current CVS revision of this class
     */
    public static final String REVISION = "$Revision: 1.7 $";
    
//---STATIC METHODS---

//---CONSTRUCTORS---  

//---PUBLIC METHODS---
    
    /**
     * This method adds a given object to every queue. It will notify
     * any waiting consumers (on an empty queue) during this process.
     *
     * @param o An Object to be added to the queues.
     */
    public void add(Object o) {
        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();
                    }
                }
            }
        }
        // we keep track of the total additions for the status() method
        _count++;
    }
    
    /**
     * 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.
     */
    public Object get(int queue) throws InvalidQueueException {
        // make sure queue exists
        if (queue >= _lists.size() || _lists.get(queue) == null) {
            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))) {
                try { ((LinkedList) _lists.get(queue)).wait(); } catch(Exception e) {}
            }
        }
        // get an item, it should never be null due to the blocking above
        Object o = null;
        synchronized(this) {
            try {
                o = ((LinkedList) _lists.get(queue)).removeFirst();
            }
            catch (NoSuchElementException e) {
                // This should never happen !
            }
        }
        return o;
    }
    
    /**
     * This method releases a get() method that's currently
     * waiting on an empty queue. This was designed for
     * shutdown() type methods that may have problems closing
     * if the thread of control is waiting on a queue.
     *
     * @param queue the queue to release.
     */
    public void releaseQueue(int queue) {
        synchronized(((LinkedList) _lists.get(queue))) {
                ((LinkedList) _lists.get(queue)).notifyAll();
        }
    }

    /**
     * This method erases the contents of a given queue. This
     * method should be used with care. It can only empty one
     * internal queue, not all of them. This must be called
     * multiple times to empty all queues.
     *
     * @param queue the queue to empty.
     */
    public void clearQueue(int queue) {
        synchronized(this) {
            ((LinkedList) _lists.get(queue)).clear();
        }
    }
    
    /**
     * 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.
     *
     * @return A String message containing status information.
     */
    public String status() {
        String status = "";
        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";
            }
            else {
                status += "Slot number "+i+" is currently empty";
                status += "\n";
            }
        }
        status += "A total of "+_count+" elements have been added to the queues";
        return status;
    }
    
    /**
     * Returns the size of a given queue. A consumer can use
     * this to see how big their queue is at any given time.
     * they should use their queue number as the parameter.
     *
     * @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) {
            throw new InvalidQueueException("Requested queue "+queue+" does not exist");
        }
        return ((LinkedList) _lists.get(queue)).size();
    }
    
    /**
     * Returns the total numer of elements to have passed
     * through this queue (ie. a counter on the add method).
     *
     * @return the element-ometer.
     */
    public int elementCount() {
        return _count;
    }
    
    /**
     * This method assigns a queue to a consumer. The idea behind
     * this is to ensure that only 1 consumer can be associated with
     * a given queue, otherwise the whole "blocking" thing fails
     * miserably. Queues are created upon requested.
     *
     * It is IMPORTANT that removeQueue() is used when the queue is
     * no longer required.
     *
     * @return An integer to be passed to the get() method.
     */
    public int getQueue() {
        int pos = -1;
        for(int i=0; i < _lists.size(); i++) {
            if(_lists.get(i) == null) {
                // found a gap, re-use it
                pos = i;
                _lists.set(i, new LinkedList());
            }
        }
        if(pos == -1) {
            //we didn't find a gap, add at end
            pos = _lists.size();
            _lists.add(pos, new LinkedList());
        }
        return pos;
    }
    
    /**
     * This method sets a entry to null in the list. This ensures
     * that it will no longer be added to after it is no longer
     * required be a consumer.
     *
     * @param queue The integer identifier for the queue, given by getQueue().
     */
    public void removeQueue(int queue) {
        _lists.set(queue, null);
    }
    
    /**
     * 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.
     */
    public String toString() {
        return FormatName.getName(
            _name,
            getClass().getName(),
            REVISION);
    }

//---PRIVATE METHODS---

//---ACCESSOR/MUTATOR METHODS---

//---ATTRIBUTES---
    
    /**
     * The LinkedLists of queues.
     */
    private LinkedList _lists = new LinkedList();
    
    /**
     * A counter so we know how many data items have been
     * passed through, for statistical purposes.
     */
    private int _count = 0;
    
    /**
     * This is the friendly identifier of the
     * component this class is running in.
     * eg, a Filter may be called "filter1",
     * If this class does not have an owning
     * component,  a name from the configuration
     * can be placed here.  This name could also
     * be changed to null for utility classes.
     */
    private String _name = null;

//---STATIC ATTRIBUTES---

}
Revision:	1.8
Committed:	Tue Jan 30 02:12:23 2001 UTC (23 years, 3 months ago) by tdb
Branch:	MAIN
Changes since 1.7:	+7 -5 lines
Log Message:	Just added a few javadoc comments that were missed.
#	Content
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	/**
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: tdb1 $
16	* @version $Id: Queue.java,v 1.7 2001/01/30 01:56:28 tdb1 Exp $
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: 1.7 $";
26
27	//---STATIC METHODS---
28
29	//---CONSTRUCTORS---
30
31	//---PUBLIC METHODS---
32
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	/**
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	synchronized(this) {
83	try {
84	o = ((LinkedList) _lists.get(queue)).removeFirst();
85	}
86	catch (NoSuchElementException e) {
87	// This should never happen !
88	}
89	}
90	return o;
91	}
92
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 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.
127	*
128	* @return A String message containing status information.
129	*/
130	public String status() {
131	String status = "";
132	for(int i=0; i < _lists.size(); i++) {
133	// check for null entries
134	if(_lists.get(i) != null) {
135	status += "Queue number "+i+" contains "+((LinkedList) _lists.get(i)).size()+" elements";
136	status += "\n";
137	}
138	else {
139	status += "Slot number "+i+" is currently empty";
140	status += "\n";
141	}
142	}
143	status += "A total of "+_count+" elements have been added to the queues";
144	return status;
145	}
146
147	/**
148	* Returns the size of a given queue. A consumer can use
149	* this to see how big their queue is at any given time.
150	* they should use their queue number as the parameter.
151	*
152	* @param queue The queue number to query.
153	* @return the current size of the queue.
154	* @throws InvalidQueueException if the queue does not exist.
155	*/
156	public int queueSize(int queue) throws InvalidQueueException {
157	if (queue >= _lists.size() \|\| _lists.get(queue) == null) {
158	throw new InvalidQueueException("Requested queue "+queue+" does not exist");
159	}
160	return ((LinkedList) _lists.get(queue)).size();
161	}
162
163	/**
164	* Returns the total numer of elements to have passed
165	* through this queue (ie. a counter on the add method).
166	*
167	* @return the element-ometer.
168	*/
169	public int elementCount() {
170	return _count;
171	}
172
173	/**
174	* This method assigns a queue to a consumer. The idea behind
175	* this is to ensure that only 1 consumer can be associated with
176	* a given queue, otherwise the whole "blocking" thing fails
177	* miserably. Queues are created upon requested.
178	*
179	* It is IMPORTANT that removeQueue() is used when the queue is
180	* no longer required.
181	*
182	* @return An integer to be passed to the get() method.
183	*/
184	public int getQueue() {
185	int pos = -1;
186	for(int i=0; i < _lists.size(); i++) {
187	if(_lists.get(i) == null) {
188	// found a gap, re-use it
189	pos = i;
190	_lists.set(i, new LinkedList());
191	}
192	}
193	if(pos == -1) {
194	//we didn't find a gap, add at end
195	pos = _lists.size();
196	_lists.add(pos, new LinkedList());
197	}
198	return pos;
199	}
200
201	/**
202	* This method sets a entry to null in the list. This ensures
203	* that it will no longer be added to after it is no longer
204	* required be a consumer.
205	*
206	* @param queue The integer identifier for the queue, given by getQueue().
207	*/
208	public void removeQueue(int queue) {
209	_lists.set(queue, null);
210	}
211
212	/**
213	* Overrides the {@link java.lang.Object#toString() Object.toString()}
214	* method to provide clean logging (every class should have this).
215	*
216	* This uses the uk.ac.ukc.iscream.util.FormatName class
217	* to format the toString()
218	*
219	* @return the name of this class and its CVS revision.
220	*/
221	public String toString() {
222	return FormatName.getName(
223	_name,
224	getClass().getName(),
225	REVISION);
226	}
227
228	//---PRIVATE METHODS---
229
230	//---ACCESSOR/MUTATOR METHODS---
231
232	//---ATTRIBUTES---
233
234	/**
235	* The LinkedLists of queues.
236	*/
237	private LinkedList _lists = new LinkedList();
238
239	/**
240	* A counter so we know how many data items have been
241	* passed through, for statistical purposes.
242	*/
243	private int _count = 0;
244
245	/**
246	* This is the friendly identifier of the
247	* component this class is running in.
248	* eg, a Filter may be called "filter1",
249	* If this class does not have an owning
250	* component, a name from the configuration
251	* can be placed here. This name could also
252	* be changed to null for utility classes.
253	*/
254	private String _name = null;
255
256	//---STATIC ATTRIBUTES---
257
258	}