Oracle Coherence 3.7およびRepresentational State Transfer（REST）の使用によるCoherenceキャッシュ・データの公開

概要

目的

所要時間

約90分

シナリオ

このチュートリアルでは、以下の手順を実行します。

JAXBまたはJSONをサポートする一部のクラスの変更
REST認識型のクラスの公開をサポートするREST構成の作成
RESTをサポートするCoherenceサーバーの構成
cURLの使用によるCoherence RESTのテスト

前記のリンクを使用し、ライセンス契約に同意してOracle Coherence 3.7.1をダウンロードします。なお、このチュートリアルでは、ファイルのダウンロード先が/tmp/およびインストール先が/optであると仮定しています。

JAXBおよびJSON注釈を使用してRESTをサポートするようにクラスを変更

Representational State Transfer（REST）は、特に形式化されたリクエストおよびレスポンスを送信するクライアントおよびサーバーに基づく、大規模アプリケーション向けのアーキテクチャ・スタイルです。そのようなリクエストは、適切なコンテキストとともに、URLや、POST、PUT、GET、DELETEなどのアクションの形をとります。それから、リクエストは特定の表現を使用してレスポンスを返します。この例では、次の2つの表現を検討します。 JSONおよびJAXBです。このチュートリアルでは、JAXBおよびJSONに注釈を導入しますが、JAXBを使用し続けることに注意してください。また、Coherenceに付属するJAXB表現は、JSONおよびXMLの読取りおよび書込みが可能なことに注意してください。

JavaScript Object Notation（JSON）は、軽量のデータ交換形式です。 JSONは、人とマシンの両方にとって読取りおよび書込みが容易で、JavaScriptプログラミング言語のサブセットに基づいています。多数のブラウザおよびJavaScriptパーサーは、JSONの読取りおよび書込みをサポートしています。 JSONについて、詳しくはwww.json.orgを参照してください。
Java API for XML Binding（JAXB）は、XMLに基づくデータ交換形式であり、そのデータにアクセスするためのAPIのセットです。これを使用すると、JavaオブジェクトのXML形式の読取りおよびXML形式への書込みが可能になります。データ交換形式としてJAXBをサポートするその他の言語も、JAXBを使用できます。 JAXBについて、詳しくはhttp://jaxb.java.netを参照してください。

JAXB注釈をサポートするようにクラスをコピーおよび変更

このサブセクションでは、JAXBを使用してプロパティを公開するために、Person.javaおよびAddress.javaクラスに注釈を付けます。

JAXB注釈を付けたクラスには、3つの最小要件があります。

クラスは、シリアライズ可能な形式の一部を実装する必要があり、この例ではjava.io.Serializableを実装します。
各クラスは、XMLルート要素名を指定する必要があり、これがXML表現のトップまたはもっとも外側の要素になります。
各クラスは、そのフィールドを公開するためのメカニズムを指定する必要があります。

JAXBは、これらの目的のために2つの注釈を提供します。XmlRootElementおよびXmlAccessorTypeです。 XMLRootElementについては一目瞭然で、一番外側のXML要素の名前を提供します。 XmlAccessType属性は、データが抽出される方法を指定します。この例ではFIELDタイプを使用しましたが、これによってパブリック・フィールドおよび特に注釈を付けたプロパティ・メソッドを公開します。 PROPERTYは、フィールドとは正反対で、パブリック・プロパティ・フィールドおよび特に注釈を付けたフィールドを公開します。

