Interface RemoteCache<K,V>
- All Superinterfaces:
AsyncCache<K,
,V> BasicCache<K,
,V> ConcurrentMap<K,
,V> Lifecycle
,Map<K,
,V> TransactionalCache
- All Known Subinterfaces:
InternalRemoteCache<K,
V>
- All Known Implementing Classes:
DelegatingRemoteCache
,InvalidatedNearRemoteCache
,RemoteCacheImpl
,RemoteCacheSupport
BasicCache
, 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 BasicCache
, 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 BasicCache
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.
Changing default behavior through Flag
s: 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.
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
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addClientListener
(Object listener) Add a client listener to receive events that happen in the remote cache.void
addClientListener
(Object listener, Object[] filterFactoryParams, Object[] converterFactoryParams) Add a client listener to receive events that happen in the remote cache.Returns client-side statistics for this cache.default CloseableIteratorSet
<Map.Entry<K, V>> entrySet()
This method is identical toentrySet()
except that it will only return entries that map to the given segments.default <T> T
Executes a remote task without passing any parameters<T> T
Executes a remote task passing a set of named parametersdefault <T> T
Executes a remote task passing a set of named parameters, hinting that the task should be executed on the server that is expected to store given key.Retrieves all of the entries for the provided keys.ReturnsCacheTopologyInfo
for this cache.Return the currentlyDataFormat
being used.Returns the HotRod protocol version supported by this RemoteCache implementationReturns theRemoteCacheContainer
that created this cache.default RemoteCacheManager
Deprecated, for removal: This API element is subject to removal in a future version.Since 14.0.getWithMetadata
(K key) Returns theMetadataValue
associated to the supplied key param, or null if it doesn't exist.getWithMetadataAsync
(K key) Asynchronously returns theMetadataValue
associated to the supplied key param, or null if it doesn't exist.boolean
default CloseableIteratorSet
<K> keySet()
This method is identical tokeySet()
except that it will only return keys that map to the given segments.publishEntries
(String filterConverterFactory, Object[] filterConverterParams, Set<Integer> segments, int batchSize) Publishes the entries from the server in a non blocking fashion.publishEntriesByQuery
(Query<?> filterQuery, Set<Integer> segments, int batchSize) Publish entries from the server matching a query.org.reactivestreams.Publisher
<Map.Entry<K, MetadataValue<V>>> publishEntriesWithMetadata
(Set<Integer> segments, int batchSize) Publish entries with metadata informationvoid
Adds or overrides each specified entry in the remote cache.void
Adds or overrides each specified entry in the remote cache.void
putAll
(Map<? extends K, ? extends V> map, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) Adds or overrides each specified entry in the remote cache.putAllAsync
(Map<? extends K, ? extends V> data) Adds or overrides each specified entry in the remote cache.putAllAsync
(Map<? extends K, ? extends V> data, long lifespan, TimeUnit unit) Adds or overrides each specified entry in the remote cache.putAllAsync
(Map<? extends K, ? extends V> data, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Adds or overrides each specified entry in the remote cache.If the return value of this operation will be ignored by the application, the user is strongly encouraged to use theFlag.IGNORE_RETURN_VALUES
flag when invoking this method in order to make it behave as efficiently as possible (i.e.boolean
void
removeClientListener
(Object listener) Remove a previously added client listener.boolean
removeWithVersion
(K key, long version) Removes the given entry only if its version matches the supplied version.removeWithVersionAsync
(K key, long version) boolean
boolean
An overloaded form ofConcurrentMap.replace(Object, Object, Object)
, which takes in lifespan parameters.boolean
replace
(K key, V oldValue, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form ofConcurrentMap.replace(Object, Object, Object)
, which takes in lifespan parameters.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 ofreplaceWithVersion(Object, Object, long)
which takes in lifespan parameters.boolean
replaceWithVersion
(K key, V newValue, long version, int lifespanSeconds, int maxIdleTimeSeconds) A overloaded form ofreplaceWithVersion(Object, Object, long)
which takes in lifespan and maximum idle time parameters.boolean
replaceWithVersion
(K key, V newValue, long version, long lifespan, TimeUnit lifespanTimeUnit, long maxIdle, TimeUnit maxIdleTimeUnit) A overloaded form ofreplaceWithVersion(Object, Object, long)
which takes in lifespan and maximum idle time parameters.replaceWithVersionAsync
(K key, V newValue, long version) replaceWithVersionAsync
(K key, V newValue, long version, int lifespanSeconds) replaceWithVersionAsync
(K key, V newValue, long version, int lifespanSeconds, int maxIdleSeconds) replaceWithVersionAsync
(K key, V newValue, long version, long lifespanSeconds, TimeUnit lifespanTimeUnit, long maxIdle, TimeUnit maxIdleTimeUnit) default CloseableIterator
<Map.Entry<Object, Object>> retrieveEntries
(String filterConverterFactory, int batchSize) retrieveEntries
(String filterConverterFactory, Object[] filterConverterParams, Set<Integer> segments, int batchSize) Retrieve entries from the server.default CloseableIterator
<Map.Entry<Object, Object>> retrieveEntries
(String filterConverterFactory, Set<Integer> segments, int batchSize) retrieveEntriesByQuery
(Query<?> filterQuery, Set<Integer> segments, int batchSize) Retrieve entries from the server matching a query.retrieveEntriesWithMetadata
(Set<Integer> segments, int batchSize) Retrieve entries with metadata informationReturns server-side statistics for this cache.Returns server-side statistics for this cache.Returns a cache where values are manipulated usingInputStream
andOutputStream
default CloseableIteratorCollection
<V> values()
This method is identical tovalues()
except that it will only return values that map to the given segments.<T,
U> RemoteCache <T, U> withDataFormat
(DataFormat dataFormat) Return a new instance ofRemoteCache
using the suppliedDataFormat
.Applies one or moreFlag
s to the scope of a single invocation.Methods inherited from interface org.infinispan.commons.api.AsyncCache
clearAsync, computeAsync, computeAsync, computeAsync, computeIfAbsentAsync, computeIfAbsentAsync, computeIfAbsentAsync, computeIfPresentAsync, computeIfPresentAsync, computeIfPresentAsync, containsKeyAsync, getAllAsync, getAsync, mergeAsync, mergeAsync, mergeAsync, putAsync, putAsync, putAsync, putIfAbsentAsync, putIfAbsentAsync, putIfAbsentAsync, removeAsync, removeAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, sizeAsync
Methods inherited from interface org.infinispan.commons.api.BasicCache
compute, compute, computeIfAbsent, computeIfAbsent, computeIfPresent, computeIfPresent, continuousQuery, getName, getVersion, merge, merge, put, put, put, putIfAbsent, putIfAbsent, query, replace, replace
Methods inherited from interface java.util.concurrent.ConcurrentMap
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, replace, replaceAll
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, size
Methods inherited from interface org.infinispan.commons.api.TransactionalCache
getTransactionManager
-
Method Details
-
removeWithVersion
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:
-
remove
If the return value of this operation will be ignored by the application, the user is strongly encouraged to use theFlag.IGNORE_RETURN_VALUES
flag when invoking this method in order to make it behave as efficiently as possible (i.e. avoiding needless remote or network calls).The returned value is only sent back if
Flag.FORCE_RETURN_VALUE
is enabled. -
remove
This method requires 2 round trips to the server. The first to retrieve the value and version and a second to remove the key with the version if the value matches. If possible user should use
getWithMetadata(Object)
andremoveWithVersion(Object, long)
. -
replace
This method requires 2 round trips to the server. The first to retrieve the value and version and a second to replace the key with the version if the value matches. If possible user should use
getWithMetadata(Object)
andreplaceWithVersion(Object, Object, long)
. -
replace
An overloaded form ofConcurrentMap.replace(Object, Object, Object)
, which takes in lifespan parameters.This method requires 2 round trips to the server. The first to retrieve the value and version and a second to replace the key with the version if the value matches. If possible user should use
getWithMetadata(Object)
andreplaceWithVersion(Object, Object, long, long, TimeUnit, long, TimeUnit)
.- Specified by:
replace
in interfaceBasicCache<K,
V> - Parameters:
key
- key to useoldValue
- value to replacevalue
- value to storelifespan
- 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
-
replace
boolean replace(K key, V oldValue, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form ofConcurrentMap.replace(Object, Object, Object)
, which takes in lifespan parameters.This method requires 2 round trips to the server. The first to retrieve the value and version and a second to replace the key with the version if the value matches. If possible user should use
getWithMetadata(Object)
andreplaceWithVersion(Object, Object, long, long, TimeUnit, long, TimeUnit)
if possible.- Specified by:
replace
in interfaceBasicCache<K,
V> - Parameters:
key
- key to useoldValue
- value to replacevalue
- value to storelifespan
- lifespan of the entry. Negative values are interpreted as unlimited lifespan.lifespanUnit
- time unit for lifespanmaxIdleTime
- the maximum amount of time this key is allowed to be idle for before it is considered as expiredmaxIdleTimeUnit
- time unit for max idle time- Returns:
- true if the value was replaced, false otherwise
-
removeWithVersionAsync
- See Also:
-
replaceWithVersion
Replaces the given value only if its version matches the supplied version. SeeremoveWithVersion(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:
-
replaceWithVersion
A overloaded form ofreplaceWithVersion(Object, Object, long)
which takes in lifespan parameters.- Parameters:
key
- key to usenewValue
- new value to be associated with the keyversion
- numeric version that should match the one in the server for the operation to succeedlifespanSeconds
- 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 ofreplaceWithVersion(Object, Object, long)
which takes in lifespan and maximum idle time parameters.- Parameters:
key
- key to usenewValue
- new value to be associated with the keyversion
- numeric version that should match the one in the server for the operation to succeedlifespanSeconds
- lifespan of the entrymaxIdleTimeSeconds
- 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
-
replaceWithVersion
boolean replaceWithVersion(K key, V newValue, long version, long lifespan, TimeUnit lifespanTimeUnit, long maxIdle, TimeUnit maxIdleTimeUnit) A overloaded form ofreplaceWithVersion(Object, Object, long)
which takes in lifespan and maximum idle time parameters.- Parameters:
key
- key to usenewValue
- new value to be associated with the keyversion
- numeric version that should match the one in the server for the operation to succeedlifespan
- lifespan of the entrylifespanTimeUnit
-TimeUnit
for lifespanmaxIdle
- the maximum amount of time this key is allowed to be idle for before it is considered as expiredmaxIdleTimeUnit
-TimeUnit
for maxIdle- Returns:
- true if the value was replaced
-
replaceWithVersionAsync
- See Also:
-
replaceWithVersionAsync
CompletableFuture<Boolean> replaceWithVersionAsync(K key, V newValue, long version, int lifespanSeconds) - See Also:
-
replaceWithVersionAsync
CompletableFuture<Boolean> replaceWithVersionAsync(K key, V newValue, long version, int lifespanSeconds, int maxIdleSeconds) - See Also:
-
replaceWithVersionAsync
CompletableFuture<Boolean> replaceWithVersionAsync(K key, V newValue, long version, long lifespanSeconds, TimeUnit lifespanTimeUnit, long maxIdle, TimeUnit maxIdleTimeUnit) - See Also:
-
retrieveEntries
default CloseableIterator<Map.Entry<Object,Object>> retrieveEntries(String filterConverterFactory, Set<Integer> segments, int batchSize) - See Also:
-
retrieveEntries
CloseableIterator<Map.Entry<Object,Object>> retrieveEntries(String filterConverterFactory, Object[] filterConverterParams, Set<Integer> segments, int batchSize) Retrieve entries from the server.- Parameters:
filterConverterFactory
- Factory name for the KeyValueFilterConverter or null for no filtering.filterConverterParams
- Parameters to the KeyValueFilterConvertersegments
- The segments to iterate. If null all segments will be iterated. An empty set will filter out all entries.batchSize
- The number of entries transferred from the server at a time.- Returns:
- Iterator for the entries
-
publishEntries
<E> org.reactivestreams.Publisher<Map.Entry<K,E>> publishEntries(String filterConverterFactory, Object[] filterConverterParams, Set<Integer> segments, int batchSize) Publishes the entries from the server in a non blocking fashion.Any subscriber that subscribes to the returned Publisher must not block. It is therefore recommended to offload any blocking or long running operations to a different thread and not use the invoking one. Failure to do so may cause concurrent operations to stall.
- Parameters:
filterConverterFactory
- Factory name for the KeyValueFilterConverter or null for no filtering.filterConverterParams
- Parameters to the KeyValueFilterConvertersegments
- The segments to utilize. If null all segments will be utilized. An empty set will filter out all entries.batchSize
- The number of entries transferred from the server at a time.- Returns:
- Publisher for the entries
-
retrieveEntries
default CloseableIterator<Map.Entry<Object,Object>> retrieveEntries(String filterConverterFactory, int batchSize) - See Also:
-
retrieveEntriesByQuery
CloseableIterator<Map.Entry<Object,Object>> retrieveEntriesByQuery(Query<?> filterQuery, Set<Integer> segments, int batchSize) Retrieve entries from the server matching a query.- Parameters:
filterQuery
-Query
segments
- The segments to iterate. If null all segments will be iterated. An empty set will filter out all entries.batchSize
- The number of entries transferred from the server at a time.- Returns:
CloseableIterator
-
publishEntriesByQuery
<E> org.reactivestreams.Publisher<Map.Entry<K,E>> publishEntriesByQuery(Query<?> filterQuery, Set<Integer> segments, int batchSize) Publish entries from the server matching a query.Any subscriber that subscribes to the returned Publisher must not block. It is therefore recommended to offload any blocking or long running operations to a different thread and not use the invoking one. Failure to do so may cause concurrent operations to stall.
- Parameters:
filterQuery
-Query
segments
- The segments to utilize. If null all segments will be utilized. An empty set will filter out all entries.batchSize
- The number of entries transferred from the server at a time.- Returns:
- Publisher containing matching entries
-
retrieveEntriesWithMetadata
CloseableIterator<Map.Entry<Object,MetadataValue<Object>>> retrieveEntriesWithMetadata(Set<Integer> segments, int batchSize) Retrieve entries with metadata information -
publishEntriesWithMetadata
org.reactivestreams.Publisher<Map.Entry<K,MetadataValue<V>>> publishEntriesWithMetadata(Set<Integer> segments, int batchSize) Publish entries with metadata informationAny subscriber that subscribes to the returned Publisher must not block. It is therefore recommended to offload any blocking or long running operations to a different thread and not use the invoking one. Failure to do so may cause concurrent operations to stall.
- Parameters:
segments
- The segments to utilize. If null all segments will be utilized. An empty set will filter out all entries.batchSize
- The number of entries transferred from the server at a time.- Returns:
- Publisher containing entries along with metadata
-
getWithMetadata
Returns theMetadataValue
associated to the supplied key param, or null if it doesn't exist. -
getWithMetadataAsync
Asynchronously returns theMetadataValue
associated to the supplied key param, or null if it doesn't exist. -
keySet
-
keySet
This method is identical tokeySet()
except that it will only return keys that map to the given segments. Note that these segments will be determined by the remote server. Thus you should be aware of how many segments it has configured and hashing algorithm it is using. If the segments and hashing algorithm are not the same this method may return unexpected keys.- Parameters:
segments
- the segments of keys to return - null means all available- Returns:
- set containing keys that map to the given segments
- Since:
- 9.4
- See Also:
-
values
-
values
This method is identical tovalues()
except that it will only return values that map to the given segments. Note that these segments will be determined by the remote server. Thus you should be aware of how many segments it has configured and hashing algorithm it is using. If the segments and hashing algorithm are not the same this method may return unexpected values.- Parameters:
segments
- the segments of values to return - null means all available- Returns:
- collection containing values that map to the given segments
- Since:
- 9.4
- See Also:
-
entrySet
-
entrySet
This method is identical toentrySet()
except that it will only return entries that map to the given segments. Note that these segments will be determined by the remote server. Thus you should be aware of how many segments it has configured and hashing algorithm it is using. If the segments and hashing algorithm are not the same this method may return unexpected entries.- Parameters:
segments
- the segments of entries to return - null means all available- Returns:
- set containing entries that map to the given segments
- Since:
- 9.4
- See Also:
-
putAll
Adds or overrides each specified entry in the remote cache. This operation provides better performance than calling put() for each entry.- Specified by:
putAll
in interfaceBasicCache<K,
V> - Parameters:
map
- map containing mappings to enterlifespan
- 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) Adds or overrides each specified entry in the remote cache. This operation provides better performance than calling put() for each entry.- Specified by:
putAll
in interfaceBasicCache<K,
V> - Parameters:
map
- map containing mappings to enterlifespan
- lifespan of the entry. Negative values are interpreted as unlimited lifespan.lifespanUnit
- time unit for lifespanmaxIdleTime
- the maximum amount of time this key is allowed to be idle for before it is considered as expiredmaxIdleTimeUnit
- time unit for max idle time- See Also:
-
putAllAsync
Adds or overrides each specified entry in the remote cache. This operation provides better performance than calling put() for each entry.- Specified by:
putAllAsync
in interfaceAsyncCache<K,
V> - Parameters:
data
- to store- Returns:
- a future containing a void return type
- See Also:
-
putAllAsync
CompletableFuture<Void> putAllAsync(Map<? extends K, ? extends V> data, long lifespan, TimeUnit unit) Adds or overrides each specified entry in the remote cache. This operation provides better performance than calling put() for each entry.- Specified by:
putAllAsync
in interfaceAsyncCache<K,
V> - Parameters:
data
- to storelifespan
- lifespan of entryunit
- time unit for lifespan- Returns:
- a future containing a void return type
- See Also:
-
putAllAsync
CompletableFuture<Void> putAllAsync(Map<? extends K, ? extends V> data, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Adds or overrides each specified entry in the remote cache. This operation provides better performance than calling put() for each entry.- Specified by:
putAllAsync
in interfaceAsyncCache<K,
V> - Parameters:
data
- to storelifespan
- lifespan of entrylifespanUnit
- time unit for lifespanmaxIdle
- the maximum amount of time this key is allowed to be idle for before it is considered as expiredmaxIdleUnit
- time unit for max idle time- Returns:
- a future containing a void return type
- See Also:
-
putAll
Adds or overrides each specified entry in the remote cache. This operation provides better performance than calling put() for each entry. -
clientStatistics
RemoteCacheClientStatisticsMXBean clientStatistics()Returns client-side statistics for this cache. -
serverStatistics
ServerStatistics serverStatistics()Returns server-side statistics for this cache. -
serverStatisticsAsync
CompletionStage<ServerStatistics> serverStatisticsAsync()Returns server-side statistics for this cache. -
withFlags
Applies one or moreFlag
s to the scope of a single invocation. See theFlag
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.
-
getRemoteCacheContainer
RemoteCacheContainer getRemoteCacheContainer()Returns theRemoteCacheContainer
that created this cache. -
getRemoteCacheManager
Deprecated, for removal: This API element is subject to removal in a future version.Since 14.0. UsegetRemoteCacheContainer()
instead.Returns theRemoteCacheManager
that created this cache. -
getAll
Retrieves all of the entries for the provided keys. A key will not be present in the resulting map if the entry was not found in the cache.- Parameters:
keys
- The keys to find values for- Returns:
- The entries that were present for the given keys
-
getProtocolVersion
String getProtocolVersion()Returns the HotRod protocol version supported by this RemoteCache implementation -
addClientListener
Add a client listener to receive events that happen in the remote cache. The listener object must be annotated with @ClientListener
annotation. -
addClientListener
void addClientListener(Object listener, Object[] filterFactoryParams, Object[] converterFactoryParams) Add a client listener to receive events that happen in the remote cache. The listener object must be annotated with @ClientListener annotation. -
removeClientListener
Remove a previously added client listener. If the listener was not added before, this operation is a no-op. -
execute
Executes a remote task without passing any parameters -
execute
Executes a remote task passing a set of named parameters -
execute
Executes a remote task passing a set of named parameters, hinting that the task should be executed on the server that is expected to store given key. The key itself is not transferred to the server. -
getCacheTopologyInfo
CacheTopologyInfo getCacheTopologyInfo()ReturnsCacheTopologyInfo
for this cache. -
streaming
StreamingRemoteCache<K> streaming()Returns a cache where values are manipulated usingInputStream
andOutputStream
-
withDataFormat
Return a new instance ofRemoteCache
using the suppliedDataFormat
. -
getDataFormat
DataFormat getDataFormat()Return the currentlyDataFormat
being used. -
isTransactional
boolean isTransactional()- Returns:
true
if the cache can participate in a transaction,false
otherwise.
-