org.apache.avalon.excalibur.event
Class DefaultQueue

java.lang.Object
  |
  +--org.apache.avalon.excalibur.event.AbstractQueue
        |
        +--org.apache.avalon.excalibur.event.DefaultQueue
All Implemented Interfaces:
Queue, Sink, Source

public final class DefaultQueue
extends AbstractQueue

The default queue implementation is a variable size queue. This queue is ThreadSafe, however the overhead in synchronization costs a few extra millis.

Author:
Berin Loritsch

Fields inherited from class org.apache.avalon.excalibur.event.AbstractQueue
m_timeout
 
Constructor Summary
DefaultQueue()
           
DefaultQueue(int size)
           
 
Method Summary
 QueueElement dequeue()
          Dequeues the next element, or returns null if there is nothing left on the queue.
 QueueElement[] dequeue(int numElements)
          Dequeues at most num available elements, or returns null if there is nothing left on the queue.
 QueueElement[] dequeueAll()
          Dequeues all available elements, or returns null if there is nothing left on the queue.
 void enqueue(QueueElement element)
          Enqueues the given element onto the queue.
 void enqueue(QueueElement[] elements)
          Given an array of elements, atomically enqueues all of the elements in the array.
 int maxSize()
          Default maxSize to -1 which is unbounded
 PreparedEnqueue prepareEnqueue(QueueElement[] elements)
          Support for transactional enqueue.
 int size()
          Returns the number of elements waiting in this queue.
 boolean tryEnqueue(QueueElement element)
          Tries to enqueue an event, but instead of throwing exceptions, it returns a boolean value of whether the attempt was successful.
 
Methods inherited from class org.apache.avalon.excalibur.event.AbstractQueue
block, canAccept, isFull, setTimeout
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DefaultQueue

public DefaultQueue(int size)

DefaultQueue

public DefaultQueue()
Method Detail

size

public int size()
Description copied from interface: Source
Returns the number of elements waiting in this queue.

maxSize

public int maxSize()
Description copied from class: AbstractQueue
Default maxSize to -1 which is unbounded
Overrides:
maxSize in class AbstractQueue
Following copied from interface: org.apache.avalon.excalibur.event.Source
Returns:
-1 if the sink has no length threshold.

prepareEnqueue

public PreparedEnqueue prepareEnqueue(QueueElement[] elements)
                               throws SourceException
Description copied from interface: Source
Support for transactional enqueue.

This method allows a client to provisionally enqueue a number of elements onto the queue, and then later commit the enqueue (with a

commitEnqueue call), or abort (with an
 abortEnqueue call). This mechanism can be used to
 perform "split-phase" enqueues, where a client first enqueues a
 set of elements on the queue and then performs some work to "fill in"
 those elements before performing a commit. This can also be used
 to perform multi-queue transactional enqueue operations, with an
 "all-or-nothing" strategy for enqueueing events on multiple queues.

This method would generally be used in the following manner:

   PreparedEnqueue enqueue = sink.prepareEnqueue(someElements);
   if (canCommit) {
     enqueue.commit();
   } else {
     enqueue.abort();
   }
 

Note that this method does not protect against "dangling prepares" -- that is, a prepare without an associated commit or abort operation. This method should be used with care. In particular, be sure that all code paths (such as exceptions) after a prepare include either a commit or an abort.

Following copied from interface: org.apache.avalon.excalibur.event.Source
Parameters:
elements - The element array to provisionally enqueue
Returns:
A PreparedEnqueueThrows:
SourceFullException - Indicates that the sink is temporarily full and that the requested elements could not be provisionally enqueued.
SourceClosedException - Indicates that the sink is no longer being serviced.
See Also:
PreparedEnqueue

tryEnqueue

public boolean tryEnqueue(QueueElement element)
Description copied from interface: Source
Tries to enqueue an event, but instead of throwing exceptions, it returns a boolean value of whether the attempt was successful.
Following copied from interface: org.apache.avalon.excalibur.event.Source
Parameters:
element - The element to attempt to enqueue
Returns:
true if successful, false if not.

enqueue

public void enqueue(QueueElement[] elements)
             throws SourceException
Description copied from interface: Source
Given an array of elements, atomically enqueues all of the elements in the array. This guarantees that no other thread can interleave its own elements with those being inserted from this array. The implementation must enqueue all of the elements or none of them; if a SourceFullException or SourceClosedException is thrown, none of the elements will have been enqueued.
Following copied from interface: org.apache.avalon.excalibur.event.Source
Parameters:
elements - The element array to enqueue
Throws:
SourceFullException - Indicates that the sink is temporarily full.
SourceClosedException - Indicates that the sink is no longer being serviced.

enqueue

public void enqueue(QueueElement element)
             throws SourceException
Description copied from interface: Source
Enqueues the given element onto the queue.
Following copied from interface: org.apache.avalon.excalibur.event.Source
Parameters:
element - The QueueElement to enqueue
Throws:
SourceFullException - Indicates that the sink is temporarily full.
SourceClosedException - Indicates that the sink is no longer being serviced.

dequeue

public QueueElement[] dequeue(int numElements)
Description copied from interface: Sink
Dequeues at most num available elements, or returns null if there is nothing left on the queue.
Following copied from interface: org.apache.avalon.excalibur.event.Sink
Returns:
At most num QueueElements on the queue

dequeueAll

public QueueElement[] dequeueAll()
Description copied from interface: Sink
Dequeues all available elements, or returns null if there is nothing left on the queue.
Following copied from interface: org.apache.avalon.excalibur.event.Sink
Returns:
all pending QueueElements on the queue

dequeue

public QueueElement dequeue()
Description copied from interface: Sink
Dequeues the next element, or returns null if there is nothing left on the queue.
Following copied from interface: org.apache.avalon.excalibur.event.Sink
Returns:
the next QueueElement on the queue


Copyright 2001 Apache Jakarta Project. All Rights Reserved.