org.infinispan.client.hotrod
Interface RemoteCache<K,V>

All Superinterfaces:

Cache<K,V>, ConcurrentMap<K,V>, Lifecycle, Listenable, Map<K,V>

All Known Implementing Classes:

RemoteCacheImpl, RemoteCacheSupport

public interface RemoteCache<K,V>
extends Cache<K,V>

Provides remote reference to a Hot Rod server/cluster. It implements Cache, but given its nature (remote) some operations are not supported. All these unsupported operations are being overridden within this interface and documented as such.

New operations: besides the operations inherited from Cache, RemoteCache also adds new operations to optimize/reduce network traffic: e.g. versioned put operation.

Concurrency: implementors of this interface will support multi-threaded access, similar to the way Cache supports it.

Return values: previously existing values for certain Map operations are not returned, null is returned instead. E.g. Map.put(Object, Object) returns the previous value associated to the supplied key. In case of RemoteCache, this returns null.

Synthetic operations: aggregate operations are being implemented based on other Hot Rod operations. E.g. all the Map.putAll(java.util.Map) is implemented through multiple individual puts. This means that the these operations are not atomic and that they are costly, e.g. as the number of network round-trips is not one, but the size of the added map. All these synthetic operations are documented as such.

changing default behavior through Flags: it is possible to change the default cache behaviour by using flags on an per invocation basis. E.g.

      RemoteCache cache = getRemoteCache();
      Object oldValue = cache.withFlags(Flag.FORCE_RETURN_VALUE).put(aKey, aValue);
 

In the previous example, using Flag.FORCE_RETURN_VALUE will make the client to also return previously existing value associated with aKey. If this flag would not be present, Infinispan would return (by default) null. This is in order to avoid fetching a possibly large object from the remote server, which might not be needed. The flags as set by the withFlags(Flag...) operation only apply for the very next operation executed by the same thread on the RemoteCache.

Eviction and expiration: Unlike local Cache cache, which allows specifying time values with any granularity (as defined by TimeUnit), HotRod only supports seconds as time units. If a different time unit is used instead, HotRod will transparently convert it to seconds, using TimeUnit.toSeconds(long) method. This might result in loss of precision for values specified as nanos or milliseconds.
Another fundamental difference is in the case of lifespan (naturally does NOT apply for max idle): If number of seconds is bigger than 30 days, this number of seconds is treated as UNIX time and so, represents the number of seconds since 1/1/1970.

Since:

4.1

Author:

Mircea.Markus@jboss.com

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

