JXTA

net.jxta.impl.util
Class UnbiasedQueue

java.lang.Object
  extended by net.jxta.impl.util.UnbiasedQueue
Direct Known Subclasses:
ConsumerBiasedQueue, ProducerBiasedQueue, UnbiasedQueue.SynchronizedQueue

Deprecated. Please convert all code to use the java.util.concurrent BlockingQueue instead.

@Deprecated
public class UnbiasedQueue
extends Object

A generic queue class. This queue is explicitly NOT a synchronized queue.

FIXME 20020511 bondolo@jxta.org This could be more efficient with a circular queue implementation, but its a pain to write since we allow the queue to be resizable.

FIXME 20020511 bondolo@jxta.org Exercise for the reader: Extend this class so that it does both LIFO and FIFO.

FIXME 20020910 bondolo@jxta.org Needs an optional listener callback for droppped elments.

FIXME 20020910 bondolo@jxta.org Needs an optional "strategy" for element insertion and removal.


Nested Class Summary
protected static class UnbiasedQueue.SynchronizedQueue
          Deprecated. An inner class for wrapping arbitrary queues with synchronization.
 
Field Summary
protected  boolean closeFlag
          Deprecated. If true the queue is being closed and is currently in the process of being flushed.
protected static int DEFAULT_MAX_OBJECTS
          Deprecated. Default number of queue elements.
protected static boolean DROP_OLDEST_OBJECT
          Deprecated. Default object dropping behaviour
protected  boolean dropOldestObject
          Deprecated. When we need to drop objects, drop the oldest obj.
protected static long DROPPED_OBJECT_WARNING_INTERVAL
          Deprecated. Number of milliseconds between notifications that objects are being dropped.
protected  int maxObjects
          Deprecated. The maximum number of objects we will hold in the queue at one time.
protected  long nextDroppedWarn
          Deprecated. absolute time in millis when it will be ok to display a obj about dropping objects.
protected  long numDequeued
          Deprecated. total number of objects which have been dequeued from this queue
protected  long numDropped
          Deprecated. the number of objects we have dropped since we began working.
protected  long numEnqueued
          Deprecated. total number of objects which have been enqueued into this queue
protected  List<Object> queue
          Deprecated. Contains the objects we currently have queued.
protected  long sumOfQueueSizesDequeue
          Deprecated. sum of queue sizes at dequeue time.
protected  long sumOfQueueSizesEnqueue
          Deprecated. sum of queue sizes at enqueue time.
 
Constructor Summary
UnbiasedQueue()
          Deprecated. Default constructor. 100 element FIFO queue which drops oldest element when full.
UnbiasedQueue(int maxsize, boolean dropOldest)
          Deprecated. Full featured constructor for creating a new UnBiasedQueue.
UnbiasedQueue(int maxsize, boolean dropOldest, List<Object> queue)
          Deprecated. Full featured constructor for creating a new UnBiasedQueue.
 
Method Summary
 void clear()
          Deprecated. Flush the queue of all pending objects.
 void close()
          Deprecated. Close the queue.
 double getAvgInQueueAtDequeue()
          Deprecated. Return the average number of elements in the queue at dequeue time.
 double getAvgInQueueAtEnqueue()
          Deprecated. Return the average number of elements in the queue at Enqueue time.
 int getCurrentInQueue()
          Deprecated. Return the number of elements currently in the queue.
 int getMaxQueueSize()
          Deprecated. How many objects will fit in this queue
 long getNumDequeued()
          Deprecated. Return the total number of objects which have been dequeued from this queue during its existance.
 long getNumDropped()
          Deprecated. Return the total number of objects which have been dropped by this queue during its existance.
 long getNumEnqueued()
          Deprecated. Return the total number of objects which have been enqueued on to this queue during its existance.
 void interrupt()
          Deprecated.  
 boolean isClosed()
          Deprecated. Atomically return whether or not this queue has been closed.
 Object peek()
          Deprecated. Return the next Object from the queue without removing it.
 Object pop()
          Deprecated. Remove and return the next Object from the queue.
 Object pop(long timeout)
          Deprecated. Gets a Object from the queue.
 Object[] popMulti(int maxObjs)
          Deprecated. Returns an array of objects, possibly empty, from the queue.
 boolean push(Object obj)
          Deprecated. Attempt to push an object onto the queue.
 boolean push(Object obj, long timeout)
          Deprecated. Push an object onto the queue.
 boolean pushBack(Object obj)
          Deprecated. Attempt to push an object back at the head the queue.
 boolean pushBack(Object obj, long timeout)
          Deprecated. Push an object back at the head of the queue.
 void setMaxQueueSize(int maxObjs)
          Deprecated. Set how many objects this queue may store.
static UnbiasedQueue synchronizedQueue(UnbiasedQueue queue)
          Deprecated. Returns a synchronized (thread-safe) list backed by the specified queue.
 String toString()
          Deprecated. 

