3.5. クライアントおよびエンドポイント設定の割り当て

クライアントおよびエンドポイント設定は以下の方法で割り当てることができます。

  • クライアントに対するアノテーション、エンドポイント、または API プログラムによる使用による明示的な割り当て。
  • デフォルト記述子からの設定の自動割り当て。
  • コンテナーからの設定の自動割り当て。

3.5.1. 明示的な設定の割り当て

明示的な設定割り当ては、指定の設定に従ってセットアップされる必要のあるエンドポイントまたはクライアントを開発者が事前に認識するためのものです。この設定は、アプリケーションデプロイメントに含まれる記述子か、webservices サブシステムに含まれます。

3.5.1.1. 設定デプロイメント記述子

JAX-WS クライアントおよびエンドポイント実装を含むことができる Java EE アーカイブには、事前定義のクライアントおよびエンドポイント設定宣言が含まれる可能性があります。すべてのエンドポイントまたは特定のアーカイブのクライアント設定定義は、単一のデプロイメント記述子ファイルに提供する必要があります。これは、EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd にあるスキーマの実装である必要があります。デプロイメント記述子ファイルには、多くのエンドポイントまたはクライアント設定を定義できます。各設定には、アプリケーションがデプロイされるサーバー内で一意の名前が必要です。設定名は、アプリケーション外のエンドポイントまたはクライアント実装で参照することはできません。

例: 2 つのエンドポイント設定を持つ記述子

<?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.jbws3282.Endpoint4Impl</config-name>
    <pre-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Log Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.LogHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </pre-handler-chains>
    <post-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Routing Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.RoutingHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </post-handler-chains>
  </endpoint-config>
  <endpoint-config>
    <config-name>EP6-config</config-name>
    <post-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Authorization Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </post-handler-chains>
  </endpoint-config>
</jaxws-config>

同様に、クライアント設定は記述子に指定できます。これは前述のスキーマを実装しています。

<?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">
  <client-config>
    <config-name>Custom Client Config</config-name>
    <pre-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Routing Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class>
        </javaee:handler>
        <javaee:handler>
          <javaee:handler-name>Custom Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.CustomHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </pre-handler-chains>
  </client-config>
  <client-config>
    <config-name>Another Client Config</config-name>
    <post-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Routing Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </post-handler-chains>
  </client-config>
</jaxws-config>

3.5.1.2. アプリケーションサーバー設定

JBoss EAP では、webservices サブシステムで JBossWS クライアントおよびサーバーの事前定義設定を宣言できます。そのため、サーバー全体のハンドラーを宣言して、特定の設定に割り当てられた各エンドポイントまたはクライアントのチェーンに追加することができます。

標準設定

同じ JBoss EAP インスタンスおよびエンドポイントで実行されているクライアントには、デフォルトで標準設定が割り当てられます。異なる設定が設定されていない限り、デフォルトが使用されます。これにより、管理者はクライアントおよびエンドポイント設定のデフォルトのハンドラーチェーンを調整することができます。webservices サブシステムで使用されるデフォルトのクライアントおよびエンドポイント設定の名前は、Standard-Client-Config および Standard-Endpoint-Config です。

ハンドラーのクラスロード

サーバー全体のハンドラーを設定する場合、ハンドラークラスは各 ws デプロイメントクラスローダーで利用可能である必要があります。そのため、特定の事前に定義された設定を使用するデプロイメントで適切なモジュール依存関係を指定する必要がある場合があります。適切なモジュール依存関係がデプロイメントで指定されるようにする方法として、org.jboss.ws.spi などのデプロイメントに対する依存関係として自動的に設定されるいずれかのモジュールのハンドラークラスを含むモジュールに依存関係を追加します。

設定例:

例: デフォルトのサブシステム設定

<subsystem xmlns="urn:jboss:domain:webservices:2.0">
    <!-- ... -->
    <endpoint-config name="Standard-Endpoint-Config"/>
    <endpoint-config name="Recording-Endpoint-Config">
        <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
            <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/>
        </pre-handler-chain>
    </endpoint-config>
    <client-config name="Standard-Client-Config"/>
</subsystem>

デプロイメント固有の ws-security エンドポイントセットアップの設定ファイル:

<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 WS-Security Endpoint</config-name>
    <property>
      <property-name>ws-security.signature.properties</property-name>
      <property-value>bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.properties</property-name>
      <property-value>bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.signature.username</property-name>
      <property-value>bob</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.username</property-name>
      <property-value>alice</property-value>
    </property>
    <property>
      <property-name>ws-security.callback-handler</property-name>
      <property-value>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

JBoss EAP のデフォルト設定は以下で SOAP メッセージの schema-validation にデフォルト設定変更されました。

<subsystem xmlns="urn:jboss:domain:webservices:2.0">
    <!-- ... -->
    <endpoint-config name="Standard-Endpoint-Config">
        <property name="schema-validation-enabled" value="true"/>
    </endpoint-config>
    <!-- ... -->
    <client-config name="Standard-Client-Config">
        <property name="schema-validation-enabled" value="true"/>
    </client-config>
</subsystem>

3.5.1.3. EndpointConfig アノテーション

任意のアプリケーションで設定が利用可能になると org.jboss.ws.api.annotation.EndpointConfig アノテーションを使用してエンドポイント設定を JAX-WS エンドポイント実装に割り当てます。webservices サブシステムに定義された設定を割り当てる場合は、設定名のみを指定する必要があります。アプリケーションに定義されている設定を割り当てる場合は、デプロイメント記述子への相対パスと設定名を指定する必要があります。

例: EndpointConfig アノテーション

@EndpointConfig(configFile = "WEB-INF/my-endpoint-config.xml", configName = "Custom WS-Security Endpoint")
public class ServiceImpl implements ServiceIface {
   public String sayHello() {
      return "Secure Hello World!";
   }
}

3.5.1.4. JAX-WS 機能

org.jboss.ws.api.configuration.ClientConfigFeature を使用することで JBossWS が提供する JAX-WS Feature 拡張の設定を行うこともできます。

import org.jboss.ws.api.configuration.ClientConfigFeature;

Service service = Service.create(wsdlURL, serviceName);

Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"));
port.echo("Kermit");

また、trueClientConfigFeature コンストラクターに渡すことで、指定された設定からプロパティーを設定することもできます。

Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"), true);

JBossWS は、現在のスレッドコンテキストクラスローダーを使用してリソースとして解決した後、指定された設定ファイルを解析します。EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd スキーマは記述子の内容を定義し、jbossws-spi アーティファクトに含まれます。

設定ファイルの null を渡すと、利用可能な場合に、現在のコンテナー設定から設定が読み込まれます。

Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature(null, "Container Custom Client Config"));

3.5.1.5. API での明示的なセットアップ

または、JBossWS API にはクライアントのビルド時に設定の割り当てに使用できるファシリティークラスが含まれています。

ハンドラー

JAX-WS ハンドラーは、以下のようにクライアント設定から読み込まれます。

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);
BindingProvider bp = (BindingProvider)port;

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config");
port.echo("Kermit");

ClientConfigUtil ユーティリティークラスを使用してハンドラーを設定することもできます。

ClientConfigUtil.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config");

デフォルトの ClientConfigurer 実装は、現在のスレッドコンテキストクラスローダーを使用してリソースとして解決した後、指定された設定ファイルを解析します。EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd スキーマは記述子の内容を定義し、jbossws-spi アーティファクトに含まれます。

設定ファイルの null を渡すと、利用可能な場合に、現在のコンテナー設定から設定が読み込まれます。

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, null, "Container Custom Client Config");
プロパティー

同様に、プロパティーは以下のようにクライアント設定から読み込まれます。

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);

ClientConfigUtil.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config");
port.echo("Kermit");

ClientConfigUtil ユーティリティークラスを使用してプロパティーを設定することもできます。

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config");

デフォルトの ClientConfigurer 実装は、現在のスレッドコンテキストクラスローダーを使用してリソースとして解決した後、指定された設定ファイルを解析します。EAP_HOME/docs/schema/jbossws-jaxws-config_4_0.xsd スキーマは記述子の内容を定義し、jbossws-spi アーティファクトに含まれます。

設定ファイルの null を渡すと、利用可能な場合に、現在のコンテナー設定から設定が読み込まれます。

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, null, "Container Custom Client Config");

3.5.2. デフォルト記述子からの自動設定

アプリケーション開発者は、クライアントおよびエンドポイントの実装に使用する必要がある設定を認識していない場合があります。その他の場合は、コンパイルタイム依存関係であるため、JBossWS API の明示的な使用が許可されない可能性があります。このようなシナリオに対応するため、JBossWS ではデフォルトのクライアント、jaxws-client-config.xml、およびエンドポイント、jaxws-endpoint-config.xml、記述子をルートディレクトリー内のアプリケーションに含めることができます。これらは、設定ファイル名が指定されていない場合に設定を取得するために解析されます。

<config-file>WEB-INF/jaxws-endpoint-config.xml</config-file>

設定名が指定されていない場合、JBossWS は以下のようにという名前の設定を自動的に検索します。

  • JAX-WS エンドポイントの場合、エンドポイント実装クラスの完全修飾名 (FQN)。
  • JAX-WS クライアントの場合、サービスエンドポイントインターフェイスの FQN。

Dispatch クライアントの自動設定名は選択されません。

たとえば、事前設定されていないエンドポイント実装クラス org.foo.bar.EndpointImpl により、JBossWS はアプリケーションデプロイメントのルートで jaxws-endpoint-config.xml 記述子内で org.foo.bar.EndpointImpl という名前の設定を検索します。同様に、クライアント側では、org.foo.bar.Endpoint インターフェイスを実装するクライアントプロキシーには、jaxws-client-config.xml 記述子の org.foo.bar.Endpoint という名前の設定からセットアップ読み取りが行われます。

3.5.3. コンテナーからの自動設定割り当て

JBossWS は、明示的な設定が指定されておらず、デフォルトの記述子が利用できないか、関連する設定を含まない場合に、コンテナーから事前定義された設定を取得するようフォールバックします。この動作により、コンテナーはデプロイされたアプリケーションから独立して管理できるため、JAX-WS クライアントおよびエンドポイントの設定に対する追加の制御が管理者に付与されます。

JBossWS は明示的に名前が付けられた設定の webservices サブシステムにアクセスします。使用されるデフォルト設定名は以下のようになります。

  • JAX-WS エンドポイントの場合、エンドポイント実装クラスの完全修飾名。
  • JAX-WS クライアントの場合は、サービスエンドポイントインターフェイスの完全修飾名。

Dispatch クライアントは自動的には設定されません。上記で計算した名前を使用して設定が見つからない場合、Standard-Client-Config および Standard-Endpoint-Config 設定がクライアントとエンドポイントにそれぞれ使用されます。