Store (ehcache 2.10.9.2 API)

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 10789 2018-04-26 02:08:13Z adahanne $

Author:

Greg Luck

Field Summary

Fields
Modifier and Type Field and Description

static String CLUSTER_COHERENT
clusterCoherent property

static String NODE_COHERENT
nodeCoherent property

Fields
Modifier and Type	Field and Description
`static String`	`CLUSTER_COHERENT` clusterCoherent property
`static String`	`NODE_COHERENT` nodeCoherent property

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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

Interface Store

Field Summary

Method Summary

Field Detail

CLUSTER_COHERENT

NODE_COHERENT

Method Detail

addStoreListener

removeStoreListener

put

putAll

putWithWriter

get

getQuiet

getKeys

remove

removeAll

removeWithWriter

removeAll

putIfAbsent

removeElement

replace

replace

dispose

getSize

getInMemorySize

getOffHeapSize

getOnDiskSize

getTerracottaClusteredSize

getInMemorySizeInBytes

getOffHeapSizeInBytes

getOnDiskSizeInBytes

hasAbortedSizeOf

getStatus

containsKey

containsKeyOnDisk

containsKeyOffHeap

containsKeyInMemory

expireElements

flush

bufferFull

getInMemoryEvictionPolicy

setInMemoryEvictionPolicy

getInternalContext

isCacheCoherent

isClusterCoherent

isNodeCoherent

setNodeCoherent

waitUntilClusterCoherent

getMBean

setAttributeExtractors

executeQuery

getSearchAttributes

getSearchAttribute

getAllQuiet

getAll

recalculateSize