org.apache.ignite

## Interface IgniteCache<K,V>

Type Parameters:
  `K` - Cache key type.
  `V` - Cache value type.

All Superinterfaces:
  AutoCloseable, javax.cache.Cache<K,V>, Closeable, IgniteAsyncSupport, Iterable<javax.cache.Cache.Entry<K,V>>

All Known Implementing Classes:
  IgniteCacheProxy

    public interface IgniteCache<K,V>
    extends javax.cache.Cache<K,V>, IgniteAsyncSupport

Main entry point for all Data Grid APIs. You can get a named cache by calling `Ignite.cache(String)` method.

# Functionality

This API extends `Cache` API which contains `JCache (JSR107)` cache functionality and documentation. In addition to `Cache` functionality this API provides:

- Ability to perform basic atomic Map-like operations available on `JCache` API.
- Ability to bulk load cache via `loadCache(IgniteBiPredicate, Object...)` method.
- Distributed lock functionality via `lock(Object)` methods.
- Ability to query cache using Predicate, SQL, and Text queries via `query(Query)` method.
- Ability to collect cache and query metrics.
- Ability to force partition rebalancing via `rebalance()` methopd (in case if delayed rebalancing was configured.)
- Ability to peek into memory without doing actual `get(...)` from cache via `localPeek(Object, CachePeekMode...)` methods
- Ability to evict and promote entries from on-heap to off-heap or swap and back.
- Ability to atomically collocate compute and data via `invoke(Object, CacheEntryProcessor, Object...)` methods.

# Transactions

Cache API supports transactions. You can group and set of cache methods within a transaction to provide ACID-compliant behavior. See `IgniteTransactions` for more information.

# Asynchronous Mode

Cache API supports asynchronous mode via `IgniteAsyncSupport` functionality. To turn on asynchronous mode invoke `withAsync()` method. Once asynchronous mode is enabled, all methods with `@IgniteAsyncSupported` annotation will be executed asynchronously.

### Nested Class Summary

### Nested classes/interfaces inherited from interface javax.cache.Cache

`javax.cache.Cache.Entry<K,V>`

### Method Summary

