org.gridgain.grid.cache

Interface GridCache<K,V>

Type Parameters:

K - Cache key type.

V - Cache value type.

All Superinterfaces:

GridCacheProjection<K,V>, GridMetadataAware, Iterable<GridCacheEntry<K,V>>, Serializable

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 GridCacheProjection<K,V>

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

Functionality

This API extends GridCacheProjection API which contains vast majority of cache functionality and documentation. In addition to GridCacheProjection 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 GridCacheAffinityFunction service for information on data partitioning and mapping keys to grid nodes responsible for caching those keys.
• Method dataStructures() provides GridCacheDataStructures service for creating and working with distributed concurrent data structures, such as GridCacheAtomicLong, GridCacheAtomicReference, GridCacheQueue, etc.
• 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

Modifier and Type	Method and Description
GridCacheAffinity<K>	affinity() Gets affinity service to provide information about data partitioning and distribution.
GridCacheConfiguration	configuration() Gets configuration bean for this cache.
GridCacheDataStructures	dataStructures() Gets data structures service to provide a gateway for creating various distributed data structures similar in APIs to java.util.concurrent package.
void	dgc() Runs DGC procedure on demand using GridCacheConfiguration.getDgcSuspectLockTimeout() to identify suspect locks.
void	dgc(long suspectLockTimeout, boolean global, boolean rmvLocks) Runs DGC procedure on demand using provided parameter to identify suspect locks.
GridFuture<?>	forceRepartition() Forces this cache node to re-balance its partitions.
void	loadCache(GridBiPredicate<K,V> p, long ttl, Object... args) Delegates to GridCacheStore.loadCache(GridBiInClosure,Object...) method to load state from the underlying persistent storage.
GridFuture<?>	loadCacheAsync(GridBiPredicate<K,V> p, long ttl, Object... args) Asynchronously delegates to GridCacheStore.loadCache(GridBiInClosure, Object...) method to reload state from the underlying persistent storage.
GridCacheMetrics	metrics() 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.
GridCacheEntry<K,V>	randomEntry() Gets a random entry out of cache.
void	resetMetrics() Resets metrics for current 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<GridCacheTxSynchronization>	txSynchronizations() Gets registered transaction synchronizations.
void	txSynchronize(GridCacheTxSynchronization syncs) Registers transactions synchronizations for all transactions started by this cache.
void	txUnsynchronize(GridCacheTxSynchronization syncs) Removes transaction synchronizations.

Methods inherited from interface org.gridgain.grid.cache.GridCacheProjection

cache, clear, clearAll, compact, compactAll, containsKey, containsValue, entry, entrySet, entrySet, evict, evictAll, evictAll, flags, flagsOff, flagsOn, forAll, forEach, get, getAll, getAllAsync, getAsync, globalClearAll, gridProjection, isEmpty, isLocked, isLockedByThread, keySet, lock, lockAll, lockAllAsync, lockAsync, name, nearSize, peek, peek, primaryEntrySet, primaryKeySet, primarySize, primaryValues, projection, projection, projection, promote, promoteAll, put, putAll, putAllAsync, putAsync, putIfAbsent, putIfAbsentAsync, putx, putxAsync, putxIfAbsent, putxIfAbsentAsync, queries, reload, reloadAll, reloadAll, reloadAllAsync, reloadAllAsync, reloadAsync, remove, remove, removeAll, removeAll, removeAllAsync, removeAllAsync, removeAsync, removeAsync, removex, removexAsync, replace, replace, replaceAsync, replaceAsync, replacex, replacexAsync, size, toMap, transform, transformAll, transformAll, transformAllAsync, transformAllAsync, transformAndCompute, transformAsync, tx, txStart, txStart, txStart, txStartAffinity, txStartPartition, unlock, unlockAll, values

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface org.gridgain.grid.GridMetadataAware

addMeta, addMetaIfAbsent, addMetaIfAbsent, allMeta, copyMeta, copyMeta, hasMeta, hasMeta, meta, putMetaIfAbsent, putMetaIfAbsent, removeMeta, removeMeta, replaceMeta

Method Detail

configuration

GridCacheConfiguration configuration()

Gets configuration bean for this cache.

Returns:

Configuration bean for this cache.

txSynchronize

void txSynchronize(@Nullable
                 GridCacheTxSynchronization 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
                   GridCacheTxSynchronization syncs)

