net.sourceforge.groboutils.util.datastruct.v1
Class ObjectCache

java.lang.Object
  net.sourceforge.groboutils.util.datastruct.v1.ObjectCache

public class ObjectCache

extends java.lang.Object

An object cache which allows for objects to be added and removed. If the cache is empty when an object is requested, the object type is created and returned. There can be a maximum size specified for the pending object list - if an object is retrieved by the cache, and the list is beyond its size, then the object is thrown away. By default, the maximum size is unlimited.

If the cache should not create objects, then a ObjectCreator should not be given to the cache.

Alternatively, you can specify that the cache not create objects and instead wait for the objects to be retrieved.

Care has been taken to keep this synchronized across threads.

Since:

April 11, 2001 (0.9.0 Alpha)

Version:

$Date: 2003/05/23 20:55:43 $

Author:

Matt Albrecht groboclown@users.sourceforge.net

Nested Class Summary

static class	ObjectCache.DefaultObjectCreator A default object creator - given a Class object, it attempts to create a new Object using the default constructor.
static interface	ObjectCache.ObjectCreator An interface which needs to be implemented and given to the cache in order to create new instances.

Field Summary

static int

UNLIMITED_SIZE The size to use when you want to specify an unlimited cache size.

Constructor Summary

ObjectCache()
Create a new ObjectCache without an object creator.

ObjectCache(java.lang.Class creator)
Create a new ObjectCache.

ObjectCache(java.lang.Class creator, int maxSize)
Create a new ObjectCache.

ObjectCache(java.lang.Class creator, int maxSize, boolean fill)
Create a new ObjectCache.

ObjectCache(int maxSize)
Create a new ObjectCache without an object creator, and sets the maximum number of objects to keep waiting in the cache.

ObjectCache(ObjectCache.ObjectCreator creator)
Create a new ObjectCache.

ObjectCache(ObjectCache.ObjectCreator creator, int maxSize)
Create a new ObjectCache.

ObjectCache(ObjectCache.ObjectCreator creator, int maxSize, boolean fill)
Create a new ObjectCache.

Method Summary

void	addObject() Create a new object and put it into the cache.
protected java.lang.Object	createObject() Generates an Object for the cache.
void	fillCache() Fills the cache to its maximum.
java.lang.Object	get() Retrieves a cached element.
java.lang.Object	get(long millisWaitTime) Retrieves a cached element.
int	getMaxSize()
int	getOverflows() Retrieves the number of "overflows" encountered.
int	getUnderflows() Retrieves the number of "underflows" encountered.
void	putBack(java.lang.Object o) Adds an element to the end of the queue.
void	setClassCreator(java.lang.Class creator) Creates a new DefaultObjectCreator based on the given class.
void	setMaxSize(int size) Resets the internal maximum number of objects that the cache can hold.
void	setObjectCreator(ObjectCache.ObjectCreator creator) Sets the internal cache-underflow Object creator.

Methods inherited from class java.lang.Object

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

Field Detail

UNLIMITED_SIZE

public static final int UNLIMITED_SIZE

The size to use when you want to specify an unlimited cache size.

See Also:

Constant Field Values

Constructor Detail

ObjectCache

public ObjectCache()

Create a new ObjectCache without an object creator.

ObjectCache

public ObjectCache(int maxSize)

Create a new ObjectCache without an object creator, and sets the maximum number of objects to keep waiting in the cache.

ObjectCache

public ObjectCache(ObjectCache.ObjectCreator creator)

Create a new ObjectCache. This uses the given creator to create new objects for the cache.

ObjectCache

public ObjectCache(java.lang.Class creator)

Create a new ObjectCache. This uses the given Class to create new objects for the cache, using its default constructor.

ObjectCache

public ObjectCache(ObjectCache.ObjectCreator creator,
                   int maxSize)

Create a new ObjectCache. This uses the given creator to create new objects for the cache, and sets the internal maximum number of elements to keep waiting.

ObjectCache

public ObjectCache(java.lang.Class creator,
                   int maxSize)

Create a new ObjectCache. This uses the given Class to create new objects for the cache, using its default constructor, and sets the internal maximum number of elements to keep waiting.

ObjectCache

public ObjectCache(ObjectCache.ObjectCreator creator,
                   int maxSize,
                   boolean fill)

Create a new ObjectCache. This uses the given creator to create new objects for the cache, and sets the internal maximum number of elements to keep waiting.

Parameters:

fill - true if the cache should be filled at construction time, or false if it should be empty initially.

ObjectCache

public ObjectCache(java.lang.Class creator,
                   int maxSize,
                   boolean fill)

Create a new ObjectCache. This uses the given Class to create new objects for the cache, using its default constructor, and sets the internal maximum number of elements to keep waiting.

Parameters:

fill - true if the cache should be filled at construction time, or false if it should be empty initially.

Method Detail

putBack

public void putBack(java.lang.Object o)

Adds an element to the end of the queue. If the list is empty, then the next waiting thread is woken up. If the list has one or fewer elements, this this method will block any access to the queue, otherwise this only blocks access to adding to the list.

Parameters:

o - the object to place at the end of the list.

get

public java.lang.Object get()

Retrieves a cached element. If the cache is empty, and no creator is known, then null is returned. If the cache is empty, and a creator is known, then a new object is created and returned.

Synchronized so that the time between the isEmpty check and the pull does not have another thread pulling out an instance. Only the get needs to be synchronized, so as to not mess with the checks.

get

public java.lang.Object get(long millisWaitTime)
                     throws java.lang.InterruptedException

Retrieves a cached element. If the cache is empty, then one of several things can happen, based on the time passed in:

• < 0: null is immediately returned. This is the identical behavior to calling get() with a null creator.
• 0: the routine will wait indefinitely until an object is putBack( Object ) into the cache.
• > 0: the routine will wait up to the given number of milliseconds for another object to be putBack( Object ). If by that time the cache is still empty, then null is returned.

Important parts of the code are synchronized.

Throws:

java.lang.InterruptedException

getOverflows

public int getOverflows()

Retrieves the number of "overflows" encountered. An overflow occurs when the cache is full and a putBack( Object ) is called.

getUnderflows

public int getUnderflows()

Retrieves the number of "underflows" encountered. An underflow occurs when the cache is empty and a get() is called.

setMaxSize

public void setMaxSize(int size)

Resets the internal maximum number of objects that the cache can hold. Note that it does not immediately clear out the extra objects - that is naturally cleared by the putBack( Object ) ignoring overflows.

getMaxSize

public int getMaxSize()

setObjectCreator

public void setObjectCreator(ObjectCache.ObjectCreator creator)

Sets the internal cache-underflow Object creator.

setClassCreator

public void setClassCreator(java.lang.Class creator)

Creates a new DefaultObjectCreator based on the given class.

addObject

public void addObject()

Create a new object and put it into the cache. This follows the rules of putBack( Object ).

fillCache

public void fillCache()

Fills the cache to its maximum. If there is no maximum or there is no creator, then nothing is done.

createObject

protected java.lang.Object createObject()

Generates an Object for the cache. May return null.