org.infinispan
Interface Cache<K,V>

All Superinterfaces:
ConcurrentMap<K,V>, Lifecycle, Listenable, Map<K,V>
All Known Subinterfaces:
AdvancedCache<K,V>, AtomicMapCache<K,V>
All Known Implementing Classes:
AbstractDelegatingAdvancedCache, AbstractDelegatingCache, CacheDelegate

public interface Cache<K,V>
extends ConcurrentMap<K,V>, Lifecycle, Listenable

The central interface of Infinispan. A Cache provides a highly concurrent, optionally distributed data structure with additional features such as:

For convenience, Cache extends ConcurrentMap and implements all methods accordingly, although methods like Map.keySet(), Map.values() and Map.entrySet() are expensive (prohibitively so when using a distributed cache) and frequent use of these methods is not recommended.

Also, like most ConcurrentMap implementations, Cache does not support the use of null keys (although null values are allowed).

Please see the Infinispan documentation for more details.

A note about return values. Certain methods on Map could have indeterminate return values, if the DISTRIBITION cache mode is used in an asynchronous manner and the invocation takes place on a cache instance where the entry involved is not local. These methods are:

The methods still behave as expected, i.e., ConcurrentMap.putIfAbsent(Object, Object) will be a no-op if there is a value present, just that since remote calls are asynchronous and the operation needs to be executed on a remote cache, the calling cache will not wait for a return value.

As such, as a general rule of thumb, return values to these methods should not be used if using DISTRIBUTION in asynchronous mode.

For all other cache modes (including synchronous DISTRIBUTION) these return values are reliable and can be used.

Since:
4.0
Author:
Mircea.Markus@jboss.com, Manik Surtani

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
 
Method Summary
 void compact()
          Method that releases object references of cached objects held in the cache by serializing them to byte buffers.
 void endBatch(boolean successful)
           
 void evict(K key)
           
 AdvancedCache<K,V> getAdvancedCache()
           
 CacheManager getCacheManager()
          Retrieves the cache manager responsible for creating this cache instance.
 Configuration getConfiguration()
           
 String getName()
           
 ComponentStatus getStatus()
           
 String getVersion()
           
 V put(K key, V value, long lifespan, TimeUnit unit)
          An overloaded form of Map.put(Object, Object), which takes in lifespan parameters.
 V put(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit)
          An overloaded form of Map.put(Object, Object), which takes in lifespan parameters.
 void putAll(Map<? extends K,? extends V> map, long lifespan, TimeUnit unit)
          An overloaded form of Map.putAll(java.util.Map), which takes in lifespan parameters.
 void putAll(Map<? extends K,? extends V> map, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit)
          An overloaded form of Map.putAll(java.util.Map), which takes in lifespan parameters.
 void putForExternalRead(K key, V value)
          Under special operating behavior, associates the value with the specified key.
 V putIfAbsent(K key, V value, long lifespan, TimeUnit unit)
          An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.
 V putIfAbsent(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit)
          An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.
 V replace(K key, V value, long lifespan, TimeUnit unit)
          An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.
 V replace(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit)
          An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.
 boolean replace(K key, V oldValue, V value, long lifespan, TimeUnit unit)
          An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.
 boolean replace(K key, V oldValue, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit)
          An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.
 boolean startBatch()
           
 
Methods inherited from interface java.util.concurrent.ConcurrentMap
putIfAbsent, remove, replace, replace
 
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values
 
Methods inherited from interface org.infinispan.lifecycle.Lifecycle
start, stop
 
Methods inherited from interface org.infinispan.notifications.Listenable
addListener, getListeners, removeListener
 

Method Detail

putForExternalRead

void putForExternalRead(K key,
                        V value)
Under special operating behavior, associates the value with the specified key. This method is for caching data that has an external representation in storage, where, concurrent modification and transactions are not a consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome' rather than a 'failing outcome'.

An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached before returning the data to the caller. Subsequent calls would prefer to get the data from the cache and if the data doesn't exist in the cache, fetch again from the legacy datastore.

See JBCACHE-848 for details around this feature.

Parameters:
key - key with which the specified value is to be associated.
value - value to be associated with the specified key.
Throws:
IllegalStateException - if getStatus() would not return ComponentStatus.RUNNING.

