Interface FunctionalMap.WriteOnlyMap<K,​V>

  • All Superinterfaces:
    AutoCloseable, FunctionalMap<K,​V>
    Enclosing interface:
    FunctionalMap<K,​V>

    @Experimental
    public static interface FunctionalMap.WriteOnlyMap<K,​V>
    extends FunctionalMap<K,​V>
    Exposes write-only operations that can be executed against the functional map. The write operations that can be applied per entry are exposed by EntryView.WriteEntryView.

    Write-only operations require locks to be acquired but crucially they do not require reading previous value or metadata parameter information associated with the cached entry, which sometimes can be expensive since they involve talking to a remote node in the cluster or the persistence layer So, exposing write-only operations makes it easy to take advantage of this important optimisation.

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

    Since:
    8.0
    • Method Detail

      • eval

        <T> CompletableFuture<Void> eval​(K key,
                                         T argument,
                                         BiConsumer<T,​EntryView.WriteEntryView<K,​V>> f)
        Evaluate a write-only BiConsumer operation, with an argument passed in and a EntryView.WriteEntryView of the value associated with the key, and return a CompletableFuture which will be completed when the operation completes.

        Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.

        This method can be used to implement single-key write-only operations which do not need to query previous value, such as javax.cache.Cache#put(Object, Object)

        This operation is very similar to eval(Object, Consumer) and in fact, the functionality provided by this function could indeed be implemented with eval(Object, Consumer), 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, Consumer) needs to capture that value. Capturing means that each time the operation is called, a new lambda needs to be instantiated. By offering a BiConsumer 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#put(Object, Object), and hence, the BiConsumer 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.

        Parameters:
        key - the key associated with the EntryView.WriteEntryView to be passed to the operation
        argument - argument passed in as first parameter to the BiConsumer operation.
        f - operation that takes a user defined value, and a EntryView.WriteEntryView associated with the key, and writes to the EntryView.WriteEntryView passed in without returning anything
        Returns:
        a CompletableFuture which will be completed when the operation completes
      • eval

        CompletableFuture<Void> eval​(K key,
                                     Consumer<EntryView.WriteEntryView<K,​V>> f)
        Evaluate a write-only Consumer operation with a EntryView.WriteEntryView of the value associated with the key, and return a CompletableFuture which will be completed with the object returned by the operation.

        Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.

        This operation can be used to either remove a cached entry, or to write a constant value along with optional metadata parameters.

        Parameters:
        key - the key associated with the EntryView.WriteEntryView to be passed to the operation
        f - operation that takes a EntryView.WriteEntryView associated with the key and writes to the it without returning anything
        Returns:
        a CompletableFuture which will be completed when the operation completes
      • evalMany

        <T> CompletableFuture<Void> evalMany​(Map<? extends K,​? extends T> arguments,
                                             BiConsumer<T,​EntryView.WriteEntryView<K,​V>> f)
        Evaluate a write-only BiConsumer operation, with an argument passed in and a EntryView.WriteEntryView of the value associated with the key, for each of the keys in the set passed in, and returns a CompletableFuture that will be completed when the write-only operation has been executed against all the entries. This method can be used to implement operations such as:

        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.

        Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.

        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.

        Parameters:
        arguments - the key/value pairs associated with each of the EntryView.WriteEntryView passed in the function callbacks
        f - operation that consumes a value associated with a key in the entries collection and the EntryView.WriteEntryView associated with that key in the cache
        Returns:
        a CompletableFuture which will be completed when the BiConsumer operation has been executed against all entries
      • evalMany

        CompletableFuture<Void> evalMany​(Set<? extends K> keys,
                                         Consumer<EntryView.WriteEntryView<K,​V>> f)
        Evaluate a write-only Consumer operation with the EntryView.WriteEntryView of the value associated with the key, for each of the keys in the set passed in, and returns a CompletableFuture that will be completed when the write-only operation has been executed against all the entries.

        This method can be used to implement operations such as javax.cache.Cache#removeAll(Set).

        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.

        Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.

        Parameters:
        keys - the keys associated with each of the EntryView.WriteEntryView passed in the function callbacks
        f - operation that the EntryView.WriteEntryView associated with one of the keys passed in
        Returns:
        a CompletableFuture which will be completed when the Consumer operation has been executed against all entries