Package net.sf.ehcache

Interface Ehcache

    • Method Detail

      • put

        void put​(Element element)
  throws java.lang.IllegalArgumentException,
         java.lang.IllegalStateException,
         CacheException
        Put an element in the cache.

        Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

        Also notifies the CacheEventListener that:

        • the element was put, but only if the Element was actually put.
        • if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested
        Parameters:
        element - An object. If Serializable it can fully participate in replication and the DiskStore.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.IllegalArgumentException - if the element is null
        CacheException - a runtime cache exception

      • putAll

        void putAll​(java.util.Collection<Element> elements)
     throws java.lang.IllegalArgumentException,
            java.lang.IllegalStateException,
            CacheException
        Puts a collection of elements in to the cache.

        This method will throw a NullPointerException if a null element or null key is encountered in the collection, and a partial completion may result (as only some of the elements may have been put).

        For each element that is put the registered CacheEventListeners are notified of a newly put item (notifyElementPut(...)) regardless of whether the individual put is a new put or an update.

        Parameters:
        elements - the collection of elements to be put in the cache.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException - a runtime cache exception
        java.lang.IllegalArgumentException

      • put

        void put​(Element element,
         boolean doNotNotifyCacheReplicators)
  throws java.lang.IllegalArgumentException,
         java.lang.IllegalStateException,
         CacheException
        Put an element in the cache.

        Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

        Also notifies the CacheEventListener that:

        • the element was put, but only if the Element was actually put.
        • if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested
        Parameters:
        element - An object. If Serializable it can fully participate in replication and the DiskStore.
        doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.IllegalArgumentException - if the element is null
        CacheException

      • putQuiet

        void putQuiet​(Element element)
       throws java.lang.IllegalArgumentException,
              java.lang.IllegalStateException,
              CacheException
        Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used in conjunction with getQuiet(java.io.Serializable)
        Parameters:
        element - An object. If Serializable it can fully participate in replication and the DiskStore.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.IllegalArgumentException - if the element is null
        CacheException

      • putWithWriter

        void putWithWriter​(Element element)
            throws java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException,
                   CacheException
        Put an element in the cache writing through a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.

        Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

        Also notifies the CacheEventListener, if the writer operation succeeds, that:

        • the element was put, but only if the Element was actually put.
        • if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested
        Parameters:
        element - An object. If Serializable it can fully participate in replication and the DiskStore.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.IllegalArgumentException - if the element is null
        CacheException - if no CacheWriter was registered

      • putIfAbsent

        Element putIfAbsent​(Element element)
             throws java.lang.NullPointerException
        Put an element in the cache 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

      • putIfAbsent

        Element putIfAbsent​(Element element,
                    boolean doNotNotifyCacheReplicators)
             throws java.lang.NullPointerException
        Put an element in the cache if no element is currently mapped to the elements key.
        Parameters:
        element - element to be added
        doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
        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

        boolean removeElement​(Element element)
               throws java.lang.NullPointerException
        Remove the Element mapped to the key for the supplied element if the value of the supplied Element compares equal to the value of the cached Element.

        This is equivalent to 

           if (elementValueComparator.equals(cache.get(element.getObjectKey()), element)) {
       return cache.remove(element.getObjectKey());
   } else return false;
        except that the action is performed atomically.
        Parameters:
        element - Element to be removed
        Returns:
        true if the value was removed
        Throws:
        java.lang.NullPointerException - if the element is null, or has a null key
        See Also:
        CacheConfiguration.addElementValueComparator(net.sf.ehcache.config.ElementValueComparatorConfiguration)

      • replace

        boolean replace​(Element old,
                Element element)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException
        Replace the cached element only if the current Element is equal to the supplied old Element.
        Parameters:
        old - Element to be test against
        element - Element to be cached
        Returns:
        true if 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

      • get

        Element get​(java.io.Serializable key)
     throws java.lang.IllegalStateException,
            CacheException
        Gets an element from the cache. Updates Element Statistics

        Note that the Element's lastAccessTime is always the time of this get. Use getQuiet(Object) to peak into the Element to see its last access time with get

        Parameters:
        key - a serializable value
        Returns:
        the element, or null, if it does not exist.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException
        See Also:
        isExpired(net.sf.ehcache.Element)

      • get

        Element get​(java.lang.Object key)
     throws java.lang.IllegalStateException,
            CacheException
        Gets an element from the cache. Updates Element Statistics

        Note that the Element's lastAccessTime is always the time of this get. Use getQuiet(Object) to peek into the Element to see its last access time with get

        Parameters:
        key - an Object value
        Returns:
        the element, or null, if it does not exist.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException
        Since:
        1.2
        See Also:
        isExpired(net.sf.ehcache.Element)

      • getAll

        java.util.Map<java.lang.Object,​Element> getAll​(java.util.Collection<?> keys)
                                              throws java.lang.IllegalStateException,
                                                     CacheException,
                                                     java.lang.NullPointerException
        Gets all the elements from the cache for the keys provided. Updates Element Statistics Throws a NullPointerException if any key in the collection is null

        Note that the Element's lastAccessTime is always the time of this get. Use getQuiet(Object) to peek into the Element to see its last access time with get

        Parameters:
        keys - a collection of keys for which value is to be fetched
        Returns:
        Map of key and elements for the provided keys, value will be null for the keys which do not exist
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.NullPointerException - if any key is null in the collection
        CacheException
        See Also:
        isExpired(net.sf.ehcache.Element)

      • getQuiet

        Element getQuiet​(java.io.Serializable key)
          throws java.lang.IllegalStateException,
                 CacheException
        Gets an element from the cache, without updating Element statistics. Cache statistics are still updated.

        Parameters:
        key - a serializable value
        Returns:
        the element, or null, if it does not exist.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException
        Since:
        2.5
        See Also:
        isExpired(net.sf.ehcache.Element)

      • getQuiet

        Element getQuiet​(java.lang.Object key)
          throws java.lang.IllegalStateException,
                 CacheException
        Gets an element from the cache, without updating Element statistics. Cache statistics are also not updated.

        Parameters:
        key - a serializable value
        Returns:
        the element, or null, if it does not exist.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException
        Since:
        1.2
        See Also:
        isExpired(net.sf.ehcache.Element)

      • getKeys

        java.util.List getKeys()
                throws java.lang.IllegalStateException,
                       CacheException
        Returns a list of all elements in the cache, whether or not they are expired.

        The returned keys are unique and can be considered a set.

        The List returned is not live. It is a copy.

        The time taken is O(n). For large caches - or caches with high-latency storage this method can take a very long time to complete, may cause timeouts if using features such NonStopCache or transactions, and is not guaranteed to give a consistent view of the cache entry set. Usage is highly discouraged.

        Returns:
        a list of Object keys
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException

      • getKeysWithExpiryCheck

        java.util.List getKeysWithExpiryCheck()
                               throws java.lang.IllegalStateException,
                                      CacheException
        Returns a list of all elements in the cache. Only keys of non-expired elements are returned.

        The returned keys are unique and can be considered a set.

        The List returned is not live. It is a copy.

        For large caches - or caches with high-latency storage this method can take a very long time to complete. You should seriously consider whether your usage requires checking for expired keys before choosing to call this method. As this method can take a long time the results may also be significantly out of date by the time the method returns.

        Returns:
        a list of Object keys
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException

      • getKeysNoDuplicateCheck

        @Deprecated
