第17章 JAX-WS エンドポイントの設定

概要

JAX-WS エンドポイントは、3 つの Spring 設定要素のいずれかを使用して設定されます。正しい要素は、設定しているエンドポイントのタイプと使用する機能によって異なります。コンシューマーの場合は、jaxws:client 要素を使用します。サービスプロバイダーの場合は、jaxws:endpoint 要素または jaxws:server 要素のいずれかを使用できます。

エンドポイントの定義に使用される情報は、通常、エンドポイントのコントラクトで定義されます。設定要素を使用して、コントラクトの情報を上書きすることができます。設定要素を使用して、コントラクトで提供されていない情報を提供することもできます。

WS-RM などの高度な機能をアクティブにするには、設定要素を使用する必要があります。これは、エンドポイントの設定要素に子要素を提供することによって行われます。Java ファーストのアプローチを使用して開発されたエンドポイントを処理する場合、エンドポイントのコントラクトとして機能する SEI には、使用するバインディングとトランスポートのタイプに関する情報が不足している可能性があることに注意してください。

17.1. サービスプロバイダーの設定

17.1.1. サービスプロバイダー設定の要素

Apache CXF には、サービスプロバイダーの設定に使用できる 2 つの要素があります。

2 つの要素の違いは、主にランタイムの内部にあります。jaxws:endpoint 要素は、サービスエンドポイントをサポートするために作成された org.apache.cxf.jaxws.EndpointImpl オブジェクトにプロパティーを挿入します。jaxws:server 要素は、エンドポイントをサポートするために作成された org.apache.cxf.jaxws.support.JaxWsServerFactoryBean オブジェクトにプロパティーをインジェクトします。EndpointImpl オブジェクトは、設定データを JaxWsServerFactoryBean オブジェクトに渡します。JaxWsServerFactoryBean オブジェクトは、実際のサービスオブジェクトを作成するために使用されます。どちらの設定要素もサービスエンドポイントを設定するため、好みの構文に基づいて選択できます。

17.1.2. jaxws:endpoint 要素の使用

概要

jaxws:endpoint 要素は、JAX-WS サービスプロバイダーを設定するためのデフォルトの要素です。その属性と子は、サービスプロバイダーをインスタンス化するために必要なすべての情報を指定します。属性の多くは、サービスのコントラクトの情報にマップされます。子は、インターセプターやその他の高度な機能を設定するために使用されます。

設定されているエンドポイントの特定

ランタイムが設定を適切なサービスプロバイダーに適用するには、ランタイムがそれを識別できる必要があります。サービスプロバイダーを識別するための基本的な手段は、エンドポイントを実装するクラスを指定することです。これは、jaxws:endpoint 要素の implementor 属性を使用して行われます。

異なるエンドポイントが共通の実装を共有する場合は、エンドポイントごとに異なる設定を提供することができます。設定で特定のエンドポイントを区別するには、次の 2 つの方法があります。

  • serviceName 属性と endpointName 属性との組み合わせ

    serviceName 属性は、サービスのエンドポイントを定義する wsdl:service 要素を指定します。endpointName 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素を指定します。どちらの属性も、ns:name の形式で QNames として指定されます。ns は要素の namespace で、name は要素の name 属性の値です。

    注記

    wsdl:service 要素に wsdl:port 要素が 1 つしかない場合は、endpointName 属性を省略できます。

  • name 属性

    name 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素の QName を指定します。QName は、{ns}localPart の形式で提供されます。nswsdl:port 要素の namespace で、localPartwsdl:port 要素の name 属性の値です。

属性

jaxws:endpoint 要素の属性は、エンドポイントの基本プロパティーを設定します。これらのプロパティーには、エンドポイントのアドレス、エンドポイントを実装するクラス、およびエンドポイントをホストする bus が含まれます。

表17.1「jaxws:endpoint 要素を使用して JAX-WS サービスプロバイダーを設定するための属性」 は、jaxws:endpoint 要素の属性について説明しています。

