001         package com.croftsoft.core.util.queue;
002    
003         /*********************************************************************
004         * An interface for queues.
005         *
006         * @author
007         *   <a href="https://www.croftsoft.com/">David Wallace Croft</a>
008         * @version
009         *   2003-06-18
010         * @since
011         *   1998-11-23
012         *********************************************************************/
013    
014         public interface  Queue
015         //////////////////////////////////////////////////////////////////////
016         //////////////////////////////////////////////////////////////////////
017         {
018    
019         /*********************************************************************
020         * Appends the object to the queue and notifies any threads that
021         * are blocked in pull().
022         *
023         * @return
024         *
025         *   Returns true if the object could be added to the queue.
026         *********************************************************************/
027         public boolean  append ( Object  o );
028    
029         /*********************************************************************
030         * Poll this queue to see if an object is available, immediately
031         * removing one if so.  If the queue is empty, this method
032         * immediately returns null.
033         *
034         * @return
035         *   An object, if one was immediately available, otherwise null.
036         *********************************************************************/
037         public Object  poll ( );
038    
039         /*********************************************************************
040         * Remove the next object in this queue, blocking until one becomes
041         * available.
042         *
043         * @throws InterruptedException
044         *    If the wait is interrupted.
045         *********************************************************************/
046         public Object  pull ( )
047           throws InterruptedException;
048    
049         /*********************************************************************
050         * Remove the next object in this queue, blocking until one becomes
051         * available or the given timeout period expires.
052         *
053         * @param timeout
054         *
055         *   If positive, block for up to <I>timeout</I> milliseconds while
056         *   waiting for an object to be added to this queue.
057         *   If zero, block indefinitely.
058         *
059         * @return
060         *
061         *   An object, if one was available within the specified timeout
062         *   period, otherwise null.
063         *
064         * @throws IllegalArgumentException
065         *
066         *    If the value of the timeout argument is negative.
067         *
068         * @throws InterruptedException
069         *
070         *    If the timeout wait is interrupted.
071         *********************************************************************/
072         public Object  pull ( long  timeout )
073           throws InterruptedException;
074    
075         /*********************************************************************
076         * Replaces the first occurrence of any equal object in the queue.
077         * The new object is placed in the same queue order as the old.
078         * If the new object is unique, it is simply appended.
079         *
080         * @return
081         *
082         *   The old object, if available, otherwise null.
083         *
084         * @throws IndexOutOfBoundsException
085         *
086         *   If appending would cause the queue to exceed the maximum size.
087         *********************************************************************/
088         public Object  replace ( Object  o )
089           throws IndexOutOfBoundsException;
090    
091         //////////////////////////////////////////////////////////////////////
092         //////////////////////////////////////////////////////////////////////
093         }