org.apache.ignite.internal.processors.cache

## Interface GridCache<K,V>

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

All Superinterfaces:
  CacheProjection<K,V>, Iterable<javax.cache.Cache.Entry<K,V>>

All Known Subinterfaces:
  GridCacheProxy<K,V>

All Known Implementing Classes:
  GridCacheAdapter, GridCacheProxyImpl, GridDhtAtomicCache, GridDhtCache, GridDhtCacheAdapter, GridDhtColocatedCache, GridDhtTransactionalCacheAdapter, GridDistributedCacheAdapter, GridLocalAtomicCache, GridLocalCache, GridNearAtomicCache, GridNearCacheAdapter, GridNearTransactionalCache

    public interface GridCache<K,V>
    extends CacheProjection<K,V>

Main entry point for all Data Grid APIs. You can get a named cache by calling `Ignite.cache(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.
- Method `affinity()` provides `AffinityFunction` service for information on data partitioning and mapping keys to grid nodes responsible for caching those keys.
- 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 `configuration()` to provide cache configuration bean.

### Method Summary

Methods
`Affinity<K>` `affinity()` Gets affinity service to provide information about data partitioning and distribution.
`boolean` `affinityNode()`
`CacheConfiguration` `configuration()` Gets configuration bean for this cache.
`IgniteInternalFuture<?>` `forceRepartition()` Forces this cache node to re-balance its partitions.
`CacheMetrics` `metrics()` Gets metrics (statistics) for this cache.
`CacheMetricsMXBean` `mxBean()` Gets metrics (statistics) for this cache.
`long` `offHeapAllocatedSize()` Gets memory size allocated in off-heap.
`long` `offHeapEntriesCount()` Gets number of cache entries stored in off-heap memory.
`Iterator<Map.Entry<K,V>>` `offHeapIterator()` Gets iterator over keys and values belonging to this cache off-heap memory on local node.
`long` `overflowSize()` Gets size (in bytes) of all entries swapped to disk.
`javax.cache.Cache.Entry<K,V>` `randomEntry()` Gets a random entry out of cache.
`Iterator<Map.Entry<K,V>>` `swapIterator()` Gets iterator over keys and values belonging to this cache swap space on local node.
`long` `swapKeys()` Gets number of swap entries (keys).
`long` `swapSize()` Gets size in bytes for swap space.
`Collection<TransactionSynchronization>` `txSynchronizations()` Gets registered transaction synchronizations.
`void` `txSynchronize(TransactionSynchronization syncs)` Registers transactions synchronizations for all transactions started by this cache.
`void` `txUnsynchronize(TransactionSynchronization syncs)` Removes transaction synchronizations.

### Methods inherited from interface org.apache.ignite.internal.processors.cache.CacheProjection

`cache, clear, clear, clear, clearAll, clearAsync, clearAsync, clearAsync, clearLocally, clearLocally, clearLocallyAll, containsKey, containsKeyAsync, containsKeys, containsKeysAsync, containsValue, entry, entrySet, entrySet, evict, evictAll, evictAll, flags, flagsOff, flagsOn, get, getAll, getAllAsync, getAsync, globalPrimarySize, globalSize, gridProjection, isEmpty, isLocked, isLockedByThread, keepPortable, keySet, keySet, localEntries, localPeek, localRemoveAll, localSize, lock, lockAll, lockAllAsync, lockAsync, name, nearSize, peek, peek, primaryEntrySet, primaryKeySet, primarySize, primaryValues, projection, projection, promote, promoteAll, put, putAll, putAllAsync, putAsync, putIfAbsent, putIfAbsentAsync, putx, putxAsync, putxIfAbsent, putxIfAbsentAsync, queries, reload, reloadAsync, remove, remove, removeAll, removeAll, removeAllAsync, removeAllAsync, removeAsync, removeAsync, removex, removexAsync, replace, replace, replaceAsync, replaceAsync, replacex, replacexAsync, size, size, sizeAsync, toMap, tx, txStart, txStart, txStart, txStartEx, unlock, unlockAll, values`

### Methods inherited from interface java.lang.Iterable

`iterator`

### Method Detail

#### configuration

    CacheConfiguration configuration()

Gets configuration bean for this cache.

Returns:
  Configuration bean for this cache.

#### txSynchronize

    void txSynchronize(@Nullable
                     TransactionSynchronization syncs)

Registers transactions synchronizations for all transactions started by this cache. Use it whenever you need to get notifications on transaction lifecycle and possibly change its course. It is also particularly useful when integrating cache transactions with some other in-house transactions.

Parameters:
  `syncs` - Transaction synchronizations to register.

#### txUnsynchronize

    void txUnsynchronize(@Nullable
                       TransactionSynchronization syncs)

Removes transaction synchronizations.

Parameters:
  `syncs` - Transactions synchronizations to remove.
See Also:
  `txSynchronize(TransactionSynchronization)`

#### txSynchronizations

    Collection<TransactionSynchronization> txSynchronizations()

Gets registered transaction synchronizations.

Returns:
  Registered transaction synchronizations.
See Also:
  `txSynchronize(TransactionSynchronization)`

#### affinity

    Affinity<K> affinity()

Gets affinity service to provide information about data partitioning and distribution.

Returns:
  Cache data affinity service.

#### metrics

    CacheMetrics metrics()

Gets metrics (statistics) for this cache.

Returns:
  Cache metrics.

#### mxBean

    CacheMetricsMXBean mxBean()

Gets metrics (statistics) for this cache.

Returns:
  Cache metrics.

#### overflowSize

    long overflowSize()
                      throws IgniteCheckedException

Gets size (in bytes) of all entries swapped to disk.

Returns:
  Size (in bytes) of all entries swapped to disk.
Throws:
  `IgniteCheckedException` - In case of error.

#### offHeapEntriesCount

    long offHeapEntriesCount()

Gets number of cache entries stored in off-heap memory.

Returns:
  Number of cache entries stored in off-heap memory.

#### offHeapAllocatedSize

    long offHeapAllocatedSize()

Gets memory size allocated in off-heap.

Returns:
  Allocated memory size.

#### swapSize

    long swapSize()
                  throws IgniteCheckedException

Gets size in bytes for swap space.

Returns:
  Size in bytes.
Throws:
  `IgniteCheckedException` - If failed.

#### swapKeys

    long swapKeys()
                  throws IgniteCheckedException

Gets number of swap entries (keys).

Returns:
  Number of entries stored in swap.
Throws:
  `IgniteCheckedException` - If failed.

#### swapIterator

    Iterator<Map.Entry<K,V>> swapIterator()
                                          throws IgniteCheckedException

Gets iterator over keys and values belonging to this cache swap space on local node. This iterator is thread-safe, which means that cache (and therefore its swap space) may be modified concurrently with iteration over swap.

Returned iterator supports `remove` operation which delegates to `removex(Object, org.apache.ignite.lang.IgnitePredicate[])` method.

## Cache Flags

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

Returns:
  Iterator over keys.
Throws:
  `IgniteCheckedException` - If failed.
See Also:
  `CacheProjection.promote(Object)`

#### offHeapIterator

    Iterator<Map.Entry<K,V>> offHeapIterator()
                                             throws IgniteCheckedException

Gets iterator over keys and values belonging to this cache off-heap memory on local node. This iterator is thread-safe, which means that cache (and therefore its off-heap memory) may be modified concurrently with iteration over off-heap. To achieve better performance the keys and values deserialized on demand, whenever accessed.

Returned iterator supports `remove` operation which delegates to `removex(Object, org.apache.ignite.lang.IgnitePredicate[])}` method.

Returns:
  Iterator over keys.
Throws:
  `IgniteCheckedException` - If failed.

#### randomEntry

    @Nullable
    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`.

Note that this method is not available on `CacheProjection` API since it is impossible (or very hard) to deterministically return a number value when pre-filtering and post-filtering is involved (e.g. projection level predicate filters).

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

#### forceRepartition

    IgniteInternalFuture<?> forceRepartition()

Forces 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 `RendezvousAffinityFunction.setHashIdResolver(AffinityNodeHashResolver)` 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.

#### affinityNode

    boolean affinityNode()

Returns:
  `True` if local node is affinity node.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0
Release Date | : March 31 2015