package org.infinispan;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.TimeUnit;
import org.infinispan.commons.api.BasicCache;
import org.infinispan.commons.api.BatchingCache;
import org.infinispan.commons.util.CloseableIteratorCollection;
import org.infinispan.commons.util.CloseableIteratorSet;
import org.infinispan.lifecycle.ComponentStatus;
import org.infinispan.manager.DefaultCacheManager;
import org.infinispan.manager.EmbeddedCacheManager;
import org.infinispan.notifications.FilteringListenable;
/**
* The central interface of Infinispan. A Cache provides a highly concurrent, optionally distributed data structure
* with additional features such as:
* <p/>
* <ul> <li>JTA transaction compatibility</li> <li>Eviction support for evicting entries from memory to prevent {@link
* OutOfMemoryError}s</li> <li>Persisting entries to a {@link org.infinispan.persistence.spi.CacheLoader}, either when they are evicted as an overflow,
* or all the time, to maintain persistent copies that would withstand server failure or restarts.</li> </ul>
* <p/>
* <p/>
* <p/>
* For convenience, Cache extends {@link ConcurrentMap} and implements all methods accordingly. Methods like
* {@link #keySet()}, {@link #values()} and {@link #entrySet()} produce backing collections in that updates done to them
* also update the original Cache instance. Certain methods on these maps can be expensive however (prohibitively so
* when using a distributed cache). The {@link #size()} and {@link #containsValue(Object)} methods upon invocation can
* also be expensive just as well. The reason these methods are expensive are that they take into account entries
* stored in a configured {@link org.infinispan.persistence.spi.CacheLoader} and remote entries when using a distributed cache.
* Frequent use of these methods is not recommended if used in this manner. These aforementioned methods do take into
* account in-flight transactions, however key/value pairs read in using an iterator will not be placed into the transactional
* context to prevent {@link OutOfMemoryError}s. Please note all of these methods behavior can be controlled using
* a {@link org.infinispan.context.Flag} to disable certain things such as taking into account the loader. Please see
* each method on this interface for more details.
* <p />
* Also, like many {@link ConcurrentMap} implementations, Cache does not support the use of <tt>null</tt> keys or
* values.
* <p/>
* <h3>Asynchronous operations</h3> Cache also supports the use of "async" remote operations. Note that these methods
* only really make sense if you are using a clustered cache. I.e., when used in LOCAL mode, these "async" operations
* offer no benefit whatsoever. These methods, such as {@link #putAsync(Object, Object)} offer the best of both worlds
* between a fully synchronous and a fully asynchronous cache in that a {@link java.util.concurrent.CompletableFuture} is returned. The
* <tt>CompletableFuture</tt> can then be ignored or thrown away for typical asynchronous behaviour, or queried for
* synchronous behaviour, which would block until any remote calls complete. Note that all remote calls are, as far as
* the transport is concerned, synchronous. This allows you the guarantees that remote calls succeed, while not
* blocking your application thread unnecessarily. For example, usage such as the following could benefit from the
* async operations:
* <pre>
* CompletableFuture f1 = cache.putAsync("key1", "value1");
* CompletableFuture f2 = cache.putAsync("key2", "value2");
* CompletableFuture f3 = cache.putAsync("key3", "value3");
* f1.get();
* f2.get();
* f3.get();
* </pre>
* The net result is behavior similar to synchronous RPC calls in that at the end, you have guarantees that all calls
* completed successfully, but you have the added benefit that the three calls could happen in parallel. This is
* especially advantageous if the cache uses distribution and the three keys map to different cache instances in the
* cluster.
* <p/>
* Also, the use of async operations when within a transaction return your local value only, as expected. A
* CompletableFuture is still returned though for API consistency.
* <p/>
* <h3>Constructing a Cache</h3> An instance of the Cache is usually obtained by using a {@link org.infinispan.manager.CacheContainer}.
* <pre>
* CacheManager cm = new DefaultCacheManager(); // optionally pass in a default configuration
* Cache c = cm.getCache();
* </pre>
* See the {@link org.infinispan.manager.CacheContainer} interface for more details on providing specific configurations, using multiple caches
* in the same JVM, etc.
* <p/>
* Please see the <a href="http://www.jboss.org/infinispan/docs">Infinispan documentation</a> and/or the <a
* href="http://www.jboss.org/community/wiki/5minutetutorialonInfinispan">5 Minute Usage Tutorial</a> for more details.
* <p/>
*
* @author Mircea.Markus@jboss.com
* @author Manik Surtani
* @author Galder Zamarreño
* @see org.infinispan.manager.CacheContainer
* @see DefaultCacheManager
* @see <a href="http://www.jboss.org/infinispan/docs">Infinispan documentation</a>
* @see <a href="http://www.jboss.org/community/wiki/5minutetutorialonInfinispan">5 Minute Usage Tutorial</a>
* @since 4.0
*/
public interface Cache<K, V> extends BasicCache<K, V>, BatchingCache, FilteringListenable<K, V> {
/**
* Under special operating behavior, associates the value with the specified key. <ul> <li> Only goes through if the
* key specified does not exist; no-op otherwise (similar to {@link ConcurrentMap#putIfAbsent(Object, Object)})</i>
* <li> Force asynchronous mode for replication to prevent any blocking.</li> <li> invalidation does not take place.
* </li> <li> 0ms lock timeout to prevent any blocking here either. If the lock is not acquired, this method is a
* no-op, and swallows the timeout exception.</li> <li> Ongoing transactions are suspended before this call, so
* failures here will not affect any ongoing transactions.</li> <li> Errors and exceptions are 'silent' - logged at a
* much lower level than normal, and this method does not throw exceptions</li> </ul> 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'.
* <p/>
* 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.
* <p/>
* See <a href="http://jira.jboss.com/jira/browse/JBCACHE-848">JBCACHE-848</a> for details around this feature.
* <p/>
*
* @param key key with which the specified value is to be associated.
* @param value value to be associated with the specified key.
* @throws IllegalStateException if {@link #getStatus()} would not return {@link ComponentStatus#RUNNING}.
*/
void putForExternalRead(K key, V value);
/**
* An overloaded form of {@link #putForExternalRead(K, V)}, which takes in lifespan parameters.
*
* @param key key to use
* @param value value to store
* @param lifespan lifespan of the entry. Negative values are interpreted as unlimited lifespan.
* @param unit unit of measurement for the lifespan
*
* @since 7.0
*/
void putForExternalRead(K key, V value, long lifespan, TimeUnit unit);
/**
* An overloaded form of {@link #putForExternalRead(K, V)}, which takes in lifespan parameters.
*
* @param key key to use
* @param value value to store
* @param lifespan lifespan of the entry. Negative values are interpreted as unlimited lifespan.
* @param lifespanUnit time unit for lifespan
* @param maxIdle the maximum amount of time this key is allowed to be idle for before it is considered as
* expired
* @param maxIdleUnit time unit for max idle time
* @since 7.0
*/
void putForExternalRead(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit);
/**
* Evicts an entry from the memory of the cache. Note that the entry is <i>not</i> removed from any configured cache
* stores or any other caches in the cluster (if used in a clustered mode). Use {@link #remove(Object)} to remove an
* entry from the entire cache system.
* <p/>
* This method is designed to evict an entry from memory to free up memory used by the application. This method uses
* a 0 lock acquisition timeout so it does not block in attempting to acquire locks. It behaves as a no-op if the
* lock on the entry cannot be acquired <i>immediately</i>.
* <p/>
* Important: this method should not be called from within a transaction scope.
*
* @param key key to evict
*/
void evict(K key);
org.infinispan.configuration.cache.Configuration getCacheConfiguration();
/**
* Retrieves the cache manager responsible for creating this cache instance.
*
* @return a cache manager
*/
EmbeddedCacheManager getCacheManager();
AdvancedCache<K, V> getAdvancedCache();
ComponentStatus getStatus();
/**
* Returns a count of all elements in this cache and cache loader across the entire cluster.
* <p/>
* Only a subset of entries is held in memory at a time when using a loader or remote entries, to prevent possible
* memory issues, however the loading of said entries can still be vary slow.
* <p/>
* If there are performance concerns then the {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} flag should be used to
* avoid hitting the cache loader in case if this is not needed in the size calculation.
* <p/>
* Also if you want the local contents only you can use the {@link org.infinispan.context.Flag#CACHE_MODE_LOCAL} flag so
* that other remote nodes are not queried for data. However the loader will still be used unless the previously
* mentioned {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} is also configured.
* <p/>
* If this method is used in a transactional context, note this method will not bring additional values into the
* transaction context and thus objects that haven't yet been read will act in a
* {@link org.infinispan.util.concurrent.IsolationLevel#READ_COMMITTED} behavior irrespective of the configured
* isolation level. However values that have been previously modified or read that are in the context will be
* adhered to. e.g. any write modification or any previous read when using
* {@link org.infinispan.util.concurrent.IsolationLevel#REPEATABLE_READ}
* <p/>
* This method should only be used for debugging purposes such as to verify that the cache contains all the keys
* entered. Any other use involving execution of this method on a production system is not recommended.
* <p/>
*
* @return the number of key-value mappings in this cache and cache loader across the entire cluster.
*/
@Override
int size();
/**
* Returns a set view of the keys contained in this cache and cache loader across the entire cluster.
* Modifications and changes to the cache will be reflected in the set and vice versa. When this method is called
* nothing is actually queried as the backing set is just returned. Invocation on the set itself is when the
* various operations are ran.
* <p/>
* <h3>Unsupported Operations</h3>
* Care should be taken when invoking {@link java.util.Set#toArray()}, {@link Set#toArray(Object[])},
* {@link java.util.Set#size()}, {@link Set#retainAll(Collection)} and {@link java.util.Set#iterator()}
* methods as they will traverse the entire contents of the cluster including a configured
* {@link org.infinispan.persistence.spi.CacheLoader} and remote entries. The former 2 methods especially have a
* very high likely hood of causing a {@link java.lang.OutOfMemoryError} due to storing all the keys in the entire
* cluster in the array.
* Use involving execution of this method on a production system is not recommended as they can be quite expensive
* operations
* <p/>
* <h3>Supported Flags</h3>
* Note any flag configured for the cache will also be passed along to the backing set when it was created. If
* additional flags are configured on the cache they will not affect any existing backings sets.
* <p/>
* If there are performance concerns then the {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} flag should be used to
* avoid hitting the cache store as this will cause all entries there to be read in (albeit in a batched form to
* prevent {@link java.lang.OutOfMemoryError})
* <p/>
* Also if you want the local contents only you can use the {@link org.infinispan.context.Flag#CACHE_MODE_LOCAL} flag so
* that other remote nodes are not queried for data. However the loader will still be used unless the previously
* mentioned {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} is also configured.
* <p/>
* <h3>Iterator Use</h3>
* This class implements the {@link CloseableIteratorSet} interface which creates a
* {@link org.infinispan.commons.util.CloseableIterator} instead of a regular one. This means this iterator must be
* explicitly closed either through try with resource or calling the close method directly. Technically this iterator
* will also close itself if you iterate fully over it, but it is safest to always make sure you close it explicitly.
* <h3>Unsupported Operations</h3>
* Due to not being able to add null values the following methods are not supported and will throw
* {@link java.lang.UnsupportedOperationException} if invoked.
* {@link Set#add(Object)}
* {@link Set#addAll(java.util.Collection)}
* @return a set view of the keys contained in this cache and cache loader across the entire cluster.
*/
@Override
CacheSet<K> keySet();
/**
* Returns a collection view of the values contained in this cache across the entire cluster. Modifications and
* changes to the cache will be reflected in the set and vice versa. When this method is called nothing is actually
* queried as the backing collection is just returned. Invocation on the collection itself is when the various
* operations are ran.
* <p/>
* Care should be taken when invoking {@link Collection#toArray()}, {@link Collection#toArray(Object[])},
* {@link Collection#size()}, {@link Collection#retainAll(Collection)} and {@link Collection#iterator()}
* methods as they will traverse the entire contents of the cluster including a configured
* {@link org.infinispan.persistence.spi.CacheLoader} and remote entries. The former 2 methods especially have a
* very high likely hood of causing a {@link java.lang.OutOfMemoryError} due to storing all the keys in the entire
* cluster in the array.
* Use involving execution of this method on a production system is not recommended as they can be quite expensive
* operations
* <p/>
* * <h3>Supported Flags</h3>
* Note any flag configured for the cache will also be passed along to the backing set when it was created. If
* additional flags are configured on the cache they will not affect any existing backings sets.
* <p/>
* If there are performance concerns then the {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} flag should be used to
* avoid hitting the cache store as this will cause all entries there to be read in (albeit in a batched form to
* prevent {@link java.lang.OutOfMemoryError})
* <p/>
* Also if you want the local contents only you can use the {@link org.infinispan.context.Flag#CACHE_MODE_LOCAL} flag so
* that other remote nodes are not queried for data. However the loader will still be used unless the previously
* mentioned {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} is also configured.
* <p/>
* <h3>Iterator Use</h3>
* <p>This class implements the {@link CloseableIteratorCollection} interface which creates a
* {@link org.infinispan.commons.util.CloseableIterator} instead of a regular one. This means this iterator must be
* explicitly closed either through try with resource or calling the close method directly. Technically this iterator
* will also close itself if you iterate fully over it, but it is safest to always make sure you close it explicitly.</p>
* <p>The iterator retrieved using {@link CacheCollection#iterator()} supports the remove method, however the
* iterator retrieved from {@link CacheStream#iterator()} will not support remove.</p>
* <h3>Unsupported Operations</h3>
* Due to not being able to add null values the following methods are not supported and will throw
* {@link java.lang.UnsupportedOperationException} if invoked.
* {@link Set#add(Object)}
* {@link Set#addAll(java.util.Collection)}
*
* @return a collection view of the values contained in this cache and cache loader across the entire cluster.
*/
@Override
CacheCollection<V> values();
/**
* Returns a set view of the mappings contained in this cache and cache loader across the entire cluster.
* Modifications and changes to the cache will be reflected in the set and vice versa. When this method is called
* nothing is actually queried as the backing set is just returned. Invocation on the set itself is when the
* various operations are ran.
* <p/>
* Care should be taken when invoking {@link java.util.Set#toArray()}, {@link Set#toArray(Object[])},
* {@link java.util.Set#size()}, {@link Set#retainAll(Collection)} and {@link java.util.Set#iterator()}
* methods as they will traverse the entire contents of the cluster including a configured
* {@link org.infinispan.persistence.spi.CacheLoader} and remote entries. The former 2 methods especially have a
* very high likely hood of causing a {@link java.lang.OutOfMemoryError} due to storing all the keys in the entire
* cluster in the array.
* Use involving execution of this method on a production system is not recommended as they can be quite expensive
* operations
* <p/>
* * <h3>Supported Flags</h3>
* Note any flag configured for the cache will also be passed along to the backing set when it was created. If
* additional flags are configured on the cache they will not affect any existing backings sets.
* <p/>
* If there are performance concerns then the {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} flag should be used to
* avoid hitting the cache store as this will cause all entries there to be read in (albeit in a batched form to
* prevent {@link java.lang.OutOfMemoryError})
* <p/>
* Also if you want the local contents only you can use the {@link org.infinispan.context.Flag#CACHE_MODE_LOCAL} flag so
* that other remote nodes are not queried for data. However the loader will still be used unless the previously
* mentioned {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} is also configured.
* <p/>
* <h3>Modifying or Adding Entries</h3>
* An entry's value is supported to be modified by using the {@link Map.Entry#setValue(Object)} and it will update
* the cache as well. Also this backing set does allow addition of a new Map.Entry(s) via the
* {@link Set#add(Object)} or {@link Set#addAll(java.util.Collection)} methods.
* <h3>Iterator Use</h3>
* This class implements the {@link CloseableIteratorSet} interface which creates a
* {@link org.infinispan.commons.util.CloseableIterator} instead of a regular one. This means this iterator must be
* explicitly closed either through try with resource or calling the close method directly. Technically this iterator
* will also close itself if you iterate fully over it, but it is safest to always make sure you close it explicitly.
* @return a set view of the mappings contained in this cache and cache loader across the entire cluster.
*/
@Override
CacheSet<Entry<K, V>> entrySet();
/**
* Removes all mappings from the cache.
* <p/>
* <b>Note:</b> This should never be invoked in production unless you can guarantee no other invocations are ran
* concurrently.
* <p/>
* If the cache is transactional, it will not interact with the transaction.
*/
@Override
void clear();
/**
* Stops a cache. If the cache is clustered, this only stops the cache on the node where it is being invoked. If you
* need to stop the cache across a cluster, use the {@link #shutdown()} method.
*/
@Override
void stop();
/**
* Performs a controlled, clustered shutdown of the cache. When invoked, the following operations are performed:
* <ul>
* <li>rebalancing for the cache is disabled</li>
* <li>in-memory data is flushed/passivated to any persistent stores</li>
* <li>state is persisted to the location defined in {@link org.infinispan.configuration.global.GlobalStateConfigurationBuilder#persistentLocation(String)}</li>
* </ul>
*
* This method differs from {@link #stop()} only in clustered modes,
* and only when {@link org.infinispan.configuration.global.GlobalStateConfiguration#enabled()} is true, otherwise it
* just behaves like {@link #stop()}.
*/
default void shutdown() {
stop();
}
}