第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>

Blueprint で JAX-RS エンドポイントを定義するには、通常、少なくとも以下の XML namespace が必要です。

以下の Spring XML の例は、(デフォルトの HTTP コンテナーにデプロイするように) 相対アドレス /customers を指定し、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 namespace が必要です。

(Spring のみ) 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 のスペース区切りリストとして指定されます。

JAX-RS サーバーエンドポイントを設定する際に最高の柔軟性を確保するために、jaxrs:serviceFactories 要素を使用してサービスファクトリーオブジェクトを 明示的に 定義するオプションがあります。このより詳細なアプローチには、デフォルトのサービスファクトリーの実装をカスタム実装に置き換えることができるため、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>

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

ファイルサフィックス (URL に表示される) を MIME コンテンツ型ヘッダーに、言語サフィックスを言語型ヘッダーに、それぞれ自動的にマッピングするように JAX-RS サーバーエンドポイントを設定することができます。たとえば、以下の形式の 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 要素の子要素をまとめます。