Package javax.cache

Interface Cache<K,​V>

  • Type Parameters:
    K - the type of key
    V - the type of value
    All Superinterfaces:
    AutoCloseable, Closeable, Iterable<Cache.Entry<K,​V>>

    public interface Cache<K,​V>
    extends Iterable<Cache.Entry<K,​V>>, Closeable
    A Cache is a Map-like data structure that provides temporary storage of application data.

    Like Maps, Caches

    1. store key-value pairs, each referred to as an Cache.Entry
    2. allow use of Java Generics to improve application type-safety
    3. are Iterable

    Unlike Maps, Caches

    1. do not allow null keys or values. Attempts to use null will result in a NullPointerException
    2. provide the ability to read values from a CacheLoader (read-through-caching) when a value being requested is not in a cache
    3. provide the ability to write values to a CacheWriter (write-through-caching) when a value being created/updated/removed from a cache
    4. provide the ability to observe cache entry changes
    5. may capture and measure operational statistics

    A simple example of how to use a cache is:

    
     String cacheName = "sampleCache";
     CachingProvider provider = Caching.getCachingProvider();
     CacheManager manager = provider.getCacheManager();
     Cache<Integer, Date> cache = manager.getCache(cacheName, Integer.class,
                                                         Date.class);
     Date value1 = new Date();
     Integer key = 1;
     cache.put(key, value1);
     Date value2 = cache.get(key);
     
    Since:
    1.0
    Author:
    Greg Luck, Yannis Cosmadopoulos, Brian Oliver
    • Method Detail

      • get

        V get​(K key)
        Gets an entry from the cache.

        If the cache is configured to use read-through, and get would return null because the entry is missing from the cache, the Cache's CacheLoader is called in an attempt to load the entry.

        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the element, or null, if it does not exist.
        Throws:
        IllegalStateException - if the cache is isClosed()
        NullPointerException - if the key is null
        CacheException - if there is a problem fetching the value
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
      • getAll

        Map<K,​V> getAll​(Set<? extends K> keys)
        Gets a collection of entries from the Cache, returning them as Map of the values associated with the set of keys requested.

        If the cache is configured read-through, and a get for a key would return null because an entry is missing from the cache, the Cache's CacheLoader is called in an attempt to load the entry. If an entry cannot be loaded for a given key, the key will not be present in the returned Map.

        Parameters:
        keys - The keys whose associated values are to be returned.
        Returns:
        A map of entries that were found for the given keys. Keys not found in the cache are not in the returned map.
        Throws:
        NullPointerException - if keys is null or if keys contains a null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem fetching the values
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
      • containsKey

        boolean containsKey​(K key)
        Determines if the Cache contains an entry for the specified key.

        More formally, returns true if and only if this cache contains a mapping for a key k such that key.equals(k). (There can be at most one such mapping.)

        If the cache is configured read-through the associated CacheLoader is not called. Only the cache is checked.

        Parameters:
        key - key whose presence in this cache is to be tested.
        Returns:
        true if this map contains a mapping for the specified key
        Throws:
        NullPointerException - if key is null
        IllegalStateException - if the cache is isClosed()
        CacheException - it there is a problem checking the mapping
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        Map.containsKey(Object)
      • loadAll

        void loadAll​(Set<? extends K> keys,
                     boolean replaceExistingValues,
                     CompletionListener completionListener)
        Asynchronously loads the specified entries into the cache using the configured CacheLoader for the given keys.

        If an entry for a key already exists in the Cache, a value will be loaded if and only if replaceExistingValues is true. If no loader is configured for the cache, no objects will be loaded. If a problem is encountered during the retrieving or loading of the objects, an exception is provided to the CompletionListener. Once the operation has completed, the specified CompletionListener is notified.

        Implementations may choose to load multiple keys from the provided Set in parallel. Iteration however must not occur in parallel, thus allow for non-thread-safe Sets to be used.

        The thread on which the completion listener is called is implementation dependent. An implementation may also choose to serialize calls to different CompletionListeners rather than use a thread per CompletionListener.

        Parameters:
        keys - the keys to load
        replaceExistingValues - when true existing values in the Cache will be replaced by those loaded from a CacheLoader
        completionListener - the CompletionListener (may be null)
        Throws:
        NullPointerException - if keys is null or if keys contains a null.
        IllegalStateException - if the cache is isClosed()
        CacheException - thrown if there is a problem performing the load. This may also be thrown on calling if there are insufficient threads available to perform the load.
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
      • getAndPut

        V getAndPut​(K key,
                    V value)
        Associates the specified value with the specified key in this cache, returning an existing value if one existed.

        If the cache previously contained a mapping for the key, the old value is replaced by the specified value. (A cache c is said to contain a mapping for a key k if and only if c.containsKey(k) would return true.)

        The previous value is returned, or null if there was no value associated with the key previously.

        If the cache is configured write-through the associated CacheWriter.write(Cache.Entry) method will be called.

        Parameters:
        key - key with which the specified value is to be associated
        value - value to be associated with the specified key
        Returns:
        the value associated with the key at the start of the operation or null if none was associated
        Throws:
        NullPointerException - if key is null or if value is null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem doing the put
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        put(Object, Object), getAndReplace(Object, Object), CacheWriter.write(Cache.Entry)
      • putIfAbsent

        boolean putIfAbsent​(K key,
                            V value)
        Atomically associates the specified key with the given value if it is not already associated with a value.

        This is equivalent to:

        
         if (!cache.containsKey(key)) {}
           cache.put(key, value);
           return true;
         } else {
           return false;
         }
         
        except that the action is performed atomically.

        If the cache is configured write-through, and this method returns true, the associated CacheWriter.write(Cache.Entry) method will be called.

        Parameters:
        key - key with which the specified value is to be associated
        value - value to be associated with the specified key
        Returns:
        true if a value was set.
        Throws:
        NullPointerException - if key is null or value is null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem doing the put
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)
      • remove

        boolean remove​(K key)
        Removes the mapping for a key from this cache if it is present.

        More formally, if this cache contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The cache can contain at most one such mapping.)

        Returns true if this cache previously associated the key, or false if the cache contained no mapping for the key.

        The cache will not contain a mapping for the specified key once the call returns.

        If the cache is configured write-through the associated CacheWriter.delete(Object) method will be called.

        Parameters:
        key - key whose mapping is to be removed from the cache
        Returns:
        returns false if there was no matching key
        Throws:
        NullPointerException - if key is null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem doing the remove
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        CacheWriter.delete(java.lang.Object)
      • remove

        boolean remove​(K key,
                       V oldValue)
        Atomically removes the mapping for a key only if currently mapped to the given value.

        This is equivalent to:

        
         if (cache.containsKey(key) && equals(cache.get(key), oldValue) {
           cache.remove(key);
           return true;
         } else {
           return false;
         }
         
        except that the action is performed atomically.

        If the cache is configured write-through, and this method returns true, the associated CacheWriter.delete(Object) method will be called.

        Parameters:
        key - key whose mapping is to be removed from the cache
        oldValue - value expected to be associated with the specified key
        Returns:
        returns false if there was no matching key
        Throws:
        NullPointerException - if key is null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem doing the remove
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        CacheWriter.delete(java.lang.Object)
      • getAndRemove

        V getAndRemove​(K key)
        Atomically removes the entry for a key only if currently mapped to some value.

        This is equivalent to:

        
         if (cache.containsKey(key)) {
           V oldValue = cache.get(key);
           cache.remove(key);
           return oldValue;
         } else {
           return null;
         }
         
        except that the action is performed atomically.

        If the cache is configured write-through the associated CacheWriter.delete(Object) method will be called.

        Parameters:
        key - key with which the specified value is associated
        Returns:
        the value if one existed or null if no mapping existed for this key
        Throws:
        NullPointerException - if the specified key or value is null.
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem during the remove
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        CacheWriter.delete(java.lang.Object)
      • replace

        boolean replace​(K key,
                        V oldValue,
                        V newValue)
        Atomically replaces the entry for a key only if currently mapped to a given value.

        This is equivalent to:

        
         if (cache.containsKey(key) && equals(cache.get(key), oldValue)) {
          cache.put(key, newValue);
         return true;
         } else {
          return false;
         }
         
        except that the action is performed atomically.

        If the cache is configured write-through, and this method returns true, the associated CacheWriter.write(Cache.Entry) method will be called.

        Parameters:
        key - key with which the specified value is associated
        oldValue - value expected to be associated with the specified key
        newValue - value to be associated with the specified key
        Returns:
        true if the value was replaced
        Throws:
        NullPointerException - if key is null or if the values are null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem during the replace
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)
      • getAndReplace

        V getAndReplace​(K key,
                        V value)
        Atomically replaces the value for a given key if and only if there is a value currently mapped by the key.

        This is equivalent to

        
         if (cache.containsKey(key)) {
           V oldValue = cache.get(key);
           cache.put(key, value);
           return oldValue;
         } else {
           return null;
         }
         
        except that the action is performed atomically.

        If the cache is configured write-through, and this method returns true, the associated CacheWriter.write(Cache.Entry) method will be called.

        Parameters:
        key - key with which the specified value is associated
        value - value to be associated with the specified key
        Returns:
        the previous value associated with the specified key, or null if there was no mapping for the key.
        Throws:
        NullPointerException - if key is null or if value is null
        IllegalStateException - if the cache is isClosed()
        CacheException - if there is a problem during the replace
        ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache
        See Also:
        ConcurrentMap.replace(Object, Object), CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)
      • getConfiguration

        <C extends Configuration<K,​V>> C getConfiguration​(Class<C> clazz)
        Provides a standard way to access the configuration of a cache using JCache configuration or additional proprietary configuration.

        The returned value must be immutable.

        If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.

        Type Parameters:
        C - the type of the Configuration
        Parameters:
        clazz - the configuration interface or class to return. This includes Configuration.class and CompleteConfigurations.
        Returns:
        the requested implementation of Configuration
        Throws:
        IllegalArgumentException - if the caching provider doesn't support the specified class.
      • getName

        String getName()
        Return the name of the cache.
        Returns:
        the name of the cache.
      • close

        void close()
        Closing a Cache signals to the CacheManager that produced or owns the Cache that it should no longer be managed. At this point in time the CacheManager:
        • must close and release all resources being coordinated on behalf of the Cache by the CacheManager. This includes calling the close method on configured CacheLoader, CacheWriter, registered CacheEntryListeners and ExpiryPolicy instances that implement the java.io.Closeable interface.
        • prevent events being delivered to configured CacheEntryListeners registered on the Cache
        • not return the name of the Cache when the CacheManager getCacheNames() method is called
        Once closed any attempt to use an operational method on a Cache will throw an IllegalStateException.

        Closing a Cache does not necessarily destroy the contents of a Cache. It simply signals to the owning CacheManager that the Cache is no longer required by the application and that future uses of a specific Cache instance should not be permitted.

        Depending on the implementation and Cache topology, (e.g. a storage-backed or distributed cache), the contents of a closed Cache may still be available and accessible by other applications, or, in fact, via the Cache Manager that previously owned the Cache, if an application calls getCache at some point in the future.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
        Throws:
        SecurityException - when the operation could not be performed due to the current security settings
      • isClosed

        boolean isClosed()
        Determines whether this Cache instance has been closed. A Cache is considered closed if;
        1. the close() method has been called
        2. the associated getCacheManager() has been closed, or
        3. the Cache has been removed from the associated getCacheManager()

        This method generally cannot be called to determine whether a Cache instance is valid or invalid. A typical client can determine that a Cache is invalid by catching any exceptions that might be thrown when an operation is attempted.

        Returns:
        true if this Cache instance is closed; false if it is still open
      • unwrap

        <T> T unwrap​(Class<T> clazz)
        Provides a standard way to access the underlying concrete caching implementation to provide access to further, proprietary features.

        If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.

        Type Parameters:
        T - the type of the underlying Cache implementation
        Parameters:
        clazz - the proprietary class or interface of the underlying concrete cache. It is this type that is returned.
        Returns:
        an instance of the underlying concrete cache
        Throws:
        IllegalArgumentException - if the caching provider doesn't support the specified class.
        SecurityException - when the operation could not be performed due to the current security settings
      • iterator

        Iterator<Cache.Entry<K,​V>> iterator()

        The ordering of iteration over entries is undefined.

        During iteration, any entries that are removed will have their appropriate CacheEntryRemovedListeners notified.

        When iterating over a cache it must be assumed that the underlying cache may be changing, with entries being added, removed, evicted and expiring. Iterator.next() may therefore return null.

        Specified by:
        iterator in interface Iterable<K>
        Throws:
        IllegalStateException - if the cache is isClosed()