You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by bl...@apache.org on 2001/12/14 23:05:07 UTC
cvs commit: jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event Sink.java Source.java BlockingQueue.java BlockingSink.java EventDroppingQueue.java EventDroppingSource.java TransactionalQueue.java TransactionalSource.java
bloritsch 01/12/14 14:05:07
Modified: src/scratchpad/org/apache/avalon/excalibur/event Sink.java
Source.java
Removed: src/scratchpad/org/apache/avalon/excalibur/event
BlockingQueue.java BlockingSink.java
EventDroppingQueue.java EventDroppingSource.java
TransactionalQueue.java TransactionalSource.java
Log:
Clean up queueing code
Revision Changes Path
1.3 +33 -25 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Sink.java 2001/12/14 03:30:47 1.2
+++ Sink.java 2001/12/14 22:05:07 1.3
@@ -14,34 +14,42 @@
* @author <a href="mailto:bloritsch@apache.org">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.
+ */
+ public void setTimeOut( long millis );
- /**
- * 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
- */
- public QueueElement dequeue();
+ /**
+ * 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
+ */
+ public QueueElement dequeue();
- /**
- * Dequeues all available elements, or returns <code>null</code> if there is
- * nothing left on the queue.
- *
- * @return all pending <code>QueueElement</code>s on the queue
- */
- public QueueElement[] dequeueAll();
+ /**
+ * Dequeues all available elements, or returns <code>null</code> if there is
+ * nothing left on the queue.
+ *
+ * @return all pending <code>QueueElement</code>s on the queue
+ */
+ public QueueElement[] dequeueAll();
- /**
- * Dequeues at most <code>num</code> available elements, or returns
- * <code>null</code> if there is nothing left on the queue.
- *
- * @return At most <code>num</code> <code>QueueElement</code>s on the queue
- */
- public QueueElement[] dequeue(int num);
+ /**
+ * Dequeues at most <code>num</code> available elements, or returns
+ * <code>null</code> if there is nothing left on the queue.
+ *
+ * @return At most <code>num</code> <code>QueueElement</code>s on the queue
+ */
+ public QueueElement[] dequeue(int num);
- /**
- * Returns the number of elements waiting in this queue.
- */
- public int size();
+ /**
+ * Returns the number of elements waiting in this queue.
+ */
+ public int size();
}
1.3 +112 -60 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Source.java 2001/12/14 03:30:47 1.2
+++ Source.java 2001/12/14 22:05:07 1.3
@@ -17,65 +17,117 @@
*/
public interface Source {
- /**
- * Enqueues the given element onto the queue.
- *
- * @param element The <code>QueueElementIF</code> to enqueue
- * @exception SourceFullException Indicates that the sink is temporarily full.
- * @exception SourceClosedException Indicates that the sink is
- * no longer being serviced.
- */
- public boolean enqueue(QueueElement element)
- throws SourceException;
-
- /**
- * 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.
- *
- */
- public boolean enqueue(QueueElement[] elements)
- throws SourceException;
-
- /**
- * Returns the number of elements waiting in this queue.
- */
- public 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.
- */
- public 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.
- */
- public 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.
- */
- public int canAccept();
+ /**
+ * Enqueues the given element onto the queue.
+ *
+ * @param element The <code>QueueElementIF</code> to enqueue
+ * @exception SourceFullException Indicates that the sink is temporarily full.
+ * @exception SourceClosedException Indicates that the sink is
+ * no longer being serviced.
+ */
+ public void enqueue( QueueElement element )
+ throws SourceException;
+
+ /**
+ * 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.
+ *
+ */
+ public void enqueue( QueueElement[] elements )
+ throws SourceException;
+
+ /**
+ * Tries to enqueue an event, but instead of throwing exceptions, it returns
+ * a boolean value of whether the attempt was successful.
+ *
+ * @param element The element to attempt to enqueue
+ * @return <code>true</code> if successful, <code>false</code> if not.
+ */
+ public boolean tryEnqueue( QueueElement element );
+
+ /**
+ * 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>
+ *
+ * @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
+ */
+ public PreparedEnqueue prepareEnqueue( QueueElement[] elements )
+ throws SourceException;
+
+ /**
+ * Returns the number of elements waiting in this queue.
+ */
+ public 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.
+ */
+ public 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.
+ */
+ public 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.
+ */
+ public int canAccept();
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>