Skip Headers
Oracle® Coherence Client Guide
Release 3.7.1

Part Number E22839-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

8 Understanding the Coherence for C++ API

The Coherence for C++ API allows C++ applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster.

Documentation of the Coherence for C++ API is available in two locations. The Oracle Coherence C++ API Reference and also in the doc directory of the Coherence for C++ distribution.

The following sections are included in this chapter:

8.1 CacheFactory

CacheFactory provides several static methods for retrieving and releasing NamedCache instances:

8.2 NamedCache

A NamedCache is a map of resources shared among members of a cluster. The NamedCache provides several methods used to retrieve the name of the cache and the service, and to release or destroy the cache:

NamedCache interface also extends the following interfaces: QueryMap, InvocableMap, ConcurrentMap, CacheMap and ObservableMap.

8.3 QueryMap

A QueryMap can be thought of as an extension of the Map class with additional query features. These features allow the ability to query a cache using various filters. Filters are described in "Filter".

Additionally, the QueryMap class includes the ability to add and remove indexes. Indexes are used to correlate values stored in the cache to their corresponding keys and can dramatically increase the performance of the keySet and entrySet methods.

See "Querying a Cache (C++)" for a more in depth look at queries. See also the C++ examples in "Simple Queries"

8.4 ObservableMap

An ObservableMap provides an application with the ability to listen for cache changes. Applications that implement ObservableMap can add key and filter listeners to receive events from any cache, regardless of whether that cache is local, partitioned, near, replicated, using read-through, write-through, write-behind, overflow, disk storage, and so on. ObservableMap also provides methods to remove these listeners.

See the C++ examples in "Signing Up for all Events".

8.5 InvocableMap

An InvocableMap is a cache against which both entry-targeted processing and aggregating operations can be invoked. The operations against the cache contents are executed by (and thus within the localized context of) a cache. This is particularly efficient in a distributed environment because it localizes processing: the processing of the cache contents are moved to the location at which the entries-to-be-processed are being managed. For more information about processors and aggregators, see "Entry Processors" and "Entry Aggregators".

8.6 Filter

Filter provides the ability to filter results and only return objects that meet a given set of criteria. All filters must implement Filter. Filters are commonly used with the QueryMap API to query the cache for entries that meet a given criteria. See also "QueryMap".

Coherence for C++ includes many concrete Filter implementations in the coherence::util::filter namespace. Below are several commonly used filters:

8.7 Value Extractors

A value extractor is used to extract values from an object and to provide an identity for the extraction. All extractors must implement ValueExtractor.


All concrete extractor implementations must also explicitly implement the hashCode and equals functions in a way that is based solely on the object's serializable state.

Coherence for C++ includes the following extractors:

See the C++ examples in "Query Concepts".

8.8 Entry Processors

An entry processor is an agent that operates against the entry objects within a cache. All entry processors must implement EntryProcessor.

Coherence for C++ includes several EntryProcessor implementations in the coherence::util::processor namespace.

See the hellogrid C++ example in Chapter 16, "Sample C++ Application."

8.9 Entry Aggregators

An entry aggregator represents processing that can be directed to occur against some subset of the entries in an InvocableMap, resulting in an aggregated result. Common examples of aggregation include functions such as minimum, maximum, sum, and average. However, the concept of aggregation applies to any process that must evaluate a group of entries to come up with a single answer. Aggregation is explicitly capable of being run in parallel, for example in a distributed environment.

All aggregators must implement the EntryAggregator interface:

Coherence for C++ includes several EntryAggregator implementations in the coherence::util::aggregator namespace.


Like cached value objects, all custom Filter, ValueExtractor, EntryProcessor, and EntryAggregator implementation classes must be correctly registered in the POF context of the C++ application and cluster-side node to which the client is connected. As such, corresponding Java implementations of the custom C++ types must be created, compiled, and deployed on the cluster-side node. Note that the actual execution of these custom types is performed by the Java implementation and not the C++ implementation. See Chapter 10, "Building Integration Objects (C++)," for additional details.