| Oracle® Coherenceクライアント・ガイド リリース3.7.1 B65027-01 |
|
 前 |
 次 |
Coherence REST APIでは、キャッシュとの相互作用に使用できる多数の操作を事前定義しています。さらに、必要に応じてアグリゲータやエントリ・プロセッサなどのカスタム操作を作成できます。
この章の内容は次のとおりです。
Coherence RESTサービスでは、公開されるキャッシュに関するメタデータが必要です。メタデータには、キャッシュ・エントリのキーと値のタイプ、およびキー・コンバータおよび値マーシャリング処理が含まれます。キーおよび値のタイプは、Coherenceが組込みのコンバータおよびマーシャリング処理を使用できるようにするために必要です(XMLとJSONがサポートされます)。
キャッシュ・エントリのキーおよび値のタイプを定義するには、coherence-rest-config.xmlファイルを編集して、<key-class>および<value-class>要素を<resource>要素の中に含め、それぞれにキーと値のタイプを設定します。<resource>要素の詳細なリファレンスは、「resource」を参照してください。
次の例では、Stringキー・クラスおよびPersonユーザー・タイプの値クラスを定義します。
<resources>
<resource>
<cache-name>dist-http-example</cache-name>
<key-class>java.lang.String</key-class>
<value-class>example.Person</value-class>
</resource>
</resources>
RESTful APIには、キャッシュ内の単一オブジェクト上での、GET、PUTおよびDELETE操作の実行のサポートが含まれます。
GET操作
GET http://host:port/cacheName/key
キーに基づいて、キャッシュから単一オブジェクトを返します。指定されたキーを持つオブジェクトが存在しないと、404 (Not Found)メッセージが返されます。get操作は、部分的な結果をサポートします(詳細は、「部分オブジェクトのREST操作」を参照してください)。
次のサンプル出力は、GET操作の応答を示しています。
* Client out-bound request
> GET http://127.0.0.1:8080/dist-http-example/1
> Accept: application/xml
* Client in-bound response
< 200
< Content-Length: 212
< Content-Type: application/xml
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Person><id>1</id><name>
Mark</name><address><street>500 Oracle Parkway</street><city>Redwood Shores</city>
<country>United States</country></address></Person>
* Client out-bound request
> GET http://127.0.0.1:8080/dist-http-example/1
> Accept: application/json
* Client in-bound response
< 200
< Content-Type: application/json
<
{"@type":"rest.Person","address":{"@type":"rest.Address","city":"Redwood Shores",
"country":"United States","street":"500 Oracle Parkway"},"id":1,"name":"Mark"}
PUT操作
PUT http://host:port/cacheName/key
キャッシュで単一オブジェクトを作成または更新します。オブジェクトが更新されると、200 (OK)メッセージが返されます。オプティミスティック同時実行性チェックが失敗すると、409 (Conflict)メッセージと、エンティティとして現在のオブジェクトが返されます。詳細は、「並列処理制御の理解」を参照してください。
次のサンプル出力は、PUT操作の応答を示しています。
* Client out-bound request
> PUT http://127.0.0.1:8080/dist-test-sepx/1
> Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Person><id>1</id><name>
Mark</name><address><street>500 Oracle Parkway</street><city>Redwood Shores</city>
<country>United States</country></address></Person>
* Client in-bound response
< 200
< Content-Length: 0
<
* Client out-bound request
> PUT http://127.0.0.1:8080/dist-test-sepj/1
> Content-Type: application/json
{"@type":"rest.Person","id":1,"name":"Mark","address":{"@type":"rest.Address","str
eet":"500 Oracle Parkway","city":"Redwood Shores","country":"United States"}}
* Client in-bound response
< 200
< Content-Length: 0
<
削除操作
DELETE http://host:port/cacheName/key
キーに基づいて、キャッシュから単一オブジェクトを削除します。オブジェクトの削除が成功した場合、200 (OK)メッセージが返されます。指定されたキーを持つオブジェクトが存在しない場合、404 (Not Found)メッセージが返されます。
複数オブジェクトの操作により、ユーザーは単一のネットワーク・リクエストで複数のオブジェクトを取得または削除できるため、ネットワークの使用量を著しく削減でき、ネットワークのパフォーマンスが向上します。
|
注意: PUT操作は、大量の破損データが生成される場合があるので、サポートされていません。特には、エンティティ・ボディ内の(シリアライズされた形式の)個々のオブジェクトを、対応するキーと同じ順序でURLに配置されることが求められます。また、更新により置換を行うため、オブジェクト全体のシリアライズされた形式を提供する必要があり、さらにオーバーヘッドが発生する場合があります。 |
GET操作
GET http://host:port/cacheName/(key1, key2, ...)
指定されたキーに基づいて、キャッシュからオブジェクトのセットを返します。返されるオブジェクトの順序は定義されず、URLのキー順序と一致する必要もありません。欠落したオブジェクトは、警告なしで結果から省略されます。常に200 (OK)メッセージが返されます。結果セットにオブジェクトがないと、空の結果セットが返されます。get操作は、部分的な結果をサポートします(詳細は、「部分オブジェクトのREST操作」を参照してください)。
DELETE操作
DELETE http://host:port/cacheName/(key1, key2, ...)
指定されたキーに基づいて、キャッシュから複数のオブジェクトを削除します。指定されたオブジェクトがキャッシュに存在しなくても、常に200 (OK)メッセージが返されます。
アプリケーションでオブジェクト全体を取得したくない(または取得する必要がない)場合があります。たとえば、アプリケーションでドロップダウンにオプションのリストを入力するために、場合によっては多数のプロパティを持つ巨大なオブジェクトから2つのプロパティしか必要ない場合があります。このような使用ケースをサポートするために、それぞれの読取り処理で、ユーザーが必要なオブジェクト・プロパティのリストをマトリックス・パラメータpとして受け取ります。
次の例では、個人のidおよびname属性のみを取得するget操作を実行します。
GET http://localhost:8080/people/123;p=id,name
住所のcountry属性も含める場合、リクエストURLは次のようになります。
GET http://localhost:8080/people/123;p=id,name,address:(country)
この方法では、URLに対応した単純な表記を使用して、アプリケーションで必要なプロパティのみを選択的に取得できます。
次のサンプル出力は、GET操作の応答を示しています。
* Client out-bound request
> GET http://127.0.0.1:8080/dist-test-sepj/1;p=name
> Accept: application/json
* Client in-bound response
< 200
< Transfer-Encoding: chunked
< Content-Type: application/json
<
{"name":"Mark"}
CohQL式を問合せパラメータqとして渡すことで、キャッシュを問合せできます。また、sortマトリックス・パラメータを使用して結果をソートしたり、startおよびcountマトリックス・パラメータを指定して、返されるオブジェクトのセットを制限することもできます。CohQLの詳細は、『Oracle Coherence開発者ガイド』を参照してください。
GET http://host:port/cacheName;sort=sortOrder;start=start;count=count?q=query
問合せはURLエンコードのCohQL式として指定する必要があります(CohQLの述語句)。sortはオプションのパラメータで、ソートするプロパティのカンマ区切りリストを表し、それぞれにソート順を決定するオプションの:asc(デフォルト)または:desc修飾子を指定できます。たとえば、個人データのリストを性でソートし、家族のメンバーは年齢の大きい順にソートする場合、sortパラメータは次のように定義します。
sort=lastName,age:desc
startおよびcountパラメータは、返す結果のサブセットを決定するオプションの整数の引数です。
キャッシュ内のデータの集計を実行できます。Coherence RESTには事前定義のアグリゲータのセットが含まれ、必要に応じてカスタムのアグリゲータも作成できます。
この項の内容は次のとおりです。
GET http://host:port/cacheName/aggregator(args, ...)
キャッシュ内のすべてのエントリを集計します。集計が成功すると、200 (OK)メッセージと、エンティティとして集計結果が返されます。
GET http://host:port/cacheName/aggregator(args, ...)?q=query
問合せ結果を集計します。集計が成功すると、200 (OK)メッセージと、エンティティとして集計結果が返されます。問合せはURLエンコードのCohQL式として指定する必要があります(CohQLの述語句)。
GET http://host:port/cacheName/(key1, key2, ...)/aggregator(args, ...)
指定されたエントリを集計します。集計が成功すると、200 (OK)メッセージと、エンティティとして集計結果が返されます。
Coherence RESTは、(アグリゲータ関連のURLセグメントから)アグリゲータを作成するための簡単な方針を提供します。出荷時の状態のCoherence RESTでは、単一のタイプcom.tangosol.util.ValueExtractor (LongMax、DoubleMaxなど)のパラメータを受け入れるコンストラクタにより、任意の登録された(組込みまたはユーザー登録の)アグリゲータを解決できます。URL内のアグリゲータのコールにパラメータが含まれない場合、com.tangosol.util.extractor.IdentityExtractorを使用してアグリゲータが作成されます。
URL内のアグリゲータ・セグメントにパラメータが含まれない場合、または単一のValueExtractorを受け入れるコンストラクタが存在しない場合、Coherence RESTはデフォルトのコンストラクタを使用してアグリゲータのインスタンス化を試行します。これは、一部の組込みのアグリゲータ(Countなど)に最適な動作です。
次の例では、キャッシュ内で最も高齢な人を取得します。
GET http://host:port/people/long-max(age)
次の例では、数字のみを含むキャッシュで最大数を計算します。
GET http://host:port/numbers/comparable-max()
次の例では、個人データのキャッシュのサイズを計算します。
GET http://host:port/people/count()
次の事前定義のアグリゲータがサポートされます。
| アグリゲータ名 | アグリゲータ |
|---|---|
big-decimal-average |
BigDecimalAverage.class |
big-decimal-max |
BigDecimalMax.class |
big-decimal-min |
BigDecimalMin.class |
big-decimal-sum |
BigDecimalSum.class |
double-average |
DoubleAverage.class |
double-max |
DoubleMax.class |
double-min |
DoubleMin.class |
double-sum |
DoubleSum.class |
long-max |
LongMax.class |
long-min |
LongMin.class |
long-sum |
LongSum.class |
comparable-max |
ComparableMax.class |
comparable-min |
ComparableMin.class |
distinct-values |
DistinctValues.class |
Count |
Count.class |
カスタム・アグリゲータ・タイプを定義するには、RESTful URLで使用する名前、com.tangosol.util.EntryAggregatorインタフェースまたはcom.tangosol.coherence.rest.util.aggregator.AggregatorFactoryインタフェースを実装するクラスを指定します。
(ほとんどの事前定義のアグリゲータのように)集計が単一のプロパティまたはキャッシュ値自身で実行される場合、EntryAggregator実装は単純なシナリオで使用されます。
より複雑な方針が必要な場合、AggregatorFactoryインタフェースが使用されます。この実装で、アグリゲータ・パラメータを含むURLセグメントを解決し、それらのパラメータを使用して適切なアグリゲータを作成できる必要があります。
カスタム・アグリゲータは、coherence-rest-config.xmlファイルの<aggregators>要素で構成されます。詳細なリファレンスは、「aggregator」を参照してください。次の例では、EntryAggregatorのカスタム実装とAggregatorFactoryのカスタム実装を構成しています。
<aggregators>
<aggregator>
<name>my-simple-aggr</name>
<class-name>com.foo.MySimpleAggregator</class-name>
</aggregator>
<aggregator>
<name>mny-complex-aggr</name>
<class-name>com.foo.MyAggreagatorFactory</class-name>
</aggregator>
</aggregators>
キャッシュ内の1つ以上のオブジェクト上でエントリ・プロセッサを呼び出せます。Coherence RESTには事前定義のエントリ・プロセッサのセットが含まれ、必要に応じてカスタムのエントリ・プロセッサも作成できます。
この項の内容は次のとおりです。
POST http://host:port/cacheName/processor(args, ...)
キャッシュ内のすべてのエントリを処理します。処理が成功すると、200 (OK)メッセージと、エンティティとして処理結果が返されます。
POST http://host:port/cacheName/processor(args, ...)?q=query
問合せ結果を処理します。処理が成功すると、200 (OK)メッセージと、エンティティとして処理結果が返されます。
POST http://host:port/cacheName/(key1, key2, ...)/processor (args, ...)
指定されたエントリを処理します。処理が成功すると、200 (OK)メッセージと、エンティティとして処理結果が返されます。
アグリゲータと異なり、プロセッサ(事前定義のプロセッサも含む)には、多彩な作成パターンがあるため、Coherence RESTではプロセッサの作成について何の想定もしていません。そのかわり、それぞれのエントリ・プロセッサ実装に対して、com.tangosol.coherence.rest.util.processorProcessorFactoryインタフェースの実装が存在する必要があります。これにより、URLセグメントからの文字列の入力を処理して、プロセッサ・インスタンスをインスタンス化できます。Coherence RESTは、出荷時にはNumberIncrementorおよびNumberMultiplierの2つのファクトリを備えています。
次の例では、キャッシュ内の各個人の年齢を5つ増加させます。
GET http://localhost:8080/people/increment(age, 5)
次の例では、数字のみを含むキャッシュ内の各数字を10倍します。
GET http://localhost:8080/numbers/multiply(10)
次の事前定義のプロセッサがサポートされます。
| プロセッサ名 | プロセッサ |
|---|---|
increment |
常に新しい(増加された)値を返すNumberIncrementorインスタンス |
post-increment |
常に古い(増加されない)値を返すNumberIncrementorインスタンス |
multiply |
常に新しい(乗算された)値を返すNumberMultiplierインスタンス |
post-multiply |
常に古い(乗算されない)値を返すNumberMultiplierインスタンス |
カスタム・エントリ・プロセッサを定義するには、RESTful URLで使用される名前とcom.tangosol.coherence.rest.util.processor.ProcessorFactoryインタフェースを実装するクラスを指定します。
カスタム・エントリ・プロセッサは、coherence-rest-config.xmlファイルの<processors>要素内で構成されます。詳細なリファレンスは、「processors」を参照してください。次の例では、ProcesorFactoryのカスタム実装を構成します。
<processors>
<processor>
<name>my-processor</name>
<class-name>com.foo.MyProcessorFactory</class-name>
</processor>
</processors>
Coherence RESTでは、HTTPプロトコルに明確にマップされる場合のみ、オプティミスティック同時実行性をサポートします。ユーザーがPUTリクエストを送信してオブジェクトを更新する際に、キャッシュ・オブジェクトでcom.tangosol.util.Versionableインタフェースを実装していると、Coherence RESTは既存オブジェクトのバージョンと新規オブジェクトのバージョンが一致する場合のみ更新を実行します。それ以外の場合は409 (Conflict)メッセージが返され、アプリケーションが変更を再度適用して再試行できるように、既存のエンティティがクライアントに返されます。
キャッシュの別名は、単純化されたキャッシュ名を指定するために使用されます。別名は、キャッシュ名がRESTful URLパス・セグメントに最適でない場合に使用されます。単純化された名前は、実際のキャッシュ名にマップされます。
キャッシュの別名を定義するには、coherence-rest-config.xmlファイルを編集して、<alias>要素を<resource>要素内に含め、その値を単純化されたキャッシュ名に設定します。
次の例では、dist-extend-not-ideal-name-for-a-cache*という名前のキャッシュに、peopleという名前のキャッシュの別名を作成します。
<resources>
<resource>
<cache-name>dist-extend-not-ideal-name-for-a-cache*</cache-name>
<alias>people</alias>
...
</resource>
</resources>
