Package com.tangosol.util

Interface InvocableMap.StreamingAggregator<K,V,P,R>

Type Parameters:
K - the type of the Map entry keys
V - the type of the Map entry values
P - the type of the partial result
R - the type of the final result
All Superinterfaces:
InvocableMap.EntryAggregator<K,V,R>, Serializable
All Known Implementing Classes:
AbstractAggregator, AbstractBigDecimalAggregator, AbstractComparableAggregator, AbstractDoubleAggregator, AbstractLongAggregator, BigDecimalAverage, BigDecimalMax, BigDecimalMin, BigDecimalSum, ComparableMax, ComparableMin, CompositeAggregator, CompositeAggregator.Parallel, Count, DistinctValues, DoubleAverage, DoubleMax, DoubleMin, DoubleSum, GroupAggregator, GroupAggregator.Parallel, LongMax, LongMin, LongSum, PartitionedJCacheStatistics.PartitionedCacheStatisticsAggregator, PartitionedJCacheStatistics.PartitionedCacheStatisticsClear, PriorityAggregator, QueryRecorder, ReducerAggregator, ScriptAggregator, TopNAggregator
Enclosing interface:
InvocableMap<K,V>
public static interface InvocableMap.StreamingAggregator<K,V,P,R> extends InvocableMap.EntryAggregator<K,V,R>
A StreamingAggregator is an extension of InvocableMap.EntryAggregator that processes entries in a streaming fashion and provides better control over execution characteristics.