Methods
`void` `clear()`
`void` `clear(K key)` Clear entry from the cache and swap storage, without notifying listeners or `CacheWriter`s.
`void` `clearAll(Set<? extends K> keys)` Clear entries from the cache and swap storage, without notifying listeners or `CacheWriter`s.
`void` `close()` Closes this cache instance.
`boolean` `containsKey(K key)`
`boolean` `containsKeys(Set<? extends K> keys)` Determines if the `Cache` contains entries for the specified keys.
`void` `destroy()` Completely deletes the cache with all its data from the system on all cluster nodes.
`V` `get(K key)`
`Map<K,V>` `getAll(Set<? extends K> keys)`
`Map<K,V>` `getAllOutTx(Set<? extends K> keys)` Gets values from cache.
`V` `getAndPut(K key, V val)`
`V` `getAndPutIfAbsent(K key, V val)` Stores given key-value pair in cache only if cache had no previous mapping for it.
`V` `getAndRemove(K key)`
`V` `getAndReplace(K key, V val)`
`<C extends javax.cache.configuration.Configuration<K,V>> C` `getConfiguration(Class<C> clazz)`
`Collection<CacheEntry<K,V>>` `getEntries(Set<? extends K> keys)` Gets a collection of entries from the `Cache`.
`CacheEntry<K,V>` `getEntry(K key)` Gets an entry from the cache.
`<T> T` `invoke(K key, CacheEntryProcessor<K,V,T> entryProcessor, Object... arguments)` Invokes an `CacheEntryProcessor` against the `Cache.Entry` specified by the provided key.
`<T> T` `invoke(K key, javax.cache.processor.EntryProcessor<K,V,T> entryProcessor, Object... arguments)`
`<T> Map<K,javax.cache.processor.EntryProcessorResult<T>>` `invokeAll(Map<? extends K,? extends javax.cache.processor.EntryProcessor<K,V,T>> map, Object... args)`
`<T> Map<K,javax.cache.processor.EntryProcessorResult<T>>` `invokeAll(Set<? extends K> keys, CacheEntryProcessor<K,V,T> entryProcessor, Object... args)` Invokes an `CacheEntryProcessor` against the set of `Cache.Entry`s specified by the set of keys.
`<T> Map<K,javax.cache.processor.EntryProcessorResult<T>>` `invokeAll(Set<? extends K> keys, javax.cache.processor.EntryProcessor<K,V,T> entryProcessor, Object... args)`
`boolean` `isLocalLocked(K key, boolean byCurrThread)` Checks if specified key is locked.
`void` `loadCache(IgniteBiPredicate<K,V> p, Object... args)` Executes `localLoadCache(IgniteBiPredicate, Object...)` on all cache nodes.
`void` `localClear(K key)` Clear entry from the cache and swap storage, without notifying listeners or `CacheWriter`s.
`void` `localClearAll(Set<? extends K> keys)` Clear entries from the cache and swap storage, without notifying listeners or `CacheWriter`s.
`Iterable<javax.cache.Cache.Entry<K,V>>` `localEntries(CachePeekMode... peekModes)` Allows for iteration over local cache entries.
`void` `localEvict(Collection<? extends K> keys)` Attempts to evict all entries associated with keys.
`void` `localLoadCache(IgniteBiPredicate<K,V> p, Object... args)` Delegates to `CacheStore.loadCache(IgniteBiInClosure,Object...)` method to load state from the underlying persistent storage.
`CacheMetrics` `localMetrics()` Gets local snapshot metrics (statistics) for this cache.
`CacheMetricsMXBean` `localMxBean()` Gets local MxBean for this cache.
`V` `localPeek(K key, CachePeekMode... peekModes)` Peeks at in-memory cached value using default optional peek mode.
`void` `localPromote(Set<? extends K> keys)` This method unswaps cache entries by given keys, if any, from swap storage into memory.
`int` `localSize(CachePeekMode... peekModes)` Gets the number of all entries cached on this node.
`long` `localSizeLong(CachePeekMode... peekModes)` Gets the number of all entries cached on this node as a long value.
`long` `localSizeLong(int partition, CachePeekMode... peekModes)` Gets the number of all entries cached on this node for the partition as a long value.
`Lock` `lock(K key)` Creates a `Lock` instance associated with passed key.
`Lock` `lockAll(Collection<? extends K> keys)` Creates a `Lock` instance associated with passed keys.
`CacheMetrics` `metrics()` Gets whole cluster snapshot metrics (statistics) for this cache.
`CacheMetrics` `metrics(ClusterGroup grp)` Gets cluster group snapshot metrics for caches in cluster group.
`CacheMetricsMXBean` `mxBean()` Gets whole cluster MxBean for this cache.
`void` `put(K key, V val)`
`void` `putAll(Map<? extends K,? extends V> map)`
`boolean` `putIfAbsent(K key, V val)`
`<R> QueryCursor<R>` `query(Query<R> qry)` Queries cache.
`<T,R> QueryCursor<R>` `query(Query<T> qry, IgniteClosure<T,R> transformer)` Queries the cache transforming the entries on the server nodes.
`Collection<? extends QueryDetailMetrics>` `queryDetailMetrics()` Gets query detail metrics.
`QueryMetrics` `queryMetrics()` Gets query metrics.
`javax.cache.Cache.Entry<K,V>` `randomEntry()` Deprecated.
`IgniteFuture<?>` `rebalance()` This cache node to re-balance its partitions.
`boolean` `remove(K key)`
`boolean` `remove(K key, V oldVal)`
`void` `removeAll()` Removes all of the mappings from this cache.
`void` `removeAll(Set<? extends K> keys)`
`boolean` `replace(K key, V val)`
`boolean` `replace(K key, V oldVal, V newVal)`
`void` `resetQueryDetailMetrics()` Reset query detail metrics.
`void` `resetQueryMetrics()` Reset query metrics.
`int` `size(CachePeekMode... peekModes)` Gets the number of all entries cached across all nodes.
`long` `sizeLong(CachePeekMode... peekModes)` Gets the number of all entries cached across all nodes as a long value.
`long` `sizeLong(int partition, CachePeekMode... peekModes)` Gets the number of all entries cached in a partition as a long value.
`IgniteCache<K,V>` `withAsync()` Gets instance of this component with asynchronous mode enabled.
`IgniteCache<K,V>` `withExpiryPolicy(javax.cache.expiry.ExpiryPolicy plc)` Returns cache with the specified expired policy set.
`<K1,V1> IgniteCache<K1,V1>` `withKeepBinary()` Returns cache that will operate with binary objects.
`IgniteCache<K,V>` `withNoRetries()`
`IgniteCache<K,V>` `withSkipStore()`

