bloritsch 01/12/13 19:30:48
Modified: src/java/org/apache/avalon/excalibur/concurrent Lock.java
src/scratchpad/org/apache/avalon/excalibur/event Sink.java
Source.java
Added: src/scratchpad/org/apache/avalon/excalibur/event
BlockingQueue.java BlockingSink.java
EventDroppingQueue.java EventDroppingSource.java
PreparedEnqueue.java SourceClosedException.java
SourceException.java SourceFullException.java
TransactionalQueue.java TransactionalSource.java
Log:
Add more interfaces for the event queue
Revision Changes Path
1.4 +2 -1
jakarta-avalon-excalibur/src/java/org/apache/avalon/excalibur/concurrent/Lock.java
Index: Lock.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/src/java/org/apache/avalon/excalibur/concurrent/Lock.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Lock.java 2001/12/11 09:53:28 1.3
+++ Lock.java 2001/12/14 03:30:47 1.4
@@ -12,8 +12,9 @@
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
- * @version CVS $Revision: 1.3 $ $Date: 2001/12/11 09:53:28 $
+ * @version CVS $Revision: 1.4 $ $Date: 2001/12/14 03:30:47 $
* @since 4.0
+ * @deprecated use the Mutex class instead
*/
public class Lock
{
1.2 +17 -51
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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Sink.java 2001/12/13 22:17:50 1.1
+++ Sink.java 2001/12/14 03:30:47 1.2
@@ -8,74 +8,40 @@
package org.apache.avalon.excalibur.event;
/**
- * 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.
+ * A Sink implements the side of an event queue where QueueElements are
+ * dequeued operations only.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface Sink {
/**
- * Enqueues the given element onto the queue.
+ * Dequeues the next element, or returns <code>null</code> if there is
+ * nothing left on the queue.
*
- * @param element The <code>QueueElementIF</code> to enqueue
- * @exception SinkFullException Indicates that the sink is temporarily
full.
- * @exception SinkClosedException Indicates that the sink is
- * no longer being serviced.
+ * @return the next <code>QueueElement</code> on the queue
*/
- public void enqueue(QueueElement element)
- throws Exception;
+ public QueueElement dequeue();
/**
- * 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.
+ * Dequeues all available elements, or returns <code>null</code> if there
is
+ * nothing left on the queue.
*
- * @param elements The element array to enqueue
- * @exception SinkFullException Indicates that the sink is temporarily
full.
- * @exception SinkClosedException Indicates that the sink is
- * no longer being serviced.
- *
- */
- public void enqueue(QueueElement[] elements)
- throws Exception;
-
- /**
- * Returns the number of elements waiting in this queue.
+ * @return all pending <code>QueueElement</code>s on the queue
*/
- public int size();
+ public QueueElement[] dequeueAll();
-
/**
- * 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().
+ * Dequeues at most <code>num</code> available elements, or returns
+ * <code>null</code> if there is nothing left on the queue.
*
- * @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.
+ * @return At most <code>num</code> <code>QueueElement</code>s on the queue
*/
- public boolean isFull();
+ public QueueElement[] dequeue(int num);
/**
- * 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.
+ * Returns the number of elements waiting in this queue.
*/
- public int canAccept();
+ public int size();
-}
\ No newline at end of file
+}
1.2 +51 -17
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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Source.java 2001/12/13 22:17:50 1.1
+++ Source.java 2001/12/14 03:30:47 1.2
@@ -8,40 +8,74 @@
package org.apache.avalon.excalibur.event;
/**
- * A Source implements the side of an event queue where QueueElements are
- * dequeued operations only.
+ * 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.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface Source {
/**
- * Dequeues the next element, or returns <code>null</code> if there is
- * nothing left on the queue.
+ * Enqueues the given element onto the queue.
*
- * @return the next <code>QueueElement</code> on 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 QueueElement dequeue();
+ public boolean enqueue(QueueElement element)
+ throws SourceException;
/**
- * Dequeues all available elements, 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 SourceFullException or SourceClosedException is thrown, none of
+ * the elements will have been enqueued.
*
- * @return all pending <code>QueueElement</code>s on the queue
+ * @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 QueueElement[] dequeueAll();
+ public int size();
+
/**
- * Dequeues at most <code>num</code> available elements, or returns
- * <code>null</code> if there is nothing left on the queue.
+ * 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 At most <code>num</code> <code>QueueElement</code>s on the queue
+ * @return -1 if the sink has no length threshold.
*/
- public QueueElement[] dequeue(int num);
+ public int maxSize();
/**
- * Returns the number of elements waiting in this queue.
+ * 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 int size();
+ 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();
-}
\ No newline at end of file
+}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/BlockingQueue.java
Index: BlockingQueue.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;
/**
* 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 BlockingQueue extends Queue, BlockingSink
{
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/BlockingSink.java
Index: BlockingSink.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;
/**
* A BlockingSink implements the side of an event queue where QueueElements
are
* dequeued operations only.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface BlockingSink {
/**
* 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(int millis);
/**
* 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(int millis);
/**
* 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, int millis);
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/EventDroppingQueue.java
Index: EventDroppingQueue.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;
/**
* 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 EventDroppingQueue extends Queue, EventDroppingSource
{
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/EventDroppingSource.java
Index: EventDroppingSource.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;
/**
* 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.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface EventDroppingSource extends Source {
/**
* Enqueues the given element onto the queue.
*
* This is lossy in that this method drops the element if the element
* could not be enqueued, rather than throwing a SourceFullException or
* SourceClosedException. This is meant as a convenience interface for
* "low priority" enqueue events which can be safely dropped.
*
* @param element The <code>QueueElementIF</code> to enqueue
* @return true if the element was enqueued, false otherwise.
*
*/
public boolean enqueue(QueueElement element);
/**
* Enqueues the given element onto the queue.
*
* This is lossy in that this method drops the element if the element
* could not be enqueued, rather than throwing a SourceFullException or
* SourceClosedException. This is meant as a convenience interface for
* "low priority" enqueue events which can be safely dropped.
*
* @param element The <code>QueueElementIF</code> to enqueue
* @return true if the element was enqueued, false otherwise.
*
*/
public boolean enqueue(QueueElement[] elements);
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/PreparedEnqueue.java
Index: PreparedEnqueue.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;
/**
* A <code>PreparedEnqueue</code> is an object returned from a
* <code>prepareEnqueue</code> method that allows you to either
* commit or abort the enqueue operation.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface PreparedEnqueue {
/**
* Commit a previously prepared provisional enqueue operation (from
* the <code>prepareEnqueue</code> method). Causes the provisionally
* enqueued elements to appear on the queue for future dequeue operations.
* Note that once a <code>prepareEnqueue</code> has returned an enqueue
* key, the queue cannot reject the entries.
*/
public void commit();
/**
* Abort a previously prepared provisional enqueue operation (from
* the <code>prepareEnqueue</code> method). Causes the queue to discard
* the provisionally enqueued elements.
*/
public void abort();
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/SourceClosedException.java
Index: SourceClosedException.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 SourceClosedException extends SourceException
{
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/SourceException.java
Index: SourceException.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 SourceException extends CascadingException
{
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/SourceFullException.java
Index: SourceFullException.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 SourceFullException extends SourceException
{
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/TransactionalQueue.java
Index: TransactionalQueue.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;
/**
* 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 TransactionalQueue extends Queue, TransactionalSource
{
}
1.1
jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/event/TransactionalSource.java
Index: TransactionalSource.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;
/**
* 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.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface TransactionalSource extends Source {
/**
* 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(QueueElementIF[] elements)
throws SourceException;
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
