001         package com.croftsoft.core.util.queue;
002    
003         import java.rmi.Remote;
004         import java.rmi.RemoteException;
005    
006         /*********************************************************************
007         *
008         * @author
009         *   <a href="http://www.CroftSoft.com/">David Wallace Croft</a>
010         * @version
011         *   1998-11-27
012         *********************************************************************/
013    
014         public interface  QueueRemote extends Remote
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         *   Returns true if the object could be added to the queue.
025         *********************************************************************/
026         public boolean  append ( Object  o )
027           throws RemoteException;
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           throws RemoteException;
039    
040         /*********************************************************************
041         * Remove the next object in this queue, blocking until one becomes
042         * available.
043         *
044         * @throws InterruptedException
045         *    If the wait is interrupted.
046         *********************************************************************/
047         public Object  pull ( ) throws InterruptedException,
048           RemoteException;
049    
050         /*********************************************************************
051         * Remove the next object in this queue, blocking until one becomes
052         * available or the given timeout period expires.
053         *
054         * @param timeout
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         *   An object, if one was available within the specified timeout
061         *   period, otherwise null.
062         *
063         * @throws IllegalArgumentException
064         *    If the value of the timeout argument is negative.
065         * @throws InterruptedException
066         *    If the timeout wait is interrupted.
067         *********************************************************************/
068         public Object  pull ( long  timeout )
069           throws IllegalArgumentException, InterruptedException,
070           RemoteException;
071    
072         /*********************************************************************
073         * Replaces the first occurrence of any equal object in the queue.
074         * The new object is placed in the same queue order as the old.
075         * If the new object is unique, calls add(o).
076         *
077         * @return
078         *   The old object, if available, otherwise null.
079         *********************************************************************/
080         public Object  replace ( Object  o )
081           throws RemoteException;
082    
083         //////////////////////////////////////////////////////////////////////
084         //////////////////////////////////////////////////////////////////////
085         }