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>
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

  • Method Details

    • 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