Package net.sf.ehcache.store

Interface Store

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CLUSTER_COHERENT
      clusterCoherent property
      static java.lang.String NODE_COHERENT
      nodeCoherent property

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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​(java.lang.Object key)
      A check to see if a key is in the Store.
      boolean containsKeyInMemory​(java.lang.Object key)
      A check to see if a key is in the Store and is currently held in memory.
      boolean containsKeyOffHeap​(java.lang.Object key)
      A check to see if a key is in the Store and is currently held off-heap.
      boolean containsKeyOnDisk​(java.lang.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​(java.lang.Object key)
      Gets an item from the cache.
      java.util.Map<java.lang.Object,​Element> getAll​(java.util.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
      java.util.Map<java.lang.Object,​Element> getAllQuiet​(java.util.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.
      java.lang.Object getInternalContext()
      This should not be used, and will generally return null
      java.util.List getKeys()
      Gets an Array of the keys for all elements in the disk store.
      java.lang.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​(java.lang.Object key)
      Gets an Element from the Store, without updating statistics
      <T> Attribute<T> getSearchAttribute​(java.lang.String attributeName)
      Retrieve the given named search attribute
      java.util.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​(java.util.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​(java.lang.Object key)
      Recalculate size of the element mapped to the key
      Element remove​(java.lang.Object key)
      Removes an item from the cache.
      void removeAll()
      Remove all of the elements from the store.
      void removeAll​(java.util.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​(java.lang.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​(java.util.Map<java.lang.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 java.lang.String CLUSTER_COHERENT
        clusterCoherent property
        See Also:
        Constant Field Values

      • NODE_COHERENT

        static final java.lang.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​(java.util.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​(java.lang.Object key)
        Gets an item from the cache.

      • getQuiet

        Element getQuiet​(java.lang.Object key)
        Gets an Element from the Store, without updating statistics
        Returns:
        The element

      • getKeys

        java.util.List getKeys()
        Gets an Array of the keys for all elements in the disk store.
        Returns:
        An List of Serializable keys

      • remove

        Element remove​(java.lang.Object key)
        Removes an item from the cache.
        Since:
        signature changed in 1.2 from boolean to Element to support notifications

      • removeAll

        void removeAll​(java.util.Collection<?> keys)
        Removes a collection of elements from the cache.

      • 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 java.lang.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:
        java.lang.NullPointerException - if the element is null, or has a null key

      • removeElement

        Element removeElement​(Element element,
                      ElementValueComparator comparator)
               throws java.lang.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:
        java.lang.NullPointerException - if the element is null, or has a null key

      • replace

        boolean replace​(Element old,
                Element element,
                ElementValueComparator comparator)
         throws java.lang.NullPointerException,
                java.lang.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:
        java.lang.NullPointerException - if the either Element is null or has a null key
        java.lang.IllegalArgumentException - if the two Element keys are non-null but not equal

      • replace

        Element replace​(Element element)
         throws java.lang.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:
        java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.io.IOException
        Flush elements to persistent store.
        Throws:
        java.io.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

        java.lang.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 java.lang.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:
        java.lang.UnsupportedOperationException - if this store does not support cache coherence, like RMI replication
        TerracottaNotRunningException
        Since:
        2.0

      • waitUntilClusterCoherent

        void waitUntilClusterCoherent()
                       throws java.lang.UnsupportedOperationException,
                              TerracottaNotRunningException,
                              java.lang.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:
        java.lang.UnsupportedOperationException - if this store does not support cache coherence, like RMI replication
        java.lang.InterruptedException
        TerracottaNotRunningException
        Since:
        2.0

      • getMBean

        java.lang.Object getMBean()
        Optional implementation specific MBean exposed by the store.
        Returns:
        implementation specific management bean

      • setAttributeExtractors

        void setAttributeExtractors​(java.util.Map<java.lang.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 -

      • getSearchAttributes

        java.util.Set<Attribute> getSearchAttributes()
        Returns:
        all search attributes known to this store at the time of invoking the method

      • getSearchAttribute

        <T> Attribute<T> getSearchAttribute​(java.lang.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

        java.util.Map<java.lang.Object,​Element> getAllQuiet​(java.util.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

        java.util.Map<java.lang.Object,​Element> getAll​(java.util.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​(java.lang.Object key)
        Recalculate size of the element mapped to the key
        Parameters:
        key - the key