org.d_haven.event.impl

Class AbstractPipe

java.lang.Object

org.d_haven.event.impl.AbstractPipe

All Implemented Interfaces:

Pipe, Sink, Source

Direct Known Subclasses:

DefaultPipe

public abstract class AbstractPipe
extends java.lang.Object
implements Pipe

Provides the base functionality for the other Pipe types.

Author:

Berin Loritsch, Leo Sutic

Field Summary

Fields

Modifier and Type	Field and Description
protected DequeueInterceptor	m_interceptor The DequeueInterceptor used.
protected java.lang.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.

Constructor Summary

Constructors

Constructor and Description
AbstractPipe()

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.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.
java.lang.Object[]	dequeue(int num) Dequeues at most num available elements.
java.lang.Object[]	dequeueAll() Dequeues all available elements.
protected abstract java.lang.Object	doDequeue() Abstract method to allow child classes to only focus on the part necessary to dequeue one event.
protected abstract java.lang.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 java.lang.Object[]	doDequeueAll() Abstract method to allow child classes to only focus on the part necessary to dequeue the remaining events.
protected abstract void	doEnqueue(java.lang.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(java.lang.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(java.lang.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(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.
DequeueInterceptor	getDequeueInterceptor() Return the dequeue executable for this sink.
EnqueuePredicate	getEnqueuePredicate() Return the EnqueuePredicate that is already set for this Pipe.
PreparedEnqueue	prepareEnqueue(java.lang.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(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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.d_haven.event.Source

size

Methods inherited from interface org.d_haven.event.Sink

size

Field Detail

m_timeout

protected long m_timeout

The number of milliseconds to wait.

m_lock

protected java.lang.Object m_lock

The lock used to delay entries.

m_predicate

protected EnqueuePredicate m_predicate

The EnqueuePredicate used.

m_interceptor

protected DequeueInterceptor m_interceptor

The DequeueInterceptor used.

Constructor Detail

AbstractPipe

public AbstractPipe()

Method Detail

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.

Specified by:

setTimeout in interface Source

Parameters:

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

setEnqueuePredicate

public void setEnqueuePredicate(EnqueuePredicate predicate)

Set the EnqueuePredicate to limit entries into this Pipe.

Specified by:

setEnqueuePredicate in interface Pipe

Parameters:

predicate - the predicate to begin using

getEnqueuePredicate

public EnqueuePredicate getEnqueuePredicate()

Return the EnqueuePredicate that is already set for this Pipe.

Specified by:

getEnqueuePredicate in interface Pipe

Returns:

the current EnqueuePredicate

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

Specified by:

setDequeueInterceptor in interface Pipe

Parameters:

executable - The dequeue executable for this sink.

Since:

Sep 23, 2002

getDequeueInterceptor

public DequeueInterceptor getDequeueInterceptor()

Return the dequeue executable for this sink.

Specified by:

getDequeueInterceptor in interface Pipe

Returns:

DequeueInterceptor The dequeue executable for this sink.

Since:

Sep 23, 2002

dequeue

public java.lang.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.

Specified by:

dequeue in interface Source

Returns:

the next queue element on the Source

doDequeue

protected abstract java.lang.Object doDequeue()

Abstract method to allow child classes to only focus on the part necessary to dequeue one event.

Returns:

the next event

dequeueAll

public java.lang.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.

Specified by:

dequeueAll in interface Source

Returns:

all pending elements on the Source

doDequeueAll

protected abstract java.lang.Object[] doDequeueAll()

Abstract method to allow child classes to only focus on the part necessary to dequeue the remaining events.

Returns:

the remaining events

dequeue

public java.lang.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.

Specified by:

dequeue in interface Source

Parameters:

num - The maximum number of elements to dequeue

Returns:

At most num elements from the Source

doDequeue

protected abstract java.lang.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

enqueue

public void enqueue(java.lang.Object element)
             throws SinkException

Enqueues the given element onto the Sink.

Specified by:

enqueue in interface 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

doEnqueue

protected abstract void doEnqueue(java.lang.Object element)
                           throws SinkException

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.

enqueue

public 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.

Specified by:

enqueue in interface Sink

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

doEnqueue

protected abstract void doEnqueue(java.lang.Object[] elements)
                           throws SinkException

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.

tryEnqueue

public 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.

Specified by:

tryEnqueue in interface Sink

Parameters:

element - The element to attempt to enqueue

Returns:

true if successful, false if not.

prepareEnqueue

public 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.

Specified by:

prepareEnqueue in interface Sink

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

doPrepareEnqueue

protected abstract PreparedEnqueue doPrepareEnqueue(java.lang.Object[] elements)
                                             throws SinkException

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.