It is strongly recommended that all new custom aggregator implementations implement this interface directly and override default implementation of the characteristics() method which intentionally errs on a conservative side.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ALLOW_INCONSISTENCIES
    A flag specifying that this aggregator may provide entries that are not consistent with the provided Filter.
    static final int
    BY_MEMBER
    A flag specifying that it might be beneficial to execute this aggregator member-by-member.
    static final int
    BY_PARTITION
    A flag specifying that it might be beneficial to execute this aggregator partition-by-partition.
    static final int
    PARALLEL
    A flag specifying that this aggregator should be executed in parallel.
    static final int
    PRESENT_ONLY
    A flag specifying that this aggregator is only interested in entries that are present in the cache and that the entries which are not present should never be passed to the accumulate(Entry) method.
    static final int
    RETAINS_ENTRIES
    A flag specifying that this aggregator retains InvocableMap.Entry instances passed to accumulate(Entry) method, which will force creation of a separate InvocableMap.Entry instance for each cache entry.
    static final int
    SERIAL
    A flag specifying that this aggregator should be executed serially.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    accumulate(InvocableMap.Entry<? extends K,? extends V> entry)
    Accumulate one entry into the result.
    default boolean
    accumulate(Streamer<? extends InvocableMap.Entry<? extends K,? extends V>> streamer)
    Accumulate multiple entries into the result.
    default R
    aggregate(Set<? extends InvocableMap.Entry<? extends K,? extends V>> setEntries)
    Process a set of InvocableMap.Entry objects in order to produce an aggregated result.
    default int
    characteristics()
    A bit mask representing the set of characteristics of this aggregator.
    boolean
    combine(P partialResult)
    Merge another partial result into the result.
    R
    finalizeResult()
    Return the final result of the aggregation.
    default R
    finalizeResult(Converter<Binary,?> convFromInternal)
    Return the final result of the aggregation.
    P
    getPartialResult()
    Return the partial result of the aggregation.
    default boolean
    isAllowInconsistencies()
    A convenience accessor to check if this streamer is ALLOW_INCONSISTENCIES.
    default boolean
    isByMember()
    A convenience accessor to check if this streamer is BY_MEMBER.
    default boolean
    isByPartition()
    A convenience accessor to check if this streamer is BY_PARTITION.
    default boolean
    isParallel()
    A convenience accessor to check if this streamer is PARALLEL.
    default boolean
    isPresentOnly()
    A convenience accessor to check if this streamer is PRESENT_ONLY.
    default boolean
    isRetainsEntries()
    A convenience accessor to check if this streamer is RETAINS_ENTRIES.
    default boolean
    isSerial()
    A convenience accessor to check if this streamer is SERIAL.
    InvocableMap.StreamingAggregator<K,V,P,R>
    supply()
    Create a new instance of this aggregator.

  • Field Details

    • PARALLEL

      static final int PARALLEL
      A flag specifying that this aggregator should be executed in parallel.

      An additional hint can be provided by combining this flag with BY_PARTITION flag, which would suggest to further parallelize the server side aggregation by splitting it per-partitions. In the absence of this flag, Coherence is free to decide which strategy to use based on the internal metrics.

      See Also:

    • SERIAL

      static final int SERIAL
      A flag specifying that this aggregator should be executed serially.

      An additional hint can be provided by combining this flag with either BY_MEMBER or BY_PARTITION flag, which are mutually exclusive. In the absence of either, Coherence is free to decide which strategy to use based on the internal metrics.

      See Also:

    • BY_MEMBER

      static final int BY_MEMBER
      A flag specifying that it might be beneficial to execute this aggregator member-by-member.

      This can be beneficial when there is a high chance for the aggregation to compute the result based solely on the one member worth set of entries.

      Note: this flag is meaningful only for serial execution.

      See Also:

    • BY_PARTITION

      static final int BY_PARTITION
      A flag specifying that it might be beneficial to execute this aggregator partition-by-partition. This implies that the entries from each partition will be processed independently and a partial result will be created for each partition.

      This can be beneficial when accumulation of individual entries is computationally intensive and would benefit from additional parallelization within each storage-enabled member. In this case, the partial results for all the partitions on a given member will be combined into a single partial result, which will then be sent back to the client for further aggregation.

      See Also:

    • RETAINS_ENTRIES

      static final int RETAINS_ENTRIES
      A flag specifying that this aggregator retains InvocableMap.Entry instances passed to accumulate(Entry) method, which will force creation of a separate InvocableMap.Entry instance for each cache entry.

      Please note that this flag is specified by default for backwards compatibility reasons, but if the aggregator does not retain entries it should be "unset" by overriding characteristics() method in order to reduce the amount of garbage that is created during the aggregation.

      See Also:

    • PRESENT_ONLY

      static final int PRESENT_ONLY
      A flag specifying that this aggregator is only interested in entries that are present in the cache and that the entries which are not present should never be passed to the accumulate(Entry) method.
      See Also:

    • ALLOW_INCONSISTENCIES

      static final int ALLOW_INCONSISTENCIES
      A flag specifying that this aggregator may provide entries that are not consistent with the provided Filter.

      Note: Coherence will ensure only entries that match the provided Filter are passed to the aggregator, which can result in repeat query evaluations if targeted partitions are concurrently modified during query evaluation. This option allows Coherence to relax this contract.

      See Also:

  • Method Details

    • supply

      InvocableMap.StreamingAggregator<K,V,P,R> supply()
      Create a new instance of this aggregator.
      Returns:
      a StreamAggregator

    • accumulate

      default boolean accumulate(Streamer<? extends InvocableMap.Entry<? extends K,? extends V>> streamer)
      Accumulate multiple entries into the result.

      Important note: The default implementation of this method provides necessary logic for aggregation short-circuiting and should rarely (if ever) be overridden by the custom aggregator implementation.

      Parameters:
      streamer - a Streamer that can be used to iterate over entries to add
      Returns:
      true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

    • accumulate

      boolean accumulate(InvocableMap.Entry<? extends K,? extends V> entry)
      Accumulate one entry into the result.
      Parameters:
      entry - the entry to accumulate into the aggregation result
      Returns:
      true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

    • combine

      boolean combine(P partialResult)
      Merge another partial result into the result.
      Parameters:
      partialResult - the partial result to merge
      Returns:
      true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

    • getPartialResult

      P getPartialResult()
      Return the partial result of the aggregation.
      Returns:
      the partial result of the aggregation

    • finalizeResult

      R finalizeResult()
      Return the final result of the aggregation.
      Returns:
      the final result of the aggregation

    • finalizeResult

      default R finalizeResult(Converter<Binary,?> convFromInternal)
      Return the final result of the aggregation.

      This method has a default implementation that simply calls finalizeResult() in order to avoid compilation errors and preserve backwards compatibility of custom aggregator implementations, even though it would make more sense to do it the other way around if we were designing this API from scratch.

      The unfortunate consequence is that even if you override this method in order to use the provided converter, you still need to implement finalizeResult() method, although you could simply implement it to throw java.lang.UnsupportedOperationException.

      Parameters:
      convFromInternal - converter that can be used to convert result from internal format
      Returns:
      the final result of the aggregation
      Since:
      24.09

    • characteristics

      default int characteristics()
      A bit mask representing the set of characteristics of this aggregator.

      By default, characteristics are a combination of PARALLEL and RETAINS_ENTRIES, which is sub-optimal and should be overridden by the aggregator implementation if the aggregator does not need to retain entries (which is often the case).

      Returns:
      a bit mask representing the set of characteristics of this aggregator
      See Also:

    • isParallel

      default boolean isParallel()
      A convenience accessor to check if this streamer is PARALLEL.
      Returns:
      true if this streamer is PARALLEL, false otherwise

    • isSerial

      default boolean isSerial()
      A convenience accessor to check if this streamer is SERIAL.
      Returns:
      true if this streamer is SERIAL, false otherwise

    • isByMember

      default boolean isByMember()
      A convenience accessor to check if this streamer is BY_MEMBER.
      Returns:
      true if this streamer is BY_MEMBER, false otherwise

    • isByPartition

      default boolean isByPartition()
      A convenience accessor to check if this streamer is BY_PARTITION.
      Returns:
      true if this streamer is BY_PARTITION, false otherwise

    • isRetainsEntries

      default boolean isRetainsEntries()
      A convenience accessor to check if this streamer is RETAINS_ENTRIES.
      Returns:
      true if this streamer is RETAINS_ENTRIES, false otherwise

    • isPresentOnly

      default boolean isPresentOnly()
      A convenience accessor to check if this streamer is PRESENT_ONLY.
      Returns:
      true if this streamer is PRESENT_ONLY, false otherwise

    • isAllowInconsistencies

      default boolean isAllowInconsistencies()
      A convenience accessor to check if this streamer is ALLOW_INCONSISTENCIES.
      Returns:
      true if this streamer is ALLOW_INCONSISTENCIES, false otherwise

    • aggregate

      default R aggregate(Set<? extends InvocableMap.Entry<? extends K,? extends V>> setEntries)
      Description copied from interface: InvocableMap.EntryAggregator
      Process a set of InvocableMap.Entry objects in order to produce an aggregated result.
      Specified by:
      aggregate in interface InvocableMap.EntryAggregator<K,V,P>
      Parameters:
      setEntries - a Set of read-only InvocableMap.Entry objects to aggregate
      Returns:
      the aggregated result from processing the entries