表17.1 jaxws:endpoint 要素を使用して JAX-WS サービスプロバイダーを設定するための属性

属性説明

id

他の設定要素がエンドポイントを参照するのに使用できる一意の識別子を指定します。

implementor

サービスを実装するクラスを指定します。実装クラスを設定する Spring Bean へのクラス名または ID 参照のいずれかを使用して、実装クラスを指定できます。このクラスはクラスパス上にある必要があります。

implementorClass

サービスを実装するクラスを指定します。この属性は、implementor 属性に指定された値が Spring AOP を使用してラップされる Bean への参照である場合に便利です。

address

HTTP エンドポイントのアドレスを指定します。この値は、サービスコントラクトで指定された値を上書きします。

wsdlLocation

エンドポイントの WSDL コントラクトの場所を指定します。WSDL コントラクトの場所は、サービスのデプロイ元のフォルダーを基準にしています。

endpointName

サービスの wsdl:port 要素の name 属性値を指定します。これは、ns:name 形式を使用して QName として指定されます。ここで、nswsdl:port 要素の namespace です。

serviceName

サービスの wsdl:service 要素の name 属性値を指定します。これは、ns:name 形式を使用して QName として指定されます。ここで、nswsdl:service 要素の namespace になります。

publish

サービスを自動的に公開するかどうかを指定します。これを false に設定すると、開発者は 31章サービスの公開 に記載されているようにエンドポイントを明示的にパブリッシュする必要があります。

bus

サービスエンドポイントの管理に使用されるバスを設定する Spring Bean の ID を指定します。これは、共通の機能セットを使用するように複数のエンドポイントを設定する場合に役立ちます。

bindingUri

サービスが使用するメッセージバインディングの ID を指定します。有効なバインディング ID のリストは、23章Apache CXF バインディング ID に提供されています。

name

サービスの wsdl:port 要素の文字列化した QName を指定します。これは、{ns}localPart 形式を使用して QName として指定されます。nswsdl:port 要素の namespace で、localPartwsdl:port 要素の name 属性の値です。

abstract

Bean が抽象 Bean であるかどうかを指定します。抽象 Bean は、具体的な Bean 定義の親として機能し、インスタンス化されません。デフォルトは false です。これを true に設定すると、Bean ファクトリーが Bean をインスタンス化しないように指示します。

depends-on

インスタンス化する前にエンドポイントがインスタンス化に依存する Bean のリストを指定します。

createdFromAPI

ユーザーが、Endpoint.publish() または Service.getPort() などの Apache CXF API を使用してその Bean を作成したことを指定します。

デフォルトは false です。

これを true に設定すると以下を行います。

  • .jaxws-endpoint を ID に追加して Bean の内部名を変更する
  • Bean を抽象化します

publishedEndpointUrl

生成された WSDL の address 要素に配置される URL。この値が指定されない場合、address 属性の値が使用されます。この属性は、パブリック URL がサービスがデプロイされている URL と同じでない場合に役立ちます。

表17.1「jaxws:endpoint 要素を使用して JAX-WS サービスプロバイダーを設定するための属性」 に一覧表示される属性の他に、複数の xmlns:shortName 属性を使用して endpointName および serviceName 属性によって使用される namespace を宣言する必要がある場合があります。

例17.1「シンプルな JAX-WS エンドポイント設定」 は、エンドポイントが公開されるアドレスを指定する JAX-WS エンドポイントの設定を示しています。この例では、他のすべての値にデフォルトを使用するか、実装で注釈に値が指定されていることを前提としています。

例17.1 シンプルな JAX-WS エンドポイント設定

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:endpoint id="example"
                  implementor="org.apache.cxf.example.DemoImpl"
                  address="http://localhost:8080/demo" />
</beans>

