com.jthreadkit
Interface SizeMonitored

All Superinterfaces:

AccessibleLock, SimpleShutdown, TimedOutExceptionOption

All Known Subinterfaces:

BasicFIFO, ObjectFIFO, SizeMonitoredCollection, SizeMonitoredList, SizeMonitoredMap, SizeMonitoredSet, SizeMonitoredSortedMap, SizeMonitoredSortedSet

All Known Implementing Classes:

AbstractSizeMonitored, WrappedSizeMonitoredMap, WrappedSizeMonitoredSortedMap, WrappedSizeMonitoredCollection, WrappedSizeMonitoredList, WrappedSizeMonitoredSet, WrappedSizeMonitoredSortedSet

public interface SizeMonitored

extends AccessibleLock, SimpleShutdown, TimedOutExceptionOption

The SizeMonitored interface is widely used throughout JThreadKit. It is used to keep tabs on the current "size" of something --for example the number of elements in a List or a FIFO queue. One thread can be waiting for the size to change while another thread does the changing.

Unless otherwise noted, all methods are internally synchronized (using synchronized blocks of code) on the Object returned by the getLockObject() method specified by the AccessibleLock interface to control concurrency. Implementors of this interface must guarantee this synchronization behavior!

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	addSizeChangeListener(SizeChangeListener listener) Adds a new SizeChangeListener for notification when the size changes.
int	getCapacity() Returns the maximum size possible.
int	getSize() Returns the current size.
boolean	isEmpty() Returns true if the size is currently zero.
boolean	isFull() Returns true if the size is equal to the value returned from getCapacity().
boolean	removeSizeChangeListener(SizeChangeListener listener) Removes the specified SizeChangeListener so that it is no longer notified of size changes.
int	setCapacity(int requestedCapacity) Requests that the capacity be grown or reduced.
boolean	shutdownWhenEmpty(long msTimeout) Waits until isEmpty() is true and then proceeds to automatically invoke SimpleShutdown.shutdown().
void	waitForSizeToChange() Waits for the size to change.
boolean	waitForSizeToChange(long msTimeout) Waits (up to the specified amount of time) for the size to change.
void	waitForSizeToClimbTo(int atLeast) Waits for the size to meet or exceed to the specified value.
boolean	waitForSizeToClimbTo(int atLeast, long msTimeout) Waits (up to the specified amount of time) for the size to meet or exceed to the specified value.
void	waitForSizeToFallTo(int atMost) Waits for the size to match or drop below to the specified value.
boolean	waitForSizeToFallTo(int atMost, long msTimeout) Waits (up to the specified amount of time) for the size to match or drop below to the specified value.
void	waitUntilEmpty() Waits for the size to drop to zero.
boolean	waitUntilEmpty(long msTimeout) Waits (up to the specified amount of time) for the size to drop to zero.
void	waitUntilFull() Waits for the size to climb to the capacity.
boolean	waitUntilFull(long msTimeout) Waits (up to the specified amount of time) for the size to climb to the capacity.
void	waitUntilSizeInRange(int min, int max) Waits until the size is in the inclusive range specified.
boolean	waitUntilSizeInRange(int min, int max, long msTimeout) Waits (up to the specified amount of time) until the size is in the inclusive range specified.
void	waitUntilSizeIs(int target) Waits until the size matches the passed target value.
boolean	waitUntilSizeIs(int target, long msTimeout) Waits (up to the specified amount of time) until the size matches the passed target value.
void	waitWhileEmpty() Waits while the size is zero.
boolean	waitWhileEmpty(long msTimeout) Waits (up to the specified amount of time) while the size is zero.
void	waitWhileFull() Waits while the size is equal to the capacity.
boolean	waitWhileFull(long msTimeout) Waits (up to the specified amount of time) while the size is equal to the capacity.
void	waitWhileSizeInRange(int min, int max) Waits while the size is in the inclusive range specified.
boolean	waitWhileSizeInRange(int min, int max, long msTimeout) Waits (up to the specified amount of time) while the size is in the inclusive range specified.
void	waitWhileSizeIs(int target) Waits while the size matches the passed target value.
boolean	waitWhileSizeIs(int target, long msTimeout) Waits (up to the specified amount of time) while the size matches the passed target value.

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

setCapacity

public int setCapacity(int requestedCapacity)
                throws ShutdownException

Requests that the capacity be grown or reduced. If the requested new capacity is less than 1, it is silently increased to 1. If the requested new capacity is less than the current value returned from getSize(), it is silently increased to match the current size. The actual new capacity is returned. If the implementing class has (virtually) infinite capacity, then all calls made to this method are effectively ignored and Integer.MAX_VALUE is returned for the "new" capacity. The implementation of this method will typically be an expensive operation, so calls to setCapacity should be used sparingly.

To trim the capacity down to the current size--but only down to a minimum of 1, use:

int newCapacity = x.setCapacity(0);

Parameters:

requestedCapacity - the desired new capacity. This number is silently increased to minimum of 1 and/or the value returned from getSize() if necessary.

Returns:

the actual new capacity--may be larger than the requested capacity.

Throws:

ShutdownException - see explanation.

getCapacity

public int getCapacity()

Returns the maximum size possible. Returns Integer.MAX_VALUE if there is no maximum.

Returns:

the maximum size.

See Also:

setCapacity(int), getSize()

getSize

public int getSize()

Returns the current size.

Returns:

the current size.

isEmpty

public boolean isEmpty()

Returns true if the size is currently zero.

isFull

public boolean isFull()

Returns true if the size is equal to the value returned from getCapacity().

waitUntilEmpty

public boolean waitUntilEmpty(long msTimeout)
                       throws InterruptedException,
                              TimedOutException,
                              ShutdownException

