net.sf.ehcache.store
Interface Store

All Known Subinterfaces:

AuthoritativeTier, TerracottaStore

All Known Implementing Classes:

AbstractStore, AbstractTransactionStore, CacheStore, CopyingCacheStore, DiskStore, ElementIdAssigningStore, JtaLocalTransactionStore, LegacyStoreWrapper, LocalTransactionStore, LruMemoryStore, MemoryStore, TerracottaTransactionalCopyingCacheStore, TxCopyingCacheStore, XATransactionStore

public interface Store

This is the interface for all stores. A store is a physical counterpart to a cache, which is a logical concept.

Version:

$Id: Store.java 7824 2013-07-23 01:54:39Z vfunshte $

Author:

Greg Luck

Field Summary

static String	CLUSTER_COHERENT clusterCoherent property
static String	NODE_COHERENT nodeCoherent property

Method Summary

void	addStoreListener(StoreListener listener) Add a listener to the store.
boolean	bufferFull() Some store types, such as the disk stores can fill their write buffers if puts come in too fast.
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.
void	dispose() Prepares for shutdown.
Results	executeQuery(StoreQuery query) Execute the given query on this store
void	expireElements() Expire all elements.
void	flush() Flush elements to persistent store.
Element	get(Object key) Gets an item from the cache.
Map<Object,Element>	getAll(Collection<?> keys) Retries the elements associated with a set of keys and update the statistics Keys which are not present in the cache will have null values associated with them in the returned map
Map<Object,Element>	getAllQuiet(Collection<?> keys) Retries the elements associated with a set of keys without updating the statistics Keys which are not present in the cache will have null values associated with them in the returned map
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 disk store.
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 Element from the Store, without updating statistics
<T> Attribute<T>	getSearchAttribute(String attributeName) Retrieve the given named search attribute
Set<Attribute>	getSearchAttributes()
int	getSize() Returns the current local store size
Status	getStatus() Returns the cache status.
int	getTerracottaClusteredSize() Returns the current Terracotta clustered store size
boolean	hasAbortedSizeOf() Checks if the cache may contain elements for which the SizeOf engine gave up and only partially calculated the size.
boolean	isCacheCoherent() Indicates whether this store provides a coherent view of all the elements in a cache.
boolean	isClusterCoherent() Returns true if the cache is in coherent mode cluster-wide.
boolean	isNodeCoherent() Returns true if the cache is in coherent mode for the current node.
boolean	put(Element element) Puts an item into the store.
void	putAll(Collection<Element> elements) Puts a collection of elements into the store.
Element	putIfAbsent(Element element) Put an element in the store if no element is currently mapped to the elements key.
boolean	putWithWriter(Element element, CacheWriterManager writerManager) Puts an item into the store and the cache writer manager in an atomic operation
void	recalculateSize(Object key) Recalculate size of the element mapped to the key
Element	remove(Object key) Removes an item from the cache.
void	removeAll() Remove all of the elements from the store.
void	removeAll(Collection<?> keys) Removes a collection of elements from the cache.
Element	removeElement(Element element, ElementValueComparator comparator) Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.
void	removeStoreListener(StoreListener listener) Remove listener from store.
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) Replace the cached element only if an Element is currently cached for this key
boolean	replace(Element old, Element element, ElementValueComparator comparator) Replace the cached element only if the value of the current Element is equal to the value of the supplied old Element.
void	setAttributeExtractors(Map<String,AttributeExtractor> extractors) Inform this store of the configured attribute extractors.
void	setInMemoryEvictionPolicy(Policy policy) Sets the eviction policy strategy.
void	setNodeCoherent(boolean coherent) Sets the cache in coherent or incoherent mode for the current node depending on the parameter.
void	waitUntilClusterCoherent() This method waits until the cache is in coherent mode in all the connected nodes.

Field Detail

CLUSTER_COHERENT

static final String CLUSTER_COHERENT

clusterCoherent property

See Also:

Constant Field Values

NODE_COHERENT

static final String NODE_COHERENT

nodeCoherent property

See Also:

Constant Field Values

Method Detail

addStoreListener

void addStoreListener(StoreListener listener)

Add a listener to the store.

Parameters:

listener -

removeStoreListener

void removeStoreListener(StoreListener listener)

Remove listener from store.

Parameters:

listener -

put

boolean put(Element element)
            throws CacheException

Puts an item into the 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

putAll

void putAll(Collection<Element> elements)
            throws CacheException

Puts a collection of elements into the store.

Parameters:

elements - Collection of elements to be put in the store

Throws:

CacheException

putWithWriter

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

get

Element get(Object key)

Gets an item from the cache.

getQuiet

Element getQuiet(Object key)

Gets an Element from the Store, without updating statistics

Returns:

The element

getKeys

List getKeys()

Gets an Array of the keys for all elements in the disk store.

Returns:

An List of Serializable keys

remove

Element remove(Object key)

Removes an item from the cache.

Since:

signature changed in 1.2 from boolean to Element to support notifications

removeAll

void removeAll(Collection<?> keys)

Removes a collection of elements from the cache.

removeWithWriter

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

void removeAll()
               throws CacheException

Remove all of the elements from the store.

If there are registered CacheEventListeners they are notified of the expiry or removal of the Element as each is removed.

Throws:

CacheException

putIfAbsent

Element putIfAbsent(Element element)
                    throws NullPointerException

Put an element in the store if no element is currently mapped to the elements key.

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

Element removeElement(Element element,
                      ElementValueComparator comparator)
                      throws NullPointerException

Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element. This is a CAS operation. It is consistent even against a distributed cache that is not coherent. If the old value is stale when this operation is attempted the remove does not take place.

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

