ehcache

net.sf.ehcache.store
Class MemoryStore

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

public class MemoryStore
extends java.lang.Object
implements Store

A Store implementation suitable for fast, concurrent in memory stores. The policy is determined by that configured in the cache.

Version:
$Id: MemoryStore.java 978 2009-06-16 23:29:59Z gregluck $
Author:
Surya Suravarapu

Field Summary
protected  Ehcache cache
          The cache this store is associated with.
protected static int CONCURRENCY_LEVEL
          Set optimisation for 100 concurrent threads.
protected static float DEFAULT_LOAD_FACTOR
          This is the default from ConcurrentHashMap.
protected  Store diskStore
          The DiskStore associated with this MemoryStore.
protected  java.util.Map map
          Map where items are stored by key.
protected  int maximumSize
          The maximum size of the store
protected  Policy policy
          The eviction policy to use
protected  Status status
          status.
protected static int TOO_LARGE_TO_EFFICIENTLY_ITERATE
          This number is magic.
protected  boolean useKeySample
          when sampling elements, whether to iterate or to use the keySample array for faster random access
 
Constructor Summary
protected MemoryStore(Ehcache cache, Store diskStore)
          Constructs things that all MemoryStores have in common.
 
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(java.lang.Object key)
          A check to see if a key is in the Store.
static MemoryStore create(Ehcache cache, Store diskStore)
          A factory method to create a MemoryStore.
protected  void determineEvictionPolicy(Ehcache cache)
          Chooses the Policy from the cache configuration
 void dispose()
          Prepares for shutdown.
protected  void doPut(Element elementJustAdded)
          Puts an element into the store
protected  void evict(Element element)
          Evict the Element.
 void expireElements()
          Expire all elsments.
protected  Element findEvictionCandidate(Element elementJustAdded)
          Find a "relatively" unused element, but not the element just added.
 void flush()
          Flush to disk only if the cache is diskPersistent.
 Element get(java.lang.Object key)
          Gets an item from the cache.
 Policy getEvictionPolicy()
           
 java.lang.Object[] getKeyArray()
          Gets an Array of the keys for all elements in the memory cache.
 Element getQuiet(java.lang.Object key)
          Gets an item from the cache, without updating statistics.
 int getSize()
          Returns the current store size.
 long getSizeInBytes()
          Measures the size of the memory store by measuring the serialized size of all elements.
 Status getStatus()
          Gets the status of the MemoryStore.
protected  int incrementIndex()
          A bounds-safe incrementer, which loops back to zero when it exceeds the array size
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.
 void put(Element element)
          Puts an item in the store.
 Element remove(java.lang.Object key)
          Removes an Element from the store.
 void removeAll()
          Remove all of the elements from the store.
protected  void removeElementChosenByEvictionPolicy(Element elementJustAdded)
          Removes the element chosen by the eviction policy
protected  Element[] sampleElements(int size)
          Uses random numbers to sample the entire map.
protected  Element[] sampleElementsViaKeyArray()
          Uses random numbers to sample the entire map.
protected  void saveKey(Element elementJustAdded)
          Saves the key to our fast access AtomicReferenceArray
 void setEvictionPolicy(Policy policy)
          Sets the policy.
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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TOO_LARGE_TO_EFFICIENTLY_ITERATE

protected static final int TOO_LARGE_TO_EFFICIENTLY_ITERATE
This number is magic. It was established using empirical testing of the two approaches in CacheTest#testConcurrentReadWriteRemoveLFU. 5000 is the cross over point between the two algorithms.

See Also:
Constant Field Values

DEFAULT_LOAD_FACTOR

protected static final float DEFAULT_LOAD_FACTOR
This is the default from ConcurrentHashMap. It should never be used, because we size the map to the max size of the store.

See Also:
Constant Field Values

CONCURRENCY_LEVEL

protected static final int CONCURRENCY_LEVEL
Set optimisation for 100 concurrent threads.

See Also:
Constant Field Values

policy

