CompositeKeyCache (documentplatform dist, documentation 5.6.10.6 API)

java.lang.Object
- org.jadice.util.mm.ckc.CompositeKeyCache

All Implemented Interfaces:

BasicCache, Cache, TrackableCache
```
public class CompositeKeyCache
extends Object
implements TrackableCache
```
General principle
This cache implementation uses internally one map as the holder. It accepts both: a simple [key -> value] mapping plus a complex [(owner, key) -> value] mapping. In fact the key of the internal map is a composite of the given owner and key, where the owner is just held as a weak reference. If there is no owner specified, the cache will be the owner itself.
The corresponding value is held as a soft reference. It persists as long as the jvm has enough memory space left and gets automatically garbage collected due to memory pressure. The owner is held weakly, meaning it can be garbage collected any time.
Since multiple [key -> value] mappings might belong to an owner, all mappings will be removed from the cache once the owner gets removed by calling the remove function or the garbage collector will collect the owner. Of course you can remove only one entry by specifying its key or (owner,key) relation. Expiry
Elements will be expired once the cache will grow bigger than its internal size (initially 24 MB), or bigger then the maximum capacity in elements it can have. Only cache entries that are younger then the minimum expiry age (initially 1 second) won't be expired. Additions
- Statistics
  The cache provides the possibility to gather data, such as the number of puts/gets/hits/misses/evictions and so on. This can either be activated in the constructor or in run time.
  For display purposes you can either access them programmatically or use the pluggable status frame that comes with the cache. It displays the status details as well as the items held and the possibility to perform certain actions like clearing the cache, forcing expiry and so on.
- Listeners
  Once activated, CacheEntryListener can be registered at the cache, informing the desired class about events such as puts/evictions/gets and so on.
