第18章 JAX-RS エンドポイントの設定

XML で JAX-RS サーバーエンドポイントを定義するには、少なくとも以下の項目を指定する必要があります。

以下の Blueprint XML の例は、(デフォルトの HTTP コンテナーにデプロイするように) 相対アドレス /customers を指定し、service.CustomerService リソースクラスによって実装される、JAX-RS エンドポイントを定義する方法を示しています。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
    xmlns:cxf="http://cxf.apache.org/blueprint/core"
    xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd
http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
">

    <cxf:bus>
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref component-id="serviceBean" />
        </jaxrs:serviceBeans>
     </jaxrs:server>

     <bean id="serviceBean" class="service.CustomerService"/>
</blueprint>

ブループリントで JAX-RS エンドポイントを定義するには、通常、少なくとも次の XML 名前空間が必要です。

以下の Spring XML の例は、相対アドレス /customers (デフォルトの HTTP コンテナーにデプロイされるように) を指定し、service.CustomerService リソースクラスによって実装される JAX-RS エンドポイントを定義する方法を示しています。

<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:jaxrs="http://cxf.apache.org/jaxrs"
      xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
         http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref bean="serviceBean"/>
        </jaxrs:serviceBeans>
     </jaxrs:server>

     <bean id="serviceBean" class="service.CustomerService"/>
</beans>

Spring で JAX-RS エンドポイントを定義するには、通常、少なくとも次の XML 名前空間が必要です。

(Spring only) JAX-RS ルートリソースクラスを明示的に指定する代わりに、Spring XML では自動検出を設定できます。これにより、特定の Java パッケージでリソースクラス (@Path によりアノテーションが付けられたクラス) が検索され、検出されたすべてのリソースクラスがエンドポイントに自動的に割り当てられます。この場合、jaxrs:server 要素に address 属性と basePackages 属性のみを指定する必要があります。

たとえば、a.b.c Java パッケージ下のすべての JAX-RS リソースクラスを使用する JAX-RS エンドポイントを定義するには、以下のように Spring XML でエンドポイントを定義できます。

<jaxrs:server address="/customers" basePackages="a.b.c"/>

自動検出メカニズムは、指定された Java パッケージで検出した JAX-RS プロバイダークラスも検出してエンドポイントにインストールします。

(Spring のみ) Spring XML では、bean 要素の scope 属性を設定することで、Bean のライフサイクルを制御できます。Spring では以下のスコープ値がサポートされます。

Spring スコープの詳細は、Bean スコープ に関する Spring フレームワークのドキュメントを参照してください。

jaxrs:serviceBeans 要素を使用して JAX-RS リソース Bean を指定すると、Spring スコープ が正しく機能しない ことに注意してください。この場合、リソース Bean で scope 属性を指定すると、scope 属性を効果的に無視されます。

Bean スコープを JAX-RS サーバーエンドポイント内で適切に機能させるには、サービスファクトリーによって提供される間接化のレベルが必要です。Bean スコープを設定する最も簡単な方法は、以下のように jaxrs:server 要素で beanNames 属性を使用してリソース Bean を指定することです。

<beans ... >
  <jaxrs:server id="customerService" address="/service1"
    beanNames="customerBean1 customerBean2"/>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>

前述の例では、customerBean1 と customerBean2 の 2 つのリソース Bean を設定します。beanNames 属性は、リソース Bean ID のスペース区切りリストとして指定されます。

最終的な柔軟性を高めるために、jaxrs:serviceFactories 要素を使用して JAX-RS サーバーエンドポイントを設定する際に、サービスファクトリーオブジェクトを 明示的 に定義することができます。このより冗長なアプローチには、デフォルトのサービスファクトリー実装をカスタム実装に置き換えることができるという利点があります。これにより、Bean のライフサイクルを最終的に制御できます。以下の例は、このアプローチを使用して、2 つのリソース Bean (customerBean1 と customerBean2) を設定する方法を示しています。

<beans ... >
  <jaxrs:server id="customerService" address="/service1">
    <jaxrs:serviceFactories>
      <ref bean="sfactory1" />
      <ref bean="sfactory2" />
    </jaxrs:serviceFactories>
  </jaxrs:server>

  <bean id="sfactory1" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean1"/>
  </bean>
  <bean id="sfactory2" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean2"/>
  </bean>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>

任意で、jaxrs:server 要素の docLocation 属性を使用して、WADL ドキュメントを JAX-RS サーバーエンドポイントに関連付けることができます。以下に例を示します。

<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
      <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
</jaxrs:server>

外部 XML スキーマがある場合、JAX-B 形式のメッセージコンテンツを記述するため、これらの外部スキーマを jaxrs:schemaLocations 要素を介して JAX-RS サーバーエンドポイントに関連付けることができます。

