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 }