### Methods inherited from interface javax.cache.Cache

`deregisterCacheEntryListener, getCacheManager, getName, isClosed, iterator, loadAll, registerCacheEntryListener, unwrap`

### Methods inherited from interface org.apache.ignite.lang.IgniteAsyncSupport

`future, isAsync`

### Method Detail

#### withAsync

    IgniteCache<K,V> withAsync()

Gets instance of this component with asynchronous mode enabled.

Specified by:
  `withAsync` in interface `IgniteAsyncSupport`
Returns:
  Instance of this component with asynchronous mode enabled.

#### getConfiguration

    <C extends javax.cache.configuration.Configuration<K,V>> C getConfiguration(Class<C> clazz)

Specified by:
  `getConfiguration` in interface `javax.cache.Cache<K,V>`

#### randomEntry

    @Deprecated
    javax.cache.Cache.Entry<K,V> randomEntry()

Deprecated.
Gets a random entry out of cache. In the worst cache scenario this method has complexity of

    O(S * N/64)

where `N` is the size of internal hash table and `S` is the number of hash table buckets to sample, which is `5` by default. However, if the table is pretty dense, with density factor of `N/64`, which is true for near fully populated caches, this method will generally perform significantly faster with complexity of O(S) where `S = 5`.

Returns:
  Random entry, or `null` if cache is empty.

#### withExpiryPolicy

    IgniteCache<K,V> withExpiryPolicy(javax.cache.expiry.ExpiryPolicy plc)

Returns cache with the specified expired policy set. This policy will be used for each operation invoked on the returned cache.

This method does not modify existing cache instance.

Parameters:
  `plc` - Expire policy to use.
Returns:
  Cache instance with the specified expiry policy set.

#### withSkipStore

    IgniteCache<K,V> withSkipStore()

Returns:
  Cache with read-through write-through behavior disabled.

#### withNoRetries

    IgniteCache<K,V> withNoRetries()

Returns:
  Cache with no-retries behavior enabled.

#### withKeepBinary

    <K1,V1> IgniteCache<K1,V1> withKeepBinary()

Returns cache that will operate with binary objects.

Cache returned by this method will not be forced to deserialize binary objects, so keys and values will be returned from cache API methods without changes. Therefore, signature of the cache can contain only following types:

- `org.apache.ignite.binary.BinaryObject` for binary classes
- All primitives (byte, int, ...) and there boxed versions (Byte, Integer, ...)
- Arrays of primitives (byte[], int[], ...)
- `String` and array of `String`s
- `UUID` and array of `UUID`s
- `Date` and array of `Date`s
- `Timestamp` and array of `Timestamp`s
- Enums and array of enums
- Maps, collections and array of objects (but objects inside them will still be converted if they are binary)

For example, if you use `Integer` as a key and `Value` class as a value (which will be stored in binary format), you should acquire following projection to avoid deserialization:

     IgniteCache<Integer, BinaryObject> prj = cache.withKeepBinary();

     // Value is not deserialized and returned in binary format.
     BinaryObject po = prj.get(1);

Note that this method makes sense only if cache is working in binary mode if default marshaller is used. If not, this method is no-op and will return current cache.

Returns:
  New cache instance for binary objects.

#### loadCache

    @IgniteAsyncSupported
    void loadCache(@Nullable
                                      IgniteBiPredicate<K,V> p,
                                      @Nullable
                                      Object... args)
                   throws javax.cache.CacheException

Executes `localLoadCache(IgniteBiPredicate, Object...)` on all cache nodes.

Parameters:
  `p` - Optional predicate (may be `null`). If provided, will be used to filter values loaded from storage before they are put into cache.
  `args` - Optional user arguments to be passed into `CacheStore.loadCache(IgniteBiInClosure, Object...)` method.
