org.apache.excalibur.event.impl
Class MultiCastSink

java.lang.Object
  extended byorg.apache.excalibur.event.impl.MultiCastSink
All Implemented Interfaces:
Sink

public class MultiCastSink
extends java.lang.Object
implements Sink

This is a org.apache.excalibur.event.seda.event.Sink implementation that multicasts enqueue operations to the contained and concrete sink objects. The multi cast sink will try to enqueue and only succeeds if no element was rejected from any sink. The sink can be configured to enqueue into one sink alone or all sinks. If a sink array in the collection of sinks contains more than one sink the multicast sink will try to enqueue the element always to only one of these sinks.

Version:
$Revision: 1.4 $
Author:
Avalon Development Team

Field Summary
 
Fields inherited from interface org.apache.excalibur.event.Sink
ROLE
 
Constructor Summary
MultiCastSink(java.util.Collection sinks)
          This constructor creates a failure in-tolerant multicast sink based on the collection of sink arrays.
MultiCastSink(java.util.Collection sinks, boolean single)
          This constructor creates a failure in-tolerant multicast sink based on the collection of sink arrays.
 
Method Summary
 int canAccept()
          Returns the number of elements it can currently accept.
 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.
 boolean isFull()
          Returns true if this sink has reached its threshold; false otherwise.
 int maxSize()
          Returns the length threshold of the sink.
 PreparedEnqueue prepareEnqueue(java.lang.Object[] elements)
          Support for transactional enqueue.
 int size()
          Returns the number of elements waiting in this Sink.
 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
 

Constructor Detail

MultiCastSink

public MultiCastSink(java.util.Collection sinks)
This constructor creates a failure in-tolerant multicast sink based on the collection of sink arrays. The delivery must succeed for all sinks in the collection or it will fail entirely.

Parameters:
sinks - A collection of sink arrays for each stage.
Since:
May 16, 2002

MultiCastSink

public MultiCastSink(java.util.Collection sinks,
                     boolean single)
This constructor creates a failure in-tolerant multicast sink based on the collection of sink arrays.

Parameters:
sinks - A collection of sink arrays for each stage.
single - true if just one operation must succeed. false if all operations must succeed.
Since:
May 16, 2002
Method Detail

canAccept

public int canAccept()
Description copied from interface: Sink
Returns the number of elements it can currently accept. This is typically the difference between size() and maxSize(). It will return -1 if the sink is unbounded.

Specified by:
canAccept in interface Sink
Returns:
the number of elements the Sink can accept
See Also:
Sink.canAccept()

isFull

public boolean isFull()
Description copied from interface: Sink
Returns true if this sink has reached its threshold; false otherwise. Like maxSize(), this is also informational, and isFull() returning false does not guarantee that future enqueue operations will succeed. Clearly, isFull() returning true does not guarantee that they will fail, since the Sink may be serviced in the meantime.

Specified by:
isFull in interface Sink
Returns:
true if the Sink is full
See Also:
Sink.isFull()

maxSize

public int maxSize()
Description copied from interface: Sink
Returns the length threshold of the sink. This is for informational purposes only; an implementation may allow more (or fewer) new entries to be enqueued than maxSize() - size(). This may be the case, for example, if the sink implements some form of dynamic thresholding, and does not always accurately report maxSize().

Specified by:
maxSize in interface Sink
Returns:
-1 if the sink has no length threshold.
See Also:
Sink.maxSize()

enqueue

public void enqueue(java.lang.Object element)
             throws SinkException
Description copied from interface: Sink
Enqueues the given element onto the Sink.

Specified by:
enqueue in interface Sink
Parameters:
element - The elements to enqueue
Throws:
SinkException
See Also:
Sink.enqueue(Object)

enqueue

public void enqueue(java.lang.Object[] elements)
             throws SinkException
Description copied from interface: Sink
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:
SinkException
See Also:
Sink.enqueue(Object[])

tryEnqueue

public boolean tryEnqueue(java.lang.Object element)
Description copied from interface: Sink
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.
See Also:
Sink.tryEnqueue(Object)

prepareEnqueue

public PreparedEnqueue prepareEnqueue(java.lang.Object[] elements)
                               throws SinkException
Description copied from interface: Sink
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:
SinkException
See Also:
Sink.prepareEnqueue(Object[])

size

public int size()
Description copied from interface: Sink
Returns the number of elements waiting in this Sink.

Important: The contract for this method was updated to account for any elements that were prepared for enqueueing. It provides a more predictable and consistent environment, as well as making it easier for EnqueuePredicates to account for those elements.

Specified by:
size in interface Sink
Returns:
the number of elements in the Sink
See Also:
Sink.size()


Copyright © 1997-2005 The Apache Software Foundation. All Rights Reserved.