avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject 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
Date Fri, 14 Dec 2001 22:05:07 GMT
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:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message