9 Coherence for C++クライアントAPIの使用

この章では、Coherence for C++ APIについて説明します。このAPIを使用すると、C++アプリケーションで、Coherenceクラスタ外部からCoherenceクラスタ化サービスにアクセスできます。

Coherence for C++ APIのドキュメントは2つの場所にあります。1つはOracle Coherence C++ APIリファレンスで、もう1つはCoherence for C++のdocディレクトリです。

この章には次の項が含まれます:

CacheFactory
NamedCache
QueryMap
ObservableMap
InvocableMap
Filter
値エクストラクタ
入力プロセッサ
エントリ・アグリゲータ

9.1 CacheFactory

CacheFactoryは、NamedCacheのインスタンスを取得および解放する、次の静的メソッドを提供します。

NamedCache::Handle getCache(String::View vsName): 指定の名前を持ち、リモートCoherenceクラスタで稼働しているNamedCacheに対応するNamedCache実装を取得します。
void releaseCache(NamedCache::Handle hCache): キャッシュの指定のインスタンスに関連付けられているローカル・リソースをすべて解放します。解放したキャッシュは使用できなくなります。ただし、そのキャッシュの内容は影響を受けません。
void destroyCache(NamedCache::Handle hCache): Coherenceクラスタ全体にある指定のキャッシュを破棄します。

9.2 NamedCache

NamedCacheは、クラスタのメンバー間で共有しているリソースのマップです。NamedCacheは、キャッシュおよびサービスの名前の取得とキャッシュの解放または破棄に使用する、次のメソッドを提供します。

String::View getCacheName(): キャッシュの名前をStringとして返します。
CacheService::Handle getCacheService(): このNamedCacheが属するCacheServiceへのハンドルを返します。
bool isActive(): このNamedCacheがアクティブかどうかを指定します。
void release(): NamedCacheのこのインスタンスに関連付けられているローカル・リソースを解放します。リソースを解放したキャッシュは使用できなくなりますが、その内容は影響を受けません。
void destroy(): NamedCacheのこのインスタンスを解放し、破棄します。

NamedCacheインタフェースは、QueryMap、InvocableMap、ConcurrentMap、CacheMap、ObservableMapの各インタフェースの拡張でもあります。

9.3 QueryMap

QueryMapは、Mapクラスに問合せ機能を追加して拡張したものと考えることができます。この機能により、様々なフィルタを使用してキャッシュを問い合せることができます。フィルタについては、「Filter」で説明しています。

Set::View keySet(Filter::View vFilter): このマップにあるキーのうち、フィルタで指定した基準を満足するエントリを対象とした一連のキーを返します。
Set::View entrySet(Filter::View vFilter): このマップにあるエントリのうち、フィルタで指定した基準を満足する一連のエントリを返します。返されたセットにある各要素は、Map::Entryオブジェクトです。
Set::View entrySet(Filter::View vFilter, Comparator::View vComparator): このマップにあるエントリのうち、フィルタで指定した基準を満足する一連のエントリを返します。返されたセットにある各要素は、Map::Entryオブジェクトです。このentrySetを使用すると、指定のComparatorまたは自然の順番でソートされたエントリ値に基づいて、イテレータがこのセットを昇順で確認していることがより確実となります。

さらに、QueryMapクラスには、索引の追加機能と削除機能があります。索引を使用すると、キャッシュに格納されている値とそれに対応するキーが関連付けられます。また、keySetメソッドとentrySetメソッドのパフォーマンスが大幅に向上します。

void addIndex(ValueExtractor::View vExtractor, boolean_t fOrdered, Comparator::View vComparator): このQueryMapに索引を追加します。索引により、この索引付きのMapに格納されている値(またはそれらの値の属性)と、同じMapの中でそれらの値に対応するキーを関連付けることができ、keySetメソッドとentrySetメソッドのパフォーマンスが向上します。
void removeIndex(ValueExtractor::View vExtractor): このQueryMapから索引を削除します。

問合せの詳細は、「キャッシュの問合せ(C++)」を参照してください。また、「単純な問合せの実行」にあるC++の例も参照してください。

9.4 ObservableMap

ObservableMapは、キャッシュの変更をリスニングする機能をアプリケーションに提供します。ObservableMapを実装したアプリケーションでは、キーとフィルタのリスナーを追加して、あらゆるキャッシュで発生したイベントを受信できます。これは、そのキャッシュがローカル、パーティション、ニア、レプリケーションのいずれであっても可能であり、またリードスルー、ライトスルー、ライトビハインド、オーバーフロー、ディスク記憶域などを使用しているかどうかに関係なく可能です。ObservableMapには、これらのリスナーを削除するメソッドもあります。

