org.apache.avalon.excalibur.event
Class FixedSizeQueue

java.lang.Object
  |
  +--org.apache.avalon.excalibur.event.AbstractQueue
        |
        +--org.apache.avalon.excalibur.event.FixedSizeQueue

All Implemented Interfaces:

Queue, Sink, Source

public final class FixedSizeQueue

extends AbstractQueue

The default queue implementation is a variabl 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

FixedSizeQueue(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

FixedSizeQueue

public FixedSizeQueue(int size)

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