java.util.List getKeysNoDuplicateCheck()
                                throws java.lang.IllegalStateException
        Deprecated.
        versions since 2.1 do not return duplicates
        Returns a list of all elements in the cache, whether or not they are expired.

        The returned keys are not unique and may contain duplicates. If the cache is only using the memory store, the list will be unique. If the disk store is being used as well, it will likely contain duplicates, because of the internal store design.

        The List returned is not live. It is a copy.

        The time taken is O(log n). On a single cpu 1.8Ghz P4, approximately 6ms is required for 1000 entries and 36 for 50000.

        This is the fastest getKeys method

        Returns:
        a list of Object keys
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • remove

        boolean remove​(java.io.Serializable key)
        throws java.lang.IllegalStateException
        Removes an Element from the Cache. This also removes it from any stores it may be in.

        Also notifies the CacheEventListener after the element was removed.

        Parameters:
        key - the key of the element to remove
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • remove

        boolean remove​(java.lang.Object key)
        throws java.lang.IllegalStateException
        Removes an Element from the Cache. This also removes it from any stores it may be in.

        Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

        Parameters:
        key - the key of the element to remove
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        Since:
        1.2

      • removeAll

        void removeAll​(java.util.Collection<?> keys)
        throws java.lang.IllegalStateException,
               java.lang.NullPointerException
        Removes given set of Element from the Cache. This also removes them from any stores it may be in. Throws a NullPointerException if any key in the collection is null

        Also notifies the CacheEventListener after the elements were removed. Notification is sent for every key irrespective of whether the key was present in the cache or not This operation is partially completed if any element or any key is null

        Parameters:
        keys - a collection of keys to operate on
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.NullPointerException - if any key is null in the collection

      • removeAll

        void removeAll​(java.util.Collection<?> keys,
               boolean doNotNotifyCacheReplicators)
        throws java.lang.IllegalStateException,
               java.lang.NullPointerException
        Removes all cached items.

        When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

        Parameters:
        keys - a collection of keys to operate on
        doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.NullPointerException

      • remove

        boolean remove​(java.io.Serializable key,
               boolean doNotNotifyCacheReplicators)
        throws java.lang.IllegalStateException
        Removes an Element from the Cache. This also removes it from any stores it may be in.

        Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

        Parameters:
        key - the key of the element to remove
        doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • remove

        boolean remove​(java.lang.Object key,
               boolean doNotNotifyCacheReplicators)
        throws java.lang.IllegalStateException
        Removes an Element from the Cache. This also removes it from any stores it may be in.

        Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

        Parameters:
        key - of the element to remove
        doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • removeQuiet

        boolean removeQuiet​(java.io.Serializable key)
             throws java.lang.IllegalStateException
        Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

        Parameters:
        key - of the element to remove
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • removeQuiet

        boolean removeQuiet​(java.lang.Object key)
             throws java.lang.IllegalStateException
        Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.
        Parameters:
        key - of the element to remove
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        Since:
        1.2

      • removeWithWriter

        boolean removeWithWriter​(java.lang.Object key)
                  throws java.lang.IllegalStateException,
                         CacheException
        Removes an Element from the Cache and any stores it might be in. This also removes through to a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.

        Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

        Parameters:
        key - of the element to remove
        Returns:
        true if the element was removed, false if it was not found in the cache
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException - if no CacheWriter was registered
        Since:
        2.0

      • removeAll

        void removeAll​(boolean doNotNotifyCacheReplicators)
        throws java.lang.IllegalStateException,
               CacheException
        Removes all cached items.

        When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

        Parameters:
        doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException

      • flush

        void flush()
    throws java.lang.IllegalStateException,
           CacheException
        Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException

      • getSize

        int getSize()
     throws java.lang.IllegalStateException,
            CacheException
        Gets the size of the cache. This is a subtle concept. See below.

        The size is the number of Elements in the MemoryStore plus the number of Elements in the DiskStore.

        This number is the actual number of elements, including expired elements that have not been removed.

        Expired elements are removed from the the memory store when getting an expired element, or when attempting to spool an expired element to disk.

        Expired elements are removed from the disk store when getting an expired element, or when the expiry thread runs, which is once every five minutes.

        To get an exact size, which would exclude expired elements, use getKeysWithExpiryCheck().size(), although see that method for the approximate time that would take.

        To get a very fast result, use getKeysNoDuplicateCheck().size(). If the disk store is being used, there will be some duplicates.

        Note:getSize() is a very expensive operation in off-heap, disk and Terracotta implementations.

        Returns:
        The size value
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        CacheException

      • calculateInMemorySize

        @Deprecated
