org.apache.avalon.excalibur.event
Interface Source

All Known Subinterfaces:

Queue

public interface Source

A Source implements the end of a finite-length event queue where QueueElements are enqueued. These operations can throw a SourceException if the sink is closed or becomes full, allowing event queues to support thresholding and backpressure.

Author:

Berin Loritsch

Method Summary

int	canAccept() Returns the number of QueueElements it can currently accept.
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.
boolean	isFull() Returns true if this sink has reached its threshold; false otherwise.
int	maxSize() Returns the length threshold of the sink.
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.

Method Detail

enqueue

public void enqueue(QueueElement element)
             throws SourceException

Enqueues the given element onto the queue.

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.

enqueue

public void enqueue(QueueElement[] elements)
             throws SourceException

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.

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.

tryEnqueue

public 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.

Parameters:

element - The element to attempt to enqueue

Returns:

true if successful, false if not.

prepareEnqueue

public PreparedEnqueue prepareEnqueue(QueueElement[] elements)
                               throws SourceException

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.

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

size

public int size()

Returns the number of elements waiting in this queue.

maxSize

public int maxSize()

Returns the length threshold of the sink. This is for informational purposes only; an implementation may allow more (or fewer) new entries to be enqueued than maxSize() - size(). This may be the case, for example, if the sink implements some form of dynamic thresholding, and does not always accurately report maxSize().

Returns:

-1 if the sink has no length threshold.

isFull

public boolean isFull()

Returns true if this sink has reached its threshold; false otherwise. Like maxSize(), this is also informational, and isFull() returning false does not guarantee that future enqueue operations will succeed. Clearly, isFull() returning true does not guarantee that they will fail, since the queue may be serviced in the meantime.

canAccept

public int canAccept()

Returns the number of QueueElements it can currently accept. This is typically the difference between size() and maxSize(). It will return -1 if the queue is unbounded.