com.tangosol.util
Interface InvocableMap

All Superinterfaces:

Map

All Known Subinterfaces:

NamedCache

All Known Implementing Classes:

BundlingNamedCache, ContinuousQueryCache, NearCache, ReadonlyNamedCache, VersionedNearCache, WrapperNamedCache

public interface InvocableMap
extends Map

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: When using the Coherence Enterprise Edition or Grid Edition, the Partitioned Cache implements the InvocableMap interface by partitioning and localizing the invocations, resulting in extremely high throughput and low latency. When using Coherence Standard Edition, the InvocableMap processes the invocations on the originating node, typically resulting in higher network, memory and CPU utilization, which translates to lower performance, and particularly when processing large data sets.

Since:

Coherence 3.1

Author:

cp/gg/jh 2005.07.19

Nested Class Summary

static interface	InvocableMap.Entry An InvocableMap.Entry contains additional information and exposes additional operations that the basic Map.Entry does not.
static interface	InvocableMap.EntryAggregator 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 An invocable agent that operates against the Entry objects within a Map.
static interface	InvocableMap.ParallelAwareAggregator A ParallelAwareAggregator is an advanced extension to EntryAggregator that is explicitly capable of being run in parallel, for example in a distributed environment.

Method Summary

Object	aggregate(Collection collKeys, InvocableMap.EntryAggregator agent) Perform an aggregating operation against the entries specified by the passed keys.
Object	aggregate(Filter filter, InvocableMap.EntryAggregator agent) Perform an aggregating operation against the set of entries that are selected by the given Filter.
Object	invoke(Object oKey, InvocableMap.EntryProcessor agent) Invoke the passed EntryProcessor against the Entry specified by the passed key, returning the result of the invocation.
Map	invokeAll(Collection collKeys, InvocableMap.EntryProcessor agent) Invoke the passed EntryProcessor against the entries specified by the passed keys, returning the result of the invocation for each.
Map	invokeAll(Filter filter, InvocableMap.EntryProcessor agent) Invoke the passed EntryProcessor against the set of entries that are selected by the given Filter, returning the result of the invocation for each.

Methods inherited from interface java.util.Map

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

Method Detail

invoke

Object invoke(Object oKey,
              InvocableMap.EntryProcessor agent)

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

Parameters:

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

agent - the EntryProcessor to use to process the specified key

Returns:

the result of the invocation as returned from the EntryProcessor

invokeAll

Map invokeAll(Collection collKeys,
              InvocableMap.EntryProcessor agent)

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

Parameters:

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

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

Map invokeAll(Filter filter,
              InvocableMap.EntryProcessor agent)

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.

Parameters:

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

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

Object aggregate(Collection collKeys,
                 InvocableMap.EntryAggregator agent)

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

Parameters:

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

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

Returns:

the result of the aggregation

aggregate

Object aggregate(Filter filter,
                 InvocableMap.EntryAggregator agent)

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

Parameters:

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

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

Returns:

the result of the aggregation