evict

void evict(K key)

getConfiguration

Configuration getConfiguration()

startBatch

boolean startBatch()
Returns:
true if a batch was successfully started; false if one was available and already running.

endBatch

void endBatch(boolean successful)

getName

String getName()

getVersion

String getVersion()

getCacheManager

CacheManager getCacheManager()
Retrieves the cache manager responsible for creating this cache instance.

Returns:
a cache manager

put

V put(K key,
      V value,
      long lifespan,
      TimeUnit unit)
An overloaded form of Map.put(Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
unit - unit of measurement for the lifespan
Returns:
the value being replaced, or null if nothing is being replaced.

putIfAbsent

V putIfAbsent(K key,
              V value,
              long lifespan,
              TimeUnit unit)
An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
unit - unit of measurement for the lifespan
Returns:
the value being replaced, or null if nothing is being replaced.

putAll

void putAll(Map<? extends K,? extends V> map,
            long lifespan,
            TimeUnit unit)
An overloaded form of Map.putAll(java.util.Map), which takes in lifespan parameters. Note that the lifespan is applied to all mappings in the map passed in.

Parameters:
map - map containing mappings to enter
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
unit - unit of measurement for the lifespan

replace

V replace(K key,
          V value,
          long lifespan,
          TimeUnit unit)
An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
unit - unit of measurement for the lifespan
Returns:
the value being replaced, or null if nothing is being replaced.

replace

boolean replace(K key,
                V oldValue,
                V value,
                long lifespan,
                TimeUnit unit)
An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
oldValue - value to replace
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
unit - unit of measurement for the lifespan
Returns:
true if the value was replaced, false otherwise

put

V put(K key,
      V value,
      long lifespan,
      TimeUnit lifespanUnit,
      long maxIdleTime,
      TimeUnit maxIdleTimeUnit)
An overloaded form of Map.put(Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
lifespanUnit - time unit for lifespan
maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired
maxIdleTimeUnit - time unit for max idle time
Returns:
the value being replaced, or null if nothing is being replaced.

putIfAbsent

V putIfAbsent(K key,
              V value,
              long lifespan,
              TimeUnit lifespanUnit,
              long maxIdleTime,
              TimeUnit maxIdleTimeUnit)
An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
lifespanUnit - time unit for lifespan
maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired
maxIdleTimeUnit - time unit for max idle time
Returns:
the value being replaced, or null if nothing is being replaced.

putAll

void putAll(Map<? extends K,? extends V> map,
            long lifespan,
            TimeUnit lifespanUnit,
            long maxIdleTime,
            TimeUnit maxIdleTimeUnit)
An overloaded form of Map.putAll(java.util.Map), which takes in lifespan parameters. Note that the lifespan is applied to all mappings in the map passed in.

Parameters:
map - map containing mappings to enter
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
lifespanUnit - time unit for lifespan
maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired
maxIdleTimeUnit - time unit for max idle time

replace

V replace(K key,
          V value,
          long lifespan,
          TimeUnit lifespanUnit,
          long maxIdleTime,
          TimeUnit maxIdleTimeUnit)
An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
lifespanUnit - time unit for lifespan
maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired
maxIdleTimeUnit - time unit for max idle time
Returns:
the value being replaced, or null if nothing is being replaced.

replace

boolean replace(K key,
                V oldValue,
                V value,
                long lifespan,
                TimeUnit lifespanUnit,
                long maxIdleTime,
                TimeUnit maxIdleTimeUnit)
An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.

Parameters:
key - key to use
oldValue - value to replace
value - value to store
lifespan - lifespan of the entry. Negative values are intepreted as unlimited lifespan.
lifespanUnit - time unit for lifespan
maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired
maxIdleTimeUnit - time unit for max idle time
Returns:
true if the value was replaced, false otherwise

getAdvancedCache

AdvancedCache<K,V> getAdvancedCache()

compact

void compact()
Method that releases object references of cached objects held in the cache by serializing them to byte buffers. Cached objects are lazily deserialized when accessed again, based on the calling thread's context class loader.

This can be expensive, based on the effort required to serialize cached objects.


getStatus

ComponentStatus getStatus()


Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.