|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Sink
A Sink implements the end of a finite-length event queue where
elements are enqueued. 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(java.lang.Object element)
Enqueues the given element onto the Sink. |
void |
enqueue(java.lang.Object[] elements)
Given an array of elements, atomically enqueues all of the elements in the array. |
PreparedEnqueue |
prepareEnqueue(java.lang.Object[] elements)
Support for transactional enqueue. |
int |
size()
Returns the number of elements waiting in this Sink. |
boolean |
tryEnqueue(java.lang.Object element)
Tries to enqueue an event, but instead of throwing exceptions, it returns a boolean value of whether the attempt was successful. |
Method Detail |
---|
void enqueue(java.lang.Object element) throws SinkException
element
- The elements to enqueue
SinkFullException
- Indicates that the sink is temporarily full.
SinkClosedException
- Indicates that the sink is no longer being serviced.
SinkException
void enqueue(java.lang.Object[] 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
boolean tryEnqueue(java.lang.Object element)
element
- The element to attempt to enqueue
true
if successful, false
if
not.PreparedEnqueue prepareEnqueue(java.lang.Object[] 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 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 Sinks.
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.
elements
- The element array to provisionally enqueue
PreparedEnqueue
that may be used to commit
or abort the provisional 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
PreparedEnqueue
int size()
Important: The contract for this method was updated to account for any elements that were prepared for enqueueing. It provides a more predictable and consistent environment, as well as making it easier for EnqueuePredicates to account for those elements.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |