LRUCache (documentplatform dist, documentation 5.6.10.6 API)

java.lang.Object
- org.jadice.util.mm.LRUCache

All Implemented Interfaces:

BasicCache, Cache
```
public class LRUCache
extends Object
implements Cache
```
An implementation of a Map which has a maximum size and uses a Least Recently Used algorithm to remove items from the Map when the maximum size is reached and new items are added.
A synchronized version can be obtained with: Collections.synchronizedMap( theMapToSynchronize ) If it will be accessed by multiple threads, you _must_ synchronize access to this Map. Even concurrent get(Object) operations produce indeterminate behavior.
Unlike the Collections 1.0 version, this version of LRUMap does use a true LRU algorithm. The keys for all gets and puts are moved to the front of the list. LRUMap is now a subclass of SequencedHashMap, and the "LRU" key is now equivalent to LRUMap.getFirst(). The contents of the cache may be displayed for debugging purposes using a status frame. This status frame can be activated by setting the system property jadice.viewer.show-cache-status=true.

Since:

1.0

Author:

James Strachan, Morgan Delagrange, j.henne@levigo.de

Constructor Summary

Constructors
Constructor and Description
`LRUCache()` Default constructor, primarily for the purpose of de-externalization.
`LRUCache(int maxCapacity)` Create a new LRUMap with a maximum capacity of i.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()` Removes all mappings from this map (optional operation).
`Object`	`get(Object key)` Get the value for a key from the Map.
`Object`	`get(Object owner, Object key)` Get the value for a key from the Map.
`int`	`getExpiryObjectCountRatio()` Returns a ratio defining the minimum number of objects to expire.
`int`	`getMaximumObjectCount()` Return the maximum mumber of entries in the cache.
`long`	`getMemoryCheckThreshold()` Returns a threshold which initiates an emergency cache clean if the VM will run out of memory.
`int`	`getMinimumExpiryAge()` Return the minimum age (in ms) of objects to be purged from the cache.
`int`	`getObjectCount()` Returns the number of objects in the cache.
`long`	`getSizeEstimate()` Returns the estimated size of all objects in the cache.
`long`	`getSizeHighwaterMark()` Returns the high water mark.
`int`	`getSizeLowwaterPercent()` Returns the low water mark.
`SizeManagementStrategy`	`getSizeManagementStrategy()`
`boolean`	`isEnableSoftReferences()`
`boolean`	`isMemoryCheckEnabled()` Returns whether the cache forces expiry runs when memory is low.
`protected void`	`performExpiry()` Purge entries from the cache until the memory use is below the low-water mark again.
`protected void`	`processRemovedEntry(Object key, Object value)` Subclasses of LRUCache may hook into this method to provide specialized actions whenever an Object is automatically removed from the cache.
`Object`	`put(Object key, Object value, int sizeEstimate)` Put the entry into the cache.
`Object`	`put(Object owner, Object key, Object value, int sizeEstimate)` Store an element in the cache, keeping a weak reference to the owner, but a hard reference to the key.
`Object`	`remove(Object key)` Remove an entry from the cache using the associated key.
`Object`	`remove(Object owner, Object key)`
`void`	`scheduleExpiry()` Schedules an expiry process if required.
`void`	`setEnableSoftReferences(boolean enableSoftReferences)`
`void`	`setExpiryObjectCountRatio(int expiryObjectCountRatio)` Sets the expiry object count ratio.
`void`	`setMaximumObjectCount(int maximumSize)` Set the maximum mumber of entries in the cache.
`void`	`setMemoryCheckEnabled(boolean memoryCheckEnabled)` Changes the cache behavior whether the cache should force expiry runs when memory is low.
`void`	`setMemoryCheckThreshold(long memoryCheckThreshold)` Sets a threshold which initiates an emergency cache clean if the VM will run out of memory.
`void`	`setMinimumExpiryAge(int minimumExpiryAge)` Set the minimum age (in ms) of objects to be purged from the cache.
`void`	`setSizeHighwaterMark(long sizeHighwaterMark)` Sets the high water mark.
`void`	`setSizeLowwaterPercent(int sizeLowwaterPercent)` Sets the low water mark.
`void`	`setSizeManagementStrategy(SizeManagementStrategy sizeManagementStrategy)`
`void`	`showStatusFrame()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LRUCache
```
public LRUCache()
```
    Default constructor, primarily for the purpose of de-externalization. This constructors sets a default LRU limit of 100 keys, but this value may be overridden internally as a result of de-externalization.
  - LRUCache
```
public LRUCache(int maxCapacity)
```
    Create a new LRUMap with a maximum capacity of i. Once i capacity is achieved, subsequent gets and puts will push keys out of the map. See .
    
    Parameters:
    
    maxCapacity - Maximum capacity of the LRUMap
- Method Detail
  - showStatusFrame
