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>

名前空間

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

XML 言語namespace

Blueprint

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

Spring

http://cxf.apache.org/jaxrs

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

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

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

+

consumes

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

+

produces

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

+

oneway

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

+

model/resource/operation/param

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

属性説明 +

name

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

+

type

REST URL またはメッセージからパラメーター値を抽出する方法を指定します。PATH、QUERY、MATRIX、HEADER、COOKIE、FORM、CONTEXT、REQUEST_BODY のいずれかの値に設定できます。

+

defaultValue

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

+

encoded

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

+