boolean replace(Element old,
                Element element,
                ElementValueComparator comparator)
                throws NullPointerException,
                       IllegalArgumentException

Replace the cached element only if the value of the current Element is equal to the value of the supplied old Element.

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

Element replace(Element element)
                throws NullPointerException

Replace the cached element only if an Element is currently cached for this key

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

dispose

void dispose()

Prepares for shutdown.

getSize

int getSize()

Returns the current local store size

Returns:

the count of the Elements in the Store on the local machine

getInMemorySize

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

getOffHeapSize

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

getOnDiskSize

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

getTerracottaClusteredSize

int getTerracottaClusteredSize()

Returns the current Terracotta clustered store size

Returns:

the count of the Elements in the Store across the cluster

getInMemorySizeInBytes

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

getOffHeapSizeInBytes

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

getOnDiskSizeInBytes

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

hasAbortedSizeOf

boolean hasAbortedSizeOf()

Checks if the cache may contain elements for which the SizeOf engine gave up and only partially calculated the size.

Returns:

true if at least one partially sized element may be in the cache

getStatus

Status getStatus()

Returns the cache status.

containsKey

boolean containsKey(Object key)

A check to see if a key is in the Store.

Parameters:

key - The Element key

Returns:

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

containsKeyOnDisk

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.

containsKeyOffHeap

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.

containsKeyInMemory

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.

expireElements

void expireElements()

Expire all elements.

flush

void flush()
           throws IOException

Flush elements to persistent store.

Throws:

IOException - if any IO error occurs

bufferFull

boolean bufferFull()

Some store types, such as the disk stores can fill their write buffers if puts come in too fast. The thread will wait for a short time before checking again.

Returns:

true if the store write buffer is backed up.

getInMemoryEvictionPolicy

Policy getInMemoryEvictionPolicy()

Returns:

the current eviction policy. This may not be the configured policy, if it has been dynamically set.

See Also:

setInMemoryEvictionPolicy(Policy)

setInMemoryEvictionPolicy

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

getInternalContext

Object getInternalContext()

This should not be used, and will generally return null

Returns:

some internal context (probably null)

isCacheCoherent

boolean isCacheCoherent()

Indicates whether this store provides a coherent view of all the elements in a cache. Note that this is same as calling isClusterCoherent() (introduced since 2.0) Use isNodeCoherent() to find out if the cache is coherent in the current node in the cluster

Returns:

true if the store is coherent; or false if the store potentially splits the cache storage with another store or isn't internally coherent

Since:

1.7

isClusterCoherent

boolean isClusterCoherent()
                          throws TerracottaNotRunningException

Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

Throws:

TerracottaNotRunningException

Since:

2.0

isNodeCoherent

boolean isNodeCoherent()
                       throws TerracottaNotRunningException

Returns true if the cache is in coherent mode for the current node. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

Throws:

TerracottaNotRunningException

Since:

2.0

setNodeCoherent

void setNodeCoherent(boolean coherent)
                     throws UnsupportedOperationException,
                            TerracottaNotRunningException

Sets the cache in coherent or incoherent mode for the current node depending on the parameter. Calling setNodeCoherent(true) when the cache is already in coherent mode or calling setNodeCoherent(false) when already in incoherent mode will be a no-op.

It applies to coherent clustering mechanisms only e.g. Terracotta

Parameters:

coherent - true transitions to coherent mode, false to incoherent mode

Throws:

UnsupportedOperationException - if this store does not support cache coherence, like RMI replication

TerracottaNotRunningException

Since:

2.0

waitUntilClusterCoherent

void waitUntilClusterCoherent()
                              throws UnsupportedOperationException,
                                     TerracottaNotRunningException,
                                     InterruptedException

This method waits until the cache is in coherent mode in all the connected nodes. If the cache is already in coherent mode it returns immediately

It applies to coherent clustering mechanisms only e.g. Terracotta

Throws:

UnsupportedOperationException - if this store does not support cache coherence, like RMI replication

InterruptedException

TerracottaNotRunningException

Since:

2.0

getMBean

Object getMBean()

Optional implementation specific MBean exposed by the store.

Returns:

implementation specific management bean

setAttributeExtractors

void setAttributeExtractors(Map<String,AttributeExtractor> extractors)

Inform this store of the configured attribute extractors. Stores that will not invoke extractors are free to ignore this call

Parameters:

extractors -

executeQuery

Results executeQuery(StoreQuery query)
                     throws SearchException

Execute the given query on this store

Parameters:

query - query to execute

Returns:

query results

Throws:

SearchException

getSearchAttributes

Set<Attribute> getSearchAttributes()

Returns:

all search attributes known to this store at the time of invoking the method

getSearchAttribute

<T> Attribute<T> getSearchAttribute(String attributeName)

Retrieve the given named search attribute

Type Parameters:

T - type of the attribute

Parameters:

attributeName - the name of the attribute to retrieve

Returns:

the search attribute or null if non-existent

getAllQuiet

Map<Object,Element> getAllQuiet(Collection<?> keys)

Retries the elements associated with a set of keys without updating the statistics Keys which are not present in the cache will have null values associated with them in the returned map

Parameters:

keys - a collection of keys to look for

Returns:

a map of keys and their corresponding values

getAll

Map<Object,Element> getAll(Collection<?> keys)

Retries the elements associated with a set of keys and update the statistics Keys which are not present in the cache will have null values associated with them in the returned map

Parameters:

keys - a collection of keys to look for

Returns:

a map of keys and their corresponding values

recalculateSize

void recalculateSize(Object key)

Recalculate size of the element mapped to the key

Parameters:

key - the key