org.infinispan.commons.api.functional

Interface FunctionalMap.WriteOnlyMap<K,V>

All Superinterfaces:

AutoCloseable, FunctionalMap<K,V>

Enclosing interface:

FunctionalMap<K,V>

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. DESIGN RATIONALES:

• Why does it make sense to expose write-only operations? Because write-only operations do not need to read. In other words, since write-only operations do not read or query the previous value, these read/query operations, which sometimes can be expensive since they involve talking to a remote node in the cluster or the persistence layer, can be avoided optimising write-only operations.
• When ported over to the main Infinispan code base, write-only maps would be expected to acquire locks on keys before executing functions.

Nested Class Summary

Nested classes/interfaces inherited from interface org.infinispan.commons.api.functional.FunctionalMap

FunctionalMap.ReadOnlyMap<K,V>, FunctionalMap.ReadWriteMap<K,V>, FunctionalMap.WriteOnlyMap<K,V>

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	eval(K key, Consumer<EntryView.WriteEntryView<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.
CompletableFuture<Void>	eval(K key, V value, BiConsumer<V,EntryView.WriteEntryView<V>> f) Evaluate a write-only BiConsumer operation, with a value 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.
CompletableFuture<Void>	evalAll(Consumer<EntryView.WriteEntryView<V>> f) Evaluate a write-only Consumer operation with the EntryView.WriteEntryView of the value associated with the key, for all existing keys in functional map, and returns a CompletableFuture that will be completed when the write-only operation has been executed against all the entries.
CompletableFuture<Void>	evalMany(Map<? extends K,? extends V> entries, BiConsumer<V,EntryView.WriteEntryView<V>> f) Evaluate a write-only BiConsumer operation, with a value 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.
CompletableFuture<Void>	evalMany(Set<? extends K> keys, Consumer<EntryView.WriteEntryView<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.
Listeners.WriteListeners<K,V>	listeners() Allows to write-only listeners to be registered.
CompletableFuture<Void>	truncate() Truncate the contents of the cache, returning a CompletableFuture that will be completed when the truncate process completes.
FunctionalMap.WriteOnlyMap<K,V>	withParams(Param<?>... ps) Tweak write-only functional map executions providing Param instances.

Methods inherited from interface org.infinispan.commons.api.functional.FunctionalMap

getName, getStatus

Methods inherited from interface java.lang.AutoCloseable

close

Method Detail

withParams

FunctionalMap.WriteOnlyMap<K,V> withParams(Param<?>... ps)

Tweak write-only functional map executions providing Param instances.

Specified by:

withParams in interface FunctionalMap<K,V>

eval

CompletableFuture<Void> eval(K key,
                             V value,
                             BiConsumer<V,EntryView.WriteEntryView<V>> f)

Evaluate a write-only BiConsumer operation, with a value 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. By returning CompletableFuture instead of the function's return type directly, the method hints at the possibility that to executing the function might require remote data present in either a persistent store or a remote clustered node. 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)

DESIGN RATIONALES:

• Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.
• Why provide this operation? Isn't eval(Object, Consumer) enough? 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.

Parameters:

key - the key associated with the EntryView.WriteEntryView to be passed to the operation

value - value to write, 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<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. By returning CompletableFuture instead of the function's return type directly, the method hints at the possibility that to executing the function might require remote data present in either a persistent store or a remote clustered node. DESIGN RATIONALES:

• Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.
• Why provide this operation? Isn't eval(Object, Object, BiConsumer) enough? Possibly, this operation makes a bit simpler to write constant values 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

CompletableFuture<Void> evalMany(Map<? extends K,? extends V> entries,
                                 BiConsumer<V,EntryView.WriteEntryView<V>> f)

Evaluate a write-only BiConsumer operation, with a value 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:

• Map.putAll(Map)
• javax.cache.Cache#putAll(Map)

DESIGN RATIONALE:

• It makes sense to expose global operation like this instead of forcing users to iterate over the keys to lookup and call get individually since Infinispan can do things more efficiently.
• Since this is a write-only operation, no entry attributes can be queried, hence the only reasonable thing can be returned is Void.

Parameters:

entries - 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<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). DESIGN RATIONALE:

• It makes sense to expose global operation like this instead of forcing users to iterate over the keys to lookup and call get individually since Infinispan can do things more efficiently.
• 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

evalAll

CompletableFuture<Void> evalAll(Consumer<EntryView.WriteEntryView<V>> f)

Evaluate a write-only Consumer operation with the EntryView.WriteEntryView of the value associated with the key, for all existing keys in functional map, 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(). DESIGN RATIONALE:

• In the original design, this method would have taken no parameters and returned a CloseableIterator>, but doing so would have created encapsulation problems, since any changes to the entry view would need to be committed, and that would happen outside of the interceptor stack scope. To avoid this problem, simply pass in a consumer with the desired operation and then, the interceptor stack can control how the consumer gets executed and make sure it's committed.

Parameters:

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

truncate

CompletableFuture<Void> truncate()

Truncate the contents of the cache, returning a CompletableFuture that will be completed when the truncate process completes. This method can be used to implement:

• Map.clear()
• javax.cache.Cache#clear()

Returns:

a CompletableFuture that completes when the truncat has finished

listeners

Listeners.WriteListeners<K,V> listeners()

Allows to write-only listeners to be registered.