例17.2「サービス名を使用した JAX-WS エンドポイント設定」 は、コントラクトに 2 つのサービス定義が含まれている JAX-WS エンドポイントの設定を示しています。この場合、serviceName 属性を使用してインスタンス化するサービス定義を指定する必要があります。

例17.2 サービス名を使用した JAX-WS エンドポイント設定

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">

  <jaxws:endpoint id="example2"
                  implementor="org.apache.cxf.example.DemoImpl"
                  serviceName="samp:demoService2"
                  xmlns:samp="http://org.apache.cxf/wsdl/example" />

</beans>

xmlns:samp 属性は、WSDL service 要素が定義される namespace を指定します。

例17.3「HTTP/2 が有効になっている JAX-WS エンドポイント設定」 は、HTTP/2 が有効になっているアドレスを指定する JAX-WS エンドポイントの設定を示しています。

Apache CXF 用の HTTP/2 の設定

Apache Karaf でスタンドアロン Apache CXF Undertow トランスポート (http-undertow ) を使用する場合、HTTP/2 がサポートされます。HTTP/2 プロトコルを有効にするには、jaxws:endpoint 要素の address 属性を絶対 URL として設定し、org.apache.cxf.transports.http_undertow.EnableHttp2 プロパティーを true に設定する必要があります。

注記

この HTTP/2 実装は、プレーン HTTP または HTTPS を使用したサーバー側の HTTP/2 トランスポートのみをサポートします。

例17.3 HTTP/2 が有効になっている JAX-WS エンドポイント設定

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
  http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
  ...">

  <cxf:bus>
    <cxf:properties>
        <entry key="org.apache.cxf.transports.http_undertow.EnableHttp2" value="true"/>
    </cxf:properties>
  </cxf:bus>

  <jaxws:endpoint id="example3"
                implementor="org.apache.cxf.example.DemoImpl"
                address="http://localhost:8080/demo" />
  </jaxws:endpoint>

</beans>
注記

パフォーマンスを向上させるために、Red Hat は Apache Karaf でサーブレットトランスポート (pax-web-undertow) を使用することを推奨します。これにより、Web コンテナーの集中設定およびチューニングが可能になりますが、pax-web-undertow は HTTP/2 トランスポートプロトコルをサポートしません。

17.1.3. jaxws:server 要素の使用

概要

jaxws:server 要素は JAX-WS サービスプロバイダーを設定する要素です。org.apache.cxf.jaxws.support.JaxWsServerFactoryBean に設定情報を注入します。これは Apache CXF 固有のオブジェクトです。純粋な Spring アプローチを使用してサービスを構築している場合、サービスと対話するために Apache CXF 固有の API を使用する必要はありません。

jaxws:server 要素の属性および子は、サービスプロバイダーをインスタンス化するために必要なすべての情報を指定します。属性は、エンドポイントをインスタンス化するために必要な情報を指定します。子は、インターセプターやその他の高度な機能を設定するために使用されます。

設定されているエンドポイントの特定

ランタイムが設定を適切なサービスプロバイダーに適用するには、ランタイムがそれを識別できる必要があります。サービスプロバイダーを識別するための基本的な手段は、エンドポイントを実装するクラスを指定することです。これは、jaxws:server 要素の serviceBean 属性を使用して行います。

異なるエンドポイントが共通の実装を共有する場合は、エンドポイントごとに異なる設定を提供することができます。設定で特定のエンドポイントを区別するには、次の 2 つの方法があります。

  • serviceName 属性と endpointName 属性との組み合わせ

    serviceName 属性は、サービスのエンドポイントを定義する wsdl:service 要素を指定します。endpointName 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素を指定します。どちらの属性も、ns:name の形式で QNames として指定されます。ns は要素の namespace で、name は要素の name 属性の値です。

    注記

    wsdl:service 要素に wsdl:port 要素が 1 つしかない場合は、endpointName 属性を省略できます。

  • name 属性

    name 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素の QName を指定します。QName は、{ns}localPart の形式で提供されます。nswsdl:port 要素の namespace で、localPartwsdl:port 要素の name 属性の値です。

