org.mycore.common
Class MCRCache

java.lang.Object
  org.mycore.common.MCRCache

public class MCRCache
extends Object

Instances of this class can be used as object cache. Each MCRCache has a certain capacity, the maximum number of objects the cache will hold. When the cache is full and another object is put into the cache, the cache will discard the least recently used object to get place for the new object. The cache will always hold the most recently used objects by updating its internal structure whenever an object is get from the cache or put into the cache. The cache also provides methods for getting the current cache hit rate and fill rate. Like in a hashtable, an MCRCache uses a unique key for each object.

Version:

$Revision: 15000 $ $Date: 2009-03-24 16:42:03 +0100 (Tue, 24 Mar 2009) $

Author:

Frank Lützenkirchen

See Also:

Hashtable

Nested Class Summary

(package private) class

MCRCache.MCRCacheEntry For each object in the cache, there is one MCRCacheEntry object encapsulating it.

Field Summary

protected int	capacity The maximum number of objects that the cache can hold
protected long	gets The number of requests to get an object from this cache
protected long	hits The number of hits, where a requested object really was in the cache
protected Hashtable<Object,MCRCache.MCRCacheEntry>	index A hashtable for looking up a cached object by a given key
protected MCRCache.MCRCacheEntry	lru The least recently used object *
protected MCRCache.MCRCacheEntry	mru The most recently used object *
protected int	size The number of objects currently stored in the cache
protected String	type Tch type string for the MCRCacheJMXBridge

Constructor Summary

MCRCache(int capacity, String type)
Creates a new cache with a given capacity.

Method Summary

void	clear() Clears the cache by removing all entries from the cache
void	close()
Object	get(Object key) Returns an object from the cache for the given key, or null if there currently is no object in the cache with this key.
int	getCapacity() Returns the capacity of this cache.
int	getCurrentSize() Returns the number of objects currently cached.
double	getFillRate() Returns the fill rate of this cache.
double	getHitRate() Returns the hit rate of this cache.
Object	getIfUpToDate(Object key, long time) Returns an object from the cache for the given key, but only if the cache entry is not older than the given timestamp.
boolean	isEmpty() Returns true if this cache is empty.
boolean	isFull() Returns true if this cache is full.
List<Object>	keys() Returns an iterable list of keys to the cached objects.
static void	main(String[] args) A small sample program for testing this class.
void	put(Object key, Object obj) Puts an object into the cache, storing it under the given key.
void	remove(Object key) Removes an object from the cache for the given key.
void	setCapacity(int capacity) Changes the capacity of this cache.
String	toString() Returns a String containing information about cache capacity, size, current fill rate and hit rate.

Methods inherited from class java.lang.Object

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

Field Detail

mru

protected MCRCache.MCRCacheEntry mru

The most recently used object *

lru

protected MCRCache.MCRCacheEntry lru

The least recently used object *

index

protected Hashtable<Object,MCRCache.MCRCacheEntry> index

A hashtable for looking up a cached object by a given key

gets

protected long gets

The number of requests to get an object from this cache

hits

protected long hits

The number of hits, where a requested object really was in the cache

size

protected int size

The number of objects currently stored in the cache

capacity

protected int capacity

The maximum number of objects that the cache can hold

type

protected String type

Tch type string for the MCRCacheJMXBridge

Constructor Detail

MCRCache

public MCRCache(int capacity,
                String type)

Creates a new cache with a given capacity.

Parameters:

capacity - the maximum number of objects this cache will hold

type - the type string for MCRCacheJMXBridge

Method Detail

put

public void put(Object key,
                Object obj)

Puts an object into the cache, storing it under the given key. If the cache is already full, the least recently used object will be removed from the cache first. If the cache already contains an entry under the key provided, this entry is replaced.

Parameters:

key - the non-null key to store the object under

obj - the non-null object to be put into the cache

remove

public void remove(Object key)

Removes an object from the cache for the given key.

Parameters:

key - the key for the object you want to remove from this cache

get

public Object get(Object key)

Returns an object from the cache for the given key, or null if there currently is no object in the cache with this key.

Parameters:

key - the key for the object you want to get from this cache

Returns:

the cached object, or null

getIfUpToDate

public Object getIfUpToDate(Object key,
                            long time)

Returns an object from the cache for the given key, but only if the cache entry is not older than the given timestamp. If there currently is no object in the cache with this key, null is returned. If the cache entry is older than the timestamp, the entry is removed from the cache and null is returned.

Parameters:

key - the key for the object you want to get from this cache

time - the timestamp to check that the cache entry is up to date

Returns:

the cached object, or null

getCurrentSize

public int getCurrentSize()

Returns the number of objects currently cached.

Returns:

the number of objects currently cached

getCapacity

public int getCapacity()

Returns the capacity of this cache. This is the maximum number of objects this cache will hold at a time.

Returns:

the capacity of this cache

setCapacity

public void setCapacity(int capacity)

Changes the capacity of this cache. This is the maximum number of objects that will be cached at a time. If the new capacity is smaller than the current number of objects in the cache, the least recently used objects will be removed from the cache.

Parameters:

capacity - the maximum number of objects this cache will hold

isFull

public boolean isFull()

Returns true if this cache is full.

Returns:

true if this cache is full

isEmpty

public boolean isEmpty()

Returns true if this cache is empty.

Returns:

true if this cache is empty

getFillRate

public double getFillRate()

Returns the fill rate of this cache. This is the current number of objects in the cache diveded by its capacity.

Returns:

the fill rate of this cache as double value

getHitRate

public double getHitRate()

Returns the hit rate of this cache. This is the number of successful hits divided by the total number of get requests so far. Using this ratio can help finding the appropriate cache capacity.

Returns:

the hit rate of this cache as double value

clear

public void clear()

Clears the cache by removing all entries from the cache

toString

public String toString()

Returns a String containing information about cache capacity, size, current fill rate and hit rate. Useful for testing and debugging.

Overrides:

toString in class Object

main

public static void main(String[] args)

A small sample program for testing this class.

close

public void close()

keys

public List<Object> keys()

Returns an iterable list of keys to the cached objects.