```
public void showStatusFrame()
```
  - get
```
public Object get(Object key)
```
    Get the value for a key from the Map. The key will be promoted to the Most Recently Used position. Note that get(Object) operations will modify the underlying Collection. Calling get(Object) inside of an iteration over keys, values, etc. is currently unsupported.
    
    Specified by:
    
    get in interface BasicCache
    
    Parameters:
    
    key - Key to retrieve
    
    Returns:
    
    Returns the value. Returns null if the key has a null value or if the key has no value.
  - get
```
public Object get(Object owner,
                  Object key)
```
    Get the value for a key from the Map. The key will be promoted to the Most Recently Used position. Note that get(Object) operations will modify the underlying Collection. Calling get(Object) inside of an iteration over keys, values, etc. is currently unsupported.
    
    Specified by:
    
    get in interface Cache
    
    Parameters:
    
    owner - the owner of the key value pairs
    
    key - Key to retrieve
    
    Returns:
    
    Returns the value. Returns null if the key has a null value or if the key has no value.
  - remove
```
public Object remove(Object owner,
                     Object key)
```
    Specified by:
    
    remove in interface Cache
  - getSizeEstimate
```
public long getSizeEstimate()
```
    Returns the estimated size of all objects in the cache.
    
    Returns:
    
    int
  - getObjectCount
```
public int getObjectCount()
```
    Returns the number of objects in the cache.
  - put
```
public Object put(Object key,
                  Object value,
                  int sizeEstimate)
```
    Description copied from interface: BasicCache
    
    Put the entry into the cache.
    
    Specified by:
    
    put in interface BasicCache
    
    Parameters:
    
    key - key to which value will be associated.
    
    value - the value to which the given key is associated.
    
    sizeEstimate - an estimated size of the value in bytes.
    
    Returns:
    
    previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values
    
    See Also:
    
    Map.put(Object, Object)
  - put
```
public Object put(Object owner,
                  Object key,
                  Object value,
                  int sizeEstimate)
```
    Store an element in the cache, keeping a weak reference to the owner, but a hard reference to the key. This way, entries will be collected when their respective owner is collected, but the keys will not be collected, because of the hard reference.
    
    Specified by:
    
    put in interface Cache
    
    See Also:
    
    Cache.put(Object, Object, Object, int)
  - remove
```
public Object remove(Object key)
```
    Remove an entry from the cache using the associated key. If the entry was stored using put(Object key, Object value, int), there is a 1:1 association between key and entry. If the entry was stored using put(Object owner, Object key, Object value, int) however, the key specified in the call corresponds to the owner, and consequently all entries cached by the owner are removed.
    
    Specified by:
    
    remove in interface BasicCache
    
    Parameters:
    
    key - key whose mapping is to be removed from the map.
    
    Returns:
    
    previous value associated with specified key, or null if there was no mapping for key.
    
    See Also:
    
    BasicCache.remove(java.lang.Object)
  - clear
```
public void clear()
```
    Description copied from interface: Cache
    
    Removes all mappings from this map (optional operation).
    
    Specified by:
    
    clear in interface Cache
  - performExpiry
```
protected void performExpiry()
```
    Purge entries from the cache until the memory use is below the low-water mark again.
  - getMaximumObjectCount
```
public int getMaximumObjectCount()
```
    Return the maximum mumber of entries in the cache.
    
    Returns:
    
    Value of property maximumObjectCount.
  - setMaximumObjectCount
```
public void setMaximumObjectCount(int maximumSize)
```
    Set the maximum mumber of entries in the cache.
    
    Parameters:
    
    maximumSize - New value of property maximumObjectCount.
  - scheduleExpiry
```
public void scheduleExpiry()
```
    Schedules an expiry process if required.
  - getMinimumExpiryAge
```
public int getMinimumExpiryAge()
```
    Return the minimum age (in ms) of objects to be purged from the cache.
    
    Returns:
    
    int
  - setMinimumExpiryAge
```
public void setMinimumExpiryAge(int minimumExpiryAge)
```
    Set the minimum age (in ms) of objects to be purged from the cache.
    
    Parameters:
    
    minimumExpiryAge - The minimumExpiryAge to set
  - getSizeHighwaterMark
```
public long getSizeHighwaterMark()
```
    Returns the high water mark. Entry expiry will start when the estimated size of all entries exceeds the high water mark.
    
    Returns:
    
    int
  - setSizeHighwaterMark
```
public void setSizeHighwaterMark(long sizeHighwaterMark)
```
    Sets the high water mark. Entry expiry will start when the estimated size of all entries exceeds the high water mark.
    
    Parameters:
    
    sizeHighwaterMark - The sizeHighwaterMark to set
  - getSizeLowwaterPercent