OBEのルート・ディレクトリが表示されていることを確認してください。このOBEでは、/opt/REST.OBEを前提としています。
元のソースをsrc/ディレクトリからwork/ディレクトリにコピーします。
cp src/* work/

任意のテキスト・エディタで、Person.javaを開きます。

完成したバージョンのクラスは、completed/jaxbサブディレクトリに表示されることに注意してください。

必要なインポートおよび注釈を追加します。
インポート（すべて表示）：

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlRootElement;

注釈：
@XmlRootElement(name="person")
@XmlAccessorType(XmlAccessType.FIELD)

完成したクラスは次のように表示されます。

work/Address.javaクラスを開き、これに注釈を付けて、フィールドではなくPROPERTYを公開します。

完成したクラスは、次のように表示されます。

変更を保存します。

エディタを閉じて終了します。

更新したソース・コードのコンパイル

コマンド・プロンプト・ウィンドウで、/opt/REST.OBEディレクトリを表示していることを確認します。
ソースを別のディレクトリにインストールした場合は、適切なディレクトリが表示されていることを確認します。

便宜上、ソースをコンパイルするコマンド・スクリプトが提供されています。

build.shを開いて、内容を確認します。必要な場合は、Coherenceのインストール場所を変更します。

スクリプトでは、Oracle Coherence 3.7.1は/opt/coherenceにインストールされていることを前提としており、coherence-rest.jarファイルを（そのマニフェスト経由で）使用してJacksonライブラリ向けのインポートを解決することに注意してください。

変更を保存して、エディタを終了します。

以下のようなコマンドを使用してクラスをコンパイルします。

./build.sh

必要な場合は、コンパイル・エラーを修正します。

JSON注釈をサポートするようにクラスをコピーおよび変更

このセクションおよび以下のコンパイル・サブセクションは、オプションであり、情報提供のみが目的です。
JAXBは、JSONの読取りおよび書込みが可能です。 JSON注釈は、JAXBがサポートする内容に加えて特殊なJSON表現機能が必要な場合に考慮する必要があります。提供されているアグリゲータ関数の多くは、厳密なJSONを使用できないことに注意してください。

このサブセクションでは、JSON注釈を使用してプロパティを公開するために、PersonクラスおよびAddressクラスに注釈を付けます。 Oracle Coherenceでは、JSONとJava間のシリアライズおよびデシリアライズにJacksonコード・ライブラリを使用します。詳しくは、http://jackson.codehaus.org/を参照してください。

各クラスは、JSON/Javaへシリアライズおよびデシリアライズされるためにいくつかの情報を提供する必要があります。この情報は、JsonTypeInfo注釈経由で提供されます。この注釈は、以下のプロパティを取得します。

use = 注釈を付けたインスタンス・タイプのタイプ情報のシリアライズおよびデシリアライズに使用される、タイプ・メタデータの種類
include =タイプ・メタデータを含めるために使用されるメカニズム
property =タイプの特定に使用されるプロパティの名前

JsonTypeInfo注釈は、org.codehaus.jackson.annotateパッケージにあります。

コマンド・プロンプトで、元のソースをsrc/ディレクトリからwork/ディレクトリへコピーします。
cp src/* work/

任意のテキスト・エディタで、Person.javaを開きます。 Personクラスは、単純なJavaBeanスタイルのシリアライズ可能なオブジェクトです。

gedit Person.java

クラスを変更して、必要なJSONインポートを含めます。

必要なインポートは以下のとおりです。

import org.codehaus.jackson.annotate.*;
import org.codehaus.jackson.annotate.JsonTypeInfo.*;

@typeプロパティを使用して、フィールドをプロパティとして公開するクラス、およびクラス・タイプ情報に注釈を付けます。
@JsonTypeInfo(use=JsonTypeInfo.Id.CLASS,
include=JsonTypeInfo.As.PROPERTY,
property="@type")

変更を保存します。

JSONをサポートするようにアドレス・クラスを変更し、明示的なフィールド名を定義

任意のテキスト・エディタでAddress.javaを開き、必要なインポートおよび注釈文を追加します。

gedit Address.java

インポート：
import org.codehaus.jackson.annotate.*;

Annotation:
@JsonTypeInfo(use=JsonTypeInfo.Id.CLASS,include=JsonTypeInfo.As.PROPERTY,property="@type")

フィールドレベルの注釈であるJsonProperty注釈を使用し、street、cityおよびcountryフィールドを変更して明示的な名前を定義します。
注釈：
@JsonProperty("name to be applied to field")

更新したソース・コードのコンパイル

コマンド・プロンプトを開いて、ディレクトリを/opt/REST.OBEへ変更します。

便宜上、ソースをコンパイルするコマンド・スクリプトが提供されています。
build.shを開いて、内容を確認します。
このスクリプトでは、Oracle Coherence 3.7.1は/opt/coherenceにインストールされていることを前提としています。
必要な場合は、Coherenceのインストール場所を変更してください。
また、スクリプトでは、Jacksonライブラリ向けのインポートの解決にcoherence-rest.jarファイルを使用することに注意してください。

変更を保存して、エディタを終了します。

以下のようなコマンドを使用してクラスをコンパイルします。

./build.sh

必要に応じて、コンパイル・エラーを修正します。

REST認識型のオブジェクトの公開をサポートするように構成を変更

RESTをサポートするためのクラスの変更は、REST経由でのキャッシュ・オブジェクトを公開するために必要な作業の一部に過ぎません。 Oracle Coherenceでは、REST認識型のオブジェクトを新しく公開するために2つの構成変更が必要です。

REST構成：HTTPリクエストをCoherenceオブジェクトにマッピングするには、オブジェクトが格納されているキャッシュ、値オブジェクトのクラス名、および複雑なマルチパート・キー・クラスを適切な表現に変換するために使用できるキー・クラスを、Coherenceが認識している必要があります。 REST構成には<resource>要素が含まれ、これらのコンポーネントをそれぞれ定義します。

REST構成ファイルのデフォルトのファイル名は、coherence-rest-config.xmlです。このデフォルト値は、システム変数tangosol.coherence.rest.configを使用してオーバーライドできます。
プロキシ構成：プロキシ・サーバーは、HTTPリクエストをインターセプトし、サービスを正しいキャッシュへ転送するために必要です。 <Proxy-scheme>要素は、プロキシの定義に使用され、HTTP操作の受入れおよびレスポンスが可能です。

coherence-rest-config.xmlの完成

コマンド・プロンプト・ウィンドウで、configディレクトリを作成し、そこにベースライン構成ファイルをコピーします。

cp src/config/* config/

テキスト・エディタで、部分的に完成しているconfig/rest-configuration.xmlファイルを開きます。以下のような<resource>要素を追加することに注意してください。
<resource>
    <cache-name>*somecache*</cache-name>
    <key-class>fully qualified path to key class</key-class>
    <value-class>*fully qualified path to value class*</value-class>
</resource>

これらの要素は、サポートされる値オブジェクトごとの<resources>要素に挿入されます。

REST認識型のオブジェクトは、REST構成ファイル内のリソース要素の中の<resource>要素を使用して公開されます。

コメント(<!--...-->)を見つけ、以下のような要素に置き換えます。

<cache-name>dist-http-example</cache-name>
<key-class>java.lang.String</key-class>
<value-class>example.Person</value-class>
</resource>

更新された構成ファイルは、以下のようになります。新しい要素は、キャッシュ構成に存在するdist-http-exampleのキャッシュ名を指定することに注意してください。

更新したファイルを保存します。

rest-cache-configuration.xmlの完成

REST OBEソースのルートを表示していることを確認し、部分的に完成しているconfig/rest-cache-configuration.xmlファイルを開きます。

REST認識型オブジェクトは、プロキシ・サーバーを使用して提供されます。プロキシ・サーバーは、キャッシュ構成ファイルの<proxy-scheme>要素を使用して定義されます。

プロキシ・スキーマ・コメントを見つけ、その下で<proxy-scheme>要素を指定します。 <proxy-scheme>要素は、サービス名**ExtendHttpProxyService**およびスレッド・カウント5で定義し、**autostart** false
としてマークする必要があります。新しい要素は以下のようになります。
<proxy-scheme>
   <service-name>ExtendHttpProxyService</service-name>
   <thread-count>5</thread-count>
   <autostart system-property="proxy.enabled">false</autostart>
</proxy-scheme>

<auto-start>要素には、system-property属性が含まれることに注意してください。このプロパティを使用すると、以下のようなコメント行要素を使用してプロキシ設定を有効化または無効化できます。

**-Dproxy.enabled=true**

更新されたキャッシュ構成は、以下のようになります。新しい<proxy-scheme>要素およびシステム・プロパティに注意してください。

プロキシ・サービスは、受信リクエストを受け入れる方法を記述するアクセプタを定義する必要があります。アクセプタには、複数のタイプがあります。ただし、RESTサポートでは、プロキシによるHTTP接続の受入れが必要とされます。以下のように、http-acceptorを定義するacceptor-configを追加します。アクセプタは、<thread-count>要素と<autostart>要素の間で定義する必要があります。アドレスおよびポート要素には、それらのために定義され、オーバーライドされる場合があるシステム・プロパティがあることに注意してください。ポート8080は典型的なデフォルトのポートですが、通常はコマンド行でオーバーライドされます。

新しい要素は、次のようになります。
<acceptor-config>
    <http-acceptor>
      <local-address>
          <address system-property="proxy.adddress">localhost</address>
            <port system-property="proxy.port">8080</port>
        </local-address>
    </http-acceptor>
</acceptor-config>

完成したキャッシュ構成は、以下のようになります。

更新したファイルを保存します。

RESTをサポートするサーバーの起動

Coherence RESTサーバーは、多数のライブラリに依存し、そのほとんどはCoherence自体で提供されます。 start-server.shおよびstart-proxy.shスクリプトは、実行に特定のライブラリを必要とします。便宜上、prepare-lib.shスクリプトが提供されており、このスクリプトはすべての必須ライブラリを含むディレクトリを作成し、移入します。

これらのライブラリには、以下が含まれます。

ライブラリ	説明	構成内容
Jersey 1.8	JAX-RSのリファレンス実装（JSR 31S、Java API for RESTful Web Services）	jerrsy-core1.8.jar jersey-json-1.8.jar jersey-server-1.8.jar jersey-grizzly2-1.8.jar、http://grizzly.java.netからダウンロードする必要あり
Jackson 1.1.1	JSONシリアライズ・サポート	jackson-all-1.8.1.jar

Container

REST OBEソースのルートを開いていることを確認し、任意のテキスト・エディタでbin/prepare-lib.shスクリプトを開きます。

**COHERENCE_HOME**変数および**OBE_HOME**変数が正しいことを確認します。 Oracle CoherenceまたはOBEソースが別のディレクトリにインストールされている場合は、これらの変数を修正します。

変更を保存して、エディタを終了します。

以下のようなコマンドを使用してスクリプトを実行します。

./bin/prepare-lib.sh

スクリプトにより、/libディレクトリへのファイルのコピー、実行時のアクションのエコーが実行され、以下のような出力が生成されます。

任意のエディタで、提供されているサーバー起動スクリプトbin/start-server.shを開きます。

以下に注意し、環境に対応しない値を修正します。

1. **CLASSPATH**

任意のエディタで、提供されているサーバープロキシ・スクリプトbin/start-proxy.shを開きます。

CLASSPATHおよびファイル名が環境に対応することを確認します。

プロキシには、ポートを定義し、背後にあるプロキシ・サービスの起動を可能にする2つの追加プロパティが含まれることに注意してください。このOBEではポート9000を使用していますが、その他のポートに変更する必要がある場合は、binディレクトリ内のさまざまなヘルパー・スクリプトを正しいポートを参照するように調整する必要があることにも注意してください。

以下のようなコメントを使用してサーバーを起動します。

./bin/start-server.sh > server.log 2>&1 &

これによりバックグラウンドのサーバーが起動し、すべての出力（通常とエラーの両方）がserver.logに送信されます。

サーバーの起動を追跡するには、以下のようなコマンドの使用を検討してください。

tail -f server.log

サーバーの起動が表示されたら、次の手順に進みます。

以下のようなコメントを使用してプロキシ・サーバーを起動します。

.bin/start-proxy.sh > proxy.log 2>&1 &

これによりバックグラウンドのサーバーが起動し、すべての出力（通常とエラーの両方）がserver.logに送信されます。

プロキシ・サーバーの起動を追跡するには、以下のようなコマンドの使用を検討してください。

tail -f proxy.log

プロキシ・サーバーの起動が表示されたら、次の手順に進みます。

cURLの使用によるRESTのテスト

cURLは、サポートされている任意のプロトコル（HTTP、HTTPS、FTPなど）を使用して、ドキュメント/ファイルの取得またはサーバーへの送信に使用できるクライアント・アプリケーションです。コマンドは、ユーザー・インタラクションやさまざまな対話の介入なしで動作するように設計されており、スクリプト・サーバー・インタラクションに使用することができます。

cURLコマンドは、OSXおよびLinuxに対してネイティブで、Windowsでの使用向けにダウンロードできます。 Windowsユーザーは、cURLのバージョンをここで参照できます。

cURLは、Coherence*Extendプロキシ・サーバーと対話するために、以下のようなさまざまなコマンドを使用します。

PUT - URLによって定義される既存のリソースを更新します。リソースが存在しない場合は作成します。
POST - 結果のURLに従属する新しいリソースを作成します。
GET - URLに関連するリソースを返します。部分的なGETも可能であることに注意してください。さらに、GETはcountやsumなどのCoherence関数およびアグリゲータの実行に使用できます。
DELETE - URLに関連するリソースを削除します。

アクセスされるエンティティのURLの特定.

構成および起動スクリプトで指定されるhostname、portおよびcacheの名前を使用して、すべてのcURLリクエストのルートURLを特定します。

localhost - すべてがローカルで実行されます。
9000 - start-proxy.shスクリプトではポート9000を指定します。
dist-http-example - config/rest-cache-configuration.xmlから、使用されているキャッシュの名前を提供します。

完成したURLの一部は、http://localhost:9000/dist-http-exampleのようになります。残りの部分のURLは、操作に依存します。

**キャッシュへのエントリの追加**.

キャッシュへの要素の追加は、PUT経由で行われ、これは提供されたURLに従属する既存の要素を追加または更新します。
PUT操作を使用するcURLコマンドの一般的な形式は次のとおりです。

curl -i -H "Content-type:application/*type*" -X **PUT** -d **data** http://*hostname[:port]/cache-name*/**keyspec**

