2 * Copyright (c) 2001-2007 Sun Microsystems, Inc. All rights reserved.
4 * The Sun Project JXTA(TM) Software License
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
9 * 1. Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the documentation
14 * and/or other materials provided with the distribution.
16 * 3. The end-user documentation included with the redistribution, if any, must
17 * include the following acknowledgment: "This product includes software
18 * developed by Sun Microsystems, Inc. for JXTA(TM) technology."
19 * Alternately, this acknowledgment may appear in the software itself, if
20 * and wherever such third-party acknowledgments normally appear.
22 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
23 * not be used to endorse or promote products derived from this software
24 * without prior written permission. For written permission, please contact
25 * Project JXTA at http://www.jxta.org.
27 * 5. Products derived from this software may not be called "JXTA", nor may
28 * "JXTA" appear in their name, without prior written permission of Sun.
30 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
32 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
33 * MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
34 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
36 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
37 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
38 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
39 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41 * JXTA is a registered trademark of Sun Microsystems, Inc. in the United
42 * States and other countries.
44 * Please see the license information page at :
45 * <http://www.jxta.org/project/www/license.html> for instructions on use of
46 * the license in source files.
48 * ====================================================================
50 * This software consists of voluntary contributions made by many individuals
51 * on behalf of Project JXTA. For more information on Project JXTA, please see
52 * http://www.jxta.org.
54 * This license is based on the BSD license adopted by the Apache Foundation.
57 package net.jxta.impl.util;
60 import java.util.logging.Logger;
61 import java.util.logging.Level;
62 import net.jxta.logging.Logging;
64 import java.util.List;
65 import java.util.ArrayList;
67 import net.jxta.impl.util.TimeUtils;
71 * A queue who's implementation is biased towards effciency in removing
72 elements from the queue.
74 * FIXME 20020511 bondolo@jxta.org This could be more efficient with a
75 * circular queue implementation, but its a pain to write since we allow the
76 * queue to be resizable.
78 * FIXME 20020511 bondolo@jxta.org Exercise for the reader: Extend this
79 * class so that it does both LIFO and FIFO.
81 * @deprecated Please convert all code to use the java.util.concurrent BlockingQueue instead.
85 public class ConsumerBiasedQueue extends UnbiasedQueue {
90 private static final Logger LOG = Logger.getLogger(ConsumerBiasedQueue.class.getName());
93 * Default constructor. 100 element FIFO queue which drops oldest element
96 public ConsumerBiasedQueue() {
97 this(DEFAULT_MAX_OBJECTS, DROP_OLDEST_OBJECT);
101 * Full featured constructor for creating a new ConsumerBiasedQueue.
103 * @param size Queue will be not grow larger than this size. Use
104 * Integer.MAX_VALUE for "unbounded" queue size.
105 * @param dropOldest Controls behaviour of element insertion when the queue is
106 * full. If "true" and the queue is full upon a push operation then the
107 * oldest element will be dropped to be replaced with the element currently
108 * being pushed. If "false" then then newest item will be dropped.
110 public ConsumerBiasedQueue(int size, boolean dropOldest) {
111 super(size, dropOldest, new ArrayList());
115 * Flush the queue of all pending objects.
118 public void clear() {
119 synchronized (queue) {
125 public synchronized boolean push(Object obj) {
126 synchronized (queue) {
127 boolean pushed = super.push(obj);
129 queue.notify(); // inform someone who is waiting. we dont have to tell everyone though
135 * Push an object onto the queue. If the queue is full then the push will
136 * wait for up to "timeout" milliseconds to push the object. At the end of
137 * "timeout" milliseconds, the push will either return false or remove the
138 * oldest item from the queue and insert "obj". This behaviour is contolled
139 * by the constructor parameter "dropOldest".
141 * This method, unlike all others is synchronized. This creates a
142 * bottleneck for producers seperate from the primary lock on the "queue"
143 * member. This reduces contention on the primary lock which benefits users
144 * who are popping items from the queue (Consumers).
146 * @param obj Object to be pushed onto the queue
147 * @param timeout Time in milliseconds to try to insert the item into a full
148 * queue. Per Java standards, a timeout of "0" (zero) will wait indefinitly.
149 * Negative values force no wait period at all.
150 * @return true if the object was intersted into the queue, otherwise false.
151 * @throws InterruptedException if the operation is interrupted before
152 * the timeout interval is completed.
155 public synchronized boolean push(Object obj, long timeout) throws InterruptedException {
156 return super.push(obj, timeout);
160 * Return next obj in the queue if there is one.
162 * @return Object, null if the queue is empty
165 public Object pop() {
166 synchronized (queue) {
172 * Returns an array of objects, possibly empty, from the queue.
174 * @param maxObjs the maximum number of items to return.
175 * @return an array of objects, possibly empty containing the returned
179 public Object[] popMulti(int maxObjs) {
180 synchronized (queue) {
181 return super.popMulti(maxObjs);
186 * Set how many objects this queue may store. Note that if there are more
187 * objects already in the queue than the specified amount then the queue
188 * will retain its current capacity.
190 * @param maxObjs The number of objects which the queue must be able to
194 public void setMaxQueueSize(int maxObjs) {
195 synchronized (queue) {
196 super.setMaxQueueSize(maxObjs);
201 * Return the number of elements currently in the queue. This method is
202 * useful for statistical sampling, but should not be used to determine
203 * program logic due to the multi-threaded behaviour of these queues. You
204 * should use the return values and timeout behaviour of the push() and
205 * pop() methods to regulate how you use the queue.
207 * @return the number of elements currently in the queue. Be warned that
208 * even two sequential calls to this method may return different answers
209 * due to activity on other threads.
213 public int getCurrentInQueue() {
214 synchronized (queue) {
215 return super.getCurrentInQueue();
220 * Return the average number of elements in the queue at Enqueue time.
222 * @return average number of elements which were in the queue at during all
223 * of the "push" operations which returned a "true" result. Does not
224 * include the item being pushed. If no elements have ever been enqueued
225 * then "NaN" will be returned.
228 public double getAvgInQueueAtEnqueue() {
229 synchronized (queue) {
230 return super.getAvgInQueueAtEnqueue();
235 * Return the average number of elements in the queue at dequeue time.
237 * @return average number of elements which were in the queue at during all
238 * of the "pop" operations which returned a non-null result. Includes the
239 * item being "pop"ed in the average. If no elements have ever been dequeued
240 * then "NaN" will be returned.
243 public double getAvgInQueueAtDequeue() {
244 synchronized (queue) {
245 return super.getAvgInQueueAtDequeue();