Throws:
  `javax.cache.CacheException` - If loading failed.

#### localLoadCache

    @IgniteAsyncSupported
    void localLoadCache(@Nullable
                                           IgniteBiPredicate<K,V> p,
                                           @Nullable
                                           Object... args)
                        throws javax.cache.CacheException

Delegates to `CacheStore.loadCache(IgniteBiInClosure,Object...)` method to load state from the underlying persistent storage. The loaded values will then be given to the optionally passed in predicate, and, if the predicate returns `true`, will be stored in cache. If predicate is `null`, then all loaded values will be stored in cache.

Note that this method does not receive keys as a parameter, so it is up to `CacheStore` implementation to provide all the data to be loaded.

This method is not transactional and may end up loading a stale value into cache if another thread has updated the value immediately after it has been loaded. It is mostly useful when pre-loading the cache from underlying data store before start, or for read-only caches.

Parameters:
  `p` - Optional predicate (may be `null`). If provided, will be used to filter values to be put into cache.
  `args` - Optional user arguments to be passed into `CacheStore.loadCache(IgniteBiInClosure, Object...)` method.
Throws:
  `javax.cache.CacheException` - If loading failed.

#### getAndPutIfAbsent

    @IgniteAsyncSupported
    V getAndPutIfAbsent(K key,
                                           V val)
                        throws javax.cache.CacheException

Stores given key-value pair in cache only if cache had no previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of `CacheMode.PARTITIONED` or `CacheMode.REPLICATED` caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If value has to be loaded from persistent storage, `CacheLoader.load(Object)` method will be used.

If the returned value is not needed, method `putIfAbsent(Object, Object)` should always be used instead of this one to avoid the overhead associated with returning of the previous value.

If write-through is enabled, the stored value will be persisted to `CacheStore` via `CacheWriter.write(javax.cache.Cache.Entry)` method.

## Transactions

This method is transactional and will enlist the entry into ongoing transaction if there is one.

Parameters:
  `key` - Key to store in cache.
  `val` - Value to be associated with the given key.
Returns:
  Previously contained value regardless of whether put happened or not (`null` if there was no previous value).
Throws:
  `NullPointerException` - If either key or value are `null`.
  `javax.cache.CacheException` - If put operation failed.
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### lock

    Lock lock(K key)

Creates a `Lock` instance associated with passed key. This method does not acquire lock immediately, you have to call appropriate method on returned instance. Returned lock does not support `Lock.newCondition()` method, other methods defined in `Lock` are supported.

Parameters:
  `key` - Key for lock.
Returns:
  New lock instance associated with passed key.
See Also:
  `Lock.lock()`, `Lock.tryLock(long, TimeUnit)`

#### lockAll

    Lock lockAll(Collection<? extends K> keys)

Creates a `Lock` instance associated with passed keys. This method does not acquire lock immediately, you have to call appropriate method on returned instance. Returned lock does not support `Lock.newCondition()` method, other methods defined in `Lock` are supported.

Parameters:
  `keys` - Keys for lock.
Returns:
  New lock instance associated with passed key.
See Also:
  `Lock.lock()`, `Lock.tryLock(long, TimeUnit)`

#### isLocalLocked

    boolean isLocalLocked(K key,
                        boolean byCurrThread)

Checks if specified key is locked.

This is a local in-VM operation and does not involve any network trips or access to persistent storage in any way.

Parameters:
  `key` - Key to check.
  `byCurrThread` - If `true` method will check that current thread owns a lock on this key, other vise will check that any thread on any node owns a lock on this key.
Returns:
  `True` if lock is owned by some node.

#### query

    <R> QueryCursor<R> query(Query<R> qry)

Queries cache. Accepts any subclass of `Query` interface.

Parameters:
  `qry` - Query.
Returns:
  Cursor.
See Also:
  `ScanQuery`, `SqlQuery`, `SqlFieldsQuery`, `TextQuery`, `SpiQuery`

#### query

    <T,R> QueryCursor<R> query(Query<T> qry,
                             IgniteClosure<T,R> transformer)

Queries the cache transforming the entries on the server nodes. Can be used, for example, to avoid network overhead in case only one field out of the large is required by client.

