ehcache

net.sf.ehcache.store
Class LruMemoryStore

java.lang.Object
  extended by net.sf.ehcache.store.AbstractStore
      extended by net.sf.ehcache.store.LruMemoryStore
All Implemented Interfaces:
Store

public class LruMemoryStore
extends AbstractStore

An implementation of a LruMemoryStore.

This uses LinkedHashMap as its backing map. It uses the LinkedHashMap LRU feature. LRU for this implementation means least recently accessed.

Version:
$Id$
Author:
Greg Luck

Nested Class Summary
 class LruMemoryStore.SpoolingLinkedHashMap
          An extension of LinkedHashMap which overrides LruMemoryStore.SpoolingLinkedHashMap.removeEldestEntry(java.util.Map.Entry) to persist cache entries to the auxiliary cache before they are removed.
 
Field Summary
protected  Ehcache cache
          The cache this store is associated with.
protected  Store diskStore
          The DiskStore associated with this MemoryStore.
protected  Map map
          Map where items are stored by key.
protected  long maximumSize
          The maximum size of the store (0 == no limit)
protected  Status status
          status.
 
Fields inherited from class net.sf.ehcache.store.AbstractStore
attributeExtractors
 
Fields inherited from interface net.sf.ehcache.store.Store
CLUSTER_COHERENT, NODE_COHERENT
 
Constructor Summary
LruMemoryStore(Ehcache cache, Store diskStore)
          Constructor for the LruMemoryStore object The backing LinkedHashMap is created with LRU by access order.
 
Method Summary
 boolean bufferFull()
          Memory stores are never backed up and always return false
protected  void clear()
          Clears any data structures and places it back to its state when it was first created.
 boolean containsKey(Object key)
          An unsynchronized check to see if a key is in the Store.
 boolean containsKeyInMemory(Object key)
          A check to see if a key is in the Store and is currently held in memory.
 boolean containsKeyOffHeap(Object key)
          A check to see if a key is in the Store and is currently held off-heap.
 boolean containsKeyOnDisk(Object key)
          A check to see if a key is in the Store and is currently held on disk.
 void dispose()
          Prepares for shutdown.
protected  void doPut(Element element)
          Allow specialised actions over adding the element to the map.
protected  void evict(Element element)
          Evict the Element.
 void expireElements()
          Expire all elsments.
 void flush()
          Flush to disk only if the cache is diskPersistent.
 Element get(Object key)
          Gets an item from the cache.
 Policy getEvictionPolicy()
           
 Policy getInMemoryEvictionPolicy()
          
 int getInMemorySize()
          Returns the current local in-memory store size
 long getInMemorySizeInBytes()
          Gets the size of the in-memory portion of the store, in bytes.
 Object getInternalContext()
          This should not be used, and will generally return null
 List getKeys()
          Gets an Array of the keys for all elements in the memory cache.
 Object getMBean()
          Optional implementation specific MBean exposed by the store.
 int getOffHeapSize()
          Returns the current local off-heap store size
 long getOffHeapSizeInBytes()
          Gets the size of the off-heap portion of the store, in bytes.
 int getOnDiskSize()
          Returns the current local on-disk store size
 long getOnDiskSizeInBytes()
          Gets the size of the on-disk portion of the store, in bytes.
 Element getQuiet(Object key)
          Gets an item from the cache, without updating statistics.
 int getSize()
          Returns the current cache size.
 long getSizeInBytes()
          Measures the size of the memory store by using the sizeof engine.
 Status getStatus()
          Gets the status of the MemoryStore.
 int getTerracottaClusteredSize()
          Returns nothing since a disk store isn't clustered
protected  boolean isFull()
          An algorithm to tell if the MemoryStore is at or beyond its carrying capacity.
protected  void notifyExpiry(Element element)
          Before eviction elements are checked.
 boolean put(Element element)
          Puts an item in the cache.
 Element putIfAbsent(Element element)
          Unsupported in LruMemoryStore
 boolean putWithWriter(Element element, CacheWriterManager writerManager)
          Puts an item into the store and the cache writer manager in an atomic operation
 Element remove(Object key)
          Removes an Element from the store.
 void removeAll()
          Remove all of the elements from the store.
 Element removeElement(Element element, ElementValueComparator comparator)
          Unsupported in LruMemoryStore
 Element removeWithWriter(Object key, CacheWriterManager writerManager)
          Removes an item from the store and the cache writer manager in an atomic operation.
 Element replace(Element element)
          Unsupported in LruMemoryStore
 boolean replace(Element old, Element element, ElementValueComparator comparator)
          Unsupported in LruMemoryStore
 void setEvictionPolicy(Policy policy)
          Sets the eviction policy strategy.
 void setInMemoryEvictionPolicy(Policy policy)
          Sets the eviction policy strategy.