コマンドの重要な部分は次のとおりです。
     ***type*** - 入力のタイプ、JSONまたはXML
   ***data*** - オブジェクトの内容を表すデータ文字列
   ***keyspec*** - 追加されるオブジェクトのリソース識別子

たとえば、キー3、名前**Rebecca、**および年齢32のexample.Personオブジェクトを追加するには、以下のようなcURLコマンドを入力します。

curl -i -H Content-type:application/json -X PUT -d '{"@type":"example.Person",""name":"Rebecca","age":"32"}'
          http://localhost:9000/dist-http-ample/3

このコマンドは、一行で入力する必要があることに注意してください。次のデータが、このOBEの例として使用されました。

**キャッシュからのエントリの返し**

キャッシュからの要素の取得はGET経由で行われ、これによってキャッシュから1つまたは複数の要素が返されます。

GET操作を使用するcURLコマンドの一般的な形式は次のとおりです。

curl -i -H "Content-type:application/*type*" -X GET http://*hostname[:port]/cache-name*/*keyspec{.type}*

コマンドの重要な部分は次のとおりです。

キャッシュからの複数エントリの返し
RESTおよびCoherenceは、{key[,key]}に類似したキー仕様の形式経由で、複数の要素を同時に返すことができます。たとえば、{1,2}は、これらのキーに関連した要素を返します。

