org.d_haven.event.impl

Class AbstractPipe

public abstract class AbstractPipe extends Object implements Pipe

Provides the base functionality for the other Pipe types.

Author: Berin Loritsch Leo Sutic

Field Summary
protected DequeueInterceptorm_interceptor
The DequeueInterceptor used.
protected Objectm_lock
The lock used to delay entries.
protected EnqueuePredicatem_predicate
The EnqueuePredicate used.
protected longm_timeout
The number of milliseconds to wait.
Method Summary
Objectdequeue()
Dequeues the next element, or null if there is nothing left on the queue or in case of a timeout while attempting to obtain the mutex.
Object[]dequeue(int num)
Dequeues at most num available elements.
Object[]dequeueAll()
Dequeues all available elements.
protected abstract ObjectdoDequeue()
Abstract method to allow child classes to only focus on the part necessary to dequeue one event.
protected abstract Object[]doDequeue(int num)
Abstract method to allow child classes to only focus on the part necessary to dequeue the supplied number of events.
protected abstract Object[]doDequeueAll()
Abstract method to allow child classes to only focus on the part necessary to dequeue the remaining events.
protected abstract voiddoEnqueue(Object element)
Abstract method provided to allow the child classes to focus only on the portion of code needed to enqueue one event.
protected abstract voiddoEnqueue(Object[] elements)
Abstract method provided to allow the child classes to focus only on the portion of code needed to enqueue the supplied events.
protected abstract PreparedEnqueuedoPrepareEnqueue(Object[] elements)
Abstract method provided to allow the child classes to focus only on the portion of code needed to do a prepared enqueue for the supplied events.
voidenqueue(Object element)
Enqueues the given element onto the Sink.
voidenqueue(Object[] elements)
Given an array of elements, atomically enqueues all of the elements in the array.
DequeueInterceptorgetDequeueInterceptor()
Return the dequeue executable for this sink.
EnqueuePredicategetEnqueuePredicate()
Return the EnqueuePredicate that is already set for this Pipe.
PreparedEnqueueprepareEnqueue(Object[] elements)
Support for transactional enqueue.
voidsetDequeueInterceptor(DequeueInterceptor executable)
Set the dequeue executable for this sink.
voidsetEnqueuePredicate(EnqueuePredicate predicate)
Set the EnqueuePredicate to limit entries into this Pipe.
voidsetTimeout(long millis)
Set the timeout for the Pipe in milliseconds.
booleantryEnqueue(Object element)
Tries to enqueue an event, but instead of throwing exceptions, it returns a boolean value of whether the attempt was successful.

Field Detail

m_interceptor

protected DequeueInterceptor m_interceptor
The DequeueInterceptor used.

m_lock

protected Object m_lock
The lock used to delay entries.

m_predicate

protected EnqueuePredicate m_predicate
The EnqueuePredicate used.

m_timeout

protected long m_timeout
The number of milliseconds to wait.

Method Detail

dequeue

public Object dequeue()
Dequeues the next element, or null if there is nothing left on the queue or in case of a timeout while attempting to obtain the mutex.

Returns: the next queue element on the Source

dequeue

public Object[] dequeue(int num)
Dequeues at most num available elements. Returns a zero-sized array in case of a timeout while attempting to obtain the mutex or if there is nothing left on the Source.

Parameters: num The maximum number of elements to dequeue

Returns: At most num elements from the Source

dequeueAll

public Object[] dequeueAll()
Dequeues all available elements. Returns a zero-sized array in case of a timeout while attempting to obtain the mutex or if there is nothing left on the Source.

Returns: all pending elements on the Source

doDequeue

protected abstract Object doDequeue()
Abstract method to allow child classes to only focus on the part necessary to dequeue one event.

Returns: the next event

doDequeue

protected abstract Object[] doDequeue(int num)
Abstract method to allow child classes to only focus on the part necessary to dequeue the supplied number of events.

Parameters: num the number of elements to dequeue

Returns: the next "num" events

doDequeueAll

protected abstract Object[] doDequeueAll()
Abstract method to allow child classes to only focus on the part necessary to dequeue the remaining events.

Returns: the remaining events

doEnqueue

protected abstract void doEnqueue(Object element)
Abstract method provided to allow the child classes to focus only on the portion of code needed to enqueue one event.

Parameters: element the event to enqueue

Throws: SinkException if there is a problem beyond the initial validation.

doEnqueue

protected abstract void doEnqueue(Object[] elements)
Abstract method provided to allow the child classes to focus only on the portion of code needed to enqueue the supplied events.

Parameters: elements the events to enqueue

Throws: SinkException if there is a problem beyond the initial validation.

doPrepareEnqueue

protected abstract PreparedEnqueue doPrepareEnqueue(Object[] elements)
Abstract method provided to allow the child classes to focus only on the portion of code needed to do a prepared enqueue for the supplied events.

Parameters: elements the events to enqueue

Returns: the PreparedEnqueue object

Throws: SinkException if there is a problem beyond the initial validation.

enqueue

public void enqueue(Object element)
Enqueues the given element onto the Sink.

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.

enqueue

public void enqueue(Object[] elements)
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: 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.

getDequeueInterceptor

public DequeueInterceptor getDequeueInterceptor()
Return the dequeue executable for this sink.

Returns: DequeueInterceptor The dequeue executable for this sink.

Since: Sep 23, 2002

getEnqueuePredicate

public EnqueuePredicate getEnqueuePredicate()
Return the EnqueuePredicate that is already set for this Pipe.

Returns: the current EnqueuePredicate

prepareEnqueue

public PreparedEnqueue prepareEnqueue(Object[] elements)
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: 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

setDequeueInterceptor

public void setDequeueInterceptor(DequeueInterceptor executable)
Set the dequeue executable for this sink. This mechanism allows users to define a methods that will be executed before or after dequeuing elements from a source

Parameters: executable The dequeue executable for this sink.

Since: Sep 23, 2002

setEnqueuePredicate

public void setEnqueuePredicate(EnqueuePredicate predicate)
Set the EnqueuePredicate to limit entries into this Pipe.

Parameters: predicate the predicate to begin using

setTimeout

public void setTimeout(long millis)
Set the timeout for the Pipe in milliseconds. The default timeout is 0, which means that we don't wait at all.

Parameters: millis The number of milliseconds to block waiting for events to be enqueued

tryEnqueue

public 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 element to attempt to enqueue

Returns: true if successful, false if not.