org.gridgain.grid.cache

Interface GridCacheEntry<K,V>

Type Parameters:

K - Key type.

V - Value type.

All Superinterfaces:

GridMetadataAware, Map.Entry<K,V>, Serializable

All Known Implementing Classes:

GridCacheEntryImpl, GridCacheEvictionEntry, GridCacheFilterEvaluationEntry, GridDhtCacheEntryImpl, GridPartitionedCacheEntryImpl

public interface GridCacheEntry<K,V>
extends Map.Entry<K,V>, GridMetadataAware

This interface provides a rich API for working with individual cache entries. It includes the following main functionality:

• Various 'get(..)' methods to synchronously or asynchronously get values from cache. All 'get(..)' methods are transactional and will participate in an ongoing transaction if there is one.
• Various 'set(..)', 'setIfAbsent(..)', and 'replace(..)' methods to synchronously or asynchronously put single or multiple entries into cache. All these methods are transactional and will participate in an ongoing transaction if there is one.
• Various 'remove(..)' methods to synchronously or asynchronously remove single or multiple keys from cache. All 'remove(..)' methods are transactional and will participate in an ongoing transaction if there is one.
• Various 'invalidate(..)' methods to set cached values to null.
• Various 'isLocked(..)' methods to check on distributed locks on a single or multiple keys in cache. All locking methods are not transactional and will not enlist keys into ongoing transaction, if any.
• Various 'peek(..)' methods to peek at values in global or transactional memory, swap storage, or persistent storage.
• Various 'reload(..)' methods to reload latest values from persistent storage.
• Method evict() to evict elements from cache, and optionally store them in underlying swap storage for later access. All 'evict(..)' methods are not transactional and will not enlist evicted keys into ongoing transaction, if any.
• Methods for timeToLive(long) to change or lookup entry's time to live.

Extended Put And Remove Methods

All methods that end with 'x' provide the same functionality as their sibling methods that don't end with 'x', however instead of returning a previous value they return a boolean flag indicating whether operation succeeded or not. Returning a previous value may involve a network trip or a persistent store lookup and should be avoided whenever not needed.

Predicate Filters

All filters passed into methods on this API are checked atomically. In other words the value of cache entry is guaranteed not to change throughout the cache operation.

Transactions