1番目と3番目の要素を返すには、次のようなキー仕様を入力します。

curl -i -X GET http://localhost:9000/dist-http-example/\{1,3\}

その他のキーの組合せを返すGETコマンドについては、前のPUT操作で試してみました。

キャッシュからの一部のエントリの返し
RESTおよびOracle Coherenceは、フィールド名のリストを使用してURLを拡張することにより、オブジェクトの一部および選択したオブジェクトを返すことができます。フィールド名は、;の後にいくつかのカンマで区切られたフィールドを続けることで、URLに追加します。以下に例を挙げます。

curl -i -X GET http://hostname[:port]/cache-name/{1,3};A,B,C

キー1および3のフィールドA、BおよびCを返します。

キー2および4のNameおよびAgeフィールドを返すには、以下のようなコマンドを入力します。

curl -i -X GET http://localhost:9000/dist-http-example/\{2.4\}

個人オブジェクトには、4つのフィールドがあります。 Name、Age、SexおよびIsValidPersonです。これらのフィールドを使用して、GETコマンドを確認します。

アグリゲータの使用によるデータの返し
Oracle Coherenceは、キー仕様ではなくアグリゲータ関数を指定する、GET操作とキー仕様の組合せにより、アグリゲータの実行をサポートします。データによって、任意の数のアグリゲータをコマンドラインで実行できます。

