Menu Close

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>

namespace

モデルスキーマの定義に使用する XML namespace は、該当する JAX-RS エンドポイントを Blueprint XML または Spring XML のどちらで定義するかによって異なります。以下の表で、それぞれの XML 言語に使用する namespace を説明します。

モデルスキーマのエンドポイントへの割り当て方法

モデルスキーマを定義してエンドポイントに割り当てるには、以下の手順を実行します。

  1. 選択した注入プラットフォーム (Blueprint XML または Spring XML) に適した XML namespace を使用して、モデルスキーマを定義します。
  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/xmlapplication/json)。

+

produces

このリソースによって生成されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xmlapplication/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 として注入されます。

+