net.sf.ehcache.store
Class MemoryStore

java.lang.Object
  net.sf.ehcache.store.AbstractStore
      net.sf.ehcache.store.MemoryStore

All Implemented Interfaces:

CacheConfigurationListener, Store

public class MemoryStore
extends AbstractStore
implements CacheConfigurationListener

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

Version:

$Id: MemoryStore.java 3250 2010-11-23 14:12:33Z lorban $

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 SelectableConcurrentHashMap	map Map where items are stored by key.
protected int	maximumSize The maximum size of the store (0 == no limit)
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

Fields inherited from interface net.sf.ehcache.store.Store

CLUSTER_COHERENT, NODE_COHERENT

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(Object key) A 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.
static MemoryStore	create(Ehcache cache, Store diskStore) A factory method to create a MemoryStore.
void	deregistered(CacheConfiguration config) Indicates that this listener was removed from the given configuration
protected Policy	determineEvictionPolicy() Chooses the Policy from the cache configuration
void	diskCapacityChanged(int oldCapacity, int newCapacity) Indicates a change in the configurations disk store capacity
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 elements.
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(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 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.
int	getTerracottaClusteredSize() Returns nothing since a disk store isn't clustered
boolean	isFull() An algorithm to tell if the MemoryStore is at or beyond its carrying capacity.
void	loggingChanged(boolean oldValue, boolean newValue) Indicates a change in the configuration for enable/disable logging
void	memoryCapacityChanged(int oldCapacity, int newCapacity) Indicates a change in the configurations memory store capacity
protected void	notifyExpiry(Element element) Before eviction elements are checked.
boolean	put(Element element) Puts an item in the store.
Element	putIfAbsent(Element element) Unsupported in MemoryStore
boolean	putWithWriter(Element element, CacheWriterManager writerManager) Puts an item into the store and the cache writer manager in an atomic operation
void	registered(CacheConfiguration config) Indicates that this listener was registered with the given configuration
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 MemoryStore
protected void	removeElementChosenByEvictionPolicy(Element elementJustAdded) Removes the element chosen by the eviction policy
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 MemoryStore
boolean	replace(Element old, Element element, ElementValueComparator comparator) Unsupported in MemoryStore
protected Element[]	sampleElements(int size) Uses random numbers to sample the entire map.
protected Element[]	sampleElements(Object keyHint) Uses random numbers to sample the entire map.
void	setEvictionPolicy(Policy policy) Sets the policy.
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.
void	timeToIdleChanged(long oldTti, long newTti) Indicates a change in the configurations time to idle
void	timeToLiveChanged(long oldTtl, long newTtl) Indicates a change in the configurations time to live

Methods inherited from class net.sf.ehcache.store.AbstractStore

addStoreListener, executeQuery, getEventListenerList, getSearchAttribute, isCacheCoherent, isClusterCoherent, isNodeCoherent, removeStoreListener, setAttributeExtractors, setNodeCoherent, waitUntilClusterCoherent

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. 5 is the cross over point between the two algorithms. In future we ditch iteration entirely

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

cache

protected Ehcache cache

The cache this store is associated with.

useKeySample

protected volatile boolean useKeySample

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

map

protected SelectableConcurrentHashMap map

Map where items are stored by key.

diskStore

protected final Store diskStore

The DiskStore associated with this MemoryStore.

maximumSize

protected volatile int maximumSize

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

status

protected volatile Status status

status.

policy

protected volatile Policy policy

The eviction policy to use

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 boolean 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

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

Specified by:

putWithWriter in interface Store

Returns:

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

Throws:

CacheException

get

public final Element get(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 key of the Element

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.

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

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.

Specified by:

removeWithWriter in interface Store

Throws:

CacheException

bufferFull

public final 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.

expireElements

public void expireElements()

Expire all elements.

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

Specified by:

expireElements in interface Store

determineEvictionPolicy

protected final Policy determineEvictionPolicy()

Chooses the Policy from the cache configuration

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

getKeys

public final List getKeys()

Gets an Array of the keys for all elements in the memory cache.

Does not check for expired entries

Specified by:

getKeys in interface Store

Returns:

An List

getSize

public final int getSize()

Returns the current store size.

Specified by:

getSize in interface Store

Returns:

The size value

getTerracottaClusteredSize

public final int getTerracottaClusteredSize()

Returns nothing since a disk store isn't clustered

Specified by:

getTerracottaClusteredSize in interface Store

Returns:

returns 0

containsKey

public final boolean containsKey(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

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:

• if, the store is diskPersistent, the Element is spooled to the DiskStore
• if not, the Element is removed.

Parameters:

element - the Element to be evicted.

Throws:

CacheException

notifyExpiry

protected final void notifyExpiry(Element element)

Before eviction elements are checked.

Parameters:

element -

isFull

public final boolean isFull()

An algorithm to tell if the MemoryStore is at or beyond its carrying capacity.

doPut

protected void doPut(Element elementJustAdded)

Puts an element into the store

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.

sampleElements

protected Element[] sampleElements(Object keyHint)

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 implementation uses the ConcurrentHashMap iterator.

Returns:

a random sample of elements

getEvictionPolicy

public Policy getEvictionPolicy()

Returns:

the active eviction 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.

Parameters:

policy - a new policy to be used in evicting elements in this store

getInternalContext

public Object getInternalContext()

This should not be used, and will generally return null

Specified by:

getInternalContext in interface Store

Returns:

some internal context (probably null)

getStatus

public final Status getStatus()

Gets the status of the MemoryStore.

Specified by:

getStatus in interface Store

timeToIdleChanged

public void timeToIdleChanged(long oldTti,
                              long newTti)

Indicates a change in the configurations time to idle

Specified by:

timeToIdleChanged in interface CacheConfigurationListener

Parameters:

oldTti - previous time to idle value

newTti - new time to idle value

timeToLiveChanged

public void timeToLiveChanged(long oldTtl,
                              long newTtl)

Indicates a change in the configurations time to live

Specified by:

timeToLiveChanged in interface CacheConfigurationListener

Parameters:

oldTtl - previous time to live value

newTtl - new time to live value

diskCapacityChanged

public void diskCapacityChanged(int oldCapacity,
                                int newCapacity)

Indicates a change in the configurations disk store capacity

Specified by:

diskCapacityChanged in interface CacheConfigurationListener

Parameters:

oldCapacity - previous capacity

newCapacity - new capacity

loggingChanged

public void loggingChanged(boolean oldValue,
                           boolean newValue)

Indicates a change in the configuration for enable/disable logging

Specified by:

loggingChanged in interface CacheConfigurationListener

Parameters:

oldValue - old value whether logging was enabled or not

newValue - new value whether logging was enabled or not

memoryCapacityChanged

public void memoryCapacityChanged(int oldCapacity,
                                  int newCapacity)

Indicates a change in the configurations memory store capacity

Specified by:

memoryCapacityChanged in interface CacheConfigurationListener

Parameters:

oldCapacity - previous capacity

newCapacity - new capacity

registered

public void registered(CacheConfiguration config)

Indicates that this listener was registered with the given configuration

Specified by:

registered in interface CacheConfigurationListener

deregistered

public void deregistered(CacheConfiguration config)

Indicates that this listener was removed from the given configuration

Specified by:

deregistered in interface CacheConfigurationListener

containsKeyInMemory

public boolean containsKeyInMemory(Object key)

A check to see if a key is in the Store and is currently held in memory.

Specified by:

containsKeyInMemory in interface Store

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.

Specified by:

containsKeyOffHeap in interface Store

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.

Specified by:

containsKeyOnDisk in interface Store

Parameters:

key - The Element key

Returns:

true if found. No check is made to see if the Element is expired.

getInMemoryEvictionPolicy

public Policy getInMemoryEvictionPolicy()

Specified by:

getInMemoryEvictionPolicy in interface Store

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

Specified by:

getInMemorySize in interface Store

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.

Specified by:

getInMemorySizeInBytes in interface Store

Returns:

the approximate in-memory size of the store in bytes

getOffHeapSize

public int getOffHeapSize()

Returns the current local off-heap store size

Specified by:

getOffHeapSize in interface Store

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.

Specified by:

getOffHeapSizeInBytes in interface Store

Returns:

the approximate off-heap size of the store in bytes

getOnDiskSize

public int getOnDiskSize()

Returns the current local on-disk store size

Specified by:

getOnDiskSize in interface Store

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.

Specified by:

getOnDiskSizeInBytes in interface Store

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.

Specified by:

setInMemoryEvictionPolicy in interface Store

Parameters:

policy - the new policy

putIfAbsent

public Element putIfAbsent(Element element)
                    throws NullPointerException

Unsupported in MemoryStore

Specified by:

putIfAbsent in interface Store

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 MemoryStore

Specified by:

removeElement in interface Store

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 MemoryStore

Specified by:

replace in interface Store

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 MemoryStore

Specified by:

replace in interface Store

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

getMBean

public Object getMBean()

Optional implementation specific MBean exposed by the store.

Specified by:

getMBean in interface Store

Returns:

implementation specific management bean