- JMX-Beans
  Per default a light weight MXBean is registered. It enables the possibility to activate and deactivate statistics, enabling and disabling listeners.
  Once statistics are enabled a second MX-Bean will be registered to inspect the statistics and reset them.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CompositeKeyCache.WeakOwnerKeyComposition` Represents the composition of the owner and key as a mapping to the cache entry.

Constructor Summary

Constructors
Constructor and Description
`CompositeKeyCache()` Constructs a cache with the maximum capacity of 1000 elements.
`CompositeKeyCache(int maxCapacity)` Constructs a cache with a maximum capacity of elements as a parameter.
`CompositeKeyCache(int maxCapacity, boolean enableStatistics)` Constructs a cache with a maximum capacity of elements as a parameter and the option to enable cache statistics.
`CompositeKeyCache(int maxCapacity, boolean enableStatistics, boolean enableListeners)` Constructs a cache with a maximum capacity of elements as a parameter and the option to enable cache statistics.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`areListenersEnabled()` Checks whether `CacheListeners` are enabled to be registered on the cache.
`boolean`	`areStatisticsEnabled()` Checks whether statistic gathering is enabled at the cache.
`void`	`cleanVoidCacheEntries()` This method checks for owners who became garbage collected by their weak reference ability or values that have been garbage collected due to memory pressure and removes their corresponding entries from the cache.
`void`	`clear()` Removes all mappings from this map (optional operation).
`void`	`connectJMXConfigurationBean()` Connects the the `CacheConfigurationMXBean` to the `MBeanServer`.
`void`	`connectJMXOccupationBean()` Connects the the `CacheOccupationMXBean` to the `MBeanServer` .
`void`	`connectJMXStatisticsBean()` Connects the the `CacheStatisticsMXBean` to the `MBeanServer` .
`void`	`deregisterCacheEntryListener(CacheEntryListener cacheEntryListener)` Unregister a cache entry listener from the cache.
`void`	`disconnectJMXConfigurationBean()` Disconnects the the `CacheConfigurationMXBean` from the `MBeanServer`.
`void`	`disconnectJMXOccupationBean()` Disconnects the the `CacheOccupationMXBean` from the `MBeanServer`.
`void`	`disconnectJMXStatisticsBean()` Disconnects the the `CacheStatisticsMXBean` from the `MBeanServer`.
`void`	`forceExpiry()` Force the execution of the `ExpiryStrategy.performExpiry(CacheIteratorFactory, TrackableCache, boolean, ExpiryPressure)` of the configured strategy.
`Object`	`get(Object key)` Returns the value to which this map maps the specified key.
`Object`	`get(Object owner, Object key)`
`Iterator<Map.Entry<OwnerKeyComposition,org.jadice.util.mm.internal.CacheEntry>>`	`getCacheElementsIterator()` Get an `Iterator` of the cache elements.
`CacheStatistics`	`getCacheStatistics()`
`long`	`getEstimatedSize()` Returns the approximate size of the cache in bytes.
`ExpiryStrategy`	`getExpiryStrategy()`
`int`	`getMaximumObjectCount()` Return the maximum number of entries in the cache.
`long`	`getMaximumSize()` Returns the maximum size of bytes the cache is allowed to store.
`int`	`getObjectCount()` Returns the number of elements in the cache in the moment where the request was finally executed.
`Object`	`put(Object key, Object value, int sizeEstimate)` Put the entry into the cache.
`Object`	`put(Object owner, Object key, Object value, int sizeEstimate)`
`void`	`registerCacheEntryListener(CacheEntryListener cacheEntryListener)` Register a cache entry listener at the cache.
`Object`	`remove(Object key)` Removes the mapping for this key from this map if it is present (optional operation).
`Object`	`remove(Object owner, Object key)`
`boolean`	`setCacheEnabled(boolean isCacheEnabled)` Enables/Disables the cache and returns the old value.
`void`	`setCacheListenersEnabled(boolean areCacheListenersEnabled)`
`void`	`setCacheStatisticsEnabled(boolean areStatisticsEnabled)`
`void`	`setExpiryInterval(long expiryInterval)` Sets the interval for the `ExpiryStrategy.ExpiryPressure.OPTIONAL_EXPIRE`.
`void`	`setExpiryStrategy(ExpiryStrategy expiryStrategy)`
`void`	`setMaximumObjectCount(int maxCount)`
`void`	`setMaximumSize(long maximumSize)`

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

- Constructor Detail
  - CompositeKeyCache
```
public CompositeKeyCache()
```
    Constructs a cache with the maximum capacity of 1000 elements.
    Statistics and listeners are disabled by default.
  - CompositeKeyCache
```
public CompositeKeyCache(int maxCapacity)
```
    Constructs a cache with a maximum capacity of elements as a parameter.
    Statistics and listeners are disabled by default.
    
    Parameters:
    
    maxCapacity - Maximum number of cache entries.
  - CompositeKeyCache
```
public CompositeKeyCache(int maxCapacity,
                         boolean enableStatistics)
```
    Constructs a cache with a maximum capacity of elements as a parameter and the option to enable cache statistics.
    Listeners are disabled by default.
    
    Parameters:
    
    maxCapacity - Maximum number of cache entries.
    
    enableStatistics - If true, the cache will collect certain statistics (such as number of puts/gets/hits/misses/evictions and so on)
  - CompositeKeyCache
```
public CompositeKeyCache(int maxCapacity,
                         boolean enableStatistics,
                         boolean enableListeners)
```
    Constructs a cache with a maximum capacity of elements as a parameter and the option to enable cache statistics. Additionally the third parameter enables the cache to register and use CacheEntryListeners.
    
    Parameters:
    
    maxCapacity - Maximum number of cache entries.
    
    enableStatistics - If true, the cache will collect certain statistics (such as number of puts/gets/hits/misses/evictions and so on)
    
    enableListeners - If true, the cache will be able to register and fire CacheEntryListeners
- Method Detail
  - 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)
```
    Specified by:
    
    put in interface Cache
  - get
```
public Object get(Object key)
```
    Description copied from interface: BasicCache
    
    Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
    More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)
    
    Specified by:
    
    get in interface BasicCache
    
    Parameters:
    
    key - key whose associated value is to be returned.
    
    Returns:
    
    the value to which this map maps the specified key, or null if the map contains no mapping for this key.
  - get