long calculateInMemorySize()
                    throws java.lang.IllegalStateException,
                           CacheException
        Deprecated.
        Gets the size of the memory store for this cache

        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 approximate size of the memory store in bytes
        Throws:
        java.lang.IllegalStateException
        CacheException

      • calculateOffHeapSize

        @Deprecated
long calculateOffHeapSize()
                   throws java.lang.IllegalStateException,
                          CacheException
        Deprecated.
        Gets the size of the off-heap store for this cache
        Returns:
        the size of the off-heap store in bytes
        Throws:
        java.lang.IllegalStateException
        CacheException

      • calculateOnDiskSize

        @Deprecated
long calculateOnDiskSize()
                  throws java.lang.IllegalStateException,
                         CacheException
        Deprecated.
        Gets the size of the on-disk store for this cache
        Returns:
        the size of the on-disk store in bytes
        Throws:
        java.lang.IllegalStateException
        CacheException

      • hasAbortedSizeOf

        boolean hasAbortedSizeOf()
        Check if the cache may contain elements which the SizeOf engine could not fully size.
        Returns:
        true if the cache may contain partially sized objects

      • getMemoryStoreSize

        @Deprecated
long getMemoryStoreSize()
                 throws java.lang.IllegalStateException
        Deprecated.
        Returns the number of elements in the memory store.
        Returns:
        the number of elements in the memory store
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • getOffHeapStoreSize

        @Deprecated