void addKeyListener(MapListener::Handle hListener, Object::View vKey, bool fLite): 特定のキーのマップ・リスナーを追加します。
void removeKeyListener(MapListener::Handle hListener, Object::View vKey): 特定のキーに関するイベントに以前サインアップしたマップ・リスナーを削除します。
void addFilterListener(MapListener::Handle hListener, Filter::View vFilter = NULL, bool fLite = false): フィルタによる評価に基づいてイベントを受信するマップ・リスナーを追加します。
void removeFilterListener(MapListener::Handle hListener, Filter::View vFilter = NULL): フィルタによる評価に基づいてイベントに以前サインアップしたマップ・リスナーを削除します。

「すべてのイベントのサインアップ」にあるC++の例を参照してください。

9.5 InvocableMap

InvocableMapは、エントリ別処理と集計操作の両方を起動できるキャッシュです。キャッシュの内容に対する操作は、キャッシュによって(したがって、特定の領域に制限されたキャッシュの内容の中で)実行できます。このメソッドは処理を特定の領域に制限できるため、分散環境で特に効率的です。つまり、キャッシュの内容に対する処理を、その処理の対象となるエントリを管理している場所に移動できます。プロセッサとアグリゲータの詳細は、「入力プロセッサ」および「エントリ・アグリゲータ」を参照してください。

Object::Holder invoke(Object::View vKey, EntryProcessor::Handle hAgent): 渡されたキーで指定されたエントリ(Entry)を対象として、渡されたプロセッサ(EntryProcessor)を起動し、その起動の結果を返します。
Map::View invokeAll(Collection::View vCollKeys, EntryProcessor::Handle hAgent): 渡されたキーで指定された複数のエントリ(Entryオブジェクト)のそれぞれを対象として、渡されたプロセッサ(EntryProcessor)を起動し、それぞれの起動の結果を返します。
Map::View invokeAll(Filter::View vFilter, EntryProcessor::Handle hAgent): 指定したフィルタで選択された複数のエントリ(Entryオブジェクト)のそれぞれを対象として、渡されたプロセッサ(EntryProcessor)を起動し、それぞれの起動の結果を返します。
Object::Holder aggregate(Collection::View vCollKeys, EntryAggregator::Handle hAgent): 渡されたキーで指定されたエントリを対象として集計操作を実行します。
Object::Holder aggregate(Filter::View vFilter, EntryAggregator::Handle hAgent): 指定したフィルタで選択されたエントリを対象として集計操作を実行します。

9.6 Filter

Filter は、結果をフィルタ処理し、指定の基準に一致するオブジェクトのみを返す機能を提供します。すべてのフィルタではFilterを実装する必要があります。多くの場合、フィルタをQueryMap APIとともに使用して、指定の基準に一致するエントリをキャッシュに問い合せます。「QueryMap」も参照。

bool evaluate(Object::View v): 指定のオブジェクトにテストを適用し、テストに合格した場合はtrue、不合格の場合はfalseを返します。

Coherence for C++では、coherence::util::filterネームスペースに、実用的なFilter実装が数多く用意されています。使用頻度が高いフィルタを次にいくつか示します。

EqualsFilterは、等価性のテストに使用します。オブジェクトが5に等しいことをテストするEqualsFilterを作成するメソッドは次のとおりです。
例9-1 EqualsFilterメソッドの使用
```
EqualsFilter::View vEqualsFilter = EqualsFilter::create(IdentityExtractor::getInstance(), Integer32::valueOf(5));
```
GreaterEqualsFilterは、「以上」条件のテストに使用します。オブジェクトの値が55以上であることをテストするGreaterEqualsFilterを作成するメソッドは次のとおりです。
例9-2 GreaterEqualsFilterメソッドの使用
```
GreaterEqualsFilter::View vGreaterEqualsFilter = GreaterEqualsFilter::create(IdentityExtractor::getInstance(), Integer32::valueOf(55));
```
LikeFilterは、パターンの照合に使用します。文字列で表現したオブジェクトの先頭がBelgであることをテストするLikeFilterを作成するメソッドは次のとおりです。
例9-3 LikeFilterメソッドの使用
```
LikeFilter::View vLikeFilter = LikeFilter::create(IdentityExtractor::getInstance(), "Belg%");
```
フィルタの中には、2つを組み合せることで複合条件を作成できるものがあります。
AndFilterは、2つのフィルタを組み合せてAND条件を作成します。オブジェクトの値が10より大きく20より小さいことをテストするAndFilterを作成するメソッドは次のとおりです。
例9-4 AndFilterメソッドの使用
```
AndFilter::View vAndFilter = AndFilter::create(
        GreaterFilter::create(IdentityExtractor::getInstance(), Integer32::valueOf(10)),
        LessFilter::create(IdentityExtractor::getInstance(), Integer32::valueOf(20)));
```
OrFilterは、2つのフィルタを組み合せてOR条件を作成します。オブジェクトの値が10より小さいか、または20より大きいことをテストするOrFilterを作成するメソッドは次のとおりです。
例9-5 OrFilterメソッドの使用
```
OrFilter::View vOrFilter = OrFilter::create(
        LessFilter::create(IdentityExtractor::getInstance(), Integer32::valueOf(10)),
        GreaterFilter::create(IdentityExtractor::getInstance(), Integer32::valueOf(20)));
```