Currently transformers are supported ONLY for `ScanQuery`. Passing any other subclass of `Query` interface to this method will end up with `UnsupportedOperationException`.

Parameters:
  `qry` - Query.
  `transformer` - Transformer.
Returns:
  Cursor.

#### localEntries

    Iterable<javax.cache.Cache.Entry<K,V>> localEntries(CachePeekMode... peekModes)
                                                        throws javax.cache.CacheException

Allows for iteration over local cache entries.

Parameters:
  `peekModes` - Peek modes.
Returns:
  Iterable over local cache entries.
Throws:
  `javax.cache.CacheException` - If failed.

#### queryMetrics

    QueryMetrics queryMetrics()

Gets query metrics.

Returns:
  Metrics.

#### resetQueryMetrics

    void resetQueryMetrics()

Reset query metrics.

#### queryDetailMetrics

    Collection<? extends QueryDetailMetrics> queryDetailMetrics()

Gets query detail metrics. Query detail metrics could be enabled via `CacheConfiguration.setQueryDetailMetricsSize(int)` method.

Returns:
  Metrics.

#### resetQueryDetailMetrics

    void resetQueryDetailMetrics()

Reset query detail metrics.

#### localEvict

    void localEvict(Collection<? extends K> keys)

Attempts to evict all entries associated with keys. Note, that entry will be evicted only if it's not used (not participating in any locks or transactions).

Parameters:
  `keys` - Keys to evict.

#### localPeek

    V localPeek(K key,
              CachePeekMode... peekModes)

Peeks at in-memory cached value using default optional peek mode.

This method will not load value from any persistent store or from a remote node.

## Transactions

This method does not participate in any transactions.

Parameters:
  `key` - Entry key.
Returns:
  Peeked value, or `null` if not found.
Throws:
  `NullPointerException` - If key is `null`.

#### localPromote

    void localPromote(Set<? extends K> keys)
                      throws javax.cache.CacheException

This method unswaps cache entries by given keys, if any, from swap storage into memory.

## Transactions

This method is not transactional.

Parameters:
  `keys` - Keys to promote entries for.
Throws:
  `javax.cache.CacheException` - If promote failed.

#### size

    @IgniteAsyncSupported
    int size(CachePeekMode... peekModes)
             throws javax.cache.CacheException

Gets the number of all entries cached across all nodes. By default, if `peekModes` value isn't defined, only size of primary copies across all nodes will be returned. This behavior is identical to calling this method with `CachePeekMode.PRIMARY` peek mode.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Parameters:
  `peekModes` - Optional peek modes. If not provided, then total cache size is returned.
Returns:
  Cache size across all nodes.
Throws:
  `javax.cache.CacheException`

#### sizeLong

    @IgniteAsyncSupported
    long sizeLong(CachePeekMode... peekModes)
                  throws javax.cache.CacheException

Gets the number of all entries cached across all nodes as a long value. By default, if `peekModes` value isn't defined, only size of primary copies across all nodes will be returned. This behavior is identical to calling this method with `CachePeekMode.PRIMARY` peek mode.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Parameters:
  `peekModes` - Optional peek modes. If not provided, then total cache size is returned.
Returns:
  Cache size across all nodes.
Throws:
  `javax.cache.CacheException`

#### sizeLong

    @IgniteAsyncSupported
    long sizeLong(int partition,
                                     CachePeekMode... peekModes)
                  throws javax.cache.CacheException

Gets the number of all entries cached in a partition as a long value. By default, if `peekModes` value isn't defined, only size of primary copies across all nodes will be returned. This behavior is identical to calling this method with `CachePeekMode.PRIMARY` peek mode.

NOTE: this operation is distributed and will query all participating nodes for their partition cache sizes.

Parameters:
  `partition` - partition.
  `peekModes` - Optional peek modes. If not provided, then total partition cache size is returned.
Returns:
  Partion cache size across all nodes.
Throws:
  `javax.cache.CacheException`

#### localSize

    int localSize(CachePeekMode... peekModes)

Gets the number of all entries cached on this node. By default, if `peekModes` value isn't defined, only size of primary copies will be returned. This behavior is identical to calling this method with `CachePeekMode.PRIMARY` peek mode.

