Package org.mycore.common

Class MCRCache<K,V>

java.lang.Object
org.mycore.common.MCRCache<K,V>
public class MCRCache<K,V> 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$ $Date$
Author:
Frank Lützenkirchen
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    MCRCache.ModifiedHandle
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected String
    type
    Tch type string for the MCRCacheJMXBridge

  • Constructor Summary

    Constructors
    Constructor
    Description
    MCRCache(long capacity, String type)
    Creates a new cache with a given capacity.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Clears the cache by removing all entries from the cache
    void
    close()
     
    V
    get(K 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.
    long
    getCapacity()
    Returns the capacity of this cache.
    long
    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.
    V
    getIfUpToDate(K 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.
    V
    getIfUpToDate(K key, MCRCache.ModifiedHandle handle)
    Returns an object from the cache for the given key, but only if the cache entry is not older than the given timestamp of the MCRCache.ModifiedHandle.
    boolean
    isEmpty()
    Returns true if this cache is empty.
    boolean
    isFull()
    Returns true if this cache is full.
    List<K>
    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(K key, V value)
    Puts an object into the cache, storing it under the given key.
    void
    put(K key, V value, long insertTime)
    Puts an object into the cache, storing it under the given key.
    void
    remove(K key)
    Removes an object from the cache for the given key.
    void
    setCapacity(long 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 Details

    • type

      protected String type
      Tch type string for the MCRCacheJMXBridge

  • Constructor Details

    • MCRCache

      public MCRCache(long 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 Details

    • main

      public static void main(String[] args)
      A small sample program for testing this class.

    • put

      public void put(K key, V value)
      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
      value - the non-null object to be put into the cache

    • put

      public void put(K key, V value, long insertTime)
      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
      value - the non-null object to be put into the cache
      insertTime - the given last modified time for this key

    • remove

      public void remove(K 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 V get(K 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 V getIfUpToDate(K 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

    • getIfUpToDate

      public V getIfUpToDate(K key, MCRCache.ModifiedHandle handle) throws IOException
      Returns an object from the cache for the given key, but only if the cache entry is not older than the given timestamp of the MCRCache.ModifiedHandle. In contrast to getIfUpToDate(Object, long) you can submit your own handle that returns the last modified timestamp after a certain period is over. Use this method if determining lastModified date is rather expensive and cache access is often.
      Parameters:
      key - the key for the object you want to get from this cache
      handle - the timestamp to check that the cache entry is up to date
      Returns:
      the cached object, or null
      Throws:
      IOException - thrown by MCRCache.ModifiedHandle.getLastModified()
      Since:
      2.1.81

    • getCurrentSize

      public long getCurrentSize()
      Returns the number of objects currently cached.
      Returns:
      the number of objects currently cached

    • getCapacity

      public long 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(long 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

    • close

      public void close()

    • keys

      public List<K> keys()
      Returns an iterable list of keys to the cached objects.