A diagnostic toString implementation.

 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_MAX_OBJECTS

protected static final int DEFAULT_MAX_OBJECTS
Deprecated. 
Default number of queue elements.

See Also:
Constant Field Values

DROP_OLDEST_OBJECT

protected static final boolean DROP_OLDEST_OBJECT
Deprecated. 
Default object dropping behaviour

See Also:
Constant Field Values

DROPPED_OBJECT_WARNING_INTERVAL

protected static final long DROPPED_OBJECT_WARNING_INTERVAL
Deprecated. 
Number of milliseconds between notifications that objects are being dropped.

See Also:
Constant Field Values

queue

protected List<Object> queue
Deprecated. 
Contains the objects we currently have queued.


maxObjects

protected int maxObjects
Deprecated. 
The maximum number of objects we will hold in the queue at one time.


closeFlag

protected volatile boolean closeFlag
Deprecated. 
If true the queue is being closed and is currently in the process of being flushed. All new "push" requests will be refused.


dropOldestObject

protected boolean dropOldestObject
Deprecated. 
When we need to drop objects, drop the oldest obj.


numEnqueued

protected long numEnqueued
Deprecated. 
total number of objects which have been enqueued into this queue


sumOfQueueSizesEnqueue

protected long sumOfQueueSizesEnqueue
Deprecated. 
sum of queue sizes at enqueue time.


numDequeued

protected long numDequeued
Deprecated. 
total number of objects which have been dequeued from this queue


sumOfQueueSizesDequeue

protected long sumOfQueueSizesDequeue
Deprecated. 
sum of queue sizes at dequeue time.


numDropped

protected long numDropped
Deprecated. 
the number of objects we have dropped since we began working.


nextDroppedWarn

protected long nextDroppedWarn
Deprecated. 
absolute time in millis when it will be ok to display a obj about dropping objects. We throttle this so that there is a chance to do work rather than just always spewing warnings.

Constructor Detail

UnbiasedQueue

public UnbiasedQueue()
Deprecated. 
Default constructor. 100 element FIFO queue which drops oldest element when full.


UnbiasedQueue

public UnbiasedQueue(int maxsize,
                     boolean dropOldest)
Deprecated. 
Full featured constructor for creating a new UnBiasedQueue.

Parameters:
maxsize - Queue will not grow larger than this size. Use Integer.MAX_VALUE for "unbounded" queue size.
dropOldest - Controls behaviour of element insertion when the queue is full. If true and the queue is full upon a push operation then the oldest element will be dropped to be replaced with the element currently being pushed. If false then the element will not be inserted if the queue is full.

UnbiasedQueue

public UnbiasedQueue(int maxsize,
                     boolean dropOldest,
                     List<Object> queue)
Deprecated. 
Full featured constructor for creating a new UnBiasedQueue.