Parameters:
  `peekModes` - Optional peek modes. If not provided, then total cache size is returned.
Returns:
  Cache size on this node.

#### localSizeLong

    long localSizeLong(CachePeekMode... peekModes)

Gets the number of all entries cached on this node as a long value. By default, if `peekModes` value isn't defined, only size of primary copies will be returned. This behavior is identical to calling this method with `CachePeekMode.PRIMARY` peek mode.

Parameters:
  `peekModes` - Optional peek modes. If not provided, then total cache size is returned.
Returns:
  Cache size on this node.

#### localSizeLong

    long localSizeLong(int partition,
                     CachePeekMode... peekModes)

Gets the number of all entries cached on this node for the partition as a long value. By default, if `peekModes` value isn't defined, only size of primary copies will be returned. This behavior is identical to calling this method with `CachePeekMode.PRIMARY` peek mode.

Parameters:
  `partition` - partition.
  `peekModes` - Optional peek modes. If not provided, then total cache size is returned.
Returns:
  Cache size on this node.

#### invokeAll

    @IgniteAsyncSupported
    <T> Map<K,javax.cache.processor.EntryProcessorResult<T>> invokeAll(Map<? extends K,? extends javax.cache.processor.EntryProcessor<K,V,T>> map,
                                                                                          Object... args)

Parameters:
  `map` - Map containing keys and entry processors to be applied to values.
  `args` - Additional arguments to pass to the `EntryProcessor`.
Returns:
  The map of `EntryProcessorResult`s of the processing per key, if any, defined by the `EntryProcessor` implementation. No mappings will be returned for `EntryProcessor`s that return a `null` value for a key.
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### get

    @IgniteAsyncSupported
    V get(K key)