たとえば、サーバーエンドポイントを WADL ドキュメントに関連付けており、着信メッセージのスキーマ検証も有効にする場合は、次のように関連付けられた XML スキーマファイルを指定できます。

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/a.xsd</jaxrs:schemaLocation>
     <jaxrs:schemaLocation>classpath:/schemas/b.xsd</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

あるいは、特定のディレクトリーのスキーマファイル *.xsd をすべて含める場合は、以下のようにディレクトリー名を指定するだけです。

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

この方法でスキーマを指定すると、一般に、JAX-B スキーマへのアクセスを必要とするあらゆる種類の機能に役立ちます。

jaxrs:dataBinding 要素を使用して、リクエストおよびリプライメッセージのメッセージボディーをエンコードするデータバインディングを指定できます。たとえば、JAX-B データバインディングを指定するには、次のように JAX-RS エンドポイントを設定できます。

<jaxrs:server id="jaxbbook" address="/jaxb">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.jaxb.JAXBDataBinding"/>
  </jaxrs:dataBinding>
</jaxrs:server>>

または、Aegis データバインディングを指定するには、JAX-RS エンドポイントを次のように設定できます。

<jaxrs:server id="aegisbook" address="/aegis">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.aegis.databinding.AegisDatabinding">
      <property name="aegisContext">
        <bean class="org.apache.cxf.aegis.AegisContext">
          <property name="writeXsiTypes" value="true"/>
        </bean>
      </property>
    </bean>
  </jaxrs:dataBinding>
</jaxrs:server>

HTTP の代わりに JMS メッセージングライブラリーをトランスポートプロトコルとして使用するように JAX-RS を設定することができます。JMS 自体はトランスポートプロトコルでは ない ため、実際のメッセージングプロトコルは設定する特定の JMS 実装によって異なります。

たとえば、次の Spring XML の例は、JMS トランスポートプロトコルを使用するように JAX-RS サーバーエンドポイントを設定する方法を示しています。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jms="http://cxf.apache.org/transports/jms"
       xmlns:jaxrs="http://cxf.apache.org/jaxrs"
       xsi:schemaLocation="
http://cxf.apache.org/transports/jms http://cxf.apache.org/schemas/configuration/jms.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    <bean id="ConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:${testutil.ports.EmbeddedJMSBrokerLauncher}" />
    </bean>

    <jaxrs:server xmlns:s="http://books.com"
    	serviceName="s:BookService"
    	transportId= "http://cxf.apache.org/transports/jms"
    	address="jms:queue:test.jmstransport.text?replyToName=test.jmstransport.response">
        <jaxrs:serviceBeans>
            <bean class="org.apache.cxf.systest.jaxrs.JMSBookStore"/>
        </jaxrs:serviceBeans>
    </jaxrs:server>

</beans>

前の例について、次の点に注意してください。

JAX-RS サーバーエンドポイントは、ファイル接尾辞 (URL に表示される) を MIME コンテンツタイプヘッダーに自動的にマップし、言語接尾辞を言語タイプヘッダーにマップするように設定できます。たとえば、次の形式の HTTP リクエストについて考えてみます。

GET /resource.xml

以下のように、.xml 接尾辞を自動的にマッピングするように JAX-RS サーバーエンドポイントを設定できます。

<jaxrs:server id="customerService" address="/">
  <jaxrs:serviceBeans>
    <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
  </jaxrs:serviceBeans>
  <jaxrs:extensionMappings>
    <entry key="json" value="application/json"/>
    <entry key="xml" value="application/xml"/>
  </jaxrs:extensionMappings>
</jaxrs:server>

上記のサーバーエンドポイントが HTTP リクエストを受信すると、型 application/xml の新しいコンテンツ型ヘッダーを自動的に作成し、リソース URL から .xml 接尾辞を除去します。

言語マッピングについては、次の形式の HTTP リクエストを検討してください。

GET /resource.en

以下のように、.en 接尾辞を自動的にマッピングするように JAX-RS サーバーエンドポイントを設定できます。

<jaxrs:server id="customerService" address="/">
  <jaxrs:serviceBeans>
    <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
  </jaxrs:serviceBeans>
  <jaxrs:languageMappings>
     <entry key="en" value="en-gb"/>
  </jaxrs:languageMappings>
</jaxrs:server>

上記のサーバーエンドポイントが HTTP リクエストを受信すると、値が en-gb の新しい受け入れ言語ヘッダーを自動的に作成し、リソース URL から .en 接尾辞を除去します。

表18.1「JAX-RS サーバーエンドポイントの属性」jaxrs:server 要素で利用可能な属性を説明します。

表18.2「JAX-RS サーバーエンドポイントの子要素」に jaxrs:server 要素の子要素をまとめます。