Package com.tangosol.util

Interface InvocableMap<K,V>

Type Parameters:

K - the type of the Map entry keys

V - the type of the Map entry values

All Superinterfaces:

Map<K,V>

All Known Subinterfaces:

NamedCache<K,V>, NamedMap<K,V>, OptimisticNamedCache

All Known Implementing Classes:

BundlingNamedCache, ContinuousQueryCache, ConverterCollections.ConverterInvocableMap, ConverterCollections.ConverterNamedCache, NearCache, ReadonlyNamedCache, VersionedNearCache, WrapperNamedCache

public interface InvocableMap<K,V>
extends Map<K,V>

An InvocableMap is a Map against which both entry-targeted processing and aggregating operations can be invoked. While a traditional model for working with a Map is to have an operation access and mutate the Map directly through its API, the InvocableMap allows that model of operation to be inverted such that the operations against the Map contents are executed by (and thus within the localized context of) a Map. This is particularly useful in a distributed environment, because it enables the processing to be moved to the location at which the entries-to-be-processed are being managed, thus providing efficiency by localization of processing.

Note: The Partitioned Cache implements the InvocableMap interface by partitioning and localizing the invocations, resulting in extremely high throughput and low latency.

Since:

Coherence 3.1

Author:

cp/gg/jh 2005.07.19, as 2014.06.14

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	InvocableMap.Entry<K,V>	An InvocableMap.Entry contains additional information and exposes additional operations that the basic Map.Entry does not.
static interface	InvocableMap.EntryAggregator<K,V,R>	An EntryAggregator represents processing that can be directed to occur against some subset of the entries in an InvocableMap, resulting in a aggregated result.
static interface	InvocableMap.EntryProcessor<K,V,R>	An invocable agent that operates against the Entry objects within a Map.
static interface	InvocableMap.ParallelAwareAggregator<K,V,P,R>	Deprecated. This interface was deprecated in Coherence 12.2.1 and might be removed in a future release.
static interface	InvocableMap.StreamingAggregator<K,V,P,R>	A StreamingAggregator is an extension of InvocableMap.EntryAggregator that processes entries in a streaming fashion and provides better control over execution characteristics.

Method Summary

Modifier and Type	Method	Description
<R> R	aggregate(Filter filter, InvocableMap.EntryAggregator<? super K,? super V,R> aggregator)	Perform an aggregating operation against the set of entries that are selected by the given Filter.
default <R> R	aggregate(InvocableMap.EntryAggregator<? super K,? super V,R> aggregator)	Perform an aggregating operation against all the entries.
<R> R	aggregate(Collection<? extends K> collKeys, InvocableMap.EntryAggregator<? super K,? super V,R> aggregator)	Perform an aggregating operation against the entries specified by the passed keys.
default V	compute(K key, Remote.BiFunction<? super K,? super V,? extends V> remappingFunction)	Compute a new mapping for the specified key and its current value.
default V	compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
default V	computeIfAbsent(K key, Remote.Function<? super K,? extends V> mappingFunction)	Compute the value using the given mapping function and enter it into this map (unless null), if the specified key is not already associated with a value (or is mapped to null).
default V	computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)	Note that the previous example will not work as expected if this method is called on a distributed map, as the add method will be called on a client-side copy of the collection stored on the server.
default V	computeIfPresent(K key, Remote.BiFunction<? super K,? super V,? extends V> remappingFunction)	Compute a new mapping given the key and its current mapped value, if the value for the specified key is present and non-null.
default V	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
default V	getOrDefault(Object key, V defaultValue)
<R> R	invoke(K key, InvocableMap.EntryProcessor<K,V,R> processor)	Invoke the passed EntryProcessor against the Entry specified by the passed key, returning the result of the invocation.
<R> Map<K,R>	invokeAll(Filter filter, InvocableMap.EntryProcessor<K,V,R> processor)	Invoke the passed EntryProcessor against the set of entries that are selected by the given Filter, returning the result of the invocation for each.
default <R> Map<K,R>	invokeAll(InvocableMap.EntryProcessor<K,V,R> processor)	Invoke the passed EntryProcessor against all the entries, returning the result of the invocation for each.
<R> Map<K,R>	invokeAll(Collection<? extends K> collKeys, InvocableMap.EntryProcessor<K,V,R> processor)	Invoke the passed EntryProcessor against the entries specified by the passed keys, returning the result of the invocation for each.
default V	merge(K key, V value, Remote.BiFunction<? super V,? super V,? extends V> remappingFunction)	If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value.
default V	merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
default V	putIfAbsent(K key, V value)
default boolean	remove(Object key, Object value)
default V	replace(K key, V value)
default boolean	replace(K key, V oldValue, V newValue)
default void	replaceAll(Filter filter, Remote.BiFunction<? super K,? super V,? extends V> function)	Replace each entry's value with the result of invoking the given function on that entry until all entries selected by the specified filter have been processed or the function throws an exception.
default void	replaceAll(Remote.BiFunction<? super K,? super V,? extends V> function)	Replace each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception.
default void	replaceAll(Collection<? extends K> collKeys, Remote.BiFunction<? super K,? super V,? extends V> function)	Replace each entry's value with the result of invoking the given function on that entry until all entries for the specified key set have been processed or the function throws an exception.
default void	replaceAll(BiFunction<? super K,? super V,? extends V> function)
default RemoteStream<InvocableMap.Entry<K,V>>	stream()	Return a stream of all entries in this map.
default RemoteStream<InvocableMap.Entry<K,V>>	stream(Filter filter)	Return a filtered stream of entries in this map.
default <T,E> RemoteStream<E>	stream(Filter filter, ValueExtractor<T,? extends E> extractor)	Return a stream of values extracted from all the entries that satisfy the specified filter.
default <T,E> RemoteStream<E>	stream(ValueExtractor<T,? extends E> extractor)	Return a stream of values extracted from the entries of this map.
default RemoteStream<InvocableMap.Entry<K,V>>	stream(Collection<? extends K> collKeys)	Return a stream of entries with the specified keys.
default <T,E> RemoteStream<E>	stream(Collection<? extends K> collKeys, ValueExtractor<T,? extends E> extractor)	Return a stream of values extracted from the entries with the specified keys.

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, forEach, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