void	addListener(Object listener) Operation might be supported for smart clients that will be able to register for topology changes.
void	compact() This operation is not supported.
boolean	containsValue(Object value)
void	endBatch(boolean successful) Completes a batch if one has been started using Cache.startBatch().
Set<Map.Entry<K,V>>	entrySet() Returns a set view of the mappings contained in this cache.
void	evict(K key) Evicts an entry from the memory of the cache.
AdvancedCache<K,V>	getAdvancedCache() This operation is not supported.
Map<K,V>	getBulk() Bulk get operations, returns all the entries within the remote cache.
Map<K,V>	getBulk(int size) Same as getBulk(), but limits the returned set of values to the specified size.
Configuration	getConfiguration()
Set<Object>	getListeners()
RemoteCacheManager	getRemoteCacheManager() Returns the RemoteCacheManager that created this cache.
VersionedValue	getVersioned(K key) Returns the VersionedValue associated to the supplied key param, or null if it doesn't exist.
boolean	isEmpty()
Set<K>	keySet() Returns a set view of the keys contained in this cache.
void	putAll(Map<? extends K,? extends V> m) Synthetic operation.
void	putAll(Map<? extends K,? extends V> map, long lifespan, TimeUnit unit) Synthetic operation.
void	putAll(Map<? extends K,? extends V> map, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) Synthetic operation.
NotifyingFuture<Void>	putAllAsync(Map<? extends K,? extends V> data) Synthetic operation.
NotifyingFuture<Void>	putAllAsync(Map<? extends K,? extends V> data, long lifespan, TimeUnit unit) Synthetic operation.
NotifyingFuture<Void>	putAllAsync(Map<? extends K,? extends V> data, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Synthetic operation.
void	putForExternalRead(K key, V value) This operation is not supported.
boolean	remove(Object key, Object value) This operation is not supported.
NotifyingFuture<Boolean>	removeAsync(Object key, Object value) This operation is not supported.
void	removeListener(Object listener) Removes a listener from the component.
boolean	removeWithVersion(K key, long version) Removes the given entry only if its version matches the supplied version.
NotifyingFuture<Boolean>	removeWithVersionAsync(K key, long version)
boolean	replace(K key, V oldValue, V newValue) This operation is not supported.
boolean	replace(K key, V oldValue, V value, long lifespan, TimeUnit unit) This operation is not supported.
boolean	replace(K key, V oldValue, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) This operation is not supported.
NotifyingFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue) This operation is not supported.
NotifyingFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit unit) This operation is not supported.
NotifyingFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) This operation is not supported.
boolean	replaceWithVersion(K key, V newValue, long version) Removes the given value only if its version matches the supplied version.
boolean	replaceWithVersion(K key, V newValue, long version, int lifespanSeconds)
boolean	replaceWithVersion(K key, V newValue, long version, int lifespanSeconds, int maxIdleTimeSeconds)
NotifyingFuture<Boolean>	replaceWithVersionAsync(K key, V newValue, long version)
NotifyingFuture<Boolean>	replaceWithVersionAsync(K key, V newValue, long version, int lifespanSeconds)
NotifyingFuture<Boolean>	replaceWithVersionAsync(K key, V newValue, long version, int lifespanSeconds, int maxIdleSeconds)
int	size()
boolean	startBatch() Starts a batch.
ServerStatistics	stats()
Collection<V>	values() Returns a collection view of the values contained in this cache.
RemoteCache<K,V>	withFlags(Flag... flags) Applies one or more Flags to the scope of a single invocation.

Methods inherited from interface org.infinispan.Cache

clearAsync, getCacheManager, getName, getStatus, getVersion, put, put, putAsync, putAsync, putAsync, putIfAbsent, putIfAbsent, putIfAbsentAsync, putIfAbsentAsync, putIfAbsentAsync, removeAsync, replace, replace, replaceAsync, replaceAsync, replaceAsync

Methods inherited from interface java.util.concurrent.ConcurrentMap

putIfAbsent, replace

Methods inherited from interface java.util.Map

clear, containsKey, equals, get, hashCode, put, remove

Methods inherited from interface org.infinispan.lifecycle.Lifecycle

start, stop

Method Detail

removeWithVersion

boolean removeWithVersion(K key,
                          long version)