Specified by:
  `get` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getEntry

    @IgniteAsyncSupported
    CacheEntry<K,V> getEntry(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 `Cache.isClosed()`.
  `NullPointerException` - If the key is `null`.
  `javax.cache.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`.
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getAll

    @IgniteAsyncSupported
    Map<K,V> getAll(Set<? extends K> keys)

Specified by:
  `getAll` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getEntries

    @IgniteAsyncSupported
    Collection<CacheEntry<K,V>> getEntries(Set<? extends K> keys)

Gets a collection of entries from the `Cache`.

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

Parameters:
  `keys` - The keys whose associated values are to be returned.
Returns:
  A collection of entries that were found for the given keys. Entries not found in the cache are not in the returned collection.
Throws:
  `NullPointerException` - If keys is null or if keys contains a `null`.
  `IllegalStateException` - If the cache is `Cache.isClosed()`.
  `javax.cache.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`.
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getAllOutTx

    @IgniteAsyncSupported
    Map<K,V> getAllOutTx(Set<? extends K> keys)

Gets values from cache. Will bypass started transaction, if any, i.e. will not enlist entries and will not lock any keys if pessimistic transaction is started by thread.

Parameters:
  `keys` - The keys whose associated values are to be returned.
Returns:
  A map of entries that were found for the given keys.

#### containsKey

    @IgniteAsyncSupported
    boolean containsKey(K key)

Specified by:
  `containsKey` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### containsKeys

    @IgniteAsyncSupported
    boolean containsKeys(Set<? extends K> keys)

Determines if the `Cache` contains entries for the specified keys.

Parameters:
  `keys` - Key whose presence in this cache is to be tested.
Returns:
  `True` if this cache contains a mapping for the specified keys.
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### put

    @IgniteAsyncSupported
    void put(K key,
                                V val)

Specified by:
  `put` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getAndPut

    @IgniteAsyncSupported
    V getAndPut(K key,
                                   V val)

Specified by:
  `getAndPut` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### putAll

    @IgniteAsyncSupported
    void putAll(Map<? extends K,? extends V> map)

Specified by:
  `putAll` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### putIfAbsent

    @IgniteAsyncSupported
    boolean putIfAbsent(K key,
                                           V val)

Specified by:
  `putIfAbsent` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### remove

    @IgniteAsyncSupported
    boolean remove(K key)

Specified by:
  `remove` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### remove

    @IgniteAsyncSupported
    boolean remove(K key,
                                      V oldVal)

Specified by:
  `remove` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getAndRemove

    @IgniteAsyncSupported
    V getAndRemove(K key)

Specified by:
  `getAndRemove` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### replace

    @IgniteAsyncSupported
    boolean replace(K key,
                                       V oldVal,
                                       V newVal)

Specified by:
  `replace` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### replace

    @IgniteAsyncSupported
    boolean replace(K key,
                                       V val)

Specified by:
  `replace` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### getAndReplace

    @IgniteAsyncSupported
    V getAndReplace(K key,
                                       V val)

Specified by:
  `getAndReplace` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### removeAll

    @IgniteAsyncSupported
    void removeAll(Set<? extends K> keys)

Specified by:
  `removeAll` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### removeAll

    @IgniteAsyncSupported
    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:

- any registered `CacheEntryRemovedListener`s
- if the cache is a write-through cache, the `CacheWriter`

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

This operation is not transactional. It calls broadcast closure that deletes all primary keys from remote nodes.

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

Specified by:
  `removeAll` in interface `javax.cache.Cache<K,V>`
Throws:
  `IllegalStateException` - if the cache is `Cache.isClosed()`
  `javax.cache.CacheException` - if there is a problem during the remove
See Also:
  `clear()`, `CacheWriter.deleteAll(java.util.Collection<?>)`

#### clear

    @IgniteAsyncSupported
    void clear()

Specified by:
  `clear` in interface `javax.cache.Cache<K,V>`

#### clear

    @IgniteAsyncSupported
    void clear(K key)

Clear entry from the cache and swap storage, without notifying listeners or `CacheWriter`s. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Parameters:
  `key` - Key to clear.
Throws:
  `IllegalStateException` - if the cache is `Cache.isClosed()`
  `javax.cache.CacheException` - if there is a problem during the clear

#### clearAll

    @IgniteAsyncSupported
    void clearAll(Set<? extends K> keys)

Clear entries from the cache and swap storage, without notifying listeners or `CacheWriter`s. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Parameters:
  `keys` - Keys to clear.
Throws:
  `IllegalStateException` - if the cache is `Cache.isClosed()`
  `javax.cache.CacheException` - if there is a problem during the clear

#### localClear

    void localClear(K key)

Clear entry from the cache and swap storage, without notifying listeners or `CacheWriter`s. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Note that this operation is local as it merely clears an entry from local cache, it does not remove entries from remote caches.

Parameters:
  `key` - Key to clear.

#### localClearAll

    void localClearAll(Set<? extends K> keys)

Clear entries from the cache and swap storage, without notifying listeners or `CacheWriter`s. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Note that this operation is local as it merely clears an entry from local cache, it does not remove entries from remote caches.

Parameters:
  `keys` - Keys to clear.

#### invoke

    @IgniteAsyncSupported
    <T> T invoke(K key,
                                    javax.cache.processor.EntryProcessor<K,V,T> entryProcessor,
                                    Object... arguments)

Specified by:
  `invoke` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### invoke

    @IgniteAsyncSupported
    <T> T invoke(K key,
                                    CacheEntryProcessor<K,V,T> entryProcessor,
                                    Object... arguments)

Invokes an `CacheEntryProcessor` against the `Cache.Entry` specified by the provided key. If an `Cache.Entry` does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate `Cache.Entry`, consisting of the key with a null value is used instead.

An instance of entry processor must be stateless as it may be invoked multiple times on primary and backup nodes in the cache. It is guaranteed that the value passed to the entry processor will be always the same.

Parameters:
  `key` - The key to the entry.
  `entryProcessor` - The `CacheEntryProcessor` to invoke.
  `arguments` - Additional arguments to pass to the `CacheEntryProcessor`.
Returns:
  The result of the processing, if any, defined by the `CacheEntryProcessor` implementation.
Throws:
  `NullPointerException` - If key or `CacheEntryProcessor` is null
  `IllegalStateException` - If the cache is `Cache.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`.
  `javax.cache.processor.EntryProcessorException` - If an exception is thrown by the `CacheEntryProcessor`, a Caching Implementation must wrap any `Exception` thrown wrapped in an `EntryProcessorException`.
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.
See Also:
  `CacheEntryProcessor`

#### invokeAll

    @IgniteAsyncSupported
    <T> Map<K,javax.cache.processor.EntryProcessorResult<T>> invokeAll(Set<? extends K> keys,
                                                                                          javax.cache.processor.EntryProcessor<K,V,T> entryProcessor,
                                                                                          Object... args)

Specified by:
  `invokeAll` in interface `javax.cache.Cache<K,V>`
Throws:
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.

#### invokeAll

    @IgniteAsyncSupported
    <T> Map<K,javax.cache.processor.EntryProcessorResult<T>> invokeAll(Set<? extends K> keys,
                                                                                          CacheEntryProcessor<K,V,T> entryProcessor,
                                                                                          Object... args)

Invokes an `CacheEntryProcessor` against the set of `Cache.Entry`s specified by the set of keys.

If an `Cache.Entry` does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate `Cache.Entry`, consisting of the key and a value of null is provided.

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 `CacheEntryProcessor` instance to process each entry, as the case may be in a non-local cache topology.

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

An instance of entry processor must be stateless as it may be invoked multiple times on primary and backup nodes in the cache. It is guaranteed that the value passed to the entry processor will be always the same.

Parameters:
  `keys` - The set of keys for entries to process.
  `entryProcessor` - The `CacheEntryProcessor` to invoke.
  `args` - Additional arguments to pass to the `CacheEntryProcessor`.
Returns:
  The map of `EntryProcessorResult`s of the processing per key, if any, defined by the `CacheEntryProcessor` implementation. No mappings will be returned for `CacheEntryProcessor`s that return a `null` value for a key.
Throws:
  `NullPointerException` - If keys or `CacheEntryProcessor` are {#code null}.
  `IllegalStateException` - If the cache is `Cache.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`.
  `TransactionTimeoutException` - If operation performs within transaction and timeout occurred.
  `TransactionRollbackException` - If operation performs within transaction that automatically rolled back.
  `TransactionHeuristicException` - If operation performs within transaction that entered an unknown state.
See Also:
  `CacheEntryProcessor`

#### close

    void close()

Closes this cache instance.

For local cache equivalent to `destroy()`. For distributed caches, if called on clients, stops client cache, if called on a server node, just closes this cache instance and does not destroy cache data.

After cache instance is closed another `IgniteCache` instance for the same cache can be created using `Ignite.cache(String)` method.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `javax.cache.Cache<K,V>`
Specified by:
  `close` in interface `Closeable`

#### destroy

    void destroy()

Completely deletes the cache with all its data from the system on all cluster nodes.

#### rebalance

    IgniteFuture<?> rebalance()

This cache node to re-balance its partitions. This method is usually used when `CacheConfiguration.getRebalanceDelay()` configuration parameter has non-zero value. When many nodes are started or stopped almost concurrently, it is more efficient to delay rebalancing until the node topology is stable to make sure that no redundant re-partitioning happens.

In case of`CacheMode.PARTITIONED` caches, for better efficiency user should usually make sure that new nodes get placed on the same place of consistent hash ring as the left nodes, and that nodes are restarted before `rebalanceDelay` expires. To place nodes on the same place in consistent hash ring, use `IgniteConfiguration.setConsistentId(Serializable)` to make sure that a node maps to the same hash ID if re-started.

See `CacheConfiguration.getRebalanceDelay()` for more information on how to configure rebalance re-partition delay.

Returns:
  Future that will be completed when rebalancing is finished.

#### metrics

    CacheMetrics metrics()

Gets whole cluster snapshot metrics (statistics) for this cache.

Returns:
  Cache metrics.

#### metrics

    CacheMetrics metrics(ClusterGroup grp)

Gets cluster group snapshot metrics for caches in cluster group.

Parameters:
  `grp` - Cluster group.
Returns:
  Cache metrics.

#### localMetrics

    CacheMetrics localMetrics()

Gets local snapshot metrics (statistics) for this cache.

Returns:
  Cache metrics.

#### mxBean

    CacheMetricsMXBean mxBean()

Gets whole cluster MxBean for this cache.

Returns:
  MxBean.

#### localMxBean

    CacheMetricsMXBean localMxBean()

Gets local MxBean for this cache.

Returns:
  MxBean.

2017 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.9.0
Release Date | : March 2 2017