Parameters:
maxsize - Queue will not grow larger than this size. Use Integer.MAX_VALUE for "unbounded" queue size.
dropOldest - Controls behaviour of element insertion when the queue is full. If true and the queue is full upon a push operation then the oldest element will be dropped to be replaced with the element currently being pushed. If false then the element will not be inserted if the queue is full.
queue - the List class instance to use. This does not need to be a synchronized list class. (and it works more effciently if it isn't).
Method Detail

synchronizedQueue

public static UnbiasedQueue synchronizedQueue(UnbiasedQueue queue)
Deprecated. 
Returns a synchronized (thread-safe) list backed by the specified queue. Most UnbiasedQueue subclasses are either unsynchronized or internally synchronized. If you need to do any atomic operations upon UnbiasedQueues (or subclasses) then this method should be used to "wrap" the queue with synchronization.

In order to guarantee serial access, it is critical that all access to the backing queue is accomplished through the returned queue.

Parameters:
queue - the queue to be "wrapped" in a synchronized queue.

toString

public String toString()
Deprecated. 

A diagnostic toString implementation.

Overrides:
toString in class Object

isClosed

public boolean isClosed()
Deprecated. 
Atomically return whether or not this queue has been closed. Closed queues will not accept "push" requests, but elements will still be returned with "pop".

Returns:
boolean indicating whether this queue has been closed.

close

public void close()
Deprecated. 
Close the queue. This will prevent any further objects from being enqueued.


clear

public void clear()
Deprecated. 
Flush the queue of all pending objects.


push

public boolean push(Object obj)
Deprecated. 
Attempt to push an object onto the queue. If the queue is full then the object will not be pushed. This method does not use any synchronization and should not be used if other threads are using pop(long) to retrieve elements.

Parameters:
obj - object to push
Returns:
true if the obj was pushed, otherwise false.

pushBack

public boolean pushBack(Object obj)
Deprecated. 
Attempt to push an object back at the head the queue. If the queue is full then the object will not be pushed. This method does not use any synchronization and should not be used if other threads are using pop(long) to retrieve elements.

Parameters:
obj - object to push
Returns:
true if the obj was pushed, otherwise false.

push

public boolean push(Object obj,
                    long timeout)
             throws InterruptedException
Deprecated. 
Push an object onto the queue. If the queue is full then the push will wait for up to "timeout" milliseconds to push the object. At the end of "timeout" milliseconds, the push will either return false or remove the oldest item from the queue and insert "obj". This behaviour is contolled by the constructor parameter "dropOldest".

Parameters:
obj - Object to be pushed onto the queue
timeout - Time in milliseconds to try to insert the item into a full queue. Per Java standards, a timeout of "0" (zero) will wait indefinitly. Negative values force no wait period at all.
Returns:
true if the object was intersted into the queue, otherwise false.
Throws:
InterruptedException - if the operation is interrupted before the timeout interval is completed.

pushBack

public boolean pushBack(Object obj,
                        long timeout)
                 throws InterruptedException
Deprecated. 
Push an object back at the head of the queue. If the queue is full then the push will wait for up to "timeout" milliseconds to push the object. At the end of "timeout" milliseconds, the push will either return false or remove the oldest item from the queue and insert "obj". This behaviour is contolled by the constructor parameter "dropOldest".

Timeout control is accomplished via synchronization and Object.wait(long). pushBack(Object,long) should only be used in conjunction with push(Object,long) and pop(long)

Parameters:
obj - Object to be pushed onto the queue
timeout - Time in milliseconds to try to insert the item into a full queue. Per Java standards, a timeout of "0" (zero) will wait indefinitly. Negative values force no wait period at all.
Returns:
true if the object was intersted into the queue, otherwise false.
Throws:
InterruptedException - if the operation is interrupted before the timeout interval is completed.

peek

public Object peek()
Deprecated. 
Return the next Object from the queue without removing it.

Returns:
Object, null if the queue is empty.

pop

public Object pop()
Deprecated. 
Remove and return the next Object from the queue.

Returns:
Object, null if the queue is empty.

pop

public Object pop(long timeout)
           throws InterruptedException
Deprecated. 
Gets a Object from the queue. If no Object is immediately available, then wait the specified amount of time for an Object to be inserted.

Parameters:
timeout - Amount of time to wait in milliseconds for an object to be available. Per Java convention, a timeout of zero (0) means wait an infinite amount of time. Negative values mean do not wait at all.
Returns:
The next object in the queue.
Throws:
InterruptedException - if the operation is interrupted before the timeout interval is completed.

popMulti

public Object[] popMulti(int maxObjs)
Deprecated. 
Returns an array of objects, possibly empty, from the queue.

Parameters:
maxObjs - the maximum number of items to return.
Returns:
an array of objects, possibly empty containing the returned queue elements.

getMaxQueueSize

public int getMaxQueueSize()
Deprecated. 
How many objects will fit in this queue

Returns:
int indicating how many objects will fit in the queue.

setMaxQueueSize

public void setMaxQueueSize(int maxObjs)
Deprecated. 
Set how many objects this queue may store. Note that if there are more objects already in the queue than the specified amount then the queue will retain its current capacity.

Parameters:
maxObjs - The number of objects which the queue must be able to store.

getCurrentInQueue

public int getCurrentInQueue()
Deprecated. 
Return the number of elements currently in the queue. This method is useful for statistical sampling, but should not be used to determine program logic due to the multi-threaded behaviour of these queues.

You should use the return values and timeout behaviour of the push(Object) and pop(long) methods to regulate how you use the queue.

Returns:
the number of elements currently in the queue. Be warned that even two sequential calls to this method may return different answers due to activity on other threads.

getNumEnqueued

public long getNumEnqueued()
Deprecated. 
Return the total number of objects which have been enqueued on to this queue during its existance.

Returns:
how many objects have been queued.

getAvgInQueueAtEnqueue

public double getAvgInQueueAtEnqueue()
Deprecated. 
Return the average number of elements in the queue at Enqueue time.

Returns:
average number of elements which were in the queue at during all of the "push" operations which returned a "true" result. Does not include the item being pushed. If no elements have ever been enqueued then "NaN" will be returned.

getNumDequeued

public long getNumDequeued()
Deprecated. 
Return the total number of objects which have been dequeued from this queue during its existance.

Returns:
how many objects have been queued.

getAvgInQueueAtDequeue

public double getAvgInQueueAtDequeue()
Deprecated. 
Return the average number of elements in the queue at dequeue time.

Returns:
average number of elements which were in the queue at during all of the "pop" operations which returned a non-null result. Includes the item being "pop"ed in the average. If no elements have ever been dequeued then "NaN" will be returned.

getNumDropped

public long getNumDropped()
Deprecated. 
Return the total number of objects which have been dropped by this queue during its existance.

Returns:
how many objects have been dropped.

interrupt

public void interrupt()
Deprecated. 

JXSE