com.jthreadkit
Class AbstractSizeMonitored

java.lang.Object
  |
  +--com.jthreadkit.AbstractSizeMonitored

All Implemented Interfaces:

AccessibleLock, SimpleShutdown, SizeMonitored, TimedOutExceptionOption

Direct Known Subclasses:

AbstractFIFO, WrappedSizeMonitoredCollection, WrappedSizeMonitoredMap

public abstract class AbstractSizeMonitored

extends Object

implements SizeMonitored

An abstract class that partially implements SizeMonitored. In many cases, this is a useful class to extend instead of directly implementing all of the methods on SizeMonitored directly.

Unless otherwise noted, all methods use synchronized blocks internally on lock which can be retrieved via getLockObject(), to allow external code to prevent interleaving between method calls.

Method Summary

void	addSizeChangeListener(SizeChangeListener listener) See addSizeChangeListener on SizeMonitored for the full spec.
int	getCapacity() Returns the maximum size possible.
Object	getLockObject() Returns the reference to the object that is synchronized on by other methods in the implementing class.
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	isUseTimedOutExceptionSet() Used to determine whether or not TimedOutException will be thrown by methods when timout periods expire.
boolean	removeSizeChangeListener(SizeChangeListener listener) See addSizeChangeListener on SizeMonitored for the full spec.
int	setCapacity(int requestedCapacity) See SizeMonitored.setCapacity(int) for full spec.
void	setUseTimedOutException(boolean useException) Used to change the timeout behavior of methods on the implementing classes.
void	shutdown() A full shutdown is immediately initiated resulting in a ShutdownException being thrown by any methods that modify the object or wait for it to be modified.
boolean	shutdownWhenEmpty(long msTimeout) Waits until isEmpty() is true and then proceeds to automatically invoke 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 class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getLockObject

public Object getLockObject()

Description copied from interface: AccessibleLock

Returns the reference to the object that is synchronized on by other methods in the implementing class. This reference is not permitted to change after construction, so this method can be called once and the reference saved.

This reference can be used in synchronized blocks to keep other threads from sneaking in between methods calls like this:

obj = //... synchronized ( obj.getLockObject() ) { obj.methodA(); obj.methodB(); }

Specified by:

getLockObject in interface AccessibleLock

Following copied from interface: com.jthreadkit.AccessibleLock

Returns:

the object used to lock on to control concurrent access.

setUseTimedOutException

public void setUseTimedOutException(boolean useException)
                             throws ShutdownException

Description copied from interface: TimedOutExceptionOption

Used to change the timeout behavior of methods on the implementing classes. If this option is set to true methods will throw a TimedOutException when the specified timeout period expires. If this option is not set, methods usually signal a timeout through a return value. Use isUseTimedOutExceptionSet() to check the current setting.

Specified by:

setUseTimedOutException in interface TimedOutExceptionOption

Following copied from interface: com.jthreadkit.TimedOutExceptionOption

Parameters:

useException - if true is passed then TimedOutException will be thrown after timeouts, if false is passed, timeouts do not result in exceptions.

Throws:

ShutdownException - if this object has already been shutdown.

isUseTimedOutExceptionSet

public boolean isUseTimedOutExceptionSet()

Description copied from interface: TimedOutExceptionOption

Used to determine whether or not TimedOutException will be thrown by methods when timout periods expire. The setUseTimedOutException() method is used to change this setting.

Specified by:

isUseTimedOutExceptionSet in interface TimedOutExceptionOption

Following copied from interface: com.jthreadkit.TimedOutExceptionOption

Returns:

true if timeouts will result in exceptions being thrown, false otherwise.

setCapacity

public int setCapacity(int requestedCapacity)
                throws ShutdownException

See SizeMonitored.setCapacity(int) for full spec.

Internally, this implementation silently increases requestedCapacity if necessary (see spec) and sets the internal value returned by getCapacity(). The new capacity is returned. If the new capacity is different than the old capacity, a notifyAll() is issued on the lock object. Subclasses may choose to override this method if they need to do more--this should be done something like this:

