Menu Close

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

概要

JAX-WS エンドポイントは、3 つの Spring 設定要素の 1 つを使用して設定されます。正しい要素は、設定するエンドポイントの型と、使用する機能によって異なります。コンシューマーの場合は 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 の形式で提供されます。ns は wsdl:port 要素の namespace で、localPart は wsdl: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 として指定されます。ここで、ns は wsdl:port 要素の namespace です。

serviceName

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

publish

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

bus

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

bindingUri

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

name

サービスの wsdl:port 要素の文字列化した QName を指定します。これは、{ns}localPart 形式を使用して QName として指定されます。ns は wsdl:port 要素の namespace で、localPart は wsdl: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 の設定

HTTP/2 は、Apache Karaf でスタンドアロンの Apache CXF Undertow トランスポート (http-undertow) を使用する場合サポートされます。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 の形式で提供されます。ns は wsdl:port 要素の namespace で、localPart は wsdl: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 として指定されます。ここで、ns は wsdl:port 要素の namespace です。

serviceName

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

publish

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

bus

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

bindingId

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

name

サービスの wsdl:port 要素の文字列化した QName を指定します。これは、{ns}localPart 形式を使用して QName として指定されます。ここで、ns は wsdl:port 要素の namespace であり、localPart は wsdl: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 Handler 実装のリストを指定します。JAX-WS Handler 実装の詳細は、「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 プロパティーで使用できる値のリストは、「スキーマ検証の型の値」を参照してください。