org.d_haven.event.impl

Class AbstractPipe

public abstract class AbstractPipe extends Object implements Pipe

Provides the base functionality for the other Pipe types.

Field Summary
protected DequeueInterceptor	m_interceptor The DequeueInterceptor used.
protected Object	m_lock The lock used to delay entries.
protected EnqueuePredicate	m_predicate The EnqueuePredicate used.
protected long	m_timeout The number of milliseconds to wait.

Method Summary
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.
Object[]	dequeue(int num) Dequeues at most `num` available elements.
Object[]	dequeueAll() Dequeues all available elements.
protected abstract Object	doDequeue() 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 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.
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.
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.
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.
DequeueInterceptor	getDequeueInterceptor() Return the dequeue executable for this sink.
EnqueuePredicate	getEnqueuePredicate() Return the EnqueuePredicate that is already set for this Pipe.
PreparedEnqueue	prepareEnqueue(Object[] elements) Support for transactional enqueue.
void	setDequeueInterceptor(DequeueInterceptor executable) Set the dequeue executable for this sink.
void	setEnqueuePredicate(EnqueuePredicate predicate) Set the EnqueuePredicate to limit entries into this Pipe.
void	setTimeout(long millis) Set the timeout for the `Pipe` in milliseconds.
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.

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.

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.

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.