18.3. モデルスキーマでの REST サービスの定義

アノテーションなしの RESTful サービス

JAX-RS モデルスキーマを使用すると、Java クラスにアノテーションを付けずに RESTful サービスを定義できます。つまり、Java クラス (またはインターフェイス) に直接 @Path@PathParam@Consumes@Produces などのアノテーションを追加する代わりに、モデルスキーマを使用して、関連する REST メタデータをすべて別の XML ファイルで指定できます。これは、たとえば、サービスを実装する Java ソースを変更できない場合に役立ちます。

モデルスキーマの例

例18.1「サンプル JAX-RS モデルスキーマ」は、BookStoreNoAnnotations ルートリソースクラスのサービスメタデータを定義するモデルスキーマの例を示しています。

例18.1 サンプル JAX-RS モデルスキーマ

<model xmlns="http://cxf.apache.org/jaxrs">
  <resource name="org.apache.cxf.systest.jaxrs.BookStoreNoAnnotations" path="bookstore"
    produces="application/json" consumes="application/json">
    <operation name="getBook" verb="GET" path="/books/{id}" produces="application/xml">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="getBookChapter" path="/books/{id}/chapter">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="updateBook" verb="PUT">
       <param name="book" type="REQUEST_BODY"/>
    </operation>
  </resource>
  <resource name="org.apache.cxf.systest.jaxrs.ChapterNoAnnotations">
    <operation name="getItself" verb="GET"/>
    <operation name="updateChapter" verb="PUT" consumes="application/xml">
        <param name="content" type="REQUEST_BODY"/>
    </operation>
  </resource>
</model>

Namespaces

モデルスキーマの定義に使用する XML 名前空間は、対応する JAX-RS エンドポイントを Blueprint XML で定義するか Spring XML で定義するかによって異なります。次の表は、どの XML 言語にどの名前空間を使用するかを示しています。

XML 言語Namespace

ブループリント

http://cxf.apache.org/blueprint/jaxrs

Spring

http://cxf.apache.org/jaxrs

モデルスキーマをエンドポイントにアタッチする方法

モデルスキーマを定義してエンドポイントにアタッチするには、次の手順を実行します。

  1. 選択したインジェクションプラットフォーム (Blueprint XML または Spring XML) に適切な XML 名前空間を使用して、モデルスキーマを定義します。
  2. モデルスキーマファイルをプロジェクトのリソースに追加して、スキーマファイルが最終パッケージ (JAR、WAR、または OSGi バンドルファイル) のクラスパスで使用できるようにします。

    注記

    あるいは、エンドポイントの jaxrs:model 子要素を使用して、モデルスキーマを直接 JAX-RS エンドポイントに組み込むこともできます。

  3. エンドポイントの modelRef 属性をクラスパス上のモデルスキーマの場所に設定し (クラスパス URL を使用)、モデルスキーマを使用するようにエンドポイントを設定します。
  4. 必要な場合は、jaxrs:serviceBeans 要素を使用して、ルートリソースを明示的にインスタンス化します。モデルスキーマが (ベースインターフェイスを参照する代わりに) ルートリソースクラスを直接参照する場合は、この手順をスキップできます。

クラスを参照するモデルスキーマの設定

モデルスキーマがルートリソースクラスに直接適用される場合、モデルスキーマは自動的にルートリソース Bean をインスタンス化するため、jaxrs:serviceBeans 要素を使用してルートリソース Bean を定義する必要はありません。

たとえば、customer-resources.xml がメタデータをカスタマーリソースクラスに関連付けるモデルスキーマの場合、以下のように customerService サービスエンドポイントをインスタンス化できます。

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-resources.xml" />

インターフェイスを参照するモデルスキーマの設定

モデルスキーマが Java インターフェイス (ルートリソースのベースインターフェイス) に適用される場合、エンドポイントの jaxrs:serviceBeans 要素を使用してルートリソースクラスをインスタンス化する必要があります。

たとえば、customer-interfaces.xml がメタデータをカスタマーリソースクラスに関連付けるモデルスキーマの場合、以下のように customerService サービスエンドポイントをインスタンス化できます。

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-interfaces.xml">
    <jaxrs:serviceBeans>
       <ref component-id="serviceBean" />
    </jaxrs:serviceBeans>
</jaxrs:server>

<bean id="serviceBean" class="service.CustomerService"/>

モデルスキーマリファレンス

モデルスキーマは、次の XML 要素を使用して定義されます。

model
モデルスキーマのルート要素。モデルスキーマを参照する必要がある場合は (たとえば、modelRef 属性を使用して JAX-RS エンドポイントから)、この要素の id 属性を設定する必要があります。
model/resource

resource 要素は、メタデータを特定のルートリソースクラス (または対応するインターフェイス) に関連付けるために使用されます。resource 要素に以下の属性を定義できます。

属性説明 +

name

このリソースモデルが適用されるリソースクラス (または対応するインターフェイス) の名前。

+

path

このリソースにマップする REST URL パスのコンポーネント。

+

consumes

このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xml または application/json)。

+

produces

このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xml または application/json)。

+

model/resource/operation

operation 要素は、メタデータを Java メソッドに関連付けるために使用されます。operation 要素に以下の属性を定義できます。

属性説明 +

name

この要素が適用される Java メソッドの名前。

+

path

このメソッドにマップする REST URL パスのコンポーネント。この属性値には、パラメーターの参照を含めることができます (例: path="/books/{id}/chapter")。ここで、{id} はパスから id パラメーターの値を抽出します。

+

verb

このメソッドにマップする HTTP 動詞を指定します。通常、GETPOSTPUT、または DELETE のいずれかです。HTTP の動詞が指定されて いない 場合、Java メソッドは サブリソースロケーター と考えられ、サブリソースオブジェクトへの参照を返します (サブリソースクラスにも resource 要素を使用してメタデータを指定する必要があります)。

+

consumes

この操作によって消費されるコンテンツタイプ (インターネットメディアタイプ) を指定します (例: application/xmlapplication/json )。

+

produces

この操作で生成されるコンテンツタイプ (インターネットメディアタイプ) を指定します (例:application/xmlapplication/json)。

+

oneway

true の場合、操作を 一方向に設定します。つまり、リプライメッセージは不要になります。デフォルトは false です。

+

model/resource/operation/param

param 要素は、REST URL から値を抽出し、それをメソッドパラメーターのいずれかに注入するために使用されます。param 要素で以下の属性を定義できます。

属性説明 +

name

この要素が適用される Java メソッドパラメーターの名前。

+

type

パラメーター値を REST URL またはメッセージから抽出する方法を指定します。PATHQUERYMATRIXHEADERCOOKIEFORMCONTEXTREQUEST_BODY のいずれかの値に設定できます。

+

defaultValue

REST URL またはメッセージから値を抽出できなかった場合に、パラメーターに挿入するデフォルト値。

+

encoded

true の場合、パラメーター値は URI でエンコードされた形式で挿入されます (つまり %nn エンコーディングを使用します)。デフォルトは false です。たとえば、URL パス (/name/Joe%20Bloggs) からパラメーターを抽出する際に、エンコードが true に設定されると、パラメーターは Joe%20Bloggs として注入されます。そうでない場合は、パラメーターは Joe Bloggs として注入されます。

+