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 SinkClosedException.java SinkException.java SinkFullException.java Sink.java Source.java SourceClosedException.java SourceException.java SourceFullException.java
Date Mon, 04 Feb 2002 18:15:29 GMT
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: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.
  +     * 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:bloritsch@apache.org">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:bloritsch@apache.org">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:bloritsch@apache.org">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:bloritsch@apache.org">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:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message