Cache API supports distributed transactions. All 'get(..)', 'put(..)', 'replace(..)', and 'remove(..)' operations are transactional and will participate in an ongoing transaction. Other methods like 'peek(..)' may be transaction-aware, i.e. check in-transaction entries first, but will not affect the current state of transaction. See GridCacheTx documentation for more information about transactions.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	backup() Gets the flag indicating if current node is backup for this entry.
boolean	clear() This method has the same semantic as GridCacheProjection.clear(Object) method.
boolean	compact() Optimizes the size of this entry.
boolean	evict() This method has the same semantic as GridCacheProjection.evict(Object) method.
long	expirationTime() Gets expiration time for this entry.
V	get() This method has the same semantic as GridCacheProjection.get(Object) method.
GridFuture<V>	getAsync() This method has the same semantic as GridCacheProjection.getAsync(Object) method.
V	getValue() This method has the same semantic as get() method, however it wraps GridException into GridRuntimeException if failed in order to comply with Map.Entry interface.
boolean	isCached() Checks whether entry is currently present in cache or not.
boolean	isLocked() This method has the same semantic as GridCacheProjection.isLocked(Object) method.
boolean	isLockedByThread() This method has the same semantic as GridCacheProjection.isLockedByThread(Object) method.
boolean	lock(long timeout, GridPredicate<GridCacheEntry<K,V>>... filter) Synchronously acquires lock on a cached object associated with this entry only if the passed in filter (if any) passes.
GridFuture<Boolean>	lockAsync(long timeout, GridPredicate<GridCacheEntry<K,V>>... filter) Asynchronously acquires lock on a cached object associated with this entry only if the passed in filter (if any) passes.
int	memorySize() Gets size of serialized key and value in addition to any overhead added by GridGain itself.
int	partition() Gets affinity partition id for this entry.
V	peek() This method has the same semantic as GridCacheProjection.peek(Object) method.
V	peek(Collection<GridCachePeekMode> modes) This method has the same semantic as GridCacheProjection.peek(Object, Collection) method.
boolean	primary() Gets the flag indicating current node's primary ownership for this entry.
GridCacheProjection<K,V>	projection() Cache projection to which this entry belongs.
V	reload() This method has the same semantic as GridCacheProjection.reload(Object) method.
GridFuture<V>	reloadAsync() This method has the same semantic as GridCacheProjection.reloadAsync(Object) method.
V	remove(GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.remove(Object, GridPredicate[]) method.
boolean	remove(V val) This method has the same semantic as GridCacheProjection.remove(Object, Object) method.
GridFuture<V>	removeAsync(GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.removeAsync(Object, GridPredicate[]) method.
GridFuture<Boolean>	removeAsync(V val) This method has the same semantic as GridCacheProjection.removeAsync(Object, Object) method.
boolean	removex(GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.removex(Object, GridPredicate[]) method.
GridFuture<Boolean>	removexAsync(GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.removexAsync(Object, GridPredicate[]) method.
V	replace(V val) This method has the same semantic as GridCacheProjection.replace(Object, Object) method.
boolean	replace(V oldVal, V newVal) This method has the same semantic as GridCacheProjection.replace(Object, Object, Object) method.
GridFuture<V>	replaceAsync(V val) This method has the same semantic as GridCacheProjection.replaceAsync(Object, Object) method.
GridFuture<Boolean>	replaceAsync(V oldVal, V newVal) This method has the same semantic as GridCacheProjection.replaceAsync(Object, Object, Object) method.
boolean	replacex(V val) This method has the same semantic as GridCacheProjection.replacex(Object, Object) method.
GridFuture<Boolean>	replacexAsync(V val) This method has the same semantic as GridCacheProjection.replacexAsync(Object, Object) method.
V	set(V val, GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.put(Object, Object, GridPredicate[]) method.
GridFuture<V>	setAsync(V val, GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.putAsync(Object, Object, GridPredicate[]) method.
V	setIfAbsent(V val) This method has the same semantic as GridCacheProjection.putIfAbsent(Object, Object) method.
GridFuture<V>	setIfAbsentAsync(V val) This method has the same semantic as GridCacheProjection.putIfAbsentAsync(Object, Object) method.
V	setValue(V val) This method has the same semantic as set(Object, GridPredicate[]) method, however it wraps GridException into GridRuntimeException if failed in order to comply with Map.Entry interface.
boolean	setx(V val, GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.putx(Object, Object, GridPredicate[]) method.
GridFuture<Boolean>	setxAsync(V val, GridPredicate<GridCacheEntry<K,V>>... filter) This method has the same semantic as GridCacheProjection.putxAsync(Object, Object, GridPredicate[]) method.
boolean	setxIfAbsent(V val) This method has the same semantic as GridCacheProjection.putxIfAbsent(Object, Object) method.
GridFuture<Boolean>	setxIfAbsentAsync(V val) This method has the same semantic as GridCacheProjection.putxIfAbsentAsync(Object, Object) method.
long	timeToLive() Gets time to live, i.e.
void	timeToLive(long ttl) Sets time to live, i.e.
void	transform(GridClosure<V,V> transformer) This method has the same semantic as GridCacheProjection.transform(Object, GridClosure) method.
GridFuture<?>	transformAsync(GridClosure<V,V> transformer) This method has the same semantic as GridCacheProjection.transformAsync(Object, GridClosure) method.
void	unlock(GridPredicate<GridCacheEntry<K,V>>... filter) Unlocks this entry only if current thread owns the lock.
Object	version() Gets current version of this cache entry.

Methods inherited from interface java.util.Map.Entry

equals, getKey, hashCode

Methods inherited from interface org.gridgain.grid.GridMetadataAware

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

Method Detail

projection

GridCacheProjection<K,V> projection()

Cache projection to which this entry belongs. Note that entry and its parent projections have same flags and filters.

Returns:

Cache projection for the cache to which this entry belongs.

peek

@Nullable
V peek()

This method has the same semantic as GridCacheProjection.peek(Object) method.

Returns:

See GridCacheProjection.peek(Object).

peek

@Nullable
V peek(@Nullable
              Collection<GridCachePeekMode> modes)
       throws GridException

This method has the same semantic as GridCacheProjection.peek(Object, Collection) method.

Parameters:

modes - See GridCacheProjection.peek(Object, Collection).

Returns:

See GridCacheProjection.peek(Object, Collection).

Throws:

GridException - See GridCacheProjection.peek(Object, Collection).

reload

@Nullable
V reload()
         throws GridException

This method has the same semantic as GridCacheProjection.reload(Object) method.

Returns:

See GridCacheProjection.reload(Object).

Throws:

GridException - See GridCacheProjection.reload(Object).

reloadAsync

GridFuture<V> reloadAsync()

This method has the same semantic as GridCacheProjection.reloadAsync(Object) method.

Returns:

See GridCacheProjection.reloadAsync(Object).

isLocked

boolean isLocked()

This method has the same semantic as GridCacheProjection.isLocked(Object) method.

Returns:

See GridCacheProjection.isLocked(Object).

isLockedByThread

boolean isLockedByThread()

This method has the same semantic as GridCacheProjection.isLockedByThread(Object) method.

Returns:

See GridCacheProjection.isLockedByThread(Object).

version

Object version()

Gets current version of this cache entry.

Returns:

Version of this cache entry.

expirationTime

long expirationTime()

Gets expiration time for this entry.

Returns:

Absolute time when this value expires.

timeToLive

long timeToLive()

Gets time to live, i.e. maximum life time, of this entry in milliseconds.

Returns:

Time to live value for this entry.

timeToLive

void timeToLive(long ttl)

Sets time to live, i.e. maximum life time, of this entry in milliseconds. Note that this method is transactional - if entry is enlisted into a transaction, then time-to-live will not be set until transaction commit.

When called outside the transaction, this method will have no effect until the next update operation.

Parameters:

ttl - Time to live value for this entry.

primary

boolean primary()

Gets the flag indicating current node's primary ownership for this entry.

Note, that this value is dynamic and may change with grid topology changes.

Returns:

True if current grid node is the primary owner for this entry.

backup

boolean backup()

Gets the flag indicating if current node is backup for this entry.

Note, that this value is dynamic and may change with grid topology changes.

Returns:

True if current grid node is the backup for this entry.

partition

int partition()

Gets affinity partition id for this entry.

Returns:

Partition id.

getValue

@Nullable
V getValue()

This method has the same semantic as get() method, however it wraps GridException into GridRuntimeException if failed in order to comply with Map.Entry interface.

Specified by:

getValue in interface Map.Entry<K,V>

Returns:

See get()

get

@Nullable
V get()
      throws GridException

This method has the same semantic as GridCacheProjection.get(Object) method.

Returns:

See GridCacheProjection.get(Object).

Throws:

GridException - See GridCacheProjection.get(Object).

getAsync

GridFuture<V> getAsync()

This method has the same semantic as GridCacheProjection.getAsync(Object) method.

Returns:

See GridCacheProjection.getAsync(Object).

setValue

@Nullable
V setValue(V val)

This method has the same semantic as set(Object, GridPredicate[]) method, however it wraps GridException into GridRuntimeException if failed in order to comply with Map.Entry interface.

Specified by:

setValue in interface Map.Entry<K,V>

Returns:

See set(Object, GridPredicate[])

set

@Nullable
V set(V val,
             @Nullable
             GridPredicate<GridCacheEntry<K,V>>... filter)
      throws GridException

This method has the same semantic as GridCacheProjection.put(Object, Object, GridPredicate[]) method.

Parameters:

val - See GridCacheProjection.put(Object, Object, GridPredicate[])

filter - See GridCacheProjection.put(Object, Object, GridPredicate[]).

Returns:

See GridCacheProjection.put(Object, Object, GridPredicate[]).

Throws:

GridException - See GridCacheProjection.put(Object, Object, GridPredicate[]).

setAsync

GridFuture<V> setAsync(V val,
                     @Nullable
                     GridPredicate<GridCacheEntry<K,V>>... filter)

This method has the same semantic as GridCacheProjection.putAsync(Object, Object, GridPredicate[]) method.

Parameters:

val - See GridCacheProjection.putAsync(Object, Object, GridPredicate[])

filter - See GridCacheProjection.putAsync(Object, Object, GridPredicate[]).

Returns:

See GridCacheProjection.putAsync(Object, Object, GridPredicate[]).

setIfAbsent

@Nullable
V setIfAbsent(V val)
              throws GridException

This method has the same semantic as GridCacheProjection.putIfAbsent(Object, Object) method.

Parameters:

val - See GridCacheProjection.putIfAbsent(Object, Object)

Returns:

See GridCacheProjection.putIfAbsent(Object, Object).

Throws:

GridException - See GridCacheProjection.putIfAbsent(Object, Object).

setIfAbsentAsync

GridFuture<V> setIfAbsentAsync(V val)

This method has the same semantic as GridCacheProjection.putIfAbsentAsync(Object, Object) method.

Parameters:

val - See GridCacheProjection.putIfAbsentAsync(Object, Object)

Returns:

See GridCacheProjection.putIfAbsentAsync(Object, Object).

setx

boolean setx(V val,
           @Nullable
           GridPredicate<GridCacheEntry<K,V>>... filter)
             throws GridException

This method has the same semantic as GridCacheProjection.putx(Object, Object, GridPredicate[]) method.

Parameters:

val - See GridCacheProjection.putx(Object, Object, GridPredicate[])

filter - See GridCacheProjection.putx(Object, Object, GridPredicate[]).

Returns:

See GridCacheProjection.putx(Object, Object, GridPredicate[]).

Throws:

GridException - See GridCacheProjection.putx(Object, Object, GridPredicate[]).

setxAsync

GridFuture<Boolean> setxAsync(V val,
                            @Nullable
                            GridPredicate<GridCacheEntry<K,V>>... filter)

This method has the same semantic as GridCacheProjection.putxAsync(Object, Object, GridPredicate[]) method.

Parameters:

val - See GridCacheProjection.putxAsync(Object, Object, GridPredicate[])

filter - See GridCacheProjection.putxAsync(Object, Object, GridPredicate[]).

Returns:

See GridCacheProjection.putxAsync(Object, Object, GridPredicate[]).

setxIfAbsent

boolean setxIfAbsent(@Nullable
                   V val)
                     throws GridException

This method has the same semantic as GridCacheProjection.putxIfAbsent(Object, Object) method.

Parameters:

val - See GridCacheProjection.putxIfAbsent(Object, Object)

Returns:

See GridCacheProjection.putxIfAbsent(Object, Object).

Throws:

GridException - See GridCacheProjection.putxIfAbsent(Object, Object).

setxIfAbsentAsync

GridFuture<Boolean> setxIfAbsentAsync(V val)

This method has the same semantic as GridCacheProjection.putxIfAbsentAsync(Object, Object) method.

Parameters:

val - See GridCacheProjection.putxIfAbsentAsync(Object, Object)

Returns:

See GridCacheProjection.putxIfAbsentAsync(Object, Object).

transform

void transform(GridClosure<V,V> transformer)
               throws GridException

This method has the same semantic as GridCacheProjection.transform(Object, GridClosure) method.

Parameters:

transformer - Closure to be applied to the previous value in cache. If this closure returns null, the associated value will be removed from cache.

Throws:

GridException - If cache update failed.

See Also:

GridCacheProjection.transform(Object, GridClosure)

transformAsync

GridFuture<?> transformAsync(GridClosure<V,V> transformer)

This method has the same semantic as GridCacheProjection.transformAsync(Object, GridClosure) method.

Parameters:

transformer - Closure to be applied to the previous value in cache. If this closure returns null, the associated value will be removed from cache.

Returns:

Transform operation future.

replace

@Nullable
V replace(V val)
          throws GridException

This method has the same semantic as GridCacheProjection.replace(Object, Object) method.

Parameters:

val - See GridCacheProjection.replace(Object, Object)

Returns:

See GridCacheProjection.replace(Object, Object).

Throws:

GridException - See GridCacheProjection.replace(Object, Object).

replaceAsync

GridFuture<V> replaceAsync(V val)

This method has the same semantic as GridCacheProjection.replaceAsync(Object, Object) method.

Parameters:

val - See GridCacheProjection.replaceAsync(Object, Object)

Returns:

See GridCacheProjection.replaceAsync(Object, Object).

replacex

boolean replacex(V val)
                 throws GridException

This method has the same semantic as GridCacheProjection.replacex(Object, Object) method.

Parameters:

val - See GridCacheProjection.replacex(Object, Object)

Returns:

See GridCacheProjection.replacex(Object, Object).

Throws:

GridException - See GridCacheProjection.replacex(Object, Object).

replacexAsync

GridFuture<Boolean> replacexAsync(V val)

This method has the same semantic as GridCacheProjection.replacexAsync(Object, Object) method.

Parameters:

val - See GridCacheProjection.replacexAsync(Object, Object)

Returns:

See GridCacheProjection.replacexAsync(Object, Object).

replace

boolean replace(V oldVal,
              V newVal)
                throws GridException

This method has the same semantic as GridCacheProjection.replace(Object, Object, Object) method.

Parameters:

oldVal - See GridCacheProjection.replace(Object, Object, Object)

newVal - See GridCacheProjection.replace(Object, Object, Object)

Returns:

See GridCacheProjection.replace(Object, Object).

Throws:

GridException - See GridCacheProjection.replace(Object, Object).

replaceAsync

GridFuture<Boolean> replaceAsync(V oldVal,
                               V newVal)

This method has the same semantic as GridCacheProjection.replaceAsync(Object, Object, Object) method.

Parameters:

oldVal - See GridCacheProjection.replaceAsync(Object, Object, Object)

newVal - See GridCacheProjection.replaceAsync(Object, Object, Object)

Returns:

See GridCacheProjection.replaceAsync(Object, Object).

remove

@Nullable
V remove(@Nullable
                GridPredicate<GridCacheEntry<K,V>>... filter)
         throws GridException

This method has the same semantic as GridCacheProjection.remove(Object, GridPredicate[]) method.

Parameters:

filter - See GridCacheProjection.remove(Object, GridPredicate[]).

Returns:

See GridCacheProjection.remove(Object, GridPredicate[]).

Throws:

GridException - See GridCacheProjection.remove(Object, GridPredicate[]).

removeAsync

GridFuture<V> removeAsync(@Nullable
                        GridPredicate<GridCacheEntry<K,V>>... filter)

This method has the same semantic as GridCacheProjection.removeAsync(Object, GridPredicate[]) method.

Parameters:

filter - See GridCacheProjection.removeAsync(Object, GridPredicate[]).

Returns:

See GridCacheProjection.removeAsync(Object, GridPredicate[]).

removex

boolean removex(@Nullable
              GridPredicate<GridCacheEntry<K,V>>... filter)
                throws GridException

This method has the same semantic as GridCacheProjection.removex(Object, GridPredicate[]) method.

Parameters:

filter - See GridCacheProjection.removex(Object, GridPredicate[]).

Returns:

See GridCacheProjection.removex(Object, GridPredicate[]).

Throws:

GridException - See GridCacheProjection.removex(Object, GridPredicate[]).

removexAsync

GridFuture<Boolean> removexAsync(@Nullable
                               GridPredicate<GridCacheEntry<K,V>>... filter)

This method has the same semantic as GridCacheProjection.removexAsync(Object, GridPredicate[]) method.

Parameters:

filter - See GridCacheProjection.removexAsync(Object, GridPredicate[]).

Returns:

See GridCacheProjection.removexAsync(Object, GridPredicate[]).

remove

boolean remove(V val)
               throws GridException

This method has the same semantic as GridCacheProjection.remove(Object, Object) method.

Parameters:

val - See GridCacheProjection.remove(Object, Object).

Returns:

See GridCacheProjection.remove(Object, Object).

Throws:

GridException - See GridCacheProjection.remove(Object, Object).

removeAsync

GridFuture<Boolean> removeAsync(V val)

This method has the same semantic as GridCacheProjection.removeAsync(Object, Object) method.

Parameters:

val - See GridCacheProjection.removeAsync(Object, Object).

Returns:

See GridCacheProjection.removeAsync(Object, Object).

evict

boolean evict()

This method has the same semantic as GridCacheProjection.evict(Object) method.

Returns:

See GridCacheProjection.evict(Object).

clear

boolean clear()

This method has the same semantic as GridCacheProjection.clear(Object) method.

Returns:

See GridCacheProjection.clear(Object).

compact

boolean compact()
                throws GridException

Optimizes the size of this entry. If entry is expired at the time of the call then entry is removed locally.

Returns:

true if entry was cleared from cache (if value was null).

Throws:

GridException - If failed to compact.

lock

boolean lock(long timeout,
           @Nullable
           GridPredicate<GridCacheEntry<K,V>>... filter)
             throws GridException

Synchronously acquires lock on a cached object associated with this entry only if the passed in filter (if any) passes. This method together with filter check will be executed as one atomic operation.

Transactions

Locks are not transactional and should not be used from within transactions. If you do need explicit locking within transaction, then you should use GridCacheTxConcurrency.PESSIMISTIC concurrency control for transaction which will acquire explicit locks for relevant cache operations.

Cache Flags

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

Parameters:

timeout - Timeout in milliseconds to wait for lock to be acquired ('0' for no expiration).

filter - Optional filter to validate prior to acquiring the lock.

Returns:

True if all filters passed and lock was acquired, false otherwise.

Throws:

GridException - If lock acquisition resulted in error.

GridCacheFlagException - If flags validation failed.

lockAsync

GridFuture<Boolean> lockAsync(long timeout,
                            @Nullable
                            GridPredicate<GridCacheEntry<K,V>>... filter)

Asynchronously acquires lock on a cached object associated with this entry only if the passed in filter (if any) passes. This method together with filter check will be executed as one atomic operation.

Transactions

Locks are not transactional and should not be used from within transactions. If you do need explicit locking within transaction, then you should use GridCacheTxConcurrency.PESSIMISTIC concurrency control for transaction which will acquire explicit locks for relevant cache operations.

Cache Flags

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

Parameters:

timeout - Timeout in milliseconds to wait for lock to be acquired ('0' for no expiration).

filter - Optional filter to validate prior to acquiring the lock.

Returns:

Future for the lock operation. The future will return true whenever all filters pass and locks are acquired before timeout is expired, false otherwise.

Throws:

GridCacheFlagException - If flags validation failed.

unlock

void unlock(GridPredicate<GridCacheEntry<K,V>>... filter)
            throws GridException

Unlocks this entry only if current thread owns the lock. If optional filter will not pass, then unlock will not happen. If this entry was never locked by current thread, then this method will do nothing.

Transactions

Locks are not transactional and should not be used from within transactions. If you do need explicit locking within transaction, then you should use GridCacheTxConcurrency.PESSIMISTIC concurrency control for transaction which will acquire explicit locks for relevant cache operations.

Cache Flags

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

Parameters:

filter - Optional filter that needs to pass prior to unlock taking effect.

Throws:

GridException - If unlock execution resulted in error.

GridCacheFlagException - If flags validation failed.

isCached

boolean isCached()

Checks whether entry is currently present in cache or not. If entry is not in cache (e.g. has been removed) false is returned. In this case all operations on this entry will cause creation of a new entry in cache.

Returns:

True if entry is in cache, false otherwise.

memorySize

int memorySize()
               throws GridException

Gets size of serialized key and value in addition to any overhead added by GridGain itself.

Returns:

size in bytes.

Throws:

GridException - If failed to evaluate entry size.