protected  void spoolAllToDisk()
          Spools all elements to disk, in preparation for shutdown.
protected  void spoolToDisk(Element element)
          Puts the element in the DiskStore.
 
Methods inherited from class net.sf.ehcache.store.AbstractStore
addStoreListener, executeQuery, getAll, getAllQuiet, getEventListenerList, getSearchAttribute, hasAbortedSizeOf, isCacheCoherent, isClusterCoherent, isNodeCoherent, putAll, recalculateSize, removeAll, removeStoreListener, setAttributeExtractors, setNodeCoherent, waitUntilClusterCoherent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cache

protected Ehcache cache
The cache this store is associated with.


map

protected Map map
Map where items are stored by key.


diskStore

protected final Store diskStore
The DiskStore associated with this MemoryStore.


status

protected Status status
status.


maximumSize

protected long maximumSize
The maximum size of the store (0 == no limit)

Constructor Detail

LruMemoryStore

public LruMemoryStore(Ehcache cache,
                      Store diskStore)
Constructor for the LruMemoryStore object The backing LinkedHashMap is created with LRU by access order.

Method Detail

put

public final boolean put(Element element)
                  throws CacheException
Puts an item in the cache. Note that this automatically results in LruMemoryStore.SpoolingLinkedHashMap.removeEldestEntry(java.util.Map.Entry) being called.

Parameters:
element - the element to add
Returns:
true if this is a new put for the key or element is null. Returns false if it was an update.
Throws:
CacheException

putWithWriter

public final boolean putWithWriter(Element element,
                                   CacheWriterManager writerManager)
                            throws CacheException
Puts an item into the store and the cache writer manager in an atomic operation

Returns:
true if this is a new put for the key or element is null. Returns false if it was an update.
Throws:
CacheException

doPut

protected void doPut(Element element)
              throws CacheException
Allow specialised actions over adding the element to the map.

Parameters:
element -
Throws:
CacheException

get

public final Element get(Object key)
Gets an item from the cache.

The last access time in Element is updated.

Parameters:
key - the cache key
Returns:
the element, or null if there was no match for the key

getQuiet

public final Element getQuiet(Object key)
Gets an item from the cache, without updating statistics.

Parameters:
key - the cache key
Returns:
the element, or null if there was no match for the key

remove

public final Element remove(Object key)
Removes an Element from the store.

Parameters:
key - the key of the Element, usually a String
Returns:
the Element if one was found, else null

removeWithWriter

public final Element removeWithWriter(Object key,
                                      CacheWriterManager writerManager)
                               throws CacheException
Removes an item from the store and the cache writer manager in an atomic operation.

Throws:
CacheException

removeAll

public final void removeAll()
                     throws CacheException
Remove all of the elements from the store.

Throws:
CacheException

clear

protected final void clear()
Clears any data structures and places it back to its state when it was first created.


dispose

public final void dispose()
Prepares for shutdown.


flush

public final void flush()
Flush to disk only if the cache is diskPersistent.


spoolAllToDisk

protected final void spoolAllToDisk()
Spools all elements to disk, in preparation for shutdown.

This revised implementation is a little slower but avoids using increased memory during the method.


spoolToDisk

protected void spoolToDisk(Element element)
Puts the element in the DiskStore. Should only be called if isOverflowToDisk is true

Relies on being called from a synchronized method

Parameters:
element - The Element

getStatus

public final Status getStatus()
Gets the status of the MemoryStore.


getKeys

public final List getKeys()
Gets an Array of the keys for all elements in the memory cache.

Does not check for expired entries

Returns:
An Object[]

getSize

public final int getSize()
Returns the current cache size.

Returns:
The size value

getTerracottaClusteredSize

public final int getTerracottaClusteredSize()
Returns nothing since a disk store isn't clustered

Returns:
returns 0

containsKey

public final boolean containsKey(Object key)
An unsynchronized check to see if a key is in the Store. No check is made to see if the Element is expired.

Parameters:
key - The Element key
Returns:
true if found. If this method return false, it means that an Element with the given key is definitely not in the MemoryStore. If it returns true, there is an Element there. An attempt to get it may return null if the Element has expired.

getSizeInBytes

public final long getSizeInBytes()
                          throws CacheException
Measures the size of the memory store by using the sizeof engine.

Warning: This method can be very expensive to run. Allow approximately 1 second per 1MB of entries. Running this method could create liveness problems because the object lock is held for a long period

Returns:
the size, in bytes
Throws:
CacheException

evict

protected final void evict(Element element)
                    throws CacheException
Evict the Element.

Evict means that the Element is:

Parameters:
element - the Element to be evicted.
Throws:
CacheException

notifyExpiry

protected final void notifyExpiry(Element element)
Before eviction elements are checked.

Parameters:
element -

isFull

