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
  • Method Details

    • 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:
    • 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
    • put

      void put(K key, V value)
      Associates the specified value with the specified key in the cache.

      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.)

      If the cache is configured write-through the 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
      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:
    • 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:
    • putAll

      void putAll(Map<? extends K,? extends V> map)
      Copies all of the entries from the specified map to the Cache.

      The effect of this call is equivalent to that of calling put(k, v) on this cache once for each mapping from key k to value v in the specified map.

      The order in which the individual puts occur is undefined.

      The behavior of this operation is undefined if entries in the cache corresponding to entries in the map are modified or removed while this operation is in progress. or if map is modified while the operation is in progress.

      In Default Consistency mode, individual puts occur atomically but not the entire putAll. Listeners may observe individual updates.

      If the cache is configured write-through the associated CacheWriter.writeAll(java.util.Collection<javax.cache.Cache.Entry<? extends K, ? extends V>>) method will be called.

      Parameters:
      map - mappings to be stored in this cache
      Throws:
      NullPointerException - if map is null or if map contains null keys or values.
      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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • replace

      boolean replace(K key, V value)
      Atomically replaces the entry for a key only if currently mapped to some 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 - the key with which the specified value is associated
      value - the value to be associated with the specified key
      Returns:
      true if the value was replaced
      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:
    • 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:
    • removeAll

      void removeAll(Set<? extends K> keys)
      Removes entries for the specified keys.

      The order in which the individual entries are removed is undefined.

      For every entry in the key set, the following are called:

      Parameters:
      keys - the keys to remove
      Throws:
      NullPointerException - if keys is null or if it contains a null key
      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:
    • removeAll

      void removeAll()
      Removes all of the mappings from this cache.

      The order that the individual entries are removed is undefined.

      For every mapping that exists the following are called:

      If the cache is empty, the CacheWriter is not called.

      This is potentially an expensive operation as listeners are invoked. Use clear() to avoid this.

      Throws:
      IllegalStateException - if the cache is isClosed()
      CacheException - if there is a problem during the remove
      See Also:
    • clear

      void clear()
      Clears the contents of the cache, without notifying listeners or CacheWriters.
      Throws:
      IllegalStateException - if the cache is isClosed()
      CacheException - if there is a problem during the clear
    • 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.
    • invoke

      <T> T invoke(K key, EntryProcessor<K,V,T> entryProcessor, Object... arguments) throws EntryProcessorException
      Invokes an EntryProcessor against the Cache.Entry specified by the provided key.
      Type Parameters:
      T - the type of the return value
      Parameters:
      key - the key to the entry
      entryProcessor - the EntryProcessor to invoke
      arguments - additional arguments to pass to the EntryProcessor
      Returns:
      the result of the processing, if any, defined by the EntryProcessor implementation
      Throws:
      NullPointerException - if key or EntryProcessor is null
      IllegalStateException - if the cache is isClosed()
      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
      EntryProcessorException - if an exception is thrown by the EntryProcessor, a Caching Implementation must wrap any Exception thrown wrapped in an EntryProcessorException.
      See Also:
    • invokeAll

      <T> Map<K,EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, EntryProcessor<K,V,T> entryProcessor, Object... arguments)
      Invokes an EntryProcessor against the set of Cache.Entrys specified by the set of keys.

      The order that the entries for the keys are processed is undefined. Implementations may choose to process the entries in any order, including concurrently. Furthermore there is no guarantee implementations will use the same EntryProcessor instance to process each entry, as the case may be in a non-local cache topology.

      The result of executing the EntryProcessor is returned as a Map of EntryProcessorResults, one result per key. Should the EntryProcessor or Caching implementation throw an exception, the exception is wrapped and re-thrown when a call to EntryProcessorResult.get() is made.

      Type Parameters:
      T - the type of the return value
      Parameters:
      keys - the set of keys for entries to process
      entryProcessor - the EntryProcessor to invoke
      arguments - additional arguments to pass to the EntryProcessor
      Returns:
      the map of EntryProcessorResults of the processing per key, if any, defined by the EntryProcessor implementation. No mappings will be returned for EntryProcessors that return a null value for a key.
      Throws:
      NullPointerException - if keys or EntryProcessor are null
      IllegalStateException - if the cache is isClosed()
      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:
    • getName

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

      CacheManager getCacheManager()
      Gets the CacheManager that owns and manages the Cache.
      Returns:
      the manager or null if the Cache is not managed
    • 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
    • registerCacheEntryListener

      void registerCacheEntryListener(CacheEntryListenerConfiguration<K,V> cacheEntryListenerConfiguration)
      Registers a CacheEntryListener. The supplied CacheEntryListenerConfiguration is used to instantiate a listener and apply it to those events specified in the configuration.
      Parameters:
      cacheEntryListenerConfiguration - a factory and related configuration for creating the listener
      Throws:
      IllegalArgumentException - is the same CacheEntryListenerConfiguration is used more than once
      IllegalStateException - if the cache is isClosed()
      See Also:
    • deregisterCacheEntryListener

      void deregisterCacheEntryListener(CacheEntryListenerConfiguration<K,V> cacheEntryListenerConfiguration)
      Deregisters a listener, using the CacheEntryListenerConfiguration that was used to register it.

      Both listeners registered at configuration time, and those created at runtime with registerCacheEntryListener(javax.cache.configuration.CacheEntryListenerConfiguration<K, V>) can be deregistered.

      Parameters:
      cacheEntryListenerConfiguration - the factory and related configuration that was used to create the listener
      Throws:
      IllegalStateException - if the cache is isClosed()
    • 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()