Removes transaction synchronizations.

Parameters:

syncs - Transactions synchronizations to remove.

See Also:

txSynchronize(GridCacheTxSynchronization)

txSynchronizations

Collection<GridCacheTxSynchronization> txSynchronizations()

Gets registered transaction synchronizations.

Returns:

Registered transaction synchronizations.

See Also:

txSynchronize(GridCacheTxSynchronization)

affinity

GridCacheAffinity<K> affinity()

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

Returns:

Cache data affinity service.

dataStructures

GridCacheDataStructures dataStructures()

Gets data structures service to provide a gateway for creating various distributed data structures similar in APIs to java.util.concurrent package.

Returns:

Cache data structures service.

metrics

GridCacheMetrics metrics()

Gets metrics (statistics) for this cache.

Returns:

Cache metrics.

overflowSize

long overflowSize()
                  throws GridException

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

Returns:

Size (in bytes) of all entries swapped to disk.

Throws:

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

Gets size in bytes for swap space.

Returns:

Size in bytes.

Throws:

GridException - If failed.

swapKeys

long swapKeys()
              throws GridException

Gets number of swap entries (keys).

Returns:

Number of entries stored in swap.

Throws:

GridException - If failed.

swapIterator

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

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 GridCacheProjection.removex(Object, GridPredicate[]) method.

Cache Flags

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

Returns:

Iterator over keys.

Throws:

GridException - If failed.

See Also:

GridCacheProjection.promote(Object)

offHeapIterator

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

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 GridCacheProjection.removex(Object, GridPredicate[]) method.

Returns:

Iterator over keys.

Throws:

GridException - If failed.

loadCache

void loadCache(@Nullable
             GridBiPredicate<K,V> p,
             long ttl,
             @Nullable
             Object... args)
               throws GridException

Delegates to GridCacheStore.loadCache(GridBiInClosure,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 GridCacheStore 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:

ttl - Time to live for loaded entries (0 for infinity).

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 GridCacheStore.loadCache(GridBiInClosure, Object...) method.

Throws:

GridException - If loading failed.

loadCacheAsync

GridFuture<?> loadCacheAsync(@Nullable
                           GridBiPredicate<K,V> p,
                           long ttl,
                           @Nullable
                           Object... args)

Asynchronously delegates to GridCacheStore.loadCache(GridBiInClosure, Object...) method to reload state from the underlying persistent storage. The reloaded 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 reloaded values will be stored in cache.

Note that this method does not receive keys as a parameter, so it is up to GridCacheStore 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.

ttl - Time to live for loaded entries (0 for infinity).

args - Optional user arguments to be passed into GridCacheStore.loadCache(GridBiInClosure,Object...) method.

Returns:

Future to be completed whenever loading completes.

randomEntry

@Nullable
GridCacheEntry<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 GridCacheProjection 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.

dgc

void dgc()

Runs DGC procedure on demand using GridCacheConfiguration.getDgcSuspectLockTimeout() to identify suspect locks.

Method blocks current thread until locks are examined and all DGC requests are sent to remote nodes.

DGC does not remove locks if GridCacheConfiguration.isDgcRemoveLocks() is set to false.

dgc

void dgc(long suspectLockTimeout,
       boolean global,
       boolean rmvLocks)

Runs DGC procedure on demand using provided parameter to identify suspect locks.

Method blocks current thread until locks are examined and all DGC requests are sent to remote nodes and (if global is true) all nodes running this cache will get signal to start GC procedure.

Parameters:

suspectLockTimeout - Custom suspect lock timeout (should be greater than or equal to 0).

global - If true then GC procedure will start on all nodes having this cache.

rmvLocks - If false then DGC does not remove locks, just report them to log.

forceRepartition

GridFuture<?> forceRepartition()

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

In case ofGridCacheMode.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 preloadDelay expires. To place nodes on the same place in consistent hash ring, use GridCacheConsistentHashAffinityFunction.setHashIdResolver(GridCacheAffinityNodeHashResolver) to make sure that a node maps to the same hash ID if re-started.

See GridCacheConfiguration.getPreloadPartitionedDelay() for more information on how to configure preload re-partition delay.

Returns:

Future that will be completed when preloading is finished.

resetMetrics

void resetMetrics()

Resets metrics for current cache.