protected final boolean isFull()
An algorithm to tell if the MemoryStore is at or beyond its carrying capacity.


expireElements

public void expireElements()
Expire all elsments.

This is a default implementation which does nothing. Expiry on demand is only implemented for disk stores.


bufferFull

public boolean bufferFull()
Memory stores are never backed up and always return false

Returns:
true if the store write buffer is backed up.

getMBean

public Object getMBean()
Optional implementation specific MBean exposed by the store.

Returns:
implementation specific management bean

getEvictionPolicy

public Policy getEvictionPolicy()
Returns:
the current eviction policy. This may not be the configured policy, if it has been dynamically set.
See Also:
setEvictionPolicy(Policy)

setEvictionPolicy

public void setEvictionPolicy(Policy policy)
Sets the eviction policy strategy. The Store will use a policy at startup. The store may allow changing the eviction policy strategy dynamically. Otherwise implementations will throw an exception if this method is called.

Parameters:
policy - the new policy

getInternalContext

public Object getInternalContext()
This should not be used, and will generally return null

Returns:
some internal context (probably null)

containsKeyInMemory

public boolean containsKeyInMemory(Object key)
A check to see if a key is in the Store and is currently held in memory.

Parameters:
key - The Element key
Returns:
true if found. No check is made to see if the Element is expired.

containsKeyOffHeap

public boolean containsKeyOffHeap(Object key)
A check to see if a key is in the Store and is currently held off-heap.

Parameters:
key - The Element key
Returns:
true if found. No check is made to see if the Element is expired.

containsKeyOnDisk

public boolean containsKeyOnDisk(Object key)
A check to see if a key is in the Store and is currently held on disk.

Parameters:
key - The Element key
Returns:
true if found. No check is made to see if the Element is expired.

getInMemoryEvictionPolicy

public Policy getInMemoryEvictionPolicy()

Returns:
the current eviction policy. This may not be the configured policy, if it has been dynamically set.
See Also:
Store.setInMemoryEvictionPolicy(Policy)

getInMemorySize

public int getInMemorySize()
Returns the current local in-memory store size

Returns:
the count of the Elements in the Store and in-memory on the local machine

getInMemorySizeInBytes

public long getInMemorySizeInBytes()
Gets the size of the in-memory portion of the store, in bytes.

This method may be expensive to run, depending on implementation. Implementers may choose to return an approximate size.

Returns:
the approximate in-memory size of the store in bytes

getOffHeapSize

public int getOffHeapSize()
Returns the current local off-heap store size

Returns:
the count of the Elements in the Store and off-heap on the local machine

getOffHeapSizeInBytes

public long getOffHeapSizeInBytes()
Gets the size of the off-heap portion of the store, in bytes.

Returns:
the approximate off-heap size of the store in bytes

getOnDiskSize

public int getOnDiskSize()
Returns the current local on-disk store size

Returns:
the count of the Elements in the Store and on-disk on the local machine

getOnDiskSizeInBytes

public long getOnDiskSizeInBytes()
Gets the size of the on-disk portion of the store, in bytes.

Returns:
the on-disk size of the store in bytes

setInMemoryEvictionPolicy

public void setInMemoryEvictionPolicy(Policy policy)
Sets the eviction policy strategy. The Store will use a policy at startup. The store may allow changing the eviction policy strategy dynamically. Otherwise implementations will throw an exception if this method is called.

Parameters:
policy - the new policy

putIfAbsent

public Element putIfAbsent(Element element)
                    throws NullPointerException
Unsupported in LruMemoryStore

Parameters:
element - element to be added
Returns:
the element previously cached for this key, or null if none.
Throws:
NullPointerException - if the element is null, or has a null key

removeElement

public Element removeElement(Element element,
                             ElementValueComparator comparator)
                      throws NullPointerException
Unsupported in LruMemoryStore

Parameters:
element - Element to be removed
comparator - ElementValueComparator to use to compare elements
Returns:
the Element removed or null if no Element was removed
Throws:
NullPointerException - if the element is null, or has a null key

replace

public boolean replace(Element old,
                       Element element,
                       ElementValueComparator comparator)
                throws NullPointerException,
                       IllegalArgumentException
Unsupported in LruMemoryStore

Parameters:
old - Element to be test against
element - Element to be cached
comparator - ElementValueComparator to use to compare elements
Returns:
true is the Element was replaced
Throws:
NullPointerException - if the either Element is null or has a null key
IllegalArgumentException - if the two Element keys are non-null but not equal

replace

public Element replace(Element element)
                throws NullPointerException
Unsupported in LruMemoryStore

Parameters:
element - Element to be cached
Returns:
the Element previously cached for this key, or null if no Element was cached
Throws:
NullPointerException - if the Element is null or has a null key

ehcache

Copyright 2001-2014, Terracotta, Inc.