net.groboclown.util.datastruct.v1
Class ObjectCache

java.lang.Object
  |
  +--net.groboclown.util.datastruct.v1.ObjectCache

public class ObjectCache

extends 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 then 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.

Version:

0.9.0 Alpha

Author:

Matt Albrecht

Inner Class Summary

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

private SynchQueue	cache We use a synch queue to optimize the store of objects
private ObjectCache.ObjectCreator	creator We also need to keep the object created.
private int	maxSize Maximum size of the cache.
private int	overflowCount Records the number of overflows - for performance tuning.
private int	underflowCount Records the number of underflows - for performance tuning.
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(Class creator)
Create a new ObjectCache.

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

ObjectCache(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 Object	createObject() Generates an Object for the cache.
void	fillCache() Fills the cache to its maximum.
Object	get() Retrieves a cached element.
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(Object o) Adds an element to the end of the queue.
void	setClassCreator(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, registerNatives, 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.

cache

private SynchQueue cache

We use a synch queue to optimize the store of objects

creator

private ObjectCache.ObjectCreator creator

We also need to keep the object created.

maxSize

private int maxSize

Maximum size of the cache.

overflowCount

private int overflowCount

Records the number of overflows - for performance tuning.

underflowCount

private int underflowCount

Records the number of underflows - for performance tuning.

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(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(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(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(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 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 Object get(long millisWaitTime)
           throws 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.

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(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 Object createObject()

Generates an Object for the cache. May return null.