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 を説明します。
XML 言語 | namespace |
---|---|
Blueprint | |
Spring |
モデルスキーマのエンドポイントへの割り当て方法
モデルスキーマを定義してエンドポイントに割り当てるには、以下の手順を実行します。
- 選択した注入プラットフォーム (Blueprint XML または Spring XML) に適した XML namespace を使用して、モデルスキーマを定義します。
モデルスキーマファイルをプロジェクトのリソースに追加して、スキーマファイルを最終的なパッケージ (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
要素に以下の属性を定義できます。属性 説明 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
として注入されます。+