com.jthreadkit.fifo
Interface ObjectFIFO

All Superinterfaces:

AccessibleLock, BasicFIFO, SimpleShutdown, SizeMonitored, TimedOutExceptionOption

All Known Implementing Classes:

AbstractObjectFIFO, MultiArrayObjectFIFO, ArrayObjectFIFO

public interface ObjectFIFO

extends BasicFIFO

Used to store object references in a First-In-First-Out queue that is thread-safe and supports inter-thread signaling. Some implementations have a fixed capacity that can only be changed by calls to SizeMonitored.setCapacity(int). On fixed queue size implementations attempts to add to a full queue block until another thread removes one or more entries. Similarly, attempts to remove entries from an empty queue block until a different thread comes along and adds more.

To allow for easy switching of implementations of this interface, it should be generally used like this:

ObjectFIFO fifo = new ArrayObjectFIFO(35);

where the reference type is the interface type not the implementing class' type. This allows us to switch in a different implementation of ObjectFIFO without having to change any code but the constructor.

There are several methods that take the int parameters atLeast and/or atMost. Unless otherwise stated, these values are silently coerced to make this true:

0 <= atLeast <= atMost <= getCapacity()

First atLeast is silently increased or decreased to fit into the range:

0 <= atLeast <= getCapacity()

and then atMost is silently increased or decreased to fit into the range:

atLeast <= atMost <= getCapacity()

You need to check the return values of these methods to see what actually happened.

InterruptedException - can be thrown from many of the methods in this class. If one thread is blocked inside one of these methods and another thread interrupts it, InterruptedException is thrown by the blocked thread.

TimedOutException - can be thrown from many of the methods in this class only if the "use TimedOutException" option is set. If true is passed to the setUseTimedOutException() method, the option is set and TimedOutException will be thrown from methods that timeout when the specified timeout period expires. If false is passed, the option is unset and TimedOutException will never be thrown. The TimedOutExceptionOption.isUseTimedOutExceptionSet() method returns true if the option is set and TimedOutException's will be thrown. TimedOutException is a subclass of RuntimeException so there is no need for a try-catch block if the option is not set. This option allows you to determine whether or not a timeout is an exceptional condition in your context (a condition that should result in an exception being thrown). If timeouts are routine, you probably will want to leave this option in its default unset state. See the class description of TimedOutException for more information.

ShutdownException - can be thrown from many of the methods in this class. This exception is not thrown by methods until the SimpleShutdown.shutdown() method is called. If shutdown() is never called, this exception will never be thrown and can be safely ignored. ShutdownException is a subclass of RuntimeException so there is no need for a try-catch block if shutdown() won't be called. After shutdown() is called, any threads that are currently blocked waiting will immediately throw this exception. In addition, any future calls to methods that would either result in waiting or would alter the object cause this exception to be thrown (if no waiting is needed because the condition is already met, this exception will not be thrown). See the class description of ShutdownException for more information.

Method Summary