long getOffHeapStoreSize()
                  throws java.lang.IllegalStateException
        Deprecated.
        Returns the number of elements in the off-heap store.
        Returns:
        the number of elements in the off-heap store
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • getDiskStoreSize

        @Deprecated
int getDiskStoreSize()
              throws java.lang.IllegalStateException
        Deprecated.
        Returns the number of elements in the disk store.
        Returns:
        the number of elements in the disk store.
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • getStatus

        Status getStatus()
        Gets the status attribute of the Cache.
        Returns:
        The status value from the Status enum class

      • getName

        java.lang.String getName()
        Gets the cache name.
        Returns:
        the name

      • setName

        void setName​(java.lang.String name)
        Sets the cache name which will name.
        Parameters:
        name - the name of the cache. Should not be null.

      • toString

        java.lang.String toString()
        Returns a String representation of Cache.
        Overrides:
        toString in class java.lang.Object

      • isExpired

        boolean isExpired​(Element element)
           throws java.lang.IllegalStateException,
                  java.lang.NullPointerException
        Checks whether this cache element has expired.

        The element is expired if:

        1. the idle time is non-zero and has elapsed, unless the cache is eternal; or
        2. the time to live is non-zero and has elapsed, unless the cache is eternal; or
        3. the value of the element is null.
        Parameters:
        element - the element to check
        Returns:
        true if it has expired
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE
        java.lang.NullPointerException - if the element is null

      • clone

        java.lang.Object clone()
                throws java.lang.CloneNotSupportedException
        Clones a cache. This is only legal if the cache has not been initialized. At that point only primitives have been set and no MemoryStore or DiskStore has been created.

        A new, empty, RegisteredEventListeners is created on clone.

        Returns:
        an object of type Cache
        Throws:
        java.lang.CloneNotSupportedException - if it's not supported

      • getCacheEventNotificationService

        RegisteredEventListeners getCacheEventNotificationService()
        Use this to access the service in order to register and unregister listeners
        Returns:
        the RegisteredEventListeners instance for this cache.

      • isElementInMemory

        boolean isElementInMemory​(java.io.Serializable key)
        Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

        Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

        Parameters:
        key - the key of the element to remove
        Returns:
        true if an element matching the key is found in memory

      • isElementInMemory

        boolean isElementInMemory​(java.lang.Object key)
        Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

        Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

        Parameters:
        key - the key of the element to remove
        Returns:
        true if an element matching the key is found in memory
        Since:
        1.2

      • isElementOnDisk

        boolean isElementOnDisk​(java.io.Serializable key)
        Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

        Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

        Parameters:
        key - the key of the element to remove
        Returns:
        true if an element matching the key is found in the diskStore

      • isElementOnDisk

        boolean isElementOnDisk​(java.lang.Object key)
        Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

        Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

        Parameters:
        key - the key of the element to remove
        Returns:
        true if an element matching the key is found in the diskStore
        Since:
        1.2

      • getGuid

        java.lang.String getGuid()
        The GUID for this cache instance can be used to determine whether two cache instance references are pointing to the same cache.
        Returns:
        the globally unique identifier for this cache instance. This is guaranteed to be unique.
        Since:
        1.2

      • getCacheManager

        CacheManager getCacheManager()
        Gets the CacheManager managing this cache. For a newly created cache this will be null until it has been added to a CacheManager.
        Returns:
        the manager or null if there is none

      • evictExpiredElements

        void evictExpiredElements()
        Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.

        For large caches - or caches with high-latency storage this method can take a very long time to complete. You should seriously consider relying on some form of capacity eviction to control cache capacity over calling this method. As this method can take a long time the cache may not be fully purged of expired elements on return, since more elements may have expired during the call.

      • isKeyInCache

        boolean isKeyInCache​(java.lang.Object key)
        An inexpensive check to see if the key exists in the cache.

        Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

        Parameters:
        key - the key to check for
        Returns:
        true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.

      • isValueInCache

        boolean isValueInCache​(java.lang.Object value)
        An extremely expensive check to see if the value exists in the cache.
        Parameters:
        value - to check for
        Returns:
        true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.

      • getStatistics

        StatisticsGateway getStatistics()
                         throws java.lang.IllegalStateException
        Gets an immutable Statistics object representing the Cache statistics at the time.
        Returns:
        the statistics gateway
        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • setCacheManager

        void setCacheManager​(CacheManager cacheManager)
        Sets the CacheManager
        Parameters:
        cacheManager - the CacheManager for this cache to use.

      • getBootstrapCacheLoader

        BootstrapCacheLoader getBootstrapCacheLoader()
        Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.
        Returns:
        the BootstrapCacheLoader to use

      • setBootstrapCacheLoader

        void setBootstrapCacheLoader​(BootstrapCacheLoader bootstrapCacheLoader)
                      throws CacheException
        Sets the bootstrap cache loader.
        Parameters:
        bootstrapCacheLoader - the loader to be used
        Throws:
        CacheException - if this method is called after the cache is initialized

      • initialise

        void initialise()
        Newly created caches do not have a MemoryStore or a DiskStore.

        This method creates those and makes the cache ready to accept elements

        This method is not intended to be called explicitly, but rather is called implicitly by the cache's CacheManager instance during the cache initialization. Invoking this method directly will likely lead to breaking.

      • bootstrap

        void bootstrap()
        Bootstrap command. This must be called after the Cache is intialised, during CacheManager initialisation. If loads are synchronous, they will complete before the CacheManager initialise completes, otherwise they will happen in the background.

        This method is not intended to be called explicitly, but rather is called implicitly by the cache's CacheManager instance during the cache initialization. Invoking this method directly will likely lead to breaking.

      • dispose

        void dispose()
      throws java.lang.IllegalStateException
        Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.

        Should be invoked only by CacheManager.

        Throws:
        java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

      • getCacheConfiguration

        CacheConfiguration getCacheConfiguration()
        Gets the cache configuration this cache was created with.

        Things like listeners that are added dynamically are excluded.

        Returns:
        CacheConfiguration the cache configuration

      • registerCacheExtension

        void registerCacheExtension​(CacheExtension cacheExtension)
        Register a CacheExtension with the cache. It will then be tied into the cache lifecycle.

        If the CacheExtension is not initialised, initialise it.

        Parameters:
        cacheExtension - the cache extension

      • unregisterCacheExtension

        void unregisterCacheExtension​(CacheExtension cacheExtension)
        Unregister a CacheExtension with the cache. It will then be detached from the cache lifecycle.
        Parameters:
        cacheExtension - the cache extension

      • getRegisteredCacheExtensions

        java.util.List<CacheExtension> getRegisteredCacheExtensions()
        Returns:
        the cache extensions as a live list

      • setCacheExceptionHandler

        void setCacheExceptionHandler​(CacheExceptionHandler cacheExceptionHandler)
        Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
        Parameters:
        cacheExceptionHandler - the cache exception handler

      • getCacheExceptionHandler

        CacheExceptionHandler getCacheExceptionHandler()
        Returns:
        an ExceptionHandler on the Cache

      • registerCacheLoader

        void registerCacheLoader​(CacheLoader cacheLoader)
        Register a CacheLoader with the cache. It will then be tied into the cache lifecycle.

        The CacheLoader instance will be initialized when the cache itself is being initialized. Should the cache already be initialized, CacheLoader.init() will not be invoked. If the loader requires initialization, the user will have to call it manually before registering it with a Cache instance that's already alive

        Parameters:
        cacheLoader - A Cache Loader to register
        Since:
        While the javadoc has changed in 2.5.2, the behavior has not.

      • unregisterCacheLoader

        void unregisterCacheLoader​(CacheLoader cacheLoader)
        Unregister a CacheLoader with the cache. It will then be detached from the cache lifecycle.
        Parameters:
        cacheLoader - A Cache Loader to unregister

      • getRegisteredCacheLoaders

        java.util.List<CacheLoader> getRegisteredCacheLoaders()
        Returns:
        the cache loaders as a live list

      • registerDynamicAttributesExtractor

        void registerDynamicAttributesExtractor​(DynamicAttributesExtractor extractor)
        Allows user to register a dynamic attribute extractor with a searchable cache that is dynamically indexable, as indicated by its configuration. Calling this method on such a cache is optional, but doing so more than once replaces previously registered extractor with the given one; i.e., there can be at most one extractor instance configured for each such cache. If the cache was not configured for dynamic indexing, an exception will be thrown
        Parameters:
        extractor - the dynamic attribute extractor

      • registerCacheWriter

        void registerCacheWriter​(CacheWriter cacheWriter)
        Register the CacheWriter for this cache. It will then be tied into the cache lifecycle.

        If the CacheWriter is not initialised, initialise it.

        Parameters:
        cacheWriter - A CacheWriter to register

      • unregisterCacheWriter

        void unregisterCacheWriter()
        Unregister the CacheWriter from the cache. It will then be detached from the cache lifecycle.

        If not CacheWriter was registered beforehand this operation has no effect.

      • getRegisteredCacheWriter

        CacheWriter getRegisteredCacheWriter()
        Retrieves the CacheWriter that was registered for this cache.
        Returns:
        the registered CacheWriter; or null if none was registered before

      • getWithLoader

        Element getWithLoader​(java.lang.Object key,
                      CacheLoader loader,
                      java.lang.Object loaderArgument)
               throws CacheException
        This method will return, from the cache, the object associated with the argument "key".

        If the object is not in the cache, the associated cache loader will be called. That is either the CacheLoader passed in, or if null, the one associated with the cache. If both are null, no load is performed and null is returned.

        Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.

        Parameters:
        key - key whose associated value is to be returned.
        loader - the override loader to use. If null, the cache's default loader will be used
        loaderArgument - an argument to pass to the CacheLoader.
        Returns:
        an element if it existed or could be loaded, otherwise null
        Throws:
        CacheException - a runtime cache exception

      • getAllWithLoader

        java.util.Map getAllWithLoader​(java.util.Collection keys,
                               java.lang.Object loaderArgument)
                        throws CacheException
        The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

        Note. If the getAll exceeds the maximum cache size, the returned map will necessarily be less than the number specified.

        Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.

        The constructs package provides similar functionality using the decorator SelfPopulatingCache

        Parameters:
        keys - a collection of keys to be returned/loaded
        loaderArgument - an argument to pass to the CacheLoader.
        Returns:
        a Map populated from the Cache. If there are no elements, an empty Map is returned.
        Throws:
        CacheException - a runtime cache exception

      • load

        void load​(java.lang.Object key)
   throws CacheException
        The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified object into the cache using the associated cacheloader. If the object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the load method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

        The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

        Parameters:
        key - key whose associated value to be loaded using the associated cacheloader if this cache doesn't contain it.
        Throws:
        CacheException - a runtime cache exception

      • loadAll

        void loadAll​(java.util.Collection keys,
             java.lang.Object argument)
      throws CacheException
        The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load the specified objects into the cache using the associated cache loader. If the an object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) should be logged. The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method.

        Parameters:
        keys - - collection of the keys whose associated values to be loaded into this cache by using the associated cacheloader if this cache doesn't contain them.
        argument - can be anything that makes sense to the loader

        The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

        Throws:
        CacheException

      • isDisabled

        boolean isDisabled()
        Whether this cache is disabled. "Disabled" means:
        1. bootstrap is disabled
        2. puts are discarded
        3. putQuites are discarded
        In all other respects the cache continues as it is.

        You can disable and enable a cache programmatically through the setDisabled(boolean) method.

        Returns:
        true if the cache is disabled.

      • setDisabled

        void setDisabled​(boolean disabled)
        Disables or enables this cache. This call overrides the previous value of disabled.
        Parameters:
        disabled - true if you wish to disable, false to enable
        See Also:
        isDisabled()

      • getInternalContext

        java.lang.Object getInternalContext()
        This should not be used
        Returns:
        some internal context (generally will be null)

      • disableDynamicFeatures

        void disableDynamicFeatures()
        Disables dynamic configuration and disable/enable for this cache.

        This is a one time operation. Once an Ehcache instance has had its dynamic operations disabled they cannot be re-enabled.

      • getWriterManager

        CacheWriterManager getWriterManager()
        Obtain the writer manager that's used by this cache instance.
        Returns:
        the writer manager that's set up for this cache

      • isNodeCoherent

        @Deprecated
