Project JXTA

net.jxta.impl.util
Class UnbiasedQueue.SynchronizedQueue

java.lang.Object
  extended bynet.jxta.impl.util.UnbiasedQueue
      extended bynet.jxta.impl.util.UnbiasedQueue.SynchronizedQueue
Enclosing class:
UnbiasedQueue

protected static class UnbiasedQueue.SynchronizedQueue
extends UnbiasedQueue

An inner class for wrapping arbitrary queues with synchronization.


Nested Class Summary
 
Nested classes inherited from class net.jxta.impl.util.UnbiasedQueue
UnbiasedQueue.SynchronizedQueue
 
Field Summary
(package private)  UnbiasedQueue innerqueue
           
 
Fields inherited from class net.jxta.impl.util.UnbiasedQueue
closeFlag, DEFAULT_MAX_OBJECTS, DROP_OLDEST_OBJECT, dropOldestObject, DROPPED_OBJECT_WARNING_INTERVAL, maxObjects, nextDroppedWarn, numDequeued, numDropped, numEnqueued, queue, sumOfQueueSizesDequeue, sumOfQueueSizesEnqueue
 
Constructor Summary
UnbiasedQueue.SynchronizedQueue(UnbiasedQueue queue)
          {@inheritDoc}
 
Method Summary
 void clear()
          Flush the queue of all pending objects.
 void close()
          Close the queue. This will prevent any further objects from being enqueued.
 double getAvgInQueueAtDequeue()
          Return the average number of elements in the queue at dequeue time.
 double getAvgInQueueAtEnqueue()
          Return the average number of elements in the queue at Enqueue time.
 int getCurrentInQueue()
          Return the number of elements currently in the queue.
 int getMaxQueueSize()
          How many objects will fit in this queue
 long getNumDequeued()
          Return the total number of objects which have been dequeued from this queue during its existance.
 long getNumDropped()
          Return the total number of objects which have been dropped by this queue during its existance.
 long getNumEnqueued()
          Return the total number of objects which have been enqueued on to this queue during its existance.
 boolean isClosed()
          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".
 Object peek()
          Return the next Object from the queue without removing it.
 Object pop()
          Remove and return the next Object from the queue.
 Object pop(long timeout)
          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.
 Object[] popMulti(int maxObjs)
          Returns an array of objects, possibly empty, from the queue.
 boolean push(Object obj)
          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 UnbiasedQueue.pop(long) to retrieve elements.
 boolean push(Object obj, long timeout)
          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".
 boolean pushBack(Object obj)
          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 UnbiasedQueue.pop(long) to retrieve elements.
 boolean pushBack(Object obj, long timeout)
          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). UnbiasedQueue.pushBack(Object,long) should only be used in conjunction with UnbiasedQueue.push(Object,long) and UnbiasedQueue.pop(long)

 void setMaxQueueSize(int maxObjs)
          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.
 
Methods inherited from class net.jxta.impl.util.UnbiasedQueue
interrupt, synchronizedQueue, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

innerqueue

UnbiasedQueue innerqueue
Constructor Detail

UnbiasedQueue.SynchronizedQueue

public UnbiasedQueue.SynchronizedQueue(UnbiasedQueue queue)
{@inheritDoc}

Method Detail

isClosed

public boolean isClosed()
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".

Overrides:
isClosed in class UnbiasedQueue
Returns:
boolean indicating whether this queue has been closed.

close

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

Overrides:
close in class UnbiasedQueue

clear

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

Overrides:
clear in class UnbiasedQueue

push

public boolean push(Object obj)
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 UnbiasedQueue.pop(long) to retrieve elements.

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

pushBack

public boolean pushBack(Object obj)
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 UnbiasedQueue.pop(long) to retrieve elements.

Overrides:
pushBack in class UnbiasedQueue
Parameters:
obj - object to push
Returns:
true if the obj was pushed, otherwise false.

push

public boolean push(Object obj,
                    long timeout)
             throws InterruptedException
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".

Overrides:
push in class UnbiasedQueue
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
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). UnbiasedQueue.pushBack(Object,long) should only be used in conjunction with UnbiasedQueue.push(Object,long) and UnbiasedQueue.pop(long)

Overrides:
pushBack in class UnbiasedQueue
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()
Return the next Object from the queue without removing it.

Overrides:
peek in class UnbiasedQueue
Returns:
Object, null if the queue is empty.

pop

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

Overrides:
pop in class UnbiasedQueue
Returns:
Object, null if the queue is empty.

pop

public Object pop(long timeout)
           throws InterruptedException
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.

Overrides:
pop in class UnbiasedQueue
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)
Returns an array of objects, possibly empty, from the queue.

Overrides:
popMulti in class UnbiasedQueue
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()
How many objects will fit in this queue

Overrides:
getMaxQueueSize in class UnbiasedQueue
Returns:
int indicating how many objects will fit in the queue.

setMaxQueueSize

public void setMaxQueueSize(int maxObjs)
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.

Overrides:
setMaxQueueSize in class UnbiasedQueue
Parameters:
maxObjs - The number of objects which the queue must be able to store.

getCurrentInQueue

public int getCurrentInQueue()
Description copied from class: UnbiasedQueue
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 UnbiasedQueue.push(Object) and UnbiasedQueue.pop(long) methods to regulate how you use the queue.

Overrides:
getCurrentInQueue in class UnbiasedQueue
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()
Return the total number of objects which have been enqueued on to this queue during its existance.

Overrides:
getNumEnqueued in class UnbiasedQueue
Returns:
how many objects have been queued.

getAvgInQueueAtEnqueue

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

Overrides:
getAvgInQueueAtEnqueue in class UnbiasedQueue
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()
Return the total number of objects which have been dequeued from this queue during its existance.

Overrides:
getNumDequeued in class UnbiasedQueue
Returns:
how many objects have been queued.

getAvgInQueueAtDequeue

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

Overrides:
getAvgInQueueAtDequeue in class UnbiasedQueue
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()
Return the total number of objects which have been dropped by this queue during its existance.

Overrides:
getNumDropped in class UnbiasedQueue
Returns:
how many objects have been dropped.

JXTA J2SE