```
public Object get(Object owner,
                  Object key)
```
    Specified by:
    
    get in interface Cache
  - getObjectCount
```
public int getObjectCount()
```
    Returns the number of elements in the cache in the moment where the request was finally executed.
    
    Specified by:
    
    getObjectCount in interface TrackableCache
    
    Returns:
    
    Number of elements in the cache
  - getMaximumObjectCount
```
public int getMaximumObjectCount()
```
    Return the maximum number of entries in the cache.
    
    Specified by:
    
    getMaximumObjectCount in interface TrackableCache
    
    Returns:
    
    Value of property maximumObjectCount.
  - getEstimatedSize
```
public long getEstimatedSize()
```
    Returns the approximate size of the cache in bytes.
    
    Specified by:
    
    getEstimatedSize in interface TrackableCache
    
    Returns:
    
    Approximate cache size in bytes
  - getMaximumSize
```
public long getMaximumSize()
```
    Returns the maximum size of bytes the cache is allowed to store.
    
    Specified by:
    
    getMaximumSize in interface TrackableCache
    
    Returns:
    
    Maximum size of the cache in bytes
  - getCacheStatistics
```
public CacheStatistics getCacheStatistics()
```
  - setExpiryStrategy
```
public void setExpiryStrategy(ExpiryStrategy expiryStrategy)
```
    Parameters:
    
    expiryStrategy - The expiry strategy the cache should use.
  - getExpiryStrategy
```
public final ExpiryStrategy getExpiryStrategy()
```
  - setExpiryInterval
```
public void setExpiryInterval(long expiryInterval)
```
    Sets the interval for the ExpiryStrategy.ExpiryPressure.OPTIONAL_EXPIRE. If more seconds than the given interval passed since the last expiry, ExpiryStrategy.performExpiry(CacheIteratorFactory, TrackableCache, boolean, ExpiryPressure) is called with the parameter ExpiryStrategy.ExpiryPressure.OPTIONAL_EXPIRE.
    
    Parameters:
    
    expiryInterval - the time interval in seconds
  - setMaximumSize
```
public void setMaximumSize(long maximumSize)
```
    Parameters:
    
    maximumSize - Maximum size of the cache. Once it's exceeded the expiry is fired.
  - setMaximumObjectCount
```
public void setMaximumObjectCount(int maxCount)
```
    Parameters:
    
    maxCount - Maximum amount of objects the cache can store.
  - setCacheListenersEnabled
```
public void setCacheListenersEnabled(boolean areCacheListenersEnabled)
```
    Parameters:
    
    areCacheListenersEnabled - Enables or disables CacheEntryListeners.
  - setCacheStatisticsEnabled
```
public void setCacheStatisticsEnabled(boolean areStatisticsEnabled)
```
    Parameters:
    
    areStatisticsEnabled - Enables if true or disables if false collection of caching statistics.
  - cleanVoidCacheEntries
```
public void cleanVoidCacheEntries()
```
    This method checks for owners who became garbage collected by their weak reference ability or values that have been garbage collected due to memory pressure and removes their corresponding entries from the cache.
  - clear
```
public void clear()
```
    Description copied from interface: Cache
    
    Removes all mappings from this map (optional operation).
    
    Specified by:
    
    clear in interface Cache
  - remove
```
public Object remove(Object key)
```
    Description copied from interface: BasicCache
    
    Removes the mapping for this key from this map if it is present (optional operation). More formally, if this map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one such mapping.)
    Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. (A null return can also indicate that the map previously associated null with the specified key if the implementation supports null values.) The map will not contain a mapping for the specified key once the call returns.
    
    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.
  - remove
```
public Object remove(Object owner,
                     Object key)
```
    Specified by:
    
    remove in interface Cache
  - forceExpiry
```
public void forceExpiry()
```
    Force the execution of the ExpiryStrategy.performExpiry(CacheIteratorFactory, TrackableCache, boolean, ExpiryPressure) of the configured strategy.
    
    See Also:
    
    getExpiryStrategy()
  - registerCacheEntryListener