Removes the given entry only if its version matches the supplied version. A typical use case looks like this:

 VersionedEntry ve = remoteCache.getVersioned(key);
 //some processing
 remoteCache.removeWithVersion(key, ve.getVersion();
 

Lat call (removeWithVersion) will make sure that the entry will only be removed if it hasn't been changed in between.

Returns:

true if the entry has been removed

See Also:

VersionedValue, getVersioned(Object)

removeWithVersionAsync

NotifyingFuture<Boolean> removeWithVersionAsync(K key,
                                                long version)

See Also:

remove(Object, Object)

replaceWithVersion

boolean replaceWithVersion(K key,
                           V newValue,
                           long version)

Removes the given value only if its version matches the supplied version. See removeWithVersion(Object, long) for a sample usage.

Returns:

true if the method has been replaced

See Also:

getVersioned(Object), VersionedValue

replaceWithVersion

boolean replaceWithVersion(K key,
                           V newValue,
                           long version,
                           int lifespanSeconds)

See Also:

replaceWithVersion(Object, Object, long)

replaceWithVersion

boolean replaceWithVersion(K key,
                           V newValue,
                           long version,
                           int lifespanSeconds,
                           int maxIdleTimeSeconds)

See Also:

replaceWithVersion(Object, Object, long)

replaceWithVersionAsync

NotifyingFuture<Boolean> replaceWithVersionAsync(K key,
                                                 V newValue,
                                                 long version)

See Also:

replaceWithVersion(Object, Object, long)

replaceWithVersionAsync

NotifyingFuture<Boolean> replaceWithVersionAsync(K key,
                                                 V newValue,
                                                 long version,
                                                 int lifespanSeconds)

See Also:

replaceWithVersion(Object, Object, long)

replaceWithVersionAsync

NotifyingFuture<Boolean> replaceWithVersionAsync(K key,
                                                 V newValue,
                                                 long version,
                                                 int lifespanSeconds,
                                                 int maxIdleSeconds)

See Also:

replaceWithVersion(Object, Object, long)

getVersioned

VersionedValue getVersioned(K key)

Returns the VersionedValue associated to the supplied key param, or null if it doesn't exist.

addListener

void addListener(Object listener)

Operation might be supported for smart clients that will be able to register for topology changes.

Specified by:

addListener in interface Listenable

Parameters:

listener - must not be null.

Throws:

UnsupportedOperationException

removeListener

void removeListener(Object listener)

Description copied from interface: Listenable

Removes a listener from the component.

Specified by:

removeListener in interface Listenable

Parameters:

listener - listener to remove. Must not be null.

Throws:

UnsupportedOperationException

See Also:

addListener(Object)

getListeners

Set<Object> getListeners()

Specified by:

getListeners in interface Listenable

Returns:

a set of all listeners registered on this component.

Throws:

UnsupportedOperationException

See Also:

addListener(Object)

size

int size()

Specified by:

size in interface Map<K,V>

Throws:

UnsupportedOperationException

isEmpty

boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

Throws:

UnsupportedOperationException

containsValue

boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

Throws:

UnsupportedOperationException

keySet

Set<K> keySet()

Description copied from interface: Cache

Returns a set view of the keys contained in this cache. This set is immutable, so it cannot be modified and changes to the cache won't be reflected in the set. When this method is called on a cache configured with distribution mode, the set returned only contains the keys locally available in the cache instance. To avoid memory issues, there will be not attempt to bring keys from other nodes.

This method should only be used for debugging purposes such as to verify that the cache contains all the keys entered. Any other use involving execution of this method on a production system is not recommended.

Specified by:

keySet in interface Cache<K,V>

Specified by:

keySet in interface Map<K,V>

Returns:

a set view of the keys contained in this cache.

Throws:

UnsupportedOperationException

values

Collection<V> values()

Description copied from interface: Cache

Returns a collection view of the values contained in this cache. This collection is immutable, so it cannot be modified and changes to the cache won't be reflected in the set. When this method is called on a cache configured with distribution mode, the collection returned only contains the values locally available in the cache instance. To avoid memory issues, there is not attempt to bring values from other nodes.

This method should only be used for testing or debugging purposes such as to verify that the cache contains all the values entered. Any other use involving execution of this method on a production system is not recommended.

Specified by:

values in interface Cache<K,V>

Specified by:

values in interface Map<K,V>

Returns:

a collection view of the values contained in this map.

Throws:

UnsupportedOperationException

entrySet

Set<Map.Entry<K,V>> entrySet()

Description copied from interface: Cache

Returns a set view of the mappings contained in this cache. This set is immutable, so it cannot be modified and changes to the cache won't be reflected in the set. Besides, each element in the returned set is an immutable Map.Entry. When this method is called on a cache configured with distribution mode, the set returned only contains the mappings locally available in the cache instance. To avoid memory issues, there will be not attempt to bring mappings from other nodes.

This method should only be used for debugging purposes such as to verify that the cache contains all the mappings entered. Any other use involving execution of this method on a production system is not recommended.

Specified by:

entrySet in interface Cache<K,V>

Specified by:

entrySet in interface Map<K,V>

Returns:

a set view of the mappings contained in this cache.

Throws:

UnsupportedOperationException

evict

void evict(K key)

Description copied from interface: Cache

Evicts an entry from the memory of the cache. Note that the entry is not removed from any configured cache stores or any other caches in the cluster (if used in a clustered mode). Use Map.remove(Object) to remove an entry from the entire cache system.

This method is designed to evict an entry from memory to free up memory used by the application. This method uses a 0 lock acquisition timeout so it does not block in attempting to acquire locks. It behaves as a no-op if the lock on the entry cannot be acquired immediately.

Important: this method should not be called from within a transaction scope.

Specified by:

evict in interface Cache<K,V>

Parameters:

key - key to evict

Throws:

UnsupportedOperationException

getConfiguration

Configuration getConfiguration()

Specified by:

getConfiguration in interface Cache<K,V>

Throws:

UnsupportedOperationException

startBatch

boolean startBatch()

Description copied from interface: Cache

Starts a batch. All operations on the current client thread are performed as a part of this batch, with locks held for the duration of the batch and any remote calls delayed till the end of the batch.

Specified by:

startBatch in interface Cache<K,V>

Returns:

true if a batch was successfully started; false if one was available and already running.

Throws:

UnsupportedOperationException

endBatch

void endBatch(boolean successful)

Description copied from interface: Cache

Completes a batch if one has been started using Cache.startBatch(). If no batch has been started, this is a no-op.

Specified by:

endBatch in interface Cache<K,V>

Parameters:

successful - if true, the batch completes, otherwise the batch is aborted and changes are not committed.

Throws:

UnsupportedOperationException

remove

boolean remove(Object key,
               Object value)

This operation is not supported. Consider using removeWithVersion(Object, long) instead.

Specified by:

remove in interface ConcurrentMap<K,V>

Throws:

UnsupportedOperationException

removeAsync

NotifyingFuture<Boolean> removeAsync(Object key,
                                     Object value)

This operation is not supported. Consider using removeWithVersionAsync(Object, long) instead.

Specified by:

removeAsync in interface Cache<K,V>

Parameters:

key - key to remove

value - value to match on

Returns:

a future containing a boolean, indicating whether the entry was removed or not

Throws:

UnsupportedOperationException

replace

boolean replace(K key,
                V oldValue,
                V newValue)

This operation is not supported. Consider using replaceWithVersion(Object, Object, long) instead.

Specified by:

replace in interface ConcurrentMap<K,V>

Throws:

UnsupportedOperationException

replace

boolean replace(K key,
                V oldValue,
                V value,
                long lifespan,
                TimeUnit unit)

This operation is not supported. Consider using replaceWithVersion(Object, Object, long, int) instead.

Specified by:

replace in interface Cache<K,V>

Parameters:

key - key to use

oldValue - value to replace

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

Returns:

true if the value was replaced, false otherwise

Throws:

UnsupportedOperationException

replace

boolean replace(K key,
                V oldValue,
                V value,
                long lifespan,
                TimeUnit lifespanUnit,
                long maxIdleTime,
                TimeUnit maxIdleTimeUnit)

This operation is not supported. Consider using replaceWithVersion(Object, Object, long, int, int) instead.

Specified by:

replace in interface Cache<K,V>

Parameters:

key - key to use

oldValue - value to replace

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

Returns:

true if the value was replaced, false otherwise

Throws:

UnsupportedOperationException

replaceAsync

NotifyingFuture<Boolean> replaceAsync(K key,
                                      V oldValue,
                                      V newValue)

This operation is not supported. Consider using replaceWithVersionAsync(Object, Object, long) instead.

Specified by:

replaceAsync in interface Cache<K,V>

Parameters:

key - key to remove

oldValue - value to overwrite

newValue - value to store

Returns:

a future containing a boolean, indicating whether the entry was replaced or not

Throws:

UnsupportedOperationException

replaceAsync

NotifyingFuture<Boolean> replaceAsync(K key,
                                      V oldValue,
                                      V newValue,
                                      long lifespan,
                                      TimeUnit unit)

This operation is not supported. Consider using replaceWithVersion(Object, Object, long, int) instead.

Specified by:

replaceAsync in interface Cache<K,V>

Parameters:

key - key to remove

oldValue - value to overwrite

newValue - value to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing a boolean, indicating whether the entry was replaced or not

Throws:

UnsupportedOperationException

replaceAsync

NotifyingFuture<Boolean> replaceAsync(K key,
                                      V oldValue,
                                      V newValue,
                                      long lifespan,
                                      TimeUnit lifespanUnit,
                                      long maxIdle,
                                      TimeUnit maxIdleUnit)

This operation is not supported. Consider using replaceWithVersion(Object, Object, long, int, int) instead.

Specified by:

replaceAsync in interface Cache<K,V>

Parameters:

key - key to remove

oldValue - value to overwrite

newValue - value to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing a boolean, indicating whether the entry was replaced or not

Throws:

UnsupportedOperationException

getAdvancedCache

AdvancedCache<K,V> getAdvancedCache()

This operation is not supported.

Specified by:

getAdvancedCache in interface Cache<K,V>

Throws:

UnsupportedOperationException

compact

void compact()

This operation is not supported.

Specified by:

compact in interface Cache<K,V>

Throws:

UnsupportedOperationException

putForExternalRead

void putForExternalRead(K key,
                        V value)

This operation is not supported.

Specified by:

putForExternalRead in interface Cache<K,V>

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Throws:

UnsupportedOperationException

putAll

void putAll(Map<? extends K,? extends V> map,
            long lifespan,
            TimeUnit unit)

Synthetic operation. The client iterates over the set of keys and calls put for each one of them. This results in operation not being atomic (if a failure happens after few puts it is not rolled back) and costly (for each key in the parameter map a remote call is performed).

Specified by:

putAll in interface Cache<K,V>

Parameters:

map - map containing mappings to enter

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

putAll

void putAll(Map<? extends K,? extends V> map,
            long lifespan,
            TimeUnit lifespanUnit,
            long maxIdleTime,
            TimeUnit maxIdleTimeUnit)

Synthetic operation.

Specified by:

putAll in interface Cache<K,V>

Parameters:

map - map containing mappings to enter

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

See Also:

putAll(java.util.Map, long, java.util.concurrent.TimeUnit)

putAllAsync

NotifyingFuture<Void> putAllAsync(Map<? extends K,? extends V> data)

Synthetic operation.

Specified by:

putAllAsync in interface Cache<K,V>

Parameters:

data - to store

Returns:

a future containing a void return type

See Also:

putAll(java.util.Map, long, java.util.concurrent.TimeUnit)

putAllAsync

NotifyingFuture<Void> putAllAsync(Map<? extends K,? extends V> data,
                                  long lifespan,
                                  TimeUnit unit)

Synthetic operation.

Specified by:

putAllAsync in interface Cache<K,V>

Parameters:

data - to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing a void return type

See Also:

putAll(java.util.Map, long, java.util.concurrent.TimeUnit)

putAllAsync

NotifyingFuture<Void> putAllAsync(Map<? extends K,? extends V> data,
                                  long lifespan,
                                  TimeUnit lifespanUnit,
                                  long maxIdle,
                                  TimeUnit maxIdleUnit)

Synthetic operation.

Specified by:

putAllAsync in interface Cache<K,V>

Parameters:

data - to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing a void return type

See Also:

putAll(java.util.Map, long, java.util.concurrent.TimeUnit)

putAll

void putAll(Map<? extends K,? extends V> m)

Synthetic operation.

Specified by:

putAll in interface Map<K,V>

See Also:

putAll(java.util.Map, long, java.util.concurrent.TimeUnit)

stats

ServerStatistics stats()

withFlags

RemoteCache<K,V> withFlags(Flag... flags)

Applies one or more Flags to the scope of a single invocation. See the Flag enumeration to for information on available flags.

Sample usage:

    remoteCache.withFlags(Flag.FORCE_RETURN_VALUE).put("hello", "world");
 

Parameters:

flags -

Returns:

the current RemoteCache instance to continue running operations on.

getRemoteCacheManager

RemoteCacheManager getRemoteCacheManager()

Returns the RemoteCacheManager that created this cache.

getBulk

Map<K,V> getBulk()

Bulk get operations, returns all the entries within the remote cache.

Returns:

the returned values depend on the configuration of the back-end infinispan servers. Read this for more details. The returned Map is unmodifiable.

getBulk

Map<K,V> getBulk(int size)

Same as getBulk(), but limits the returned set of values to the specified size. No ordering is guaranteed, and there is no guarantee that "size" elements are returned( e.g. if the number of elements in the back-end server is smaller that "size")