boolean isNodeCoherent()
                throws TerracottaNotRunningException
        Deprecated.
        Use isNodeBulkLoadEnabled() instead
        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

      • setNodeCoherent

        @Deprecated
void setNodeCoherent​(boolean coherent)
              throws java.lang.UnsupportedOperationException,
                     TerracottaNotRunningException
        Deprecated.
        Use setNodeBulkLoadEnabled(boolean) instead
        Sets the cache in coherent or incoherent mode depending on the parameter on this node. 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

        When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the config.

        Parameters:
        coherent - true transitions to coherent mode, false to incoherent mode
        Throws:
        java.lang.UnsupportedOperationException - if this cache does not support coherence, like RMI replication
        TerracottaNotRunningException

      • waitUntilClusterCoherent

        @Deprecated
void waitUntilClusterCoherent()
                       throws java.lang.UnsupportedOperationException,
                              TerracottaNotRunningException
        Deprecated.
        Use waitUntilClusterBulkLoadComplete() instead
        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 cache does not support coherence, like RMI replication
        TerracottaNotRunningException

      • setTransactionManagerLookup

        void setTransactionManagerLookup​(TransactionManagerLookup transactionManagerLookup)
        This class is used to access the transaction manager used during XA.
        Parameters:
        transactionManagerLookup - the transactionManagerLookup

      • addPropertyChangeListener

        void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Add a PropertyChangeListener.
        Parameters:
        listener - the listener to add

      • removePropertyChangeListener

        void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Remove a PropertyChangeListener.
        Parameters:
        listener - the listener to remove

      • getSearchAttribute

        <T> Attribute<T> getSearchAttribute​(java.lang.String attributeName)
                             throws CacheException
        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
        Throws:
        CacheException - if no such attribute is defined for the given name

      • getSearchAttributes

        java.util.Set<Attribute> getSearchAttributes()
                                      throws CacheException
        Returns:
        set of all search attributes in effect at the time of calling this method
        Throws:
        CacheException - a runtime cache exception

      • createQuery

        Query createQuery()
        Create a new query builder for this cache
        Returns:
        a new query builder

      • isSearchable

        boolean isSearchable()
        Is this cache searchable?
        Returns:
        true if this cache is searchable

      • acquireReadLockOnKey

        void acquireReadLockOnKey​(java.lang.Object key)
        Acquires the proper read lock for a given cache key
        Parameters:
        key - - The key that retrieves a value that you want to protect via locking

      • acquireWriteLockOnKey

        void acquireWriteLockOnKey​(java.lang.Object key)
        Acquires the proper write lock for a given cache key
        Parameters:
        key - - The key that retrieves a value that you want to protect via locking

      • tryReadLockOnKey

        boolean tryReadLockOnKey​(java.lang.Object key,
                         long timeout)
                  throws java.lang.InterruptedException
        Try to get a read lock on a given key. If can't get it in timeout millis then return a boolean telling that it didn't get the lock
        Parameters:
        key - - The key that retrieves a value that you want to protect via locking
        timeout - - millis until giveup on getting the lock
        Returns:
        whether the lock was awarded
        Throws:
        java.lang.InterruptedException - if the thread was interrupted

      • tryWriteLockOnKey

        boolean tryWriteLockOnKey​(java.lang.Object key,
                          long timeout)
                   throws java.lang.InterruptedException
        Try to get a write lock on a given key. If can't get it in timeout millis then return a boolean telling that it didn't get the lock
        Parameters:
        key - - The key that retrieves a value that you want to protect via locking
        timeout - - millis until giveup on getting the lock
        Returns:
        whether the lock was awarded
        Throws:
        java.lang.InterruptedException - if the thread was interrupted

      • releaseReadLockOnKey

        void releaseReadLockOnKey​(java.lang.Object key)
        Release a held read lock for the passed in key
        Parameters:
        key - - The key that retrieves a value that you want to protect via locking

      • releaseWriteLockOnKey

        void releaseWriteLockOnKey​(java.lang.Object key)
        Release a held write lock for the passed in key
        Parameters:
        key - - The key that retrieves a value that you want to protect via locking

      • isReadLockedByCurrentThread

        boolean isReadLockedByCurrentThread​(java.lang.Object key)
                             throws java.lang.UnsupportedOperationException
        Returns true if a read lock for the key is held by the current thread
        Parameters:
        key - the key
        Returns:
        true if a read lock for the key is held by the current thread
        Throws:
        java.lang.UnsupportedOperationException - if querying the read lock state is not supported

      • isWriteLockedByCurrentThread

        boolean isWriteLockedByCurrentThread​(java.lang.Object key)
                              throws java.lang.UnsupportedOperationException
        Returns true if a write lock for the key is held by the current thread
        Parameters:
        key - the key
        Returns:
        true if a write lock for the key is held by the current thread
        Throws:
        java.lang.UnsupportedOperationException - if querying the write lock state is not supported

      • isClusterBulkLoadEnabled

        boolean isClusterBulkLoadEnabled()
                          throws java.lang.UnsupportedOperationException,
                                 TerracottaNotRunningException
        Returns true if at least one node in the cluster is in bulk-load mode. Returns false otherwise.

        NOTE: if isNodeBulkLoadEnabled() returns true, this method will always return true. Applies to caches clustered with Terracotta only.

        Returns:
        true if the cache is in bulk-load mode cluster-wide, false otherwise
        Throws:
        java.lang.UnsupportedOperationException - if the cache is not clustered with Terracotta
        TerracottaNotRunningException

      • isNodeBulkLoadEnabled

        boolean isNodeBulkLoadEnabled()
                       throws java.lang.UnsupportedOperationException,
                              TerracottaNotRunningException
        Returns true if the current node is in bulk-load mode. Returns false otherwise.

        NOTE: if this method returns true, isClusterBulkLoadEnabled() method will always return true. Applies to caches clustered with Terracotta only.

        Returns:
        true if the cache is in coherent mode cluster-wide, false otherwise
        Throws:
        java.lang.UnsupportedOperationException - if the cache is not clustered with Terracotta
        TerracottaNotRunningException

      • setNodeBulkLoadEnabled

        void setNodeBulkLoadEnabled​(boolean enabledBulkLoad)
                     throws java.lang.UnsupportedOperationException,
                            TerracottaNotRunningException
        Enable/disable bulk-load mode in this node for this cache. Calling setBulkLoadEnabled(true) when the cache is already in bulk-load mode or calling setBulkLoadEnabled(false) when already NOT in bulk-load mode will be a no-op.

        Applies to caches clustered with Terracotta only.

        When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

        Parameters:
        enabledBulkLoad - true enables bulk-load, false disables it if not already disabled
        Throws:
        java.lang.UnsupportedOperationException - if the cache is not clustered with Terracotta
        TerracottaNotRunningException

      • waitUntilClusterBulkLoadComplete

        void waitUntilClusterBulkLoadComplete()
                               throws java.lang.UnsupportedOperationException,
                                      TerracottaNotRunningException
        This method waits until all the connected nodes have disabled bulk-load. Or in other words, calling this method will block until all connected nodes in the cluster disables bulk-load. If none of the nodes did not enable bulk-load this method will return immediately

        Applies to caches clustered with Terracotta only.

        Throws:
        java.lang.UnsupportedOperationException - if the cache is not clustered with Terracotta
        TerracottaNotRunningException