属性

jaxws:server 要素の属性は、エンドポイントの基本プロパティーを設定します。これらのプロパティーには、エンドポイントのアドレス、エンドポイントを実装するクラス、およびエンドポイントをホストする bus が含まれます。

表17.2「jaxws:server 要素を使用して JAX-WS サービスプロバイダーを設定するための属性」 は、jaxws:server 要素の属性を説明します。

表17.2 jaxws:server 要素を使用して JAX-WS サービスプロバイダーを設定するための属性

属性説明

id

他の設定要素がエンドポイントを参照するのに使用できる一意の識別子を指定します。

serviceBean

サービスを実装するクラスを指定します。実装クラスを設定する Spring Bean へのクラス名または ID 参照のいずれかを使用して、実装クラスを指定できます。このクラスはクラスパス上にある必要があります。

serviceClass

サービスを実装するクラスを指定します。この属性は、implementor 属性に指定された値が Spring AOP を使用してラップされる Bean への参照である場合に便利です。

address

HTTP エンドポイントのアドレスを指定します。この値は、サービスコントラクトで指定された値を上書きします。

wsdlLocation

エンドポイントの WSDL コントラクトの場所を指定します。WSDL コントラクトの場所は、サービスのデプロイ元のフォルダーを基準にしています。

endpointName

サービスの wsdl:port 要素の name 属性値を指定します。これは、ns:name 形式を使用して QName として指定されます。ここで、nswsdl:port 要素の namespace になります。

serviceName

サービスの wsdl:service 要素の name 属性値を指定します。これは、ns:name 形式を使用して QName として指定されます。ここで、nswsdl:service 要素の namespace になります。

publish

サービスを自動的に公開するかどうかを指定します。これを false に設定すると、開発者は 31章サービスの公開 に記載されているようにエンドポイントを明示的にパブリッシュする必要があります。

bus

サービスエンドポイントの管理に使用されるバスを設定する Spring Bean の ID を指定します。これは、共通の機能セットを使用するように複数のエンドポイントを設定する場合に役立ちます。

bindingId

サービスが使用するメッセージバインディングの ID を指定します。有効なバインディング ID のリストは、23章Apache CXF バインディング ID に提供されています。

name

サービスの wsdl:port 要素の文字列化した QName を指定します。これは、{ns}localPart 形式を使用して QName として指定されます。ここで、nswsdl:port 要素の namespace であり、localPartwsdl:port 要素の name 属性の値になります。

abstract

Bean が抽象 Bean であるかどうかを指定します。抽象 Bean は、具体的な Bean 定義の親として機能し、インスタンス化されません。デフォルトは false です。これを true に設定すると、Bean ファクトリーが Bean をインスタンス化しないように指示します。

depends-on

エンドポイントをインスタンス化する前に、エンドポイントがインスタンス化に依存する Bean のリストを指定します。

createdFromAPI

ユーザーが、Endpoint.publish() または Service.getPort() などの Apache CXF API を使用してその Bean を作成したことを指定します。

デフォルトは false です。

これを true に設定すると以下を行います。

  • .jaxws-endpoint を ID に追加して Bean の内部名を変更する
  • Bean を抽象化します

表17.2「jaxws:server 要素を使用して JAX-WS サービスプロバイダーを設定するための属性」 に一覧表示される属性の他に、複数の xmlns:shortName 属性を使用して endpointName および serviceName 属性によって使用される namespace を宣言する必要がある場合があります。

例17.4「シンプルな JAX-WS サーバー設定」 は、エンドポイントが公開されるアドレスを指定する JAX-WS エンドポイントの設定を示しています。

例17.4 シンプルな JAX-WS サーバー設定

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:server id="exampleServer"
                  serviceBean="org.apache.cxf.example.DemoImpl"
                  address="http://localhost:8080/demo" />
