bloritsch 02/02/04 10:15:29
Modified: src/scratchpad/org/apache/avalon/excalibur/event Sink.java
Source.java
Added: src/scratchpad/org/apache/avalon/excalibur/event
SinkClosedException.java SinkException.java
SinkFullException.java
Removed: src/scratchpad/org/apache/avalon/excalibur/event
SourceClosedException.java SourceException.java
SourceFullException.java
Log:
Change Source to Sink
Revision Changes Path
1.6 +98 -20
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/Sink.java
Index: Sink.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/Sink.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Sink.java 2 Jan 2002 12:03:00 -0000 1.5
+++ Sink.java 4 Feb 2002 18:15:29 -0000 1.6
@@ -8,48 +8,126 @@
package org.apache.avalon.excalibur.event;
/**
- * A Sink implements the side of an event queue where QueueElements are
- * dequeued operations only.
+ * A Sink implements the end of a finite-length event queue where
QueueElements
+ * are enqueued. These operations can throw a SinkException if the sink is
+ * closed or becomes full, allowing event queues to support thresholding and
+ * backpressure.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface Sink {
+
/**
- * Sets the timeout on a blocking Sink. Values above <code>1</code> will
- * force all <code>dequeue</code> operations to block for up to that
number
- * of milliseconds waiting for new elements. Values below <code>1</code>
- * will turn off blocking for Sink. This is intentional because a Sink
should
- * never block indefinitely.
+ * Enqueues the given element onto the queue.
+ *
+ * @param element The <code>QueueElement</code> to enqueue
+ * @throws SinkFullException Indicates that the sink is temporarily full.
+ * @throws SinkClosedException Indicates that the sink is
+ * no longer being serviced.
*/
- void setTimeout( long millis );
+ void enqueue( QueueElement element )
+ throws SinkException;
/**
- * Dequeues the next element, or returns <code>null</code> if there is
- * nothing left on the queue.
+ * 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.
+ *
+ * @param elements The element array to enqueue
+ * @throws SinkFullException Indicates that the sink is temporarily full.
+ * @throws SinkClosedException Indicates that the sink is
+ * no longer being serviced.
*
- * @return the next <code>QueueElement</code> on the queue
*/
- QueueElement dequeue();
+ void enqueue( QueueElement[] elements )
+ throws SinkException;
/**
- * Dequeues all available elements, or returns <code>null</code> if
there is
- * nothing left on the queue.
+ * Tries to enqueue an event, but instead of throwing exceptions, it
returns
+ * a boolean value of whether the attempt was successful.
*
- * @return all pending <code>QueueElement</code>s on the queue
+ * @param element The element to attempt to enqueue
+ * @return <code>true</code> if successful, <code>false</code> if not.
*/
- QueueElement[] dequeueAll();
+ boolean tryEnqueue( QueueElement element );
/**
- * Dequeues at most <code>num</code> available elements, or returns
- * <code>null</code> if there is nothing left on the queue.
+ * Support for transactional enqueue.
+ *
+ * <p>This method allows a client to provisionally enqueue a number
+ * of elements onto the queue, and then later commit the enqueue (with
+ * a <pre>commitEnqueue</code> call), or abort (with an
+ * <code>abortEnqueue</code> 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
queues.</p>
+ *
+ * <p>This method would generally be used in the following manner:</p>
+ * <pre>
+ * PreparedEnqueue enqueue = sink.prepareEnqueue(someElements);
+ * if (canCommit) {
+ * enqueue.commit();
+ * } else {
+ * enqueue.abort();
+ * }
+ * </pre>
*
- * @return At most <code>num</code> <code>QueueElement</code>s on the
queue
+ * <p> Note that this method does <strong>not</strong> 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.</p>
+ *
+ * @param elements The element array to provisionally enqueue
+ * @return A <code>PreparedEnqueue</code 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.
+ * @throws SinkClosedException Indicates that the sink is
+ * no longer being serviced.
+ *
+ * @see PreparedEnqueue
*/
- QueueElement[] dequeue(int num);
+ PreparedEnqueue prepareEnqueue( QueueElement[] elements )
+ throws SinkException;
/**
* Returns the number of elements waiting in this queue.
*/
int size();
+
+
+ /**
+ * 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().
+ *
+ * @return -1 if the sink has no length threshold.
+ */
+ int maxSize();
+
+ /**
+ * 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 queue may be serviced in the meantime.
+ */
+ boolean isFull();
+
+ /**
+ * Returns the number of QueueElements it can currently accept. This is
+ * typically the difference between <code>size()</code> and
+ * <code>maxSize()</code>. It will return -1 if the queue is unbounded.
+ */
+ int canAccept();
}
1.6 +21 -97
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/Source.java
Index: Source.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/Source.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Source.java 28 Dec 2001 12:18:29 -0000 1.5
+++ Source.java 4 Feb 2002 18:15:29 -0000 1.6
@@ -8,126 +8,50 @@
package org.apache.avalon.excalibur.event;
/**
- * A Source implements the end of a finite-length event queue where
QueueElements
- * are enqueued. These operations can throw a SourceException if the sink is
- * closed or becomes full, allowing event queues to support thresholding and
- * backpressure.
+ * A Source implements the side of an event queue where QueueElements are
+ * dequeued operations only.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface Source {
-
/**
- * Enqueues the given element onto the queue.
+ * Sets the timeout on a blocking Source. Values above <code>1</code>
will
+ * force all <code>dequeue</code> operations to block for up to that
number
+ * of milliseconds waiting for new elements. Values below <code>1</code>
+ * will turn off blocking for Source. This is intentional because a
Source
+ * should never block indefinitely.
*
- * @param element The <code>QueueElement</code> to enqueue
- * @exception SourceFullException Indicates that the sink is temporarily
full.
- * @exception SourceClosedException Indicates that the sink is
- * no longer being serviced.
+ * @param Number of milliseconds to block
*/
- void enqueue( QueueElement element )
- throws SourceException;
+ void setTimeout( long millis );
/**
- * 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 SourceFullException or SourceClosedException is thrown, none of
- * the elements will have been enqueued.
- *
- * @param elements The element array to enqueue
- * @exception SourceFullException Indicates that the sink is temporarily
full.
- * @exception SourceClosedException Indicates that the sink is
- * no longer being serviced.
+ * Dequeues the next element, or returns <code>null</code> if there is
+ * nothing left on the queue.
*
+ * @return the next <code>QueueElement</code> on the queue
*/
- void enqueue( QueueElement[] elements )
- throws SourceException;
+ QueueElement dequeue();
/**
- * Tries to enqueue an event, but instead of throwing exceptions, it
returns
- * a boolean value of whether the attempt was successful.
+ * Dequeues all available elements, or returns <code>null</code> if
there is
+ * nothing left on the queue.
*
- * @param element The element to attempt to enqueue
- * @return <code>true</code> if successful, <code>false</code> if not.
+ * @return all pending <code>QueueElement</code>s on the queue
*/
- boolean tryEnqueue( QueueElement element );
+ QueueElement[] dequeueAll();
/**
- * Support for transactional enqueue.
- *
- * <p>This method allows a client to provisionally enqueue a number
- * of elements onto the queue, and then later commit the enqueue (with
- * a <pre>commitEnqueue</code> call), or abort (with an
- * <code>abortEnqueue</code> 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
queues.</p>
- *
- * <p>This method would generally be used in the following manner:</p>
- * <pre>
- * PreparedEnqueue enqueue = sink.prepareEnqueue(someElements);
- * if (canCommit) {
- * enqueue.commit();
- * } else {
- * enqueue.abort();
- * }
- * </pre>
- *
- * <p> Note that this method does <strong>not</strong> 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.</p>
+ * Dequeues at most <code>num</code> available elements, or returns
+ * <code>null</code> if there is nothing left on the queue.
*
- * @param elements The element array to provisionally enqueue
- * @return A <code>PreparedEnqueue</code that may be used to commit or
abort
- * the provisional enqueue
- * @exception SourceFullException Indicates that the sink is temporarily
full
- * and that the requested elements could not be provisionally
- * enqueued.
- * @exception SourceClosedException Indicates that the sink is
- * no longer being serviced.
- *
- * @see PreparedEnqueue
+ * @return At most <code>num</code> <code>QueueElement</code>s on the
queue
*/
- PreparedEnqueue prepareEnqueue( QueueElement[] elements )
- throws SourceException;
+ QueueElement[] dequeue(int num);
/**
* Returns the number of elements waiting in this queue.
*/
int size();
-
-
- /**
- * 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().
- *
- * @return -1 if the sink has no length threshold.
- */
- int maxSize();
-
- /**
- * 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 queue may be serviced in the meantime.
- */
- boolean isFull();
-
- /**
- * Returns the number of QueueElements it can currently accept. This is
- * typically the difference between <code>size()</code> and
- * <code>maxSize()</code>. It will return -1 if the queue is unbounded.
- */
- int canAccept();
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/SinkClosedException.java
Index: SinkClosedException.java
===================================================================
/*
* Copyright (C) The Apache Software Foundation. All rights reserved.
*
* This software is published under the terms of the Apache Software License
* version 1.1, a copy of which has been included with this distribution in
* the LICENSE.txt file.
*/
package org.apache.avalon.excalibur.event;
import org.apache.avalon.framework.CascadingException;
/**
* A SinkClosedException is thrown when an enqueue operation occurs on a queue
* that is already closed.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public class SinkClosedException extends SinkException
{
public SinkClosedException( String message )
{
super( message );
}
public SinkClosedException( String message, Throwable e )
{
super( message, e );
}
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/SinkException.java
Index: SinkException.java
===================================================================
/*
* Copyright (C) The Apache Software Foundation. All rights reserved.
*
* This software is published under the terms of the Apache Software License
* version 1.1, a copy of which has been included with this distribution in
* the LICENSE.txt file.
*/
package org.apache.avalon.excalibur.event;
import org.apache.avalon.framework.CascadingException;
/**
* A SourceException is thrown when an enqueue operation fails.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public class SinkException extends CascadingException
{
public SinkException( String message )
{
super( message );
}
public SinkException( String message, Throwable e )
{
super( message, e );
}
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/SinkFullException.java
Index: SinkFullException.java
===================================================================
/*
* Copyright (C) The Apache Software Foundation. All rights reserved.
*
* This software is published under the terms of the Apache Software License
* version 1.1, a copy of which has been included with this distribution in
* the LICENSE.txt file.
*/
package org.apache.avalon.excalibur.event;
import org.apache.avalon.framework.CascadingException;
/**
* A SinkException is thrown when an enqueue operation occurs on a queue that
is
* already full.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public class SinkFullException extends SinkException
{
public SinkFullException( String message )
{
super( message );
}
public SinkFullException( String message, Throwable e )
{
super( message, e );
}
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