protected Policy policy
The eviction policy to use


useKeySample

protected boolean useKeySample
when sampling elements, whether to iterate or to use the keySample array for faster random access


cache

protected Ehcache cache
The cache this store is associated with.


map

protected java.util.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 int maximumSize
The maximum size of the store

Constructor Detail

MemoryStore

protected MemoryStore(Ehcache cache,
                      Store diskStore)
Constructs things that all MemoryStores have in common.

Parameters:
cache -
diskStore -
Method Detail

create

public static MemoryStore create(Ehcache cache,
                                 Store diskStore)
A factory method to create a MemoryStore.

Parameters:
cache -
diskStore -
Returns:
an instance of a MemoryStore, configured with the appropriate eviction policy

put

public final void put(Element element)
               throws CacheException
Puts an item in the store. Note that this automatically results in an eviction if the store is full.

Specified by:
put in interface Store
Parameters:
element - the element to add
Throws:
CacheException

get

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

The last access time in Element is updated.

Specified by:
get in interface Store
Parameters:
key - the cache key
Returns:
the element, or null if there was no match for the key

getQuiet

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

Specified by:
getQuiet in interface Store
Parameters:
key - the cache key
Returns:
the element, or null if there was no match for the key

remove

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

Specified by:
remove in interface Store
Parameters:
key - the key of the Element, usually a String
Returns:
the Element if one was found, else null

removeAll

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

Specified by:
removeAll in interface 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.

Specified by:
dispose in interface Store

flush

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

Specified by:
flush in interface Store

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 overflowToDisk 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.

Specified by:
getStatus in interface Store

getKeyArray

public final java.lang.Object[] getKeyArray()
Gets an Array of the keys for all elements in the memory cache.

Does not check for expired entries

Specified by:
getKeyArray in interface Store
Returns:
An Object[]

getSize

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

Specified by:
getSize in interface Store
Returns:
The size value

containsKey

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

Specified by:
containsKey in interface Store
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 measuring the serialized size of all elements. If the objects are not Serializable they count as 0.

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

Specified by:
getSizeInBytes in interface Store
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.

Specified by:
expireElements in interface Store

bufferFull

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

Specified by:
bufferFull in interface Store
Returns:
true if the store write buffer is backed up.

doPut

protected void doPut(Element elementJustAdded)
Puts an element into the store


saveKey

protected void saveKey(Element elementJustAdded)
Saves the key to our fast access AtomicReferenceArray

Parameters:
elementJustAdded - the new element

incrementIndex

protected int incrementIndex()
A bounds-safe incrementer, which loops back to zero when it exceeds the array size


removeElementChosenByEvictionPolicy

protected void removeElementChosenByEvictionPolicy(Element elementJustAdded)
Removes the element chosen by the eviction policy

Parameters:
elementJustAdded - it is possible for this to be null

findEvictionCandidate

protected final Element findEvictionCandidate(Element elementJustAdded)
Find a "relatively" unused element, but not the element just added.


sampleElementsViaKeyArray

protected Element[] sampleElementsViaKeyArray()
Uses random numbers to sample the entire map.

This implemenation uses a key array.

Returns:
a random sample of elements

sampleElements

protected Element[] sampleElements(int size)
Uses random numbers to sample the entire map.

This implemenation uses the ConcurrentHashMap iterator.

Returns:
a random sample of elements

determineEvictionPolicy

protected void determineEvictionPolicy(Ehcache cache)
Chooses the Policy from the cache configuration

Parameters:
cache -

getEvictionPolicy

public Policy getEvictionPolicy()
Specified by:
getEvictionPolicy in interface Store
Returns:
the active eviction policy.
See Also:
Store.setEvictionPolicy(Policy)

setEvictionPolicy

public void setEvictionPolicy(Policy policy)
Sets the policy. Use this method to inject a custom policy. This can be done while the store is alive.

Specified by:
setEvictionPolicy in interface Store
Parameters:
policy - a new policy to be used in evicting elements in this store

ehcache

true