9.7 値エクストラクタ

値エクストラクタは、オブジェクトから値を抽出し、その抽出を識別する情報を提供します。すべてのエクストラクタではValueExtractorを実装する必要があります。

注意:

実用的なすべてのエクストラクタ実装では、オブジェクトのシリアル化可能な状態のみに基づくようにhashCode関数とequals関数を明示的に実装することも必要です。

Object::Holder extract(Object::Holder ohTarget): 渡されたオブジェクトから値を抽出します。
bool equals(Object::View v): ValueExtractorと別のオブジェクトを比較し、両方が等価かどうかを判断します。2つのValueExtractorオブジェクトであるve1とve2は、vのあらゆる値について、ve1->extract(v)とve2->extract(v)が等しい場合にのみ、等価であると見なされます。
size32_t hashCode(): 一般的なObject#hashCode()の規定に従って、ValueExtractorオブジェクトのハッシュ値を決定します。

Coherence for C++には次のエクストラクタがあります。

ChainedExtractor: エクストラクタの配列に基づく複合的なValueExtractor実装です。配列内のエクストラクタは左から右に順次適用され、前のエクストラクタの結果が次のエクストラクタのターゲット・オブジェクトとなります。
ComparisonValueExtractor: 同じターゲットから抽出した2つの値の比較結果を返します。
IdentityExtractor: 渡された値から何も抽出せず、その値そのものを返す単純な実装です。
KeyExtractor: 値ではなく主要なオブジェクトに対して問合せを実行する必要があることを示す、特殊な目的の実装です。
MultiExtractor: エクストラクタの配列に基づく複合的なValueExtractor実装です。配列内のエクストラタはすべて、同じターゲット・オブジェクトに適用され、抽出した値のリストが抽出結果となります。
ReflectionExtractor: 指定したオブジェクトのプロパティから値を抽出します。

「問合せの概念の理解」にあるC++の例を参照してください。

9.8 入力プロセッサ

入力プロセッサは、キャッシュ内のエントリ・オブジェクトに対して作動するエージェントです。すべての入力プロセッサではEntryProcessorを実装する必要があります。

Object::Holder process(InvocableMap::Entry::Handle hEntry): 指定したエントリを処理します。
Map::View processAll(Set::View vSetEntries): エントリのコレクションを処理します。

Coherence for C++では、coherence::util::processorネームスペースに、EntryProcessor実装がいくつか用意されています。

Coherence Javaディストリビューションの一部であるC++の例を参照してください。

9.9 エントリ・アグリゲータ

エントリ・アグリゲータは、InvocableMapにあるエントリの一部のサブセットに対して実行し、集計結果を得るように指定できる処理を表します。集計の一般的な例として、最小、最大、合計、平均などの関数があります。ただし、集計の概念は、エントリのグループを評価して1つの答えを算出する必要のある任意のプロセスに適用されます。集計は、分散環境などで並列に実行する機能を明示的に備えています。

すべてのアグリゲータではEntryAggregatorインタフェースを実装する必要があります。

Object::Holder aggregate(Collection::View vCollKeys): エントリのコレクションを処理して集計結果を生成します。

Coherence for C++では、coherence::util::aggregatorネームスペースに、EntryAggregator実装がいくつか用意されています。

注意:

キャッシュした値オブジェクト同様、Filter、ValueExtractor、EntryProcessorおよびEntryAggregatorのすべてのカスタム実装クラスは、C++アプリケーションのPOFコンテキストおよびクライアントが接続されているクラスタ側ノードのPOFコンテキストに正しく登録する必要があります。したがって、カスタムのC++型の対応するJava実装を、クラスタ側ノードで作成、コンパイルおよびデプロイする必要があります。このようなカスタム型を実際に実行するのは、C++の実装ではなくJavaの実装であることに注意してください。詳細は、第10章「統合オブジェクトの構築(C++)」を参照してください。