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 名前空間は、対応する JAX-RS エンドポイントを Blueprint XML で定義するか Spring XML で定義するかによって異なります。次の表は、どの XML 言語にどの名前空間を使用するかを示しています。

XML 言語	Namespace
ブループリント	`http://cxf.apache.org/blueprint/jaxrs`
Spring	`http://cxf.apache.org/jaxrs`

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

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

選択したインジェクションプラットフォーム (Blueprint XML または Spring XML) に適切な XML 名前空間を使用して、モデルスキーマを定義します。
モデルスキーマファイルをプロジェクトのリソースに追加して、スキーマファイルが最終パッケージ (JAR、WAR、または OSGi バンドルファイル) のクラスパスで使用できるようにします。
注記
あるいは、エンドポイントの jaxrs:model 子要素を使用して、モデルスキーマを直接 JAX-RS エンドポイントに組み込むこともできます。
エンドポイントの modelRef 属性をクラスパス上のモデルスキーマの場所に設定し (クラスパス URL を使用)、モデルスキーマを使用するようにエンドポイントを設定します。
必要な場合は、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 要素に以下の属性を定義できます。

Attribute	説明
`name`	このリソースモデルが適用されるリソースクラス (または対応するインターフェイス) の名前。 +
`path`	このリソースにマップする REST URL パスのコンポーネント。 +
`consumes`	このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: `application/xml` または `application/json`)。 +
`produces`	このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: `application/xml` または `application/json`)。 +

model/resource/operation

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

Attribute	説明
`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 要素で以下の属性を定義できます。

Attribute	説明
`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` として注入されます。 +

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

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

モデルスキーマの例

namespace

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

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

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

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

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links