Package org.infinispan.functional

Interface FunctionalMap.ReadWriteMap<K,​V>

  • All Superinterfaces:
    java.lang.AutoCloseable, FunctionalMap<K,​V>
    Enclosing interface:
    FunctionalMap<K,​V>
    public static interface FunctionalMap.ReadWriteMap<K,​V>
extends FunctionalMap<K,​V>
    Exposes read-write operations that can be executed against the functional map. The read-write operations that can be applied per entry are exposed by EntryView.ReadWriteEntryView.

    Read-write operations offer the possibility of writing values or metadata parameters, and returning previously stored information. Read-write operations are also crucial for implementing conditional, compare-and-swap (CAS) like operations.

    Locks are acquired before executing the read-write lambda.

    Method parameters for read-write operations, including lambdas, must be marshallable when running in a cluster.

    Since:
    8.0

    • Method Detail

      • eval

        <R> java.util.concurrent.CompletableFuture<R> eval​(K key,
                                                   java.util.function.Function<EntryView.ReadWriteEntryView<K,​V>,​R> f)
        Evaluate a read-write function on the value and metadata associated with the key and return a CompletableFuture with the return type of the function. If the user is not sure if the key is present, EntryView.ReadEntryView.find() can be used to find out for sure. This method can be used to implement single-key read-write operations in ConcurrentMap and javax.cache.Cache that do not depend on value information given by the user such as:
        • Map.remove(Object)
        • javax.cache.Cache#remove(Object)
        • javax.cache.Cache#getAndRemove(Object)
        • javax.cache.Cache#invoke(Object, EntryProcessor, Object...)

        The function must not mutate neither the key returned through EntryView.ReadEntryView.key() nor the internally stored value provided through EntryView.ReadEntryView.get() or EntryView.ReadEntryView.find().

        Type Parameters:
        R - function return type
        Parameters:
        key - the key associated with the EntryView.ReadWriteEntryView to be passed to the function.
        f - function that takes a EntryView.ReadWriteEntryView associated with the key, and returns a value.
        Returns:
        a CompletableFuture which will be completed with the returned value from the function

      • eval

        <T,​R> java.util.concurrent.CompletableFuture<R> eval​(K key,
                                                           T argument,
                                                           java.util.function.BiFunction<T,​EntryView.ReadWriteEntryView<K,​V>,​R> f)
        Evaluate a read-write function, with an argument passed in and a EntryView.WriteEntryView of the value associated with the key, and return a CompletableFuture which will be completed with the returned value by the function.

        This method provides the the capability to both update the value and metadata associated with that key, and return previous value or metadata.

        This method can be used to implement the vast majority of single-key read-write operations in ConcurrentMap and javax.cache.Cache such as:

        • Map.put(Object, Object)
        • ConcurrentMap.putIfAbsent(Object, Object)
        • ConcurrentMap.replace(Object, Object)
        • ConcurrentMap.replace(Object, Object, Object)
        • ConcurrentMap.remove(Object, Object)
        • javax.cache.Cache#getAndPut(Object, Object)
        • javax.cache.Cache#putIfAbsent(Object, Object)
        • javax.cache.Cache#remove(Object, Object)
        • javax.cache.Cache#replace(Object, Object, Object)
        • javax.cache.Cache#replace(Object, Object)
        • javax.cache.Cache#getAndReplace(Object, Object)

        The functionality provided by this function could indeed be implemented with eval(Object, Function), but there's a crucial difference. If you want to store a value and reference the value to be stored from the passed in operation, eval(Object, Function) needs to capture that value. Capturing means that each time the operation is called, a new lambda needs to be instantiated. By offering a BiFunction that takes user provided value as first parameter, the operation does not capture any external objects when implementing simple operations such as javax.cache.Cache#getAndPut(Object, Object), and hence, the BiFunction could be cached and reused each time it's invoked.

        Note that when encoders are in place despite the argument type and value type don't have to match the argument will use value encoding.

        The function must not mutate neither the key returned through EntryView.ReadEntryView.key() nor the internally stored value provided through EntryView.ReadEntryView.get() or EntryView.ReadEntryView.find().

        Type Parameters:
        R - type of the function's return
        Parameters:
        key - the key associated with the EntryView.ReadWriteEntryView to be passed to the operation
        argument - argument passed in as first parameter to the BiFunction.
        f - operation that takes a user defined value, and a EntryView.ReadWriteEntryView associated with the key, and writes to the EntryView.ReadWriteEntryView passed in, possibly returning previously stored value or metadata information
        Returns:
        a CompletableFuture which will be completed with the returned value from the function

      • evalMany

        <T,​R> Traversable<R> evalMany​(java.util.Map<? extends K,​? extends T> arguments,
                                    java.util.function.BiFunction<T,​EntryView.ReadWriteEntryView<K,​V>,​R> f)
        Evaluate a read-write BiFunction, with an argument passed in and a EntryView.ReadWriteEntryView of the value associated with the key, for each of the keys in the set passed in, and returns an Traversable to navigate each of the BiFunction invocation returns.

        This method can be used to implement operations that store a set of keys and return previous values or metadata parameters.

        These kind of operations are preferred to traditional end user iterations because the internal logic can often iterate more efficiently since it knows more about the system.

        Note that when encoders are in place despite the argument type and value type don't have to match the argument will use value encoding.

        The function must not mutate neither the key returned through EntryView.ReadEntryView.key() nor the internally stored value provided through EntryView.ReadEntryView.get() or EntryView.ReadEntryView.find().

        Parameters:
        arguments - the key/value pairs associated with each of the EntryView.ReadWriteEntryView passed in the function callbacks
        f - function that takes in a value associated with a key in the entries collection and the EntryView.ReadWriteEntryView associated with that key in the cache
        Returns:
        a Traversable to navigate each BiFunction return