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.

Since:
Coherence 3.1
Author:
cp/gg/jh 2005.07.19, as 2014.06.14
See Also:

  • Field Details

    • PARALLEL

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

      The execution granularity can be specified by combining this flag with either BY_MEMBER or BY_PARTITION, which are mutually exclusive. If neither is specified, Coherence is free to choose member or partition granularity using current service pressure and other internal metrics.

      See Also:

    • SERIAL

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

      The execution granularity can be specified by combining this flag with either BY_MEMBER or BY_PARTITION, which are mutually exclusive. If neither is specified, Coherence is free to choose member or partition granularity using current service pressure and other internal metrics.

      See Also:

    • BY_MEMBER

      static final int BY_MEMBER
      A flag requiring this aggregator to execute member-by-member.

      Each storage member processes its complete local entry set as one partial aggregation. Coherence will not subdivide that work by partition, even when the aggregator is PARALLEL.

      This flag is mutually exclusive with BY_PARTITION.

      See Also:

    • BY_PARTITION

      static final int BY_PARTITION
      A flag requiring this aggregator to execute partition-by-partition. The entries from each partition are processed independently and an independent partial result is created for every partition represented by the request.

      A storage member combines its partition partials into one member partial before sending it to the caller. The guarantee is about aggregation granularity; it does not require partitions to execute concurrently when the service is under pressure.

      This flag is mutually exclusive with BY_MEMBER.

      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:

    • CONTINUOUS

      static final int CONTINUOUS
      A flag specifying that this aggregator supports long-lived, incremental maintenance.

      An aggregator with this characteristic must return an empty aggregator from supply(), must not retain entries, and must return a non-destructive partial result from getPartialResult(). It must also implement retract(Entry) and explicitly return InvocableMap.StreamingAggregator.RetractionResult.REBUILD_REQUIRED when it cannot maintain a correct result after a removal. Its Object.equals(Object) and Object.hashCode() implementations must be based solely on serialized definition state so equivalent registrations can be identified after serialization.

      See Also:

    • STATE_CHECKPOINTABLE

      static final int STATE_CHECKPOINTABLE
      A flag specifying that this aggregator can create and restore an exact maintenance-state snapshot using snapshotState() and restoreState(Object).

      This characteristic is meaningful only together with CONTINUOUS. Snapshot and restore implementations must preserve all information required for future retractions, not merely the partial result used for distributed combination.

      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

    • retract

      default InvocableMap.StreamingAggregator.RetractionResult retract(InvocableMap.Entry<? extends K, ? extends V> entry)
      Retract the contribution of a single entry from the aggregation result.

      When the supplied entry is a MapTrigger.Entry, an implementation should retract the entry's original value. Otherwise, it should retract the value represented by the supplied entry.

      The default implementation cannot retract an entry and requires the caller to rebuild the aggregation result.

      Parameters:
      entry - the entry to retract
      Returns:
      the state of the aggregation result after the retraction

    • update

      default InvocableMap.StreamingAggregator.RetractionResult update(InvocableMap.Entry<? extends K, ? extends V> entry)
      Replace the contribution of an entry that was present before and remains present after a map update.

      The supplied entry is expected to be a MapTrigger.Entry exposing both its original and current values. The default implementation retracts the original contribution, accumulates the current contribution, and therefore preserves the semantics of an update for aggregators that do not provide a specialized implementation.

      Parameters:
      entry - the updated entry
      Returns:
      the state of the aggregation result after the update

    • getMaintenanceStatus

      default InvocableMap.StreamingAggregator.RetractionResult getMaintenanceStatus()
      Return the current maintenance status of this aggregator.

      This method is evaluated after an update has been fully applied, so an aggregator may report InvocableMap.StreamingAggregator.RetractionResult.STALE_BOUND from retract(Entry) and return InvocableMap.StreamingAggregator.RetractionResult.UPDATED here if accumulating the replacement value restored an exact result.

      Returns:
      the current maintenance status

    • snapshotState

      default Object snapshotState()
      Return a detached, serializer-compatible snapshot of the state required to continue incremental maintenance.

      This method is used only when STATE_CHECKPOINTABLE is advertised. The default implementation does not support state checkpointing.

      Returns:
      a detached maintenance-state snapshot
      Throws:
      UnsupportedOperationException - if state checkpointing is not supported

    • restoreState

      default void restoreState(Object state)
      Restore a maintenance-state snapshot into this empty supplied instance.

      This method is used only when STATE_CHECKPOINTABLE is advertised. The default implementation does not support state checkpointing.

      Parameters:
      state - the snapshot returned by snapshotState()
      Throws:
      UnsupportedOperationException - if state checkpointing is not supported

    • 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

    • isContinuous

      default boolean isContinuous()
      A convenience accessor to check if this aggregator supports the continuous aggregation lifecycle.
      Returns:
      true if this aggregator supports continuous aggregation, false otherwise

    • isStateCheckpointable

      default boolean isStateCheckpointable()
      Return whether this aggregator supports exact maintenance-state snapshots for transfer and persistence.
      Returns:
      true if this aggregator supports state checkpoints

    • 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