</beans>

17.1.4. サービスプロバイダーへの機能の追加

概要

jaxws:endpoint および jaxws:server 要素は、サービスプロバイダーをインスタンス化するために必要な基本的な設定情報を提供します。サービスプロバイダーに機能を追加したり、高度な設定を実行したりするには、設定に子要素を追加する必要があります。

子要素を使用すると、次のことができます。

要素

表17.3「JAX-WS サービスプロバイダーの設定に使用される要素」 では、jaxws:endpoint がサポートする子要素が説明されています。

表17.3 JAX-WS サービスプロバイダーの設定に使用される要素

要素説明

jaxws:handlers

メッセージを処理するための JAX-WS ハンドラー実装のリストを指定します。JAX-WS ハンドラーの実装の詳細は、43章ハンドラーの作成 を参照してください。

jaxws:inInterceptors

インバウンド要求を処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」 を参照してください。

jaxws:inFaultInterceptors

インバウンド障害メッセージを処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」 を参照してください。

jaxws:outInterceptors

アウトバウンド応答を処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」 を参照してください。

jaxws:outFaultInterceptors

アウトバウンド障害メッセージを処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」 を参照してください。

jaxws:binding

エンドポイントが使用するメッセージバインディングを設定する Bean を指定します。メッセージバインディングは、org.apache.cxf.binding.BindingFactory インターフェイスの実装を使用して設定されます。[a]

jaxws:dataBinding [b]

エンドポイントで使用されるデータバインディングを実装するクラスを指定します。これは、埋め込み Bean 定義を使用して指定されます。

jaxws:executor

サービスに使用される Java エグゼキュータを指定します。これは、埋め込み Bean 定義を使用して指定されます。

jaxws:features

Apache CXF の高度な機能を設定する Bean のリストを指定します。Bean 参照のリストまたは埋め込み Bean のリストのいずれかを提供できます。

jaxws:invoker

サービスが使用する org.apache.cxf.service.Invoker インターフェイスの実装を指定します。 [c]

jaxws:properties

エンドポイントに渡されるプロパティーの Spring マップを指定します。これらのプロパティーを使用して、MTOM サポートの有効化などの機能を制御できます。

jaxws:serviceFactory

サービスのインスタンス化に使用される JaxWsServiceFactoryBean オブジェクトを設定する Bean を指定します。

[a] SOAP バインディングは soap:soapBinding Bean を使用して設定されます。
[b] jaxws:endpoint 要素は jaxws:dataBinding 要素をサポートしません。
[c] Invoker 実装は、サービスの呼び出し方法を制御します。たとえば、各リクエストをサービス実装の新しいインスタンスで処理するかどうか、または呼び出し間で状態を保持するかどうかを制御します。

17.1.5. JAX-WS エンドポイントでスキーマ検証を有効にする

概要

schema-validation-enabled プロパティーを設定して、jaxws:endpoint 要素または jaxws: server 要素でスキーマ検証を有効にできます。スキーマ検証が有効になっている場合、クライアントとサーバー間で送信されるメッセージは、スキーマに準拠しているかどうかがチェックされます。スキーマ検証はパフォーマンスに大きな影響を与えるため、デフォルトではオフになっています。

JAX-WS エンドポイントでスキーマ検証を有効にするには、jaxws:endpoint 要素または jaxws:server 要素の jaxws:properties 子要素の schema-validation-enabled プロパティーを設定します。たとえば、jaxws:endpoint 要素でスキーマ検証を有効にするには、以下を実行します。

<jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort"
    wsdlLocation="wsdl/hello_world.wsdl"
    createdFromAPI="true">
    <jaxws:properties>
        <entry key="schema-validation-enabled" value="BOTH" />
    </jaxws:properties>
</jaxws:endpoint>

schema-validation-enabled プロパティーの許可される値の一覧は、「スキーマ検証タイプの値」 を参照してください。