void	add(Object obj) Adds the specified object to the FIFO.
boolean	add(Object obj, long msTimeout) Adds the specified object to the FIFO.
void	addEach(Object[] list) Adds each of the objects in the array to the FIFO as individual elements.
void	addEach(Object[] list, int offset, int length) Adds some of the objects in the array to the FIFO as individual elements starting at the specifed offset and continuing for length elements.
int	addEach(Object[] list, int offset, int length, long msTimeout) Adds some of the objects in the array to the FIFO as individual elements starting at the specifed offset and continuing for length elements.
int	addEach(Object[] list, long msTimeout) Adds each of the objects in the array to the FIFO as individual elements.
Class	getElementType() Returns the type of items that can be stored in this FIFO.
Object	peek() Returns the next item that will be removed--without removing it from the FIFO.
Object[]	peek(int atLeast, int atMost) The same as remove(int, int) except that the items are not removed from the FIFO.
Object[]	peek(int atLeast, int atMost, long msTimeout) The same as remove(int, int, long) except that the items are not removed from the FIFO.
Object	peek(long msTimeout) Returns the next item that will be removed--without removing it from the FIFO.
int	peek(Object[] dest, int offset, int atLeast, int atMost) The same as remove(Object[], int, int, int) except that the items are not removed from the FIFO.
int	peek(Object[] dest, int offset, int atLeast, int atMost, long msTimeout) The same as remove(Object[], int, int, int, long) except that the items are not removed from the FIFO.
Object[]	peekAll() Returns a copy of everything currently in the FIFO (without removing the items).
Object[]	peekAtLeastOne() Waits until at least one item is in the FIFO and then returns all of the items (without removing them).
Object[]	peekAtLeastOne(long msTimeout) Waits until at least one item is in the FIFO and then returns all of the items (without removing them).
Object	remove() Removes one item from the FIFO.
Object[]	remove(int atLeast, int atMost) Wait until atLeast items are available and then remove up to atMost items from the FIFO.
Object[]	remove(int atLeast, int atMost, long msTimeout) Wait until atLeast items are available and then remove up to atMost items from the FIFO.
Object	remove(long msTimeout) Removes one item from the FIFO.
int	remove(Object[] dest, int offset, int atLeast, int atMost) Wait until atLeast items are available and then remove up to atMost items from the FIFO.
int	remove(Object[] dest, int offset, int atLeast, int atMost, long msTimeout) Wait until atLeast items are available and then remove up to atMost items from the FIFO.
Object[]	removeAll() Removes all the the items currently in the FIFO without blocking.
Object[]	removeAtLeastOne() Waits until at least one item is in the FIFO and then removes and returns all of the items.
Object[]	removeAtLeastOne(long msTimeout) Waits until at least one item is in the FIFO and then removes and returns all of the items.
void	setElementType(Class newType) Specifies a restriction on the type of objects than can be stored in this FIFO.

Methods inherited from interface com.jthreadkit.fifo.BasicFIFO

skip, skip, skipExactly, skipExactly

Methods inherited from interface com.jthreadkit.SizeMonitored

addSizeChangeListener, getCapacity, getSize, isEmpty, isFull, removeSizeChangeListener, setCapacity, shutdownWhenEmpty, waitForSizeToChange, waitForSizeToChange, waitForSizeToClimbTo, waitForSizeToClimbTo, waitForSizeToFallTo, waitForSizeToFallTo, waitUntilEmpty, waitUntilEmpty, waitUntilFull, waitUntilFull, waitUntilSizeInRange, waitUntilSizeInRange, waitUntilSizeIs, waitUntilSizeIs, waitWhileEmpty, waitWhileEmpty, waitWhileFull, waitWhileFull, waitWhileSizeInRange, waitWhileSizeInRange, waitWhileSizeIs, waitWhileSizeIs

Methods inherited from interface com.jthreadkit.AccessibleLock

getLockObject

Methods inherited from interface com.jthreadkit.SimpleShutdown

shutdown

Methods inherited from interface com.jthreadkit.TimedOutExceptionOption

isUseTimedOutExceptionSet, setUseTimedOutException

Method Detail

setElementType

public void setElementType(Class newType)
                    throws ClassCastException,
                           ShutdownException

Specifies a restriction on the type of objects than can be stored in this FIFO. By default this is Object.class and any reference can be stored, but sometimes you might want to restrict what can be put in.

Note: This is a somewhat expensive operation in most implementations and should be used sparingly.

Parameters:

newType - the class to restrict entries to.

Throws:

ClassCastException - if any of the elements already in the FIFO can't be cast into the specified type. This exception won't be thrown on empty queues. If this exception is thrown, the element type reverts back to what it was before and the FIFO is in the same (non-corrupted) state that it was before the request.

ShutdownException - see explanation.

getElementType

public Class getElementType()

Returns the type of items that can be stored in this FIFO. See setElementType(java.lang.Class).

add

public boolean add(Object obj,
                   long msTimeout)
            throws InterruptedException,
                   TimedOutException,
                   ShutdownException,
                   ClassCastException

Adds the specified object to the FIFO. If any exception is thrown, the item will not be added and the FIFO will remain coherent (will not be corrupted).

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

ClassCastException - if the passed object can't be cast into the type specified. See getElementType().

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

add

public void add(Object obj)
         throws InterruptedException,
                ShutdownException,
                ClassCastException

Adds the specified object to the FIFO. If any exception is thrown, the item will not be added and the FIFO will remain coherent (will not be corrupted).

Throws:

ClassCastException - if the passed object can't be cast into the type specified. See getElementType().

