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.jcache(String)` method.

# Functionality

This API extends `CacheProjection` API which contains vast majority of cache functionality and documentation. In addition to `CacheProjection` functionality this API provides:

- Various `'loadCache(..)'` methods to load cache either synchronously or asynchronously. These methods don't specify any keys to load, and leave it to the underlying storage to load cache data based on the optionally passed in arguments.
- Methods like `'tx{Un}Synchronize(..)'` witch allow to get notifications for transaction state changes. This feature is very useful when integrating cache transactions with some other in-house transactions.
- Method `metrics()` to provide metrics for the whole cache.
- Method `getConfiguration(Class)`} to provide cache configuration bean.

### Nested Class Summary

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

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

### Method Summary

Methods
`void` `clear()`
`boolean` `containsKey(K key)`
`boolean` `containsKeys(Set<? extends K> keys)`
`V` `get(K key)`
`Map<K,V>` `getAll(Set<? extends K> keys)`
`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)`
`<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, 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.
`Iterable<javax.cache.Cache.Entry<K,V>>` `localEntries(CachePeekMode... peekModes)`
`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.
`V` `localPeek(K key, CachePeekMode... peekModes)` Peeks at in-memory cached value using default `GridCachePeekMode.SMART` peek mode.
`void` `localPromote(Set<? extends K> keys)` This method unswaps cache entries by given keys, if any, from swap storage into memory.
`QueryCursor<javax.cache.Cache.Entry<K,V>>` `localQuery(Query qry)` Queries cache locally.
`QueryCursor<List<?>>` `localQueryFields(SqlFieldsQuery qry)` Queries separate entry fields locally.
`int` `localSize(CachePeekMode... peekModes)` Gets the number of all entries cached on this nodes.
`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 snapshot metrics (statistics) for this cache.
`CacheMetricsMXBean` `mxBean()` Gets MxBean for this cache.
`void` `put(K key, V val)`
`void` `putAll(Map<? extends K,? extends V> map)`
`boolean` `putIfAbsent(K key, V val)`
`QueryCursor<javax.cache.Cache.Entry<K,V>>` `query(Query qry)` Queries cache.
`QueryCursor<List<?>>` `queryFields(SqlFieldsQuery qry)` Queries separate entry fields.
`javax.cache.Cache.Entry<K,V>` `randomEntry()` Gets a random entry out of cache.
`boolean` `remove(K key)`
`boolean` `remove(K key, V oldVal)`
`void` `removeAll()`
`void` `removeAll(Set<? extends K> keys)`
`boolean` `replace(K key, V val)`
`boolean` `replace(K key, V oldVal, V newVal)`
`int` `size(CachePeekMode... peekModes)` Gets the number of all entries cached across all nodes.
`IgniteCache<K,V>` `withAsync()` Gets component with asynchronous mode enabled.
`IgniteCache<K,V>` `withExpiryPolicy(javax.cache.expiry.ExpiryPolicy plc)`
`IgniteCache<K,V>` `withSkipStore()`

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

`close, 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 component with asynchronous mode enabled.

Specified by:
  `withAsync` in interface `IgniteAsyncSupport`
Returns:
  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

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

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)

#### withSkipStore

    IgniteCache<K,V> withSkipStore()

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

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

#### 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(Cache.Entry)` method.

## Transactions

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

## Cache Flags

This method is not available if any of the following flags are set on projection: `CacheFlag.LOCAL`, `CacheFlag.READ`.

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.
  `CacheFlagException` - If projection flags validation failed.

#### 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

    QueryCursor<javax.cache.Cache.Entry<K,V>> query(Query qry)

Queries cache. Accepts any subclass of `Query`.

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

#### queryFields

    QueryCursor<List<?>> queryFields(SqlFieldsQuery qry)

Queries separate entry fields.

Parameters:
  `qry` - SQL Query.
Returns:
  Cursor.

#### localQuery

    QueryCursor<javax.cache.Cache.Entry<K,V>> localQuery(Query qry)

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

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

#### localQueryFields

    QueryCursor<List<?>> localQueryFields(SqlFieldsQuery qry)

Queries separate entry fields locally.

Parameters:
  `qry` - SQL Query.
Returns:
  Cursor.

#### localEntries

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

Throws:
  `javax.cache.CacheException`

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

If `CacheConfiguration.isSwapEnabled()` is set to `true` and `CacheFlag.SKIP_SWAP` is not enabled, the evicted entry will be swapped to offheap, and then to disk.

## Cache Flags

This method is not available if any of the following flags are set on projection: `CacheFlag.READ`.

Parameters:
  `keys` - Keys to evict.

#### localPeek

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

Peeks at in-memory cached value using default `GridCachePeekMode.SMART` 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, however, it will peek at transactional value according to the `GridCachePeekMode.SMART` mode semantics.

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.

## Cache Flags

This method is not available if any of the following flags are set on projection: `CacheFlag.SKIP_SWAP`, `CacheFlag.READ`.

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

#### size

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

Gets the number of all entries cached across all nodes.

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`

#### localSize

    int localSize(CachePeekMode... peekModes)

Gets the number of all entries cached on this nodes.

Parameters:
  `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.

#### get

    @IgniteAsyncSupported
    V get(K key)

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

#### getAll

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

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

#### containsKey

    @IgniteAsyncSupported
    boolean containsKey(K key)

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

#### containsKeys

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

#### put

    @IgniteAsyncSupported
    void put(K key,
                                V val)

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

#### getAndPut

    @IgniteAsyncSupported
    V getAndPut(K key,
                                   V val)

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

#### putAll

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

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

#### putIfAbsent

    @IgniteAsyncSupported
    boolean putIfAbsent(K key,
                                           V val)

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

#### remove

    @IgniteAsyncSupported
    boolean remove(K key)

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

#### remove

    @IgniteAsyncSupported
    boolean remove(K key,
                                      V oldVal)

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

#### getAndRemove

    @IgniteAsyncSupported
    V getAndRemove(K key)

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

#### replace

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

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

#### replace

    @IgniteAsyncSupported
    boolean replace(K key,
                                       V val)

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

#### getAndReplace

    @IgniteAsyncSupported
    V getAndReplace(K key,
                                       V val)

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

#### removeAll

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

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

#### removeAll

    @IgniteAsyncSupported
    void removeAll()

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

#### clear

    @IgniteAsyncSupported
    void clear()

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

#### 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>`

#### 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>`

#### metrics

    CacheMetrics metrics()

Gets snapshot metrics (statistics) for this cache.

Returns:
  Cache metrics.

#### mxBean

    CacheMetricsMXBean mxBean()

Gets MxBean for this cache.

Returns:
  MxBean.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC1
Release Date | : February 17 2015