|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface SinkIF
A SinkIF implements the 'sink' end of a finite-length event queue: it supports enqueue operations only. These operations can throw a SinkException if the sink is closed or becomes full, allowing event queues to support thresholding and backpressure.
Method Summary | |
---|---|
void |
enqueue_abort(java.lang.Object enqueue_key)
Abort a previously prepared provisional enqueue operation (from the enqueue_prepare() method). |
void |
enqueue_commit(java.lang.Object enqueue_key)
Commit a previously prepared provisional enqueue operation (from the enqueue_prepare() method). |
boolean |
enqueue_lossy(QueueElementIF element)
Enqueues the given element onto the queue. |
void |
enqueue_many(QueueElementIF[] elements)
Given an array of elements, atomically enqueues all of the elements in the array. |
java.lang.Object |
enqueue_prepare(QueueElementIF[] elements)
Support for transactional enqueue. |
void |
enqueue(QueueElementIF element)
Enqueues the given element onto the queue. |
EnqueuePredicateIF |
getEnqueuePredicate()
Return the enqueue predicate for this sink. |
void |
setEnqueuePredicate(EnqueuePredicateIF pred)
Set the enqueue predicate for this sink. |
int |
size()
Return the number of elements in this sink. |
Method Detail |
---|
void enqueue(QueueElementIF element) throws SinkException
element
- The QueueElementIF
to enqueue
SinkFullException
- Indicates that the sink is temporarily full.
SinkClosedException
- Indicates that the sink is
no longer being serviced.
SinkException
boolean enqueue_lossy(QueueElementIF element)
element
- The QueueElementIF
to enqueue
void enqueue_many(QueueElementIF[] elements) throws SinkException
elements
- The element array to enqueue
SinkFullException
- Indicates that the sink is temporarily full.
SinkClosedException
- Indicates that the sink is
no longer being serviced.
SinkException
java.lang.Object enqueue_prepare(QueueElementIF[] elements) throws SinkException
This method allows a client to provisionally enqueue a number of elements onto the queue, and then later commit the enqueue (with a enqueue_commit() call), or abort (with a enqueue_abort() 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:
Object key = sink.enqueue_prepare(someElements); if (can_commit) { sink.enqueue_commit(key); } else { sink.enqueue_abort(key); }
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.
Like enqueue_many, enqueue_prepare is an "all or none" operation: the enqueue predicate must accept all elements for enqueue, or none of them will be enqueued.
elements
- The element array to provisionally enqueue
SinkFullException
- Indicates that the sink is temporarily full
and that the requested elements could not be provisionally enqueued.
SinkClosedException
- Indicates that the sink is
no longer being serviced.
SinkException
enqueue_commit
,
enqueue_abort
void enqueue_commit(java.lang.Object enqueue_key)
key
- The enqueue key returned by a previous call to
enqueue_prepare().
java.lang.IllegalArgumentException
- Thrown if an unknown enqueue key
is provided.void enqueue_abort(java.lang.Object enqueue_key)
key
- The enqueue key returned by a previous call to
enqueue_prepare().
java.lang.IllegalArgumentException
- Thrown if an unknown enqueue key
is provided.void setEnqueuePredicate(EnqueuePredicateIF pred)
EnqueuePredicateIF getEnqueuePredicate()
int size()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |