3.13. Apache CXF の統合

JBoss EAP 上の JBossWS によって提供されるすべての JAX-WS 機能は、ほとんどの Apache CXF プロジェクトモジュールを含む JBossWS スタックの適切な統合によって提供されます。

Apache CXF はオープンソースサービスフレームワークです。JAX-WS を含むフロントエンドプログラミング API を使用してサービスを構築および開発でき、サービスは HTTP や JMS などのさまざまなトランスポート上で SOAP や XML/HTTP などのさまざまなプロトコルを通信します。

JBossWS と Apache CXF 間の統合レイヤーは主に以下の目的で使用されます。

  • JAX-WS などの標準の Web サービス API を JBoss EAP で使用可能。これは、ユーザーがこれに対応する必要なく、Apache CXF を内部的に活用します。
  • JBoss EAP 上で WS-* を含む Apache CXF の高度な機能を使用できるようにし、これらのコンテナーでの実行に必要な統合手順をユーザーが処理、設定、考慮したりする必要性を省きます。

これらの目的をサポートするため、Apache CXF を使用した JBossWS 統合は JBossWS エンドポイントデプロイメントメカニズムをサポートし、Apache CXF 上で多数の内部カスタマイズが提供されます。

Apache CXF アーキテクチャーの詳細は、Apache CXF 公式ドキュメント を参照してください。

3.13.1. サーバー側統合のカスタマイズ

JBossWS サーバー側の Apache CXF との統合では、提供された Web サービスデプロイメントに適切な Apache CXF 構造を内部で作成します。デプロイメントに複数のエンドポイントが含まれる場合、それらはすべて同じ Apache CXF バス内に存在し、他のデプロイメントのバスインスタンスとは分離されます。

JBossWS はサーバー側で Apache CXF 設定オプションのほとんどに対して適切なデフォルト値を設定しますが、ユーザーはデプロイメント用に作成される Bus インスタンスを微調整する必要があるかもしれません。jboss-webservices.xml 記述子はデプロイメントレベルのカスタマイズに使用できます。

3.13.1.1. デプロイメント記述子プロパティー

jboss-webservices.xml 記述子は、プロパティー値を提供するために使用できます。

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
  ...
  <property>
    <name>...</name>
    <value>...</value>
  </property>
  ...
</webservices>

Apache CXF との JBossWS 統合には、Apache CXF 内部を制御するために許可されるプロパティー名のセットが含まれています。

3.13.1.2. WorkQueue の設定

Apache CXF は、@Oneway 要求処理などの一部の操作を処理する WorkQueue インスタンスを使用します。WorkQueueManager は拡張として Bus にインストールされ、キューを追加または削除したり、既存のキューを制御したりできます。

サーバー側では、jboss-webservices.xmlcxf.queue.<queue-name>.* プロパティーを使用してキューを指定できます。たとえば、cxf.queue.default.maxQueueSize プロパティーを使用して、デフォルトの WorkQueue の最大キューサイズを設定できます。デプロイメント時に、JBossWS 統合は AutomaticWorkQueueImpl の新しいインスタンスを現在設定されている WorkQueueManager に追加できます。以下のプロパティーは、AutomaticWorkQueueImpl constructor パラメーターを埋めるために使用されます。

表3.5 AutomaticWorkQueueImpl コンストラクトープロパティー

プロパティーデフォルト値

cxf.queue.<queue-name>.maxQueueSize

256

cxf.queue.<queue-name>.initialThreads

0

cxf.queue.<queue-name>.highWaterMark

25

cxf.queue.<queue-name>.lowWaterMark

5

cxf.queue.<queue-name>.dequeueTimeout

120000

3.13.1.3. ポリシー代替セレクター

Apache CXF ポリシーエンジンは、ポリシーの代替に対応するさまざまなストラテジーをサポートします。JBossWS 統合のデフォルトは MaximalAlternativeSelector ですが、jboss-webservices.xml ファイルで cxf.policy.alternativeSelector プロパティーを使用して異なるセレクター実装を設定することもできます。

3.13.1.4. MBean 管理

Apache CXF を使用すると、JBoss EAP MBean サーバーにインストールされた MBean オブジェクトを管理できます。この機能は、jboss-webservices.xml ファイルの cxf.management.enabled プロパティーを使用してデプロイメントベースで有効にできます。cxf.management.installResponseTimeInterceptors プロパティーを使用して、CXF 応答時間インターセプターのインストールを制御することもできます。これらのインターセプターは、MBean 管理を有効にするとデフォルトで追加されますが、場合によっては必要ない可能性があります。

例: jboss-webservices.xml ファイルの MBean 管理

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
  <property>
    <name>cxf.management.enabled</name>
    <value>true</value>
  </property>
  <property>
    <name>cxf.management.installResponseTimeInterceptors</name>
    <value>false</value>
  </property>
</webservices>

3.13.1.5. スキーマの検証

Apache CXF には、クライアントとサーバーの両方での SOAP メッセージの受信および送信を検証する機能が含まれます。検証は、サービスプロキシー (クライアント側) のビルドに使用されるエンドポイントの WSDL コントラクト (サーバー側) または WSDL コントラクトの関連するスキーマに対して実行されます。

スキーマの検証は、以下のいずれかの方法で有効にできます。

  • JBoss EAP サーバー設定の最適化

    たとえば、以下の管理 CLI コマンドは、デフォルトの Standard-Endpoint-Config エンドポイント設定のスキーマ検証を有効にします。

    /subsystem=webservices/endpoint-config=Standard-Endpoint-Config/property=schema-validation-enabled:add(value=true)
  • 事前定義されたクライアントまたはエンドポイント設定ファイルです。

    参照された設定ファイルで schema-validation-enabled プロパティーを true に設定すると、事前に設定されている設定 に、コンテナー内で実行しているエンドポイントまたはクライアントを関連付けることができます。

  • クライアント側でプログラムで

    クライアント側では、スキーマ検証をプログラムで有効にできます。例を以下に示します。

    ((BindingProvider)proxy).getRequestContext().put("schema-validation-enabled", true);
  • サーバー側で @org.apache.cxf.annotations.SchemaValidation アノテーションを使用します。

    サーバー側では、@org.apache.cxf.annotations.SchemaValidation アノテーションを使用できます。例を以下に示します。

    import javax.jws.WebService;
    import org.apache.cxf.annotations.SchemaValidation;
    
    @WebService(...)
    @SchemaValidation
    public class ValidatingHelloImpl implements Hello {
       ...
    }

3.13.1.6. Apache CXF インターセプター

jboss-webservices.xml 記述子 では、cxf.interceptors.in および cxf.interceptors.out プロパティーを指定できます。これらのプロパティーにより、宣言しているインターセプターを、デプロイメントを提供するために作成された Bus インスタンスに割り当てることができます。

例: jboss-webservices.xml ファイル

<?xml version="1.1" encoding="UTF-8"?>
<webservices
  xmlns="http://www.jboss.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">

  <property>
    <name>cxf.interceptors.in</name>
    <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusInterceptor</value>
  </property>
  <property>
    <name>cxf.interceptors.out</name>
    <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusCounterInterceptor</value>
  </property>
</webservices>

以下の方法のいずれかを使用してインターセプターを宣言できます。

  • エンドポイントクラスのアノテーションの使用 (@org.apache.cxf.interceptor.InInterceptor または @org.apache.cxf.interceptor.OutInterceptor)。
  • org.apache.cxf.interceptor.InterceptorProvider インターフェイスを使用したクライアント側での直接 API 使用。
  • JBossWS 記述子の使用方法。

JBoss EAP では Spring 統合がサポートされなくなったため、JBossWS 統合では、際のクライアントまたはエンドポイントコードの変更を不要にするために jaxws-endpoint-config.xml 記述子ファイルを使用します。cxf.interceptors.in および cxf.interceptors.out プロパティーのインターセプタークラス名のリストを指定して、事前定義されたクライアントおよびエンドポイント設定内でインターセプターを宣言します。

例: jaxws-endpoint-config.xml ファイル

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

注記

指定された各インターセプタークラスの新規インスタンスは、設定が割り当てられるクライアントまたはエンドポイントに追加されます。インターセプタークラスには no-argument コンストラクターが必要です。

3.13.1.7. Apache CXF の機能

jboss-webservices.xml 記述子を使用すると、cxf.features プロパティーを指定できます。このプロパティーを使用すると、デプロイメントを提供するために作成された Bus インスタンスに属するエンドポイントに機能を宣言できます。

例: jboss-webservices.xml ファイル

<?xml version="1.1" encoding="UTF-8"?>
<webservices
  xmlns="http://www.jboss.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">

  <property>
    <name>cxf.features</name>
    <value>org.apache.cxf.feature.FastInfosetFeature</value>
  </property>
</webservices>

以下の方法のいずれかを使用して機能を宣言できます。

  • エンドポイントクラスでのアノテーション使用 (例: @org.apache.cxf.feature.Features)
  • org.apache.cxf.feature.AbstractFeature クラスの拡張により、クライアント側で API の直接使用。
  • JBossWS 記述子の使用方法。

JBoss EAP では Spring 統合がサポートされなくなったため、JBossWS 統合は追加の記述子 (jaxws-endpoint-config.xml ファイルベースのアプローチ) を追加して、実際のクライアントまたはエンドポイントコードへの変更を回避します。cxf.features プロパティーの機能クラス名のリストを指定して、事前定義のクライアントおよびエンドポイント設定内で機能を宣言できます。

例: jaxws-endpoint-config.xml ファイル

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

注記

指定された各機能クラスの新規インスタンスは、設定が割り当てられるクライアントまたはエンドポイントに追加されます。機能クラスには no-argument コンストラクターが必要です。

3.13.1.8. プロパティー駆動 Bean の作成

Apache CXF Interceptors および Apache CXF Features セクションでは、クライアントまたはエンドポイントの事前定義設定または jboss-webservices.xml 記述子でプロパティーを使用して CXF インターセプターおよび機能を宣言する方法を説明します。指定された feature または interceptor クラス名のみを取得することにより、コンテナーはクラスデフォルトコンストラクターを使用して bean インスタンスを作成しようとします。これは、vanilla CXF クラスのカスタム拡張機能が提供されない限り、機能またはインターセプター設定の制限を設定します。ただし、デフォルトのコンストラクター設定プロパティーは、最終的にスーパーコンストラクターを使用する前に設定されます。

この問題に対処するために、JBossWS 統合には、プロパティーからビルドする際に単純な bean 階層を設定するメカニズムが含まれています。プロパティーには bean 参照値を持たせることができます。これは、## で始まる文字列です。プロパティー参照キーは、bean クラス名と各属性の値を指定するために使用されます。

たとえば、以下のプロパティーを使用すると、スタックは機能インスタンスをインストールします。

キー

cxf.features

##foo, ##bar

##foo

org.jboss.Foo

##foo.par

34

##bar

org.jboss.Bar

##bar.color

blue

以下のコードでは、同じ結果を作成できます。

import org.Bar;
import org.Foo;
...
Foo foo = new Foo();
foo.setPar(34);
Bar bar = new Bar();
bar.setColor("blue");

このメカニズムは、クラスが適切な getter() および setter() メソッドを持つ有効な Bean であることを前提としています。値オブジェクトは、クラス定義を検査して正しいプリミティブ型にキャストされます。ネストされた Bean を設定することもできます。