org.infinispan.AdvancedCache Maven / Gradle / Ivy
package org.infinispan;
import java.util.Collection;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeUnit;
import java.util.function.BiFunction;
import java.util.function.Function;
import javax.security.auth.Subject;
import javax.transaction.xa.XAResource;
import org.infinispan.batch.BatchContainer;
import org.infinispan.cache.impl.DecoratedCache;
import org.infinispan.commons.TimeoutException;
import org.infinispan.commons.api.TransactionalCache;
import org.infinispan.commons.dataconversion.Encoder;
import org.infinispan.commons.dataconversion.MediaType;
import org.infinispan.commons.dataconversion.Wrapper;
import org.infinispan.configuration.cache.ConfigurationBuilder;
import org.infinispan.configuration.cache.PartitionHandlingConfiguration;
import org.infinispan.container.DataContainer;
import org.infinispan.container.entries.CacheEntry;
import org.infinispan.context.Flag;
import org.infinispan.distribution.DistributionManager;
import org.infinispan.encoding.DataConversion;
import org.infinispan.expiration.ExpirationManager;
import org.infinispan.metadata.Metadata;
import org.infinispan.partitionhandling.AvailabilityMode;
import org.infinispan.partitionhandling.impl.PartitionHandlingManager;
import org.infinispan.persistence.spi.CacheLoader;
import org.infinispan.remoting.rpc.RpcManager;
import org.infinispan.security.AuthorizationManager;
import org.infinispan.stats.Stats;
import org.infinispan.transaction.LockingMode;
import org.infinispan.util.concurrent.locks.LockManager;
import org.infinispan.util.function.SerializableBiFunction;
import org.infinispan.util.function.SerializableFunction;
/**
* An advanced interface that exposes additional methods not available on {@link Cache}.
*
* @author Manik Surtani
* @author Galder Zamarreño
* @author Tristan Tarrant
* @since 4.0
*/
public interface AdvancedCache extends Cache, TransactionalCache {
/**
* A method that adds flags to any API call. For example, consider the following code snippet:
*
* cache.withFlags(Flag.FORCE_WRITE_LOCK).get(key);
*
* will invoke a cache.get() with a write lock forced.
*
* Note that for the flag to take effect, the cache operation must be invoked on the instance returned
* by this method.
*
* As an alternative to setting this on every invocation, users should also consider saving the decorated
* cache, as this allows for more readable code. E.g.:
*
* AdvancedCache<?, ?> forceWriteLockCache = cache.withFlags(Flag.FORCE_WRITE_LOCK);
* forceWriteLockCache.get(key1);
* forceWriteLockCache.get(key2);
* forceWriteLockCache.get(key3);
*
*
* @param flags a set of flags to apply. See the {@link Flag} documentation.
* @return an {@link AdvancedCache} instance on which a real operation is to be invoked, if the flags are to be
* applied.
*/
AdvancedCache withFlags(Flag... flags);
/**
* An alternative to {@link #withFlags(Flag...)} not requiring array allocation.
*
* @since 9.2
*/
default AdvancedCache withFlags(Collection flags) {
if (flags == null) return this;
int numFlags = flags.size();
if (numFlags == 0) return this;
return withFlags(flags.toArray(new Flag[numFlags]));
}
/**
* An alternative to {@link #withFlags(Flag...)} optimized for a single flag.
*
* @since 10.0
*/
default AdvancedCache withFlags(Flag flag) {
return withFlags(new Flag[]{flag});
}
/**
* Unset all flags set on this cache using {@link #withFlags(Flag...)} or {@link #withFlags(Collection)} methods.
*
* @return Cache not applying any flags to the command; possibly this.
*/
default AdvancedCache noFlags() {
throw new UnsupportedOperationException();
}
/**
* Apply the transformation on each {@link AdvancedCache} instance in a delegation chain, starting
* with the innermost implementation.
*
* @param transformation
* @return The outermost transformed cache.
*/
default AdvancedCache transform(Function, ? extends AdvancedCache> transformation) {
throw new UnsupportedOperationException();
}
/**
* Performs any cache operations using the specified {@link Subject}. Only applies to caches with authorization
* enabled (see {@link ConfigurationBuilder#security()}).
*
* @param subject
* @return an {@link AdvancedCache} instance on which a real operation is to be invoked, using the specified subject
*/
AdvancedCache withSubject(Subject subject);
/**
* @return the expiration manager - if one is configured - for this cache instance
*/
ExpirationManager getExpirationManager();
/**
* Retrieves a reference to the {@link org.infinispan.distribution.DistributionManager} if the cache is configured to
* use Distribution. Otherwise, returns a null.
*
* @return a DistributionManager, or null.
*/
DistributionManager getDistributionManager();
/**
* Retrieves the {@link AuthorizationManager} if the cache has security enabled. Otherwise returns null
*
* @return an AuthorizationManager or null
*/
AuthorizationManager getAuthorizationManager();
/**
* Whenever this cache acquires a lock it will do so using the given Object as the owner of said lock.
*
* This can be useful when a lock may have been manually acquired and you wish to reuse that lock across
* invocations.
*
* Great care should be taken with this command as misuse can very easily lead to deadlocks.
*
* @param lockOwner the lock owner to lock any keys as
* @return an {@link AdvancedCache} instance on which when an operation is invoked it will use lock owner object to
* acquire any locks
*/
AdvancedCache lockAs(Object lockOwner);
/**
* Locks a given key or keys eagerly across cache nodes in a cluster.
*
* Keys can be locked eagerly in the context of a transaction only.
*
* @param keys the keys to lock
* @return true if the lock acquisition attempt was successful for all keys; false will only be returned if
* the lock acquisition timed out and the operation has been called with {@link Flag#FAIL_SILENTLY}.
* @throws TimeoutException if the lock cannot be acquired within the configured lock
* acquisition time.
*/
boolean lock(K... keys);
/**
* Locks collections of keys eagerly across cache nodes in a cluster.
*
* Collections of keys can be locked eagerly in the context of a transaction only.
*
* @param keys collection of keys to lock
* @return true if the lock acquisition attempt was successful for all keys; false will only be returned if
* the lock acquisition timed out and the operation has been called with {@link Flag#FAIL_SILENTLY}.
* @throws TimeoutException if the lock cannot be acquired within the configured lock
* acquisition time.
*/
boolean lock(Collection keys);
/**
* Returns the component in charge of communication with other caches in the cluster. If the cache's {@link
* org.infinispan.configuration.cache.ClusteringConfiguration#cacheMode()} is {@link
* org.infinispan.configuration.cache.CacheMode#LOCAL}, this method will return null.
*
* @return the RPC manager component associated with this cache instance or null
*/
RpcManager getRpcManager();
/**
* Returns the component in charge of batching cache operations.
*
* @return the batching component associated with this cache instance
*/
BatchContainer getBatchContainer();
/**
* Returns the container where data is stored in the cache. Users should interact with this component with care
* because direct calls on it bypass the internal interceptors and other infrastructure in place to guarantee the
* consistency of data.
*
* @return the data container associated with this cache instance
*/
DataContainer getDataContainer();
/**
* Returns the component that deals with all aspects of acquiring and releasing locks for cache entries.
*
* @return retrieves the lock manager associated with this cache instance
*/
LockManager getLockManager();
/**
* Returns a {@link Stats} object that allows several statistics associated with this cache at runtime.
*
* @return this cache's {@link Stats} object
*/
Stats getStats();
/**
* Returns the {@link XAResource} associated with this cache which can be used to do transactional recovery.
*
* @return an instance of {@link XAResource}
*/
XAResource getXAResource();
/**
* Returns the cache loader associated associated with this cache. As an alternative to setting this on every
* invocation, users could also consider using the {@link DecoratedCache} wrapper.
*
* @return this cache's cache loader
*/
ClassLoader getClassLoader();
/**
* An overloaded form of {@link #put(K, V)}, which takes in an instance of {@link org.infinispan.metadata.Metadata}
* which can be used to provide metadata information for the entry being stored, such as lifespan, version of
* value...etc.
*
* @param key key to use
* @param value value to store
* @param metadata information to store alongside the value
* @return the previous value associated with key, or null if there was no mapping for
* key.
* @since 5.3
*/
V put(K key, V value, Metadata metadata);
/**
* An overloaded form of {@link #putAll(Map)}, which takes in an instance of {@link org.infinispan.metadata.Metadata}
* which can be used to provide metadata information for the entries being stored, such as lifespan, version of
* value...etc.
*
* @param map the values to store
* @param metadata information to store alongside the value(s)
* @since 7.2
*/
void putAll(Map map, Metadata metadata);
default CompletableFuture putAllAsync(Map map, Metadata metadata) {
return putAllAsync(map, metadata.lifespan(), TimeUnit.MILLISECONDS, metadata.maxIdle(), TimeUnit.MILLISECONDS);
}
/**
* An overloaded form of {@link #replace(K, V)}, which takes in an instance of {@link Metadata} which can be used to
* provide metadata information for the entry being stored, such as lifespan, version of value...etc. The {@link
* Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return the previous value associated with the specified key, or null if there was no mapping for the
* key.
* @since 5.3
*/
V replace(K key, V value, Metadata metadata);
/**
* An overloaded form of {@link #replaceAsync(K, V)}, which takes in an instance of {@link Metadata} which can be used to
* provide metadata information for the entry being stored, such as lifespan, version of value...etc. The {@link
* Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return the future that contains previous value associated with the specified key, or null
* if there was no mapping for the key.
* @since 9.2
*/
default CompletableFuture replaceAsync(K key, V value, Metadata metadata) {
return replaceAsync(key, value, metadata.lifespan(), TimeUnit.MILLISECONDS, metadata.maxIdle(), TimeUnit.MILLISECONDS);
}
/**
* An extension of {@link #replaceAsync(K, V, Metadata)}, which returns a {@link CacheEntry} instead of
* only the value.
*
* @param key key with which the specified value is associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return the future that contains previous {@link CacheEntry} associated with the specified key,
* or null if there was no mapping for the key.
* @since 14.0
* @see #replaceAsync(K, V, Metadata)
*/
CompletableFuture> replaceAsyncEntry(K key, V value, Metadata metadata);
/**
* An overloaded form of {@link #replace(K, V, V)}, which takes in an instance of {@link Metadata} which can be used
* to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The {@link
* Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param oldValue value expected to be associated with the specified key
* @param newValue value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return true if the value was replaced
* @since 5.3
*/
boolean replace(K key, V oldValue, V newValue, Metadata metadata);
default CompletableFuture replaceAsync(K key, V oldValue, V newValue, Metadata metadata) {
return replaceAsync(key, oldValue, newValue, metadata.lifespan(), TimeUnit.MILLISECONDS, metadata.maxIdle(), TimeUnit.MILLISECONDS);
}
/**
* An overloaded form of {@link #putIfAbsent(K, V)}, which takes in an instance of {@link Metadata} which can be used
* to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The {@link
* Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is to be associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return the previous value associated with the specified key, or null if there was no mapping for the
* key.
* @since 5.3
*/
V putIfAbsent(K key, V value, Metadata metadata);
/**
* An overloaded form of {@link #putIfAbsentAsync(K, V)}, which takes in an instance of {@link Metadata} which can be used
* to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The {@link
* Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is to be associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return A future containing the previous value associated with the specified key, or null if there was no mapping for the
* key.
* @since 9.2
*/
default CompletableFuture putIfAbsentAsync(K key, V value, Metadata metadata) {
return putIfAbsentAsync(key, value, metadata.lifespan(), TimeUnit.MILLISECONDS, metadata.maxIdle(), TimeUnit.MILLISECONDS);
}
/**
* An extension form of {@link #putIfAbsentAsync(K, V, Metadata)}, which returns a {@link CacheEntry} instead of
* only the value.
*
* @param key key with which the specified value is to be associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @return the future that contains previous {@link CacheEntry} associated with the specified key,
* or null if there was no mapping for the key.
* @since 14.0
* @see #putIfAbsentAsync(K, V, Metadata)
*/
CompletableFuture> putIfAbsentAsyncEntry(K key, V value, Metadata metadata);
/**
* An overloaded form of {@link #putForExternalRead(K, V)}, which takes in an instance of {@link Metadata} which can
* be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The
* {@link Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is to be associated
* @param value value to be associated with the specified key
* @param metadata information to store alongside the new value
* @since 7.0
*/
void putForExternalRead(K key, V value, Metadata metadata);
/**
* An overloaded form of {@link #compute(K, BiFunction)}, which takes in an instance of {@link Metadata} which can be
* used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
*
* @param key key with which the specified value is associated
* @param remappingFunction function to be applied to the specified key/value
* @param metadata information to store alongside the new value
* @return the previous value associated with the specified key, or null if remapping function is gives
* null.
* @since 9.1
*/
V compute(K key, BiFunction remappingFunction, Metadata metadata);
/**
* Overloaded {@link #compute(Object, BiFunction, Metadata)} with {@link SerializableBiFunction}
*/
default V compute(K key, SerializableBiFunction remappingFunction, Metadata metadata) {
return this.compute(key, (BiFunction) remappingFunction, metadata);
}
/**
* An overloaded form of {@link #computeIfPresent(K, BiFunction)}, which takes in an instance of {@link Metadata}
* which can be used to provide metadata information for the entry being stored, such as lifespan, version of
* value...etc. The {@link Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param remappingFunction function to be applied to the specified key/value
* @param metadata information to store alongside the new value
* @return the previous value associated with the specified key, or null if there was no mapping for the
* key.
* @since 9.1
*/
V computeIfPresent(K key, BiFunction remappingFunction, Metadata metadata);
/**
* Overloaded {@link #computeIfPresent(Object, BiFunction, Metadata)} with {@link SerializableBiFunction}
*/
default V computeIfPresent(K key, SerializableBiFunction remappingFunction, Metadata metadata) {
return this.computeIfPresent(key, (BiFunction) remappingFunction, metadata);
}
/**
* An overloaded form of {@link #computeIfAbsent(K, Function)}, which takes in an instance of {@link Metadata} which
* can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
* The {@link Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param mappingFunction function to be applied to the specified key
* @param metadata information to store alongside the new value
* @return the value created with the mapping function associated with the specified key, or the previous value
* associated with the specified key if the key is not absent.
* @since 9.1
*/
V computeIfAbsent(K key, Function mappingFunction, Metadata metadata);
/**
* Overloaded {@link #computeIfAbsent(Object, Function, Metadata)} with {@link SerializableFunction}
*/
default V computeIfAbsent(K key, SerializableFunction mappingFunction, Metadata metadata) {
return this.computeIfAbsent(key, (Function) mappingFunction, metadata);
}
/**
* An overloaded form of {@link #merge(Object, Object, BiFunction)}, which takes in an instance of {@link Metadata}
* which can be used to provide metadata information for the entry being stored, such as lifespan, version of
* value...etc. The {@link Metadata} is only stored if the call is successful.
*
* @param key, key with which the resulting value is to be associated
* @param value, the non-null value to be merged with the existing value associated with the key or, if
* no existing value or a null value is associated with the key, to be associated with the
* key
* @param remappingFunction, the function to recompute a value if present
* @param metadata, information to store alongside the new value
* @return the new value associated with the specified key, or null if no value is associated with the key
* @since 9.2
*/
V merge(K key, V value, BiFunction remappingFunction, Metadata metadata);
/**
* Overloaded {@link #merge(Object, Object, BiFunction, Metadata)} with {@link SerializableBiFunction}
*/
default V merge(K key, V value, SerializableBiFunction remappingFunction, Metadata metadata) {
return this.merge(key, value, (BiFunction) remappingFunction, metadata);
}
/**
* Asynchronous version of {@link #put(Object, Object, Metadata)} which stores metadata alongside the value. This
* method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over {@link
* #put(Object, Object, Metadata)} if used in LOCAL mode.
*
*
* @param key key to use
* @param value value to store
* @param metadata information to store alongside the new value
* @return a future containing the old value replaced.
* @since 5.3
*/
CompletableFuture putAsync(K key, V value, Metadata metadata);
/**
* Extension of {@link #putAsync(K, V, Metadata)} which returns a {@link CacheEntry} instead of only the
* previous value.
*
* @param key key to use
* @param value value to store
* @param metadata information to store alongside the new value
* @return a future containing the old {@link CacheEntry} replaced.
* @since 14.0
*/
CompletableFuture> putAsyncEntry(K key, V value, Metadata metadata);
/**
* Overloaded {@link #computeAsync(K, BiFunction)}, which stores metadata alongside the value. This
* method does not block on remote calls, even if your cache mode is synchronous.
*
* @param key key with which the specified value is associated
* @param remappingFunction function to be applied to the specified key/value
* @param metadata information to store alongside the new value
* @return the previous value associated with the specified key, or null if remapping function is gives
* null.
* @since 9.4
*/
CompletableFuture computeAsync(K key, BiFunction remappingFunction, Metadata metadata);
/**
* Overloaded {@link #computeAsync(Object, BiFunction, Metadata)} with {@link SerializableBiFunction}
* @since 9.4
*/
default CompletableFuture computeAsync(K key, SerializableBiFunction remappingFunction, Metadata metadata) {
return this.computeAsync(key, (BiFunction) remappingFunction, metadata);
}
/**
* Overloaded {@link #computeIfPresentAsync(K, BiFunction)}, which takes in an instance of {@link Metadata}
* which can be used to provide metadata information for the entry being stored, such as lifespan, version of
* value...etc. The {@link Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param remappingFunction function to be applied to the specified key/value
* @param metadata information to store alongside the new value
* @return the previous value associated with the specified key, or null if there was no mapping for the
* key.
* @since 9.4
*/
CompletableFuture computeIfPresentAsync(K key, BiFunction remappingFunction, Metadata metadata);
/**
* Overloaded {@link #computeIfPresentAsync(Object, BiFunction, Metadata)} with {@link SerializableBiFunction}
* @since 9.4
*/
default CompletableFuture computeIfPresentAsync(K key, SerializableBiFunction remappingFunction, Metadata metadata) {
return this.computeIfPresentAsync(key, (BiFunction) remappingFunction, metadata);
}
/**
* Overloaded {@link #computeIfAbsentAsync(K, Function)}, which takes in an instance of {@link Metadata} which
* can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
* The {@link Metadata} is only stored if the call is successful.
*
* @param key key with which the specified value is associated
* @param mappingFunction function to be applied to the specified key
* @param metadata information to store alongside the new value
* @return the value created with the mapping function associated with the specified key, or the previous value
* associated with the specified key if the key is not absent.
* @since 9.4
*/
CompletableFuture computeIfAbsentAsync(K key, Function mappingFunction, Metadata metadata);
/**
* Overloaded {@link #computeIfAbsentAsync(Object, Function, Metadata)} with {@link SerializableFunction}
* @since 9.4
*/
default CompletableFuture computeIfAbsentAsync(K key, SerializableFunction mappingFunction, Metadata metadata) {
return this.computeIfAbsentAsync(key, (Function) mappingFunction, metadata);
}
/**
* Overloaded {@link #mergeAsync(Object, Object, BiFunction)}, which takes in an instance of {@link Metadata}
* which can be used to provide metadata information for the entry being stored, such as lifespan, version of
* value...etc. The {@link Metadata} is only stored if the call is successful.
*
* @param key, key with which the resulting value is to be associated
* @param value, the non-null value to be merged with the existing value associated with the key or, if
* no existing value or a null value is associated with the key, to be associated with the
* key
* @param remappingFunction, the function to recompute a value if present
* @param metadata, information to store alongside the new value
* @return the new value associated with the specified key, or null if no value is associated with the key
* @since 9.4
*/
CompletableFuture mergeAsync(K key, V value, BiFunction remappingFunction, Metadata metadata);
/**
* Overloaded {@link #mergeAsync(Object, Object, BiFunction, Metadata)} with {@link SerializableBiFunction}
*/
default CompletableFuture mergeAsync(K key, V value, SerializableBiFunction remappingFunction, Metadata metadata) {
return this.mergeAsync(key, value, (BiFunction) remappingFunction, metadata);
}
// TODO: Even better: add replace/remove calls that apply the changes if a given function is successful
// That way, you could do comparison not only on the cache value, but also based on version...etc
/**
* Gets a collection of entries, returning them as {@link Map} of the values associated with the set of keys
* requested.
*
* If the cache is configured read-through, and a get for a key would return null because an entry is missing from
* the cache, the Cache's {@link CacheLoader} is called in an attempt to load the entry. If an entry cannot be loaded
* for a given key, the returned Map will contain null for value of the key.
*
* Unlike other bulk methods if this invoked in an existing transaction all entries will be stored in the current
* transactional context
*
* The returned {@link Map} will be a copy and updates to the map will not be reflected in the Cache and vice versa.
* The keys and values themselves however may not be copies depending on if storeAsBinary is enabled and the value
* was retrieved from the local node.
*
* @param keys The keys whose associated values are to be returned.
* @return A map of entries that were found for the given keys. If an entry is not found for a given key, it will not
* be in the returned map.
* @throws NullPointerException if keys is null or if keys contains a null
*/
Map getAll(Set keys);
/**
* Retrieves a CacheEntry corresponding to a specific key.
*
* @param key the key whose associated cache entry is to be returned
* @return the cache entry to which the specified key is mapped, or {@code null} if this map contains no mapping for
* the key
* @since 5.3
*/
CacheEntry getCacheEntry(Object key);
/**
* Retrieves a CacheEntry corresponding to a specific key.
*
* @param key the key whose associated cache entry is to be returned
* @return a future with the cache entry to which the specified key is mapped, or with {@code null}
* if this map contains no mapping for the key
* @since 9.2
*/
default CompletableFuture> getCacheEntryAsync(Object key) {
throw new UnsupportedOperationException("getCacheEntryAsync");
}
/**
* Gets a collection of entries from the {@link AdvancedCache}, returning them as {@link Map} of the cache entries
* associated with the set of keys requested.
*
* If the cache is configured read-through, and a get for a key would return null because an entry is missing from
* the cache, the Cache's {@link CacheLoader} is called in an attempt to load the entry. If an entry cannot be loaded
* for a given key, the returned Map will contain null for value of the key.
*
* Unlike other bulk methods if this invoked in an existing transaction all entries will be stored in the current
* transactional context
*
* The returned {@link Map} will be a copy and updates to the map will not be reflected in the Cache and vice versa.
* The keys and values themselves however may not be copies depending on if storeAsBinary is enabled and the value
* was retrieved from the local node.
*
* @param keys The keys whose associated values are to be returned.
* @return A map of entries that were found for the given keys. Keys not found in the cache are present in the map
* with null values.
* @throws NullPointerException if keys is null or if keys contains a null
*/
Map> getAllCacheEntries(Set keys);
/**
* Executes an equivalent of {@link Map#putAll(Map)}, returning previous values of the modified entries.
*
* @param map mappings to be stored in this map
* @return A map of previous values for the given keys. If the previous mapping does not exist it will not be in the
* returned map.
* @since 9.1
*/
default Map getAndPutAll(Map map) {
Map result = new HashMap<>(map.size());
for (Entry entry : map.entrySet()) {
V prev = put(entry.getKey(), entry.getValue());
if (prev != null) {
result.put(entry.getKey(), prev);
}
}
return result;
}
/**
* It fetches all the keys which belong to the group.
*
* Semantically, it iterates over all the keys in memory and persistence, and performs a read operation in the keys
* found. Multiple invocations inside a transaction ensures that all the keys previous read are returned and it may
* return newly added keys to the group from other committed transactions (also known as phantom reads).
*
* The {@code map} returned is immutable and represents the group at the time of the invocation. If you want to add
* or remove keys from a group use {@link #put(Object, Object)} and {@link #remove(Object)}. To remove all the keys
* in the group use {@link #removeGroup(String)}.
*
* To improve performance you may use the {@code flag} {@link org.infinispan.context.Flag#SKIP_CACHE_LOAD} to avoid
* fetching the key/value from persistence. However, you will get an inconsistent snapshot of the group.
*
* @param groupName the group name.
* @return an immutable {@link java.util.Map} with the key/value pairs.
*/
Map getGroup(String groupName);
/**
* It removes all the key which belongs to a group.
*
* Semantically, it fetches the most recent group keys/values and removes them.
*
* Note that, concurrent addition perform by other transactions/threads to the group may not be removed.
*
* @param groupName the group name.
*/
void removeGroup(String groupName);
/**
* Returns the cache's availability. In local mode this method will always return {@link AvailabilityMode#AVAILABLE}.
* In clustered mode, the {@link PartitionHandlingManager} is queried to obtain the availability mode.
*/
AvailabilityMode getAvailability();
/**
* Manually change the availability of the cache. Doesn't change anything if the cache is not clustered or {@link
* PartitionHandlingConfiguration#whenSplit()} is set to {@link org.infinispan.partitionhandling.PartitionHandling#ALLOW_READ_WRITES}.
*/
void setAvailability(AvailabilityMode availabilityMode);
/**
* Touches the given key if present. This will refresh its last access time, used for max idle, and count as a recent
* access for eviction purposes.
*
* Note that it is possible to touch an entry that is expired via max idle if {@code touchEvenIfExpired} argument is
* {@code true}.
*
* This method will return without blocking and complete the returned stage with a value after all appropriate nodes
* have actually touched the value.
* @param key key of the entry to touch
* @param touchEvenIfExpired true if the entry should be touched even if already expired via max idle, effectively
* making it so the entry is no longer expired via max idle
* @return true if the entry was actually touched
*/
CompletionStage touch(Object key, boolean touchEvenIfExpired);
/**
* The same as {@link #touch(Object, boolean)} except that the segment is already known. This can be helpful to reduce
* an extra segment computation
* @param key key of the entry to touch
* @param segment segment of the key
* @param touchEvenIfExpired true if the entry should be touched even if already expired via max idle, effectively
* making it so the entry is no longer expired via max idle
* @return true if the entry was actually touched
*/
CompletionStage touch(Object key, int segment, boolean touchEvenIfExpired);
/**
* Identical to {@link Cache#entrySet()} but is typed to return CacheEntries instead of Entries. Please see the
* other method for a description of its behaviors.
*
* This method is needed since nested generics do not support covariance
*
* @return the entry set containing all of the CacheEntries
* @see Cache#entrySet()
*/
CacheSet> cacheEntrySet();
/**
* Returns a sequential stream using this Cache as the source. This stream is very similar to using the {@link
* CacheStream} returned from the {@link CacheSet#stream()} method of the collection returned via {@link
* AdvancedCache#cacheEntrySet()}. The use of this locked stream is that when an entry is being processed by the user
* the entry is locked for the invocation preventing a different thread from modifying it.
*
* Note that this stream is not supported when using a optimistic transactional or simple cache. Both non
* transactional and pessimistic transactional caches are supported.
*
* The stream will not share any ongoing transaction the user may have. Code executed by the stream should be treated
* as completely independent. That is any operation performed via the stream will require the user to start their own
* transaction or will be done intrinsically on the invocation. Note that if there is an ongoing transaction that has
* a lock on a key from the cache, that it will cause a deadlock.
*
* Currently simple cache, {@link org.infinispan.configuration.cache.ConfigurationBuilder#simpleCache(boolean)} was
* set to true, and optimistic caches, {@link org.infinispan.configuration.cache.TransactionConfigurationBuilder#lockingMode(LockingMode)}
* was set to {@link LockingMode#OPTIMISTIC}, do not support this method. In this case it will throw an {@link
* UnsupportedOperationException}. This restriction may be removed in a future version. Also this method cannot be
* used on a cache that has a lock owner already specified via {@link AdvancedCache#lockAs(Object)} as this could
* lead to a deadlock or the release of locks early and will throw an {@link IllegalStateException}.
*
* @return the locked stream
* @throws UnsupportedOperationException this is thrown if invoked from a cache that doesn't support this
* @throws IllegalStateException if this cache has already explicitly set a lock owner
* @since 9.1
*/
LockedStream lockedStream();
/**
* Attempts to remove the entry if it is expired. Due to expired entries not being consistent across nodes, this
* will still attempt to remove the value if it is not present. Note that this will raise an expired event even if
* the entry is not present. Normally this method should never be invoked except by the {@link ExpirationManager}.
*
* This command will only remove the value if the value and lifespan also match if provided.
*
* This method will suspend any ongoing transaction and start a new one just for the invocation of this command. It
* is automatically committed or rolled back after the command completes, either successfully or via an exception.
*
* NOTE: This method may be removed at any point including in a minor release and is not supported for external
* usage.
*
* @param key the key that is expiring
* @param value the value that mapped to the given. Null means it will match any value
* @param lifespan the lifespan that should match. If null is provided it will match any lifespan value
* @return if the entry was removed
*/
CompletableFuture removeLifespanExpired(K key, V value, Long lifespan);
/**
* Attempts to remove the entry for the given key, if it has expired due to max idle. This command first locks
* the key and then verifies that the entry has expired via maxIdle across all nodes. If it has this will then
* remove the given key.
*
* This method returns a boolean when it has determined if the entry has expired. This is useful for when a backup
* node invokes this command for a get that found the entry expired. This way the node can return back to the caller
* much faster when the entry is not expired and do any additional processing asynchronously if needed.
*
* This method will suspend any ongoing transaction and start a new one just for the invocation of this command. It
* is automatically committed or rolled back after the command completes, either successfully or via an exception.
*
* NOTE: This method may be removed at any point including in a minor release and is not supported for external
* usage.
* @param key the key that expired via max idle for the given entry
* @return if the entry was removed
*/
CompletableFuture removeMaxIdleExpired(K key, V value);
/**
* Performs any cache operations using the specified pair of {@link Encoder}.
*
* @param keyEncoder {@link Encoder} for the keys.
* @param valueEncoder {@link Encoder} for the values.
* @return an instance of {@link AdvancedCache} where all operations will use the supplied encoders.
* @deprecated Since 12.1, to be removed in a future version.
*/
@Deprecated(forRemoval=true, since = "12.1")
AdvancedCache withEncoding(Class keyEncoder, Class valueEncoder);
/**
* Performs any cache operations using the specified pair of {@link Wrapper}.
*
* @param keyWrapper {@link Wrapper} for the keys.
* @param valueWrapper {@link Wrapper} for the values.
* @return {@link AdvancedCache} where all operations will use the supplied wrappers.
* @deprecated Since 11.0. To be removed in 14.0, with no replacement.
*/
@Deprecated(forRemoval = true, since = "11.0")
AdvancedCache withWrapping(Class keyWrapper, Class valueWrapper);
/**
* Performs any cache operations using the specified {@link Encoder}.
*
* @param encoder {@link Encoder} used for both keys and values.
* @return an instance of {@link AdvancedCache} where all operations will use the supplied encoder.
* @deprecated Since 12.1, to be removed in a future version.
*/
@Deprecated(forRemoval=true, since = "12.1")
AdvancedCache withEncoding(Class encoder);
/**
* Performs any cache operations using the specified {@link Wrapper}.
*
* @param wrapper {@link Wrapper} for the keys and values.
* @return an instance of {@link AdvancedCache} where all operations will use the supplied wrapper.
* @deprecated Since 11.0. To be removed in 14.0, with no replacement.
*/
@Deprecated(forRemoval = true, since = "11.0")
AdvancedCache withWrapping(Class wrapper);
/**
* Perform any cache operations using an alternate {@link org.infinispan.commons.dataconversion.MediaType}.
*
* @param keyMediaType {@link org.infinispan.commons.dataconversion.MediaType} for the keys.
* @param valueMediaType {@link org.infinispan.commons.dataconversion} for the values.
* @return an instance of {@link AdvancedCache} where all data will formatted according to the supplied {@link
* org.infinispan.commons.dataconversion.MediaType}.
*
* @deprecated Use {@link #withMediaType(MediaType, MediaType)} instead.
*/
@Deprecated(forRemoval=true, since = "12.1")
AdvancedCache withMediaType(String keyMediaType, String valueMediaType);
/**
* @see #withMediaType(String, String)
*/
AdvancedCache withMediaType(MediaType keyMediaType, MediaType valueMediaType);
/**
* Perform any cache operations using the same {@link org.infinispan.commons.dataconversion.MediaType} of the cache
* storage. This is equivalent to disabling transcoding on the cache.
*
* @return an instance of {@link AdvancedCache} where no data conversion will take place.
*/
AdvancedCache withStorageMediaType();
/**
* @return The associated {@link DataConversion} for the keys.
*/
DataConversion getKeyDataConversion();
/**
* @return The associated {@link DataConversion} for the cache's values.
*/
DataConversion getValueDataConversion();
/**
* @deprecated Since 12.1, to be removed in a future version.
*/
@Deprecated(forRemoval=true, since = "12.1")
AdvancedCache withKeyEncoding(Class encoder);
/**
* An extension of {@link #removeAsync(Object)}, which returns a {@link CacheEntry} instead of only the value.
*
* @param key key to remove
* @return a future containing the {@link CacheEntry} removed or null if not found.
* @since 14.0
* @see #removeAsync(Object)
* @see #remove(Object)
*/
CompletableFuture> removeAsyncEntry(Object key);
}