org.d_haven.event
public interface Sink
SinkException
if the sink is closed or becomes full,
allowing event queues to support thresholding and backpressure.
The interface design is heavily influenced by Matt Welsh's SandStorm server,
his demonstration of the SEDA architecture. We have deviated where
we felt the design differences where better.
Method Summary | |
---|---|
void | enqueue(Object element)
Enqueues the given element onto the Sink.
|
void | enqueue(Object[] elements)
Given an array of elements, atomically enqueues all of the
elements in the array. |
PreparedEnqueue | prepareEnqueue(Object[] elements)
Support for transactional enqueue.
|
int | size()
Returns the number of elements waiting in this Sink.
|
boolean | tryEnqueue(Object 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 elements to enqueue
Throws: org.d_haven.event.SinkFullException Indicates that the sink is temporarily full. org.d_haven.event.SinkClosedException Indicates that the sink is no longer being serviced.
Parameters: elements The element array to enqueue
Throws: org.d_haven.event.SinkFullException Indicates that the sink is temporarily full. org.d_haven.event.SinkClosedException Indicates that the sink is no longer being serviced.
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.
Parameters: elements The element array to provisionally enqueue
Returns: A PreparedEnqueue
that may be used to commit
or abort the provisional enqueue
Throws: org.d_haven.event.SinkFullException Indicates that the sink is temporarily full and that the requested elements could not be provisionally enqueued. org.d_haven.event.SinkClosedException Indicates that the sink is no longer being serviced.
See Also: PreparedEnqueue
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.
Returns: the number of elements in the Sink
Parameters: element The element to attempt to enqueue
Returns: true
if successful, false
if
not.