13.3 メタデータの発行

JAX-RSエンジンは,RESTful Webサービス(Webリソース)のWADL(メタデータ)を自動的に発行します。

ここでは,WADLの発行を利用するに当たって,注意が必要な点について説明します。

<この節の構成>
(1) メタデータの発行条件

(1) メタデータの発行条件

WebリソースのWADLを発行するメソッドは,次に示す二つです。

HTTP GETメソッドを使用してWebリソースのWADLを発行する条件を次の表に示します。JAX-RSエンジンが,次の表に示す条件をすべて満たしたHTTPリクエストを受信したときにWADLが発行されます。

表13-2  Webリソースのメタデータの発行に必要なHTTPリクエスト(GET)

項番項目条件
1HTTPメソッドGETメソッド
2URLスキーマhttpまたはhttps
3ホスト名(:ポート番号)メタデータの発行を要求するWebリソースが存在するホスト名(およびポート番号)
4コンテキストパスメタデータの発行を要求するWebリソースが含まれるWebアプリケーションのコンテキストパス
5コンテキストパスの後ろのパス"application.wadl"

例えば,Webリソースを含むWebアプリケーション(WARファイル)のコンテキストルートが,"sample" で,Webアプリケーションが"example.org"というホストで公開されていると仮定すると,URLは「http://example.org/sample/application.wadl」です。この場合,発行されるWADLには,web.xmlのcom.sun.jersey.config.property.packages初期化パラメタ(init-param要素)に指定されたすべてのWebリソースが含まれます。web.xmlにcom.sun.jersey.config.property.packages初期化パラメタ(init-param要素)が記述されていない場合は,WARファイルに含まれるすべてのWebリソースが含まれます。web.xmlのcom.sun.jersey.config.property.packages初期化パラメタ(init-param要素)については「11.2 web.xmlの作成」を参照してください。

WebリソースのWADLの例を次に示します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
<doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Cosminexus JAX-RS 09-00"/>
<resources base="http://example.org/sample/">
 <resource path="root">
  <method name="GET" id="resourceMethod">
   <response>
    <representation mediaType="*/*"/>
   </response>
  </method>
  <method name="POST" id="postHandler">
   <request>
    <representation mediaType="*/*">
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
      style="query" name="form"/>
    </representation>
   </request>
   <response>
    <representation mediaType="text/html"/>
   </response>
  </method>
  <resource path="subresourceMethod">
   <method name="GET" id="subResourceMethod">
    <request>
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="1"
      type="xs:string" style="matrix" name="matrix"/>
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
      name="cookie"/>
    </request>
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
  </resource>
  <resource path="exception">
   <method name="GET" id="subResourceMethodThrowingException">
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
  </resource>
  <resource path="subresourceLocator/{id}">
   <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
    style="template" name="id"/>
   <method name="GET" id="getHandlerForSubResource">
    <request>
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
      style="header" name="HeaderKey"/>
    </request>
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
  </resource>
 </resource>
</resources>
</application>

HTTP OPTIONSメソッドを使用してWebリソースのメタデータを発行する条件を次の表に示します。Webサービス側のJAX-RSエンジンが,次の表に示す条件をすべて満たしたHTTPリクエストを受信したときにメタデータが発行されます。

表13-3  Webリソースのメタデータの発行に必要なHTTPリクエスト(OPTIONS)

項番項目条件
1HTTPメソッドOPTIONSメソッド
2URLスキーマhttp
3ホスト名(:ポート番号)メタデータの発行を要求するWebリソースが存在するホスト名(およびポート番号)
4コンテキストパスメタデータの発行を要求するWebリソースが含まれるWebアプリケーションのコンテキストパス
5WebリソースのパスWebリソースで使われているPathアノテーションの値

例えば,WebリソースAのPathアノテーションの値が「/rootA」,ホスト名が「example.org」,コンテキストパスが「sample」だとします。この場合,メタデータを発行するURLは「http://example.org/sample/rootA」となります。

このとき,発行されるWADLには,要求されたWebリソースだけが含まれます。

ポイント
対象となるWebリソースのメソッドがOPTIONSアノテーションを持ち,HTTP OPTIONS要求を処理できる場合,JAX-RSエンジンはWADLを発行しないで,そのWebリソースのHTTP OPTIONSリクエストを処理するメソッドを呼び出します。WebリソースがHTTP OPTIONSリクエストを処理できなければ,JAX-RSエンジンは自動でWADLを生成します。

HTTP OPTIONSメソッドを使用したWADLの例を次に示します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
<doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Cosminexus JAX-RS 09-00"/>
<resources base="http://example.org/sample/">
 <resource path="/root">
  <method name="GET" id="resourceMethod">
   <response>
    <representation mediaType="*/*"/>
   </response>
  </method>
  <method name="POST" id="postHandler">
   <request>
    <representation mediaType="*/*">
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
      style="query" name="form"/>
    </representation>
   </request>
   <response>
    <representation mediaType="text/html"/>
   </response>
  </method>
  <resource path="subresourceMethod">
   <method name="GET" id="subResourceMethod">
    <request>
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="1"
      type="xs:string" style="matrix" name="matrix"/>
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
      name="cookie"/>
    </request>
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
  </resource>
  <resource path="exception">
   <method name="GET" id="subResourceMethodThrowingException">
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
  </resource>
  <resource path="subresourceLocator/{id}">
   <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
    style="template" name="id"/>
   <method name="GET" id="getHandlerForSubResource">
    <request>
     <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
      style="header" name="HeaderKey"/>
    </request>
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
  </resource>
 </resource>
</resources>
</application>

com.sun.jersey.config.feature.DisableWADLプロパティにtrueまたはfalseを設定することで,WADLの発行の有無を選択できます。このプロパティは次の個所に指定します。

どちらも指定された場合,サーブレット初期化パラメタが優先されます。

WADLの発行の有無を次の表に示します。

表13-4 WADLの発行の有無

項番サーブレット初期化パラメタJAX-RSエンジンの動作
1com.sun.jersey.config.feature.DisableWADLtrueWADLを発行しません。
値の大文字と小文字を区別しません。
falseWADLを発行します。
値の大文字と小文字を区別しません。
trueまたはfalse以外の値共通定義ファイル(cjrconf.properties)で取得したプロパティの値が使用されて,WADLを発行します。なお,web.xmlで指定した値は無視されます。