InterruptedException - see explanation.

ShutdownException - see explanation.

addEach

public int addEach(Object[] list,
                   long msTimeout)
            throws InterruptedException,
                   TimedOutException,
                   ShutdownException,
                   ClassCastException

Adds each of the objects in the array to the FIFO as individual elements.

WARNING: If any exception is thrown, an indeterminate number of elements may have been added. The FIFO will remain coherent (will not be corrupted), but you have to examine it to find out exactly what portion (if any) of the list was successfully added before the exception.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the number of elements from the list that were actually added (this might be less than the total if a timeout occurred).

Throws:

ClassCastException - if the one of the objects can't be cast into the type specified. See getElementType().

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

addEach

public void addEach(Object[] list)
             throws InterruptedException,
                    ShutdownException,
                    ClassCastException

Adds each of the objects in the array to the FIFO as individual elements.

WARNING: If any exception is thrown, an indeterminate number of elements may have been added. The FIFO will remain coherent (will not be corrupted), but you have to examine it to find out exactly what portion (if any) of the list was successfully added before the exception.

Throws:

ClassCastException - if the one of the objects can't be cast into the type specified. See getElementType().

InterruptedException - see explanation.

ShutdownException - see explanation.

addEach

public int addEach(Object[] list,
                   int offset,
                   int length,
                   long msTimeout)
            throws InterruptedException,
                   TimedOutException,
                   ShutdownException,
                   ClassCastException

Adds some of the objects in the array to the FIFO as individual elements starting at the specifed offset and continuing for length elements.

WARNING: If any exception is thrown, an indeterminate number of elements may have been added. The FIFO will remain coherent (will not be corrupted), but you have to examine it to find out exactly what portion (if any) of the list was successfully added before the exception.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the number of elements from the list that were actually added (this might be less than length if a timeout occurred).

Throws:

ClassCastException - if the one of the objects can't be cast into the type specified. See getElementType().

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

addEach

public void addEach(Object[] list,
                    int offset,
                    int length)
             throws InterruptedException,
                    ShutdownException,
                    ClassCastException

Adds some of the objects in the array to the FIFO as individual elements starting at the specifed offset and continuing for length elements.

WARNING: If any exception is thrown, an indeterminate number of elements may have been added. The FIFO will remain coherent (will not be corrupted), but you have to examine it to find out exactly what portion (if any) of the list was successfully added before the exception.

Throws:

ClassCastException - if the one of the objects can't be cast into the type specified. See getElementType().

InterruptedException - see explanation.

ShutdownException - see explanation.

remove

public Object remove(long msTimeout)
              throws InterruptedException,
                     TimedOutException,
                     ShutdownException

Removes one item from the FIFO.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted).

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the object removed, or null if there was a timeout. Caution: null can be validly entered into the FIFO, so in that case, we can't tell if a timeout occurred or if the null returned was actually removed from the queue!

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

remove

public Object remove()
              throws InterruptedException,
                     ShutdownException

Removes one item from the FIFO.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted).

Returns:

the object removed.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

peek

public Object peek(long msTimeout)
            throws InterruptedException,
                   TimedOutException,
                   ShutdownException

Returns the next item that will be removed--without removing it from the FIFO.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the next object, or null if there was a timeout. Caution: null can be validly entered into the FIFO, so in that case, we can't tell if a timeout occurred or if the null returned was actually from the queue!

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

peek

public Object peek()
            throws InterruptedException,
                   ShutdownException

Returns the next item that will be removed--without removing it from the FIFO.

Returns:

the next object.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

remove

public int remove(Object[] dest,
                  int offset,
                  int atLeast,
                  int atMost,
                  long msTimeout)
           throws InterruptedException,
                  TimedOutException,
                  ShutdownException,
                  ClassCastException

Wait until atLeast items are available and then remove up to atMost items from the FIFO. Load these items into the specified array dest starting at the specified offset.

The values for atLeast and atMost may be silently coerced into this range:

0 <= atLeast <= atMost <= getCapacity()

See this explanation for more details.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted). It is possible that a portion of the destination array is overwritten, but this partial information should be ignored.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the number of items actually removed. This will be zero on a timeout. Under some circumstances, it can be less than atLeast see explanation

Throws:

ClassCastException - if the one of the stored objects can't be cast into the type of the dest array.

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

remove

public int remove(Object[] dest,
                  int offset,
                  int atLeast,
                  int atMost)
           throws InterruptedException,
                  ShutdownException,
                  ClassCastException

Wait until atLeast items are available and then remove up to atMost items from the FIFO. Load these items into the specified array dest starting at the specified offset.

The values for atLeast and atMost may be silently coerced into this range:

0 <= atLeast <= atMost <= getCapacity()

See this explanation for more details.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted). It is possible that a portion of the destination array is overwritten, but this partial information should be ignored.

Returns:

the number of items actually removed. Under some circumstances, it can be less than atLeast see explanation

Throws:

ClassCastException - if the one of the stored objects can't be cast into the type of the dest array.

InterruptedException - see explanation.

ShutdownException - see explanation.

peek

public int peek(Object[] dest,
                int offset,
                int atLeast,
                int atMost,
                long msTimeout)
         throws InterruptedException,
                TimedOutException,
                ShutdownException,
                ClassCastException

The same as remove(Object[], int, int, int, long) except that the items are not removed from the FIFO.

peek

public int peek(Object[] dest,
                int offset,
                int atLeast,
                int atMost)
         throws InterruptedException,
                ShutdownException,
                ClassCastException

The same as remove(Object[], int, int, int) except that the items are not removed from the FIFO.

remove

public Object[] remove(int atLeast,
                       int atMost,
                       long msTimeout)
                throws InterruptedException,
                       TimedOutException,
                       ShutdownException

Wait until atLeast items are available and then remove up to atMost items from the FIFO.

The values for atLeast and atMost may be silently coerced into this range:

0 <= atLeast <= atMost <= getCapacity()

See this explanation for more details.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted).

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the items removed, or a zero-length array if a timeout occurred. Under some circumstances, it can be less than atLeast see explanation

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

remove

public Object[] remove(int atLeast,
                       int atMost)
                throws InterruptedException,
                       ShutdownException

Wait until atLeast items are available and then remove up to atMost items from the FIFO.

The values for atLeast and atMost may be silently coerced into this range:

0 <= atLeast <= atMost <= getCapacity()

See this explanation for more details.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted).

Returns:

the items removed. Under some circumstances, it can be less than atLeast see explanation

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

peek

public Object[] peek(int atLeast,
                     int atMost,
                     long msTimeout)
              throws InterruptedException,
                     TimedOutException,
                     ShutdownException

The same as remove(int, int, long) except that the items are not removed from the FIFO.

peek

public Object[] peek(int atLeast,
                     int atMost)
              throws InterruptedException,
                     ShutdownException

The same as remove(int, int) except that the items are not removed from the FIFO.

removeAll

public Object[] removeAll()
                   throws ShutdownException

Removes all the the items currently in the FIFO without blocking. If the FIFO is empty, a zero-length array is returned.

Throws:

ShutdownException - see explanation.

peekAll

public Object[] peekAll()

Returns a copy of everything currently in the FIFO (without removing the items). If the FIFO is empty, a zero-length array is immediately returned (no blocking).

removeAtLeastOne

public Object[] removeAtLeastOne(long msTimeout)
                          throws InterruptedException,
                                 TimedOutException,
                                 ShutdownException

Waits until at least one item is in the FIFO and then removes and returns all of the items.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted).

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the items removed, or a zero-length array if a timeout occurred.

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

removeAtLeastOne

public Object[] removeAtLeastOne()
                          throws InterruptedException,
                                 ShutdownException

Waits until at least one item is in the FIFO and then removes and returns all of the items.

If any exception is thrown, the contents of the FIFO are not altered and the FIFO remains coherent (not corrupted).

Returns:

the items removed.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

peekAtLeastOne

public Object[] peekAtLeastOne(long msTimeout)
                        throws InterruptedException,
                               TimedOutException,
                               ShutdownException

Waits until at least one item is in the FIFO and then returns all of the items (without removing them).

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

the items removed, or a zero-length array if a timeout occurred.

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

peekAtLeastOne

public Object[] peekAtLeastOne()
                        throws InterruptedException,
                               ShutdownException

Waits until at least one item is in the FIFO and then returns all of the items (without removing them).

Returns:

the items removed.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.