public int setCapacity(int requestedCapacity) { synchronized ( lock ) { int oldCap = getCapacity(); int newCap = super.setCapacity(requestedCapacity); if ( newCap != oldCap ) { // do the additional stuff // ... } } }

Subclasses may also choose to override this method because they don't allow the capacity to be changed--this should be done something like this:

public int setCapacity(int requestedCapacity) { return getCapacity(); }

Specified by:

setCapacity in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Parameters:

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

Returns:

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

Throws:

ShutdownException - see explanation.

getCapacity

public int getCapacity()

Description copied from interface: SizeMonitored

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

Specified by:

getCapacity in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Returns:

the maximum size.

See Also:

SizeMonitored.setCapacity(int), SizeMonitored.getSize()

getSize

public int getSize()

Description copied from interface: SizeMonitored

Returns the current size.

Specified by:

getSize in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Returns:

the current size.

isEmpty

public boolean isEmpty()

Description copied from interface: SizeMonitored

Returns true if the size is currently zero.

Specified by:

isEmpty in interface SizeMonitored

isFull

public boolean isFull()

Description copied from interface: SizeMonitored

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

Specified by:

isFull in interface SizeMonitored

waitUntilEmpty

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

Description copied from interface: SizeMonitored

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

Specified by:

waitUntilEmpty in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits for the size to drop to zero.

Specified by:

waitUntilEmpty in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileEmpty

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

Description copied from interface: SizeMonitored

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

Specified by:

waitWhileEmpty in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits while the size is zero.

Specified by:

waitWhileEmpty in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilFull

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

Description copied from interface: SizeMonitored

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

Specified by:

waitUntilFull in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits for the size to climb to the capacity.

Specified by:

waitUntilFull in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileFull

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

Description copied from interface: SizeMonitored

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

Specified by:

waitWhileFull in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits while the size is equal to the capacity.

Specified by:

waitWhileFull in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForSizeToClimbTo

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

Description copied from interface: SizeMonitored

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

Specified by:

waitForSizeToClimbTo in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

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

Specified by:

waitForSizeToClimbTo in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForSizeToFallTo

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

Description copied from interface: SizeMonitored

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

Specified by:

waitForSizeToFallTo in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

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

Specified by:

waitForSizeToFallTo in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForSizeToChange

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

Description copied from interface: SizeMonitored

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

Specified by:

waitForSizeToChange in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits for the size to change.

Specified by:

waitForSizeToChange in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileSizeInRange

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

Description copied from interface: SizeMonitored

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

Specified by:

waitWhileSizeInRange in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits while the size is in the inclusive range specified.

Specified by:

waitWhileSizeInRange in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilSizeInRange

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

Description copied from interface: SizeMonitored

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

Specified by:

waitUntilSizeInRange in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits until the size is in the inclusive range specified.

Specified by:

waitUntilSizeInRange in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitWhileSizeIs

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

Description copied from interface: SizeMonitored

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

Specified by:

waitWhileSizeIs in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits while the size matches the passed target value.

Specified by:

waitWhileSizeIs in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilSizeIs

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

Description copied from interface: SizeMonitored

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

Specified by:

waitUntilSizeIs in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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

Description copied from interface: SizeMonitored

Waits until the size matches the passed target value.

Specified by:

waitUntilSizeIs in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

shutdownWhenEmpty

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

Description copied from interface: SizeMonitored

Waits until SizeMonitored.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.

Specified by:

shutdownWhenEmpty in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

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.

shutdown

public void shutdown()

Description copied from interface: SimpleShutdown

A full shutdown is immediately initiated resulting in a ShutdownException being thrown by any methods that modify the object or wait for it to be modified. See this explanation for more.

Specified by:

shutdown in interface SimpleShutdown

addSizeChangeListener

public void addSizeChangeListener(SizeChangeListener listener)

See addSizeChangeListener on SizeMonitored for the full spec. This implementation fully supports this option and does not throw UnsupportedOperationException.

Specified by:

addSizeChangeListener in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

UnsupportedOperationException - if the implementation does not support size listeners.

removeSizeChangeListener

public boolean removeSizeChangeListener(SizeChangeListener listener)

See addSizeChangeListener on SizeMonitored for the full spec. This implementation fully supports this option and does not throw UnsupportedOperationException.

Specified by:

removeSizeChangeListener in interface SizeMonitored

Following copied from interface: com.jthreadkit.SizeMonitored

Throws:

UnsupportedOperationException - if the implementation does not support size listeners.