org.d_haven.event.impl
Class AbstractPipe

java.lang.Object
  extended by 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
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
AbstractPipe()
           
 
Method Summary
 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.