invoke

<R> R invoke(K key,
             InvocableMap.EntryProcessor<K,V,R> processor)

Invoke the passed EntryProcessor against the Entry specified by the passed key, returning the result of the invocation.

Type Parameters:

R - the type of value returned by the EntryProcessor

Parameters:

key - the key to process; it is not required to exist within the Map

processor - the EntryProcessor to use to process the specified key

Returns:

the result of the invocation as returned from the EntryProcessor

invokeAll

default <R> Map<K,R> invokeAll(InvocableMap.EntryProcessor<K,V,R> processor)

Invoke the passed EntryProcessor against all the entries, returning the result of the invocation for each.

Type Parameters:

R - the type of value returned by the EntryProcessor

Parameters:

processor - the EntryProcessor to use to process the specified keys

Returns:

a Map containing the results of invoking the EntryProcessor against each of the specified keys

invokeAll

<R> Map<K,R> invokeAll(Collection<? extends K> collKeys,
                             InvocableMap.EntryProcessor<K,V,R> processor)

Invoke the passed EntryProcessor against the entries specified by the passed keys, returning the result of the invocation for each.

Type Parameters:

R - the type of value returned by the EntryProcessor

Parameters:

collKeys - the keys to process; these keys are not required to exist within the Map

processor - the EntryProcessor to use to process the specified keys

Returns:

a Map containing the results of invoking the EntryProcessor against each of the specified keys

invokeAll

<R> Map<K,R> invokeAll(Filter filter,
                             InvocableMap.EntryProcessor<K,V,R> processor)

Invoke the passed EntryProcessor against the set of entries that are selected by the given Filter, returning the result of the invocation for each.

Unless specified otherwise, InvocableMap implementations will perform this operation in two steps: (1) use the filter to retrieve a matching entry set; (2) apply the agent to every filtered entry. This algorithm assumes that the agent's processing does not affect the result of the specified filter evaluation, since the filtering and processing could be performed in parallel on different threads. If this assumption does not hold, the processor logic has to be idempotent, or at least re-evaluate the filter. This could be easily accomplished by wrapping the processor with the ConditionalProcessor.

Type Parameters:

R - the type of value returned by the EntryProcessor

Parameters:

filter - a Filter that results in the set of keys to be processed

processor - the EntryProcessor to use to process the specified keys

Returns:

a Map containing the results of invoking the EntryProcessor against the keys that are selected by the given Filter

aggregate

default <R> R aggregate(InvocableMap.EntryAggregator<? super K,? super V,R> aggregator)

Perform an aggregating operation against all the entries.

Type Parameters:

R - the type of value returned by the EntryAggregator

Parameters:

aggregator - the EntryAggregator that is used to aggregate across the specified entries of this Map

Returns:

the result of the aggregation

aggregate

<R> R aggregate(Collection<? extends K> collKeys,
                InvocableMap.EntryAggregator<? super K,? super V,R> aggregator)

Perform an aggregating operation against the entries specified by the passed keys.

Type Parameters:

R - the type of value returned by the EntryAggregator

Parameters:

collKeys - the Collection of keys that specify the entries within this Map to aggregate across

aggregator - the EntryAggregator that is used to aggregate across the specified entries of this Map

Returns:

the result of the aggregation

aggregate

<R> R aggregate(Filter filter,
                InvocableMap.EntryAggregator<? super K,? super V,R> aggregator)

Perform an aggregating operation against the set of entries that are selected by the given Filter.

Type Parameters:

R - the type of value returned by the EntryAggregator

Parameters:

filter - the Filter that is used to select entries within this Map to aggregate across

aggregator - the EntryAggregator that is used to aggregate across the selected entries of this Map

Returns:

the result of the aggregation

getOrDefault

default V getOrDefault(Object key,
                       V defaultValue)

Specified by:

getOrDefault in interface Map<K,V>

putIfAbsent

default V putIfAbsent(K key,
                      V value)

Specified by:

putIfAbsent in interface Map<K,V>

remove

default boolean remove(Object key,
                       Object value)

Specified by:

remove in interface Map<K,V>

replace

default boolean replace(K key,
                        V oldValue,
                        V newValue)

Specified by:

replace in interface Map<K,V>

replace

default V replace(K key,
                  V value)

Specified by:

replace in interface Map<K,V>

computeIfAbsent

default V computeIfAbsent(K key,
                          Remote.Function<? super K,? extends V> mappingFunction)

Compute the value using the given mapping function and enter it into this map (unless null), if the specified key is not already associated with a value (or is mapped to null).

If the mapping function returns null no mapping is recorded. If the function itself throws an (unchecked) exception, the exception is rethrown, and no mapping is recorded.

The most common usage is to construct a new object serving as an initial mapped value or memoized result, as in:

 
 map.computeIfAbsent(key, k -> new Value(f(k)));
 

Or to implement a multi-value map, Map<K, Collection<V>>, supporting multiple values per key:

 
 map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);
 

Note that the previous example will not work as expected if this method is called on a distributed map, as the add method will be called on the client-side copy of the collection stored on the server.

Parameters:

key - key with which the specified value is to be associated

mappingFunction - the function to compute a value

Returns:

the current (existing or computed) value associated with the specified key, or null if the computed value is null

computeIfAbsent

default V computeIfAbsent(K key,
                          Function<? super K,? extends V> mappingFunction)

Note that the previous example will not work as expected if this method is called on a distributed map, as the add method will be called on a client-side copy of the collection stored on the server.

Specified by:

computeIfAbsent in interface Map<K,V>

computeIfPresent

default V computeIfPresent(K key,
                           Remote.BiFunction<? super K,? super V,? extends V> remappingFunction)

Compute a new mapping given the key and its current mapped value, if the value for the specified key is present and non-null.

If the function returns null, the mapping is removed. If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

Parameters:

key - the key with which the specified value is to be associated

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or null if none

computeIfPresent

default V computeIfPresent(K key,
                           BiFunction<? super K,? super V,? extends V> remappingFunction)

Specified by:

computeIfPresent in interface Map<K,V>

compute

default V compute(K key,
                  Remote.BiFunction<? super K,? super V,? extends V> remappingFunction)

Compute a new mapping for the specified key and its current value.

If the function returns null, the mapping is removed (or remains absent if initially absent). If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

Parameters:

key - the key with which the computed value is to be associated

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or null if none

compute

default V compute(K key,
                  BiFunction<? super K,? super V,? extends V> remappingFunction)

Specified by:

compute in interface Map<K,V>

merge

default V merge(K key,
                V value,
                Remote.BiFunction<? super V,? super V,? extends V> remappingFunction)

If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value. Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result is null.

This method may be of use when combining multiple mapped values for a key. For example, to either create or append a String msg to a value mapping:

 
 map.merge(key, msg, String::concat)
 

If the function returns null the mapping is removed. If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

Parameters:

key - key with which the resulting value is to be associated

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

remappingFunction - the function to recompute a value if present

Returns:

the new value associated with the specified key, or null if no value is associated with the key

merge

default V merge(K key,
                V value,
                BiFunction<? super V,? super V,? extends V> remappingFunction)

Specified by:

merge in interface Map<K,V>

replaceAll

default void replaceAll(Remote.BiFunction<? super K,? super V,? extends V> function)

Replace each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception.

Exceptions thrown by the function are relayed to the caller.

Parameters:

function - the function to apply to each entry

replaceAll

default void replaceAll(BiFunction<? super K,? super V,? extends V> function)

Specified by:

replaceAll in interface Map<K,V>

replaceAll

default void replaceAll(Collection<? extends K> collKeys,
                        Remote.BiFunction<? super K,? super V,? extends V> function)

