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 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>
      • 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​(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