アグリゲータを使用するための一般的な形式は次のとおりです。

curl -i -X GET http://hostname[:port]/cache/[optional key spec][/aggregators([arguments])

たとえば、countアグリゲータは、キャッシュ内のすべてのオブジェクトの個数を返すために使用できます。 countを使用するには、次を実行します（スラッシュは、"("および")"文字を"エスケープ"するために使用されますが、BASHによって必要とされ、コマンドの一部ではないことに注意してください）。

curl -i -X GET http://localhost:9000/dist-http-example/count\(\)

以下のように、多数の標準のアグリゲータがあります。

関数	説明
max、long-max	整数値または長いフィールドの最大値を返します。
min、long-min	整数値または長いフィールドの最小値を返します。
sum、long-sum、double-sum	整数値のフィールドの合計、長いフィールドの合計、またはフィールドの合計の2倍を返します。
count	キャッシュ内の要素の総数を返します。

さまざまな方法を確認してみましょう。年齢はlongであり、long関数とともに使用する必要があることに注意してください。

キャッシュ内のすべての年齢の合計を返すには、以下を実行します。

curl -i -X GET http://localhost:9000/dist-http-example/long-sum\(age\)

キャッシュからのエントリの削除
キャッシュからのオブジェクトの削除は、GETに類似した表記法を使用しますが、DELETE操作を指定することによって行います。単一および複数の削除がサポートされていることに注意してください。