Replace each entry's value with the result of invoking the given function on that entry until all entries for the specified key set have been processed or the function throws an exception.

Exceptions thrown by the function are relayed to the caller.

Parameters:

collKeys - the keys to process; these keys are not required to exist within the Map

function - the function to apply to each entry

replaceAll

default void replaceAll(Filter filter,
                        Remote.BiFunction<? super K,? super V,? extends V> function)

Replace each entry's value with the result of invoking the given function on that entry until all entries selected by the specified filter have been processed or the function throws an exception.

Exceptions thrown by the function are relayed to the caller.

Parameters:

filter - the filter that should be used to select entries

function - the function to apply to each entry

stream

default RemoteStream<InvocableMap.Entry<K,V>> stream()

Return a stream of all entries in this map.

Returns:

a stream of all entries in this map

stream

default RemoteStream<InvocableMap.Entry<K,V>> stream(Collection<? extends K> collKeys)

Return a stream of entries with the specified keys.

Parameters:

collKeys - the keys to process; these keys are not required to exist within the Map

Returns:

a stream of entries for the specified keys

stream

default RemoteStream<InvocableMap.Entry<K,V>> stream(Filter filter)

Return a filtered stream of entries in this map.

Parameters:

filter - filter to apply to this map's entries before creating the stream

Returns:

a stream of entries that satisfy the specified filter

stream

default <T,E> RemoteStream<E> stream(ValueExtractor<T,? extends E> extractor)

Return a stream of values extracted from the entries of this map.

This method is highly recommended when the intention is to work against a stream of InvocableMap.Entry attributes, and is functionally equivalent to:

     cache.stream().map(entry -> entry.extract(extractor))
 

The use of this method over the stream() method, allows relevant indices to be used avoiding potential deserialization and significantly improving performance of value extraction.

The same goal can be achieved by simply using multiple RemoteStream.map(ValueExtractor) calls against the entry stream, such as:

     cache.stream()
          .map(Map.Entry::getValue)
          .map(MyValue::getAttribute)
 

However, this will only be efficient if you have a DeserializationAccelerator configured for the cache. Otherwise, it will result in deserialization of all cache entries, which is likely to have significant negative impact on performance.

Type Parameters:

T - the type of the value to extract from

E - the type of value that will be extracted

Parameters:

extractor - the extractor to use

Returns:

a stream of extracted values from the entries of this map

stream

default <T,E> RemoteStream<E> stream(Collection<? extends K> collKeys,
                                           ValueExtractor<T,? extends E> extractor)

Return a stream of values extracted from the entries with the specified keys.

This method is highly recommended when the intention is to work against a stream of InvocableMap.Entry attributes, and is functionally equivalent to:

     cache.stream(collKeys).map(entry -> entry.extract(extractor))
 

The use of this method over the stream(Collection) method, allows relevant indices to be used avoiding potential deserialization and significantly improving performance of value extraction.

The same goal can be achieved by simply using multiple RemoteStream.map(ValueExtractor) calls against the entry stream, such as:

     cache.stream(collKeys)
          .map(Map.Entry::getValue)
          .map(MyValue::getAttribute)
 

However, this will only be efficient if you have a DeserializationAccelerator configured for the cache. Otherwise, it will result in deserialization of all selected entries, which is likely to have significant negative impact on performance.

Type Parameters:

T - the type of the value to extract from

E - the type of value that will be extracted

Parameters:

collKeys - the keys to process; these keys are not required to exist within the Map

extractor - the extractor to use

Returns:

a stream of values extracted from all the entries with the specified keys

stream

default <T,E> RemoteStream<E> stream(Filter filter,
                                           ValueExtractor<T,? extends E> extractor)

Return a stream of values extracted from all the entries that satisfy the specified filter.

This method is highly recommended when the intention is to work against a stream of InvocableMap.Entry attributes, and is functionally equivalent to:

     cache.stream(filter).map(entry -> entry.extract(extractor))
 

The use of this method over the stream(Filter) method, allows relevant indices to be used avoiding potential deserialization and significantly improving performance of value extraction.

The same goal can be achieved by simply using multiple RemoteStream.map(ValueExtractor) calls against the entry stream, such as:

     cache.stream(filter)
          .map(Map.Entry::getValue)
          .map(MyValue::getAttribute)
 

However, this will only be efficient if you have a DeserializationAccelerator configured for the cache. Otherwise, it will result in deserialization of all selected entries, which is likely to have significant negative impact on performance.

Type Parameters:

T - the type of the value to extract from

E - the type of value that will be extracted

Parameters:

filter - filter to apply to this map's entries before creating the stream

extractor - the extractor to use

Returns:

a stream of values extracted from all the entries that satisfy the specified filter