```
public int getSizeLowwaterPercent()
```
    Returns the low water mark. Once entry expiry has been started, entries will be removed until the estimated size falls below the low water mark. The low water mark is expressed as a percentage of the high water mark.
    
    Returns:
    
    int
  - setSizeLowwaterPercent
```
public void setSizeLowwaterPercent(int sizeLowwaterPercent)
```
    Sets the low water mark. Once entry expiry has been started, entries will be removed until the estimated size falls below the low water mark. The low water mark is expressed as a percentage of the high water mark.
    
    Parameters:
    
    sizeLowwaterPercent - The sizeLowwaterPercent to set
  - getExpiryObjectCountRatio
```
public int getExpiryObjectCountRatio()
```
    Returns a ratio defining the minimum number of objects to expire. Once entry expiry has been started caused by exceeding maximum object count, this ratio determines how many entries at least will be removed. This ratio is expressed as a percentage of the maximum object count. If the ratio is set to 0, it will be ignored by expiry process.
    
    Returns:
    
    int ratio
  - setExpiryObjectCountRatio
```
public void setExpiryObjectCountRatio(int expiryObjectCountRatio)
```
    Sets the expiry object count ratio. Once entry expiry has been started caused by exceeding maximum object count, this ratio determines how many entries at least will be removed. This ratio is expressed as a percentage of the maximum object count. If the ratio is set to 0, it will be ignored by expiry process.
    
    Parameters:
    
    expiryObjectCountRatio - The expiry object count ration to set
  - isMemoryCheckEnabled
```
public boolean isMemoryCheckEnabled()
```
    Returns whether the cache forces expiry runs when memory is low. This feature is only supported for JVM 1.4.x and newer ones.
    
    Returns:
    
    boolean flag, true when expiry will be triggered otherwise false
  - setMemoryCheckEnabled
```
public void setMemoryCheckEnabled(boolean memoryCheckEnabled)
```
    Changes the cache behavior whether the cache should force expiry runs when memory is low. This feature is only supported for JVM 1.4.x and newer ones.
    
    Parameters:
    
    memoryCheckEnabled - true when expiry should be triggered otherwise false
  - getMemoryCheckThreshold
```
public long getMemoryCheckThreshold()
```
    Returns a threshold which initiates an emergency cache clean if the VM will run out of memory. The threshold initiates an emergency cache clean if the following comparison maxMemory - totalMemory + freeMemory < threshold becomes true. If isMemoryCheckEnabled() is false this setting will be ignored.
    
    Returns:
    
    the heap size threshold used to initiate an emergency cache clean if memory becomes low.
  - setMemoryCheckThreshold
```
public void setMemoryCheckThreshold(long memoryCheckThreshold)
```
    Sets a threshold which initiates an emergency cache clean if the VM will run out of memory. The threshold initiates an emergency cache clean if the following comparison maxMemory - totalMemory + freeMemory < threshold becomes true. If isMemoryCheckEnabled() is false this setting will be ignored.
    
    Parameters:
    
    memoryCheckThreshold - the heap size limit used to initiate an emergency cache clean This setting must be at least 10485760 = 10MB or greater. If the value of memoryCheckThreshold is smaller then 10MB a default value of 26214400=25MB will be assumed.
  - processRemovedEntry
```
protected void processRemovedEntry(Object key,
                                   Object value)
```
    Subclasses of LRUCache may hook into this method to provide specialized actions whenever an Object is automatically removed from the cache. By default, this method flushes the following object types:
    - BufferedImage: calls Image.flush()
    - Flushable: calls Flushable.flush()
    - Collection: flushes Flushables contained in the collection, then clears it
    Parameters:
    
    key - key that was removed
    
    value - value of that key (can be null)
  - setEnableSoftReferences
```
public void setEnableSoftReferences(boolean enableSoftReferences)
```
  - isEnableSoftReferences
```
public boolean isEnableSoftReferences()
```
  - getSizeManagementStrategy
```
public SizeManagementStrategy getSizeManagementStrategy()
```
  - setSizeManagementStrategy
```
public void setSizeManagementStrategy(SizeManagementStrategy sizeManagementStrategy)
```

Class LRUCache

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LRUCache

LRUCache

Method Detail

showStatusFrame

get

get

remove

getSizeEstimate

getObjectCount

put

put

remove

clear

performExpiry

getMaximumObjectCount

setMaximumObjectCount

scheduleExpiry

getMinimumExpiryAge

setMinimumExpiryAge

getSizeHighwaterMark

setSizeHighwaterMark

getSizeLowwaterPercent

setSizeLowwaterPercent

getExpiryObjectCountRatio

setExpiryObjectCountRatio

isMemoryCheckEnabled

setMemoryCheckEnabled

getMemoryCheckThreshold

setMemoryCheckThreshold

processRemovedEntry

setEnableSoftReferences

isEnableSoftReferences

getSizeManagementStrategy

setSizeManagementStrategy