seda.sandStorm.api
Interface SinkIF

All Known Subinterfaces:

DriverFilterIF, DriverIF, QueueIF

All Known Implementing Classes:

AFile, AFileImpl, AFileTPImpl, ATcpConnection, AUdpSocket, EventSink, FiniteQueue, GnutellaConnection, httpConnection, SimpleSink, SinkProxy

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

enqueue

void enqueue(QueueElementIF element)
             throws SinkException

Enqueues the given element onto the queue.

Parameters:

element - The QueueElementIF to enqueue

Throws:

SinkFullException - Indicates that the sink is temporarily full.

SinkClosedException - Indicates that the sink is no longer being serviced.

SinkException

enqueue_lossy

boolean enqueue_lossy(QueueElementIF element)

Enqueues the given element onto the queue. This is lossy in that this method drops the element if the element could not be enqueued, rather than throwing a SinkFullException or SinkClosedException. This is meant as a convenience interface for "low priority" enqueue events which can be safely dropped.

Parameters:

element - The QueueElementIF to enqueue

Returns:

true if the element was enqueued, false otherwise.

enqueue_many

void enqueue_many(QueueElementIF[] 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. This implies that the enqueue predicate (if any) must accept all elements in the array for the enqueue to proceed.

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

enqueue_prepare

java.lang.Object enqueue_prepare(QueueElementIF[] 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 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.

Parameters:

elements - The element array to provisionally enqueue

Returns:

A "transaction key" 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:

enqueue_commit, enqueue_abort

enqueue_commit

void enqueue_commit(java.lang.Object enqueue_key)

Commit a previously prepared provisional enqueue operation (from the enqueue_prepare() method). Causes the provisionally enqueued elements to appear on the queue for future dequeue operations. Note that once a enqueue_prepare() has returned an enqueue key, the queue cannot reject the entries.

Parameters:

key - The enqueue key returned by a previous call to enqueue_prepare().

Throws:

java.lang.IllegalArgumentException - Thrown if an unknown enqueue key is provided.

enqueue_abort

void enqueue_abort(java.lang.Object enqueue_key)

Abort a previously prepared provisional enqueue operation (from the enqueue_prepare() method). Causes the queue to discard the provisionally enqueued elements.

Parameters:

key - The enqueue key returned by a previous call to enqueue_prepare().

Throws:

java.lang.IllegalArgumentException - Thrown if an unknown enqueue key is provided.

setEnqueuePredicate

void setEnqueuePredicate(EnqueuePredicateIF pred)

Set the enqueue predicate for this sink. This mechanism allows user to define a method that will 'screen' QueueElementIF's during the enqueue procedure to either accept or reject them. The enqueue predicate runs in the context of the caller of enqueue(), which means it must be simple and fast. This can be used to implement many interesting queue-thresholding policies, such as simple count threshold, credit-based mechanisms, and more.

getEnqueuePredicate

EnqueuePredicateIF getEnqueuePredicate()

Return the enqueue predicate for this sink.

size

int size()

Return the number of elements in this sink.