Sink

All Known Subinterfaces:

Pipe

All Known Implementing Classes:

AbstractPipe, DefaultPipe, MultiCastSink
```
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.
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.

Author:

Berin Loritsch

Method Summary

Methods
Modifier and Type	Method and Description
`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
  - enqueue
```
void enqueue(java.lang.Object element)
             throws SinkException
```
    Enqueues the given element onto the Sink.
    
    Parameters:
    element - The elements to enqueue
    
    Throws:
    
    SinkFullException - Indicates that the sink is temporarily full.
    
    SinkClosedException - Indicates that the sink is no longer being serviced.
    
    SinkException
  - enqueue
```
void enqueue(java.lang.Object[] elements)
             throws SinkException
```
    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 SinkFullException or SinkClosedException is thrown, none of the elements will have been enqueued.
    
    Parameters:
    elements - The element array to enqueue
    
    Throws:
    
    SinkFullException - Indicates that the sink is temporarily full.
    
    SinkClosedException - Indicates that the sink is no longer being serviced.
    
    SinkException
  - tryEnqueue
```
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.
    
    Parameters:
    element - The element to attempt to enqueue
    
    Returns:
    true if successful, false if not.
  - prepareEnqueue
```
PreparedEnqueue prepareEnqueue(java.lang.Object[] elements)
                               throws SinkException
```
    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 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:
    
    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
    See Also:
    PreparedEnqueue
  - size
```
int size()
```
    Returns the number of elements waiting in this Sink.
    
    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

Interface Sink

Method Summary

Method Detail

enqueue

enqueue

tryEnqueue

prepareEnqueue

size