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

All Superinterfaces:
BasicCache<K,V>, ConcurrentMap<K,V>, Lifecycle, Map<K,V>
All Known Implementing Classes:
RemoteCacheImpl, RemoteCacheSupport

public interface RemoteCache<K,V>
extends BasicCache<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.
Note on default expiration values: Due to limitations on the first version of the protocol, it's not possible for clients to rely on default lifespan and maxIdle values set on the server. This is because the protocol does not support a way to tell the server that no expiration lifespan and/or maxIdle were provided and that default values should be used. This will be resolved in a future revision of the protocol. In the mean time, the workaround is to explicitly provide the desired expiry lifespan/maxIdle values in each remote cache operation.

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
 boolean containsValue(Object value)
           
 Set<Map.Entry<K,V>> entrySet()
           
 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.
 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()
           
 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.
 boolean remove(Object key, Object value)
          This operation is not supported.
 NotifyingFuture<Boolean> removeAsync(Object key, Object value)
          This operation is not supported.
 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)
          Replaces the given value only if its version matches the supplied version.
 boolean replaceWithVersion(K key, V newValue, long version, int lifespanSeconds)
          A overloaded form of replaceWithVersion(Object, Object, long) which takes in lifespan parameters.
 boolean replaceWithVersion(K key, V newValue, long version, int lifespanSeconds, int maxIdleTimeSeconds)
          A overloaded form of replaceWithVersion(Object, Object, long) which takes in lifespan and maximum idle time parameters.
 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()
           
 ServerStatistics stats()
           
 Collection<V> values()
           
 RemoteCache<K,V> withFlags(Flag... flags)
          Applies one or more Flags to the scope of a single invocation.
 
Methods inherited from interface org.infinispan.api.BasicCache
clearAsync, getAsync, getName, 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)
Replaces the given value only if its version matches the supplied version. See removeWithVersion(Object, long) for a sample usage of the version-based methods.

Parameters:
version - numeric version that should match the one in the server for the operation to succeed
Returns:
true if the value has been replaced
See Also:
getVersioned(Object), VersionedValue

replaceWithVersion

boolean replaceWithVersion(K key,
                           V newValue,
                           long version,
                           int lifespanSeconds)
A overloaded form of replaceWithVersion(Object, Object, long) which takes in lifespan parameters.

Parameters:
key - key to use
newValue - new value to be associated with the key
version - numeric version that should match the one in the server for the operation to succeed
lifespanSeconds - lifespan of the entry
Returns:
true if the value was replaced

replaceWithVersion

boolean replaceWithVersion(K key,
                           V newValue,
                           long version,
                           int lifespanSeconds,
                           int maxIdleTimeSeconds)
A overloaded form of replaceWithVersion(Object, Object, long) which takes in lifespan and maximum idle time parameters.

Parameters:
key - key to use
newValue - new value to be associated with the key
version - numeric version that should match the one in the server for the operation to succeed
lifespanSeconds - lifespan of the entry
maxIdleTimeSeconds - the maximum amount of time this key is allowed to be idle for before it is considered as expired
Returns:
true if the value was replaced

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.


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()
Specified by:
keySet in interface Map<K,V>
Throws:
UnsupportedOperationException

values

Collection<V> values()
Specified by:
values in interface Map<K,V>
Throws:
UnsupportedOperationException

entrySet

Set<Map.Entry<K,V>> entrySet()
Specified by:
entrySet in interface Map<K,V>
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 BasicCache<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 BasicCache<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 BasicCache<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 BasicCache<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 BasicCache<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 BasicCache<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

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 BasicCache<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 BasicCache<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 BasicCache<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 BasicCache<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 BasicCache<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")


-->

Copyright © 2012 JBoss, a division of Red Hat. All Rights Reserved.