```
public void registerCacheEntryListener(CacheEntryListener cacheEntryListener)
                                throws CacheEntryListenerException
```
    Register a cache entry listener at the cache.
    
    Parameters:
    
    cacheEntryListener - that should be added
    
    Throws:
    
    CacheEntryListenerException - Gets thrown once listeners are disabled at the cache
  - deregisterCacheEntryListener
```
public void deregisterCacheEntryListener(CacheEntryListener cacheEntryListener)
                                  throws CacheEntryListenerException
```
    Unregister a cache entry listener from the cache.
    
    Parameters:
    
    cacheEntryListener - that should be unregistered
    
    Throws:
    
    CacheEntryListenerException - Gets thrown once listeners are disabled at the cache
  - setCacheEnabled
```
public boolean setCacheEnabled(boolean isCacheEnabled)
```
    Enables/Disables the cache and returns the old value.
    This just blocks the "put()" calls, resulting in a "null" return.
    
    Parameters:
    
    isCacheEnabled - Indicates if the cache should be enabled.
    
    Returns:
    
    The old state before the change.
  - connectJMXConfigurationBean
```
public void connectJMXConfigurationBean()
```
    Connects the the CacheConfigurationMXBean to the MBeanServer.
  - connectJMXStatisticsBean
```
public void connectJMXStatisticsBean()
```
    Connects the the CacheStatisticsMXBean to the MBeanServer .
  - disconnectJMXStatisticsBean
```
public void disconnectJMXStatisticsBean()
```
    Disconnects the the CacheStatisticsMXBean from the MBeanServer.
  - disconnectJMXConfigurationBean
```
public void disconnectJMXConfigurationBean()
```
    Disconnects the the CacheConfigurationMXBean from the MBeanServer.
  - connectJMXOccupationBean
```
public void connectJMXOccupationBean()
```
    Connects the the CacheOccupationMXBean to the MBeanServer .
  - disconnectJMXOccupationBean
```
public void disconnectJMXOccupationBean()
```
    Disconnects the the CacheOccupationMXBean from the MBeanServer.
  - areListenersEnabled
```
public boolean areListenersEnabled()
```
    Checks whether CacheListeners are enabled to be registered on the cache.
    
    Returns:
    
    True if this yields true, otherwise false
  - areStatisticsEnabled
```
public boolean areStatisticsEnabled()
```
    Checks whether statistic gathering is enabled at the cache.
    
    Returns:
    
    True if it's enabled, else false
  - getCacheElementsIterator
```
public Iterator<Map.Entry<OwnerKeyComposition,org.jadice.util.mm.internal.CacheEntry>> getCacheElementsIterator()
```
    Description copied from interface: TrackableCache
    
    Get an Iterator of the cache elements. This Iterator is read only. Thus calls to Iterator.remove() will always result in a UnsupportedOperationException
    
    Specified by:
    
    getCacheElementsIterator in interface TrackableCache
    
    Returns:
    
    The iterator to the elements of the cache

Class CompositeKeyCache

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CompositeKeyCache

CompositeKeyCache

CompositeKeyCache

CompositeKeyCache

Method Detail

put

put

get

get

getObjectCount

getMaximumObjectCount

getEstimatedSize

getMaximumSize

getCacheStatistics

setExpiryStrategy

getExpiryStrategy

setExpiryInterval

setMaximumSize

setMaximumObjectCount

setCacheListenersEnabled

setCacheStatisticsEnabled

cleanVoidCacheEntries

clear

remove

remove

forceExpiry

registerCacheEntryListener

deregisterCacheEntryListener

setCacheEnabled

connectJMXConfigurationBean

connectJMXStatisticsBean

disconnectJMXStatisticsBean

disconnectJMXConfigurationBean

connectJMXOccupationBean

disconnectJMXOccupationBean

areListenersEnabled

areStatisticsEnabled

getCacheElementsIterator