削除を実行するための一般的な形式は次のとおりです。

curl -i -X DELETE http://hostname[:port]/cache/multi-or-single-keyspec

たとえば、1および3の要素を削除するには、以下のようなコマンドを入力します。

curl -i -X DELETE http://localhost:9000/dist-http-example/{1,3}

要素5を削除するには、以下のようなコマンドを入力します。

curl -i -X DELETE http://localhost:9000/dist-http-example/5

DELETEコマンドを確認してください。要素の再追加には、提供されているbin/out.shスクリプトを常に使用できることに注意してください。

まとめ

このチュートリアルで学習した内容は、次のとおりです。

JAXBまたはJSONをサポートするクラスの変更
REST認識型のクラスの公開をサポートするREST構成の作成
RESTをサポートするCoherenceサーバーの構成
残りのサーバーおよびプロキシの起動
cURLの使用によるCoherence RESTのテスト

参考資料

Oracle Coherence 3.7.1ドキュメントは、ここから参照できます。
Oracle Coherenceの開発と管理に関する各種クラスおよび上級者向けトレーニングは、こちらで検索できます。
Oracle Coherenceについて、詳しくはOracle Learning Libraryにあるその他のOBEを参照してください。

著者

Lead Curriculum Developer： Al Saganich
共著者： Jason Howes、Tim Middleton、Noah Arlis他

このOracle by Exampleをナビゲートする際、次の機能を使用できます。

ヘッダー・ボタンの非表示：: ヘッダー内のボタンを非表示にするには、タイトルをクリックします。ボタンを再表示するには、もう一度タイトルをクリックします。
トピック一覧ボタン：: すべてのトピックの一覧です。いずれかのトピックをクリックすると、その項に移動します。
すべてのトピックを開く/閉じる：: すべての項に対する詳細を表示または非表示にします。デフォルトでは、すべてのトピックが閉じられています。
すべてのイメージを表示/非表示：: すべてのスクリーンショットを表示または非表示にします。デフォルトでは、すべてのイメージが表示されています。
印刷：: コンテンツを印刷します。現在表示または非表示にされているコンテンツが印刷されます。

このチュートリアルの特定の項に移動するには、一覧からトピックを選択してください。

Oracle Coherence 3.7およびRepresentational State Transfer（REST）の使用によるCoherenceキャッシュ・データの公開

概要

目的

所要時間

シナリオ

はじめに

ハードウェアとソフトウェアの要件

前提条件

JAXBおよびJSON注釈を使用してRESTをサポートするようにクラスを変更

JAXB注釈をサポートするようにクラスをコピーおよび変更

更新したソース・コードのコンパイル

JSON注釈をサポートするようにクラスをコピーおよび変更

JSONをサポートするようにアドレス・クラスを変更し、明示的なフィールド名を定義

更新したソース・コードのコンパイル

REST認識型のオブジェクトの公開をサポートするように構成を変更

coherence-rest-config.xmlの完成

rest-cache-configuration.xmlの完成

RESTをサポートするサーバーの起動

cURLの使用によるRESTのテスト

まとめ

参考資料

著者

キー	名前	年齢
1	Rusty	52
2	Al	49
3	Rebecca	32
4	Bill	39