Waits (up to the specified amount of time) for the size to drop to zero.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilEmpty

public void waitUntilEmpty()
                    throws InterruptedException,
                           ShutdownException

Waits for the size to drop to zero.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileEmpty

public boolean waitWhileEmpty(long msTimeout)
                       throws InterruptedException,
                              TimedOutException,
                              ShutdownException

Waits (up to the specified amount of time) while the size is zero.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitWhileEmpty

public void waitWhileEmpty()
                    throws InterruptedException,
                           ShutdownException

Waits while the size is zero.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilFull

public boolean waitUntilFull(long msTimeout)
                      throws InterruptedException,
                             TimedOutException,
                             ShutdownException

Waits (up to the specified amount of time) for the size to climb to the capacity.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilFull

public void waitUntilFull()
                   throws InterruptedException,
                          ShutdownException

Waits for the size to climb to the capacity.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileFull

public boolean waitWhileFull(long msTimeout)
                      throws InterruptedException,
                             TimedOutException,
                             ShutdownException

Waits (up to the specified amount of time) while the size is equal to the capacity.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitWhileFull

public void waitWhileFull()
                   throws InterruptedException,
                          ShutdownException

Waits while the size is equal to the capacity.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForSizeToClimbTo

public boolean waitForSizeToClimbTo(int atLeast,
                                    long msTimeout)
                             throws InterruptedException,
                                    TimedOutException,
                                    ShutdownException

Waits (up to the specified amount of time) for the size to meet or exceed to the specified value.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitForSizeToClimbTo

public void waitForSizeToClimbTo(int atLeast)
                          throws InterruptedException,
                                 ShutdownException

Waits for the size to meet or exceed to the specified value.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForSizeToFallTo

public boolean waitForSizeToFallTo(int atMost,
                                   long msTimeout)
                            throws InterruptedException,
                                   TimedOutException,
                                   ShutdownException

Waits (up to the specified amount of time) for the size to match or drop below to the specified value.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitForSizeToFallTo

public void waitForSizeToFallTo(int atMost)
                         throws InterruptedException,
                                ShutdownException

Waits for the size to match or drop below to the specified value.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForSizeToChange

public boolean waitForSizeToChange(long msTimeout)
                            throws InterruptedException,
                                   TimedOutException,
                                   ShutdownException

Waits (up to the specified amount of time) for the size to change.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitForSizeToChange

public void waitForSizeToChange()
                         throws InterruptedException,
                                ShutdownException

Waits for the size to change.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileSizeInRange

public boolean waitWhileSizeInRange(int min,
                                    int max,
                                    long msTimeout)
                             throws InterruptedException,
                                    TimedOutException,
                                    ShutdownException

Waits (up to the specified amount of time) while the size is in the inclusive range specified.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitWhileSizeInRange

public void waitWhileSizeInRange(int min,
                                 int max)
                          throws InterruptedException,
                                 ShutdownException

Waits while the size is in the inclusive range specified.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilSizeInRange

public boolean waitUntilSizeInRange(int min,
                                    int max,
                                    long msTimeout)
                             throws InterruptedException,
                                    TimedOutException,
                                    ShutdownException

Waits (up to the specified amount of time) until the size is in the inclusive range specified.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilSizeInRange

public void waitUntilSizeInRange(int min,
                                 int max)
                          throws InterruptedException,
                                 ShutdownException

Waits until the size is in the inclusive range specified.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileSizeIs

public boolean waitWhileSizeIs(int target,
                               long msTimeout)
                        throws InterruptedException,
                               TimedOutException,
                               ShutdownException

Waits (up to the specified amount of time) while the size matches the passed target value.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitWhileSizeIs

public void waitWhileSizeIs(int target)
                     throws InterruptedException,
                            ShutdownException

Waits while the size matches the passed target value.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilSizeIs

public boolean waitUntilSizeIs(int target,
                               long msTimeout)
                        throws InterruptedException,
                               TimedOutException,
                               ShutdownException

Waits (up to the specified amount of time) until the size matches the passed target value.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilSizeIs

public void waitUntilSizeIs(int target)
                     throws InterruptedException,
                            ShutdownException

Waits until the size matches the passed target value.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

shutdownWhenEmpty

public boolean shutdownWhenEmpty(long msTimeout)
                          throws InterruptedException,
                                 TimedOutException,
                                 ShutdownException

Waits until isEmpty() is true and then proceeds to automatically invoke SimpleShutdown.shutdown(). Calls block until empty or only until the specified timeout elapses. Once the size gets down to zero, a full shutdown occurs resulting in a ShutdownException being thrown by any methods that modify the object or wait for it to be modified.

Parameters:

msTimeout - the maximum amount of time to wait for empty.

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:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

addSizeChangeListener

public void addSizeChangeListener(SizeChangeListener listener)
                           throws UnsupportedOperationException

Adds a new SizeChangeListener for notification when the size changes. Requests to add duplicate listeners are silently ignored. See SizeChangeListener for more information.

Implementations that don't support this feature throw UnsupportedOperationException. However, many implementations do support it, and because this exception is a subclass of RuntimeException, a try-catch block is not required.

Throws:

UnsupportedOperationException - if the implementation does not support size listeners.

removeSizeChangeListener

public boolean removeSizeChangeListener(SizeChangeListener listener)
                                 throws UnsupportedOperationException

Removes the specified SizeChangeListener so that it is no longer notified of size changes.

Implementations that don't support this feature throw UnsupportedOperationException. However, many implementations do support it, and because this exception is a subclass of RuntimeException, a try-catch block is not required.

Throws:

UnsupportedOperationException - if the implementation does not support size listeners.