Apache CXF 開発ガイド

Red Hat Fuse 7.9

Apache CXF Web サービスを使用したアプリケーションの開発

概要

Apache CXF を使用して Web サービスを開発するためのガイド

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、CTO である Chris Wright のメッセージ をご覧ください。

パート I. WSDL コントラクトの作成

ここでは、WSDL を使用して Web サービスインターフェースを定義する方法を説明します。

第1章 WSDL コントラクトの概要

概要

WSDL ドキュメントは、Web Service Description Language と、多数の使用可能な拡張機能を使用してサービスを定義します。ドキュメントには、論理部分と具体的な部分があります。コントラクトの抽象化部分は、不要なデータ型やメッセージの実装に関してサービスを定義します。本書の具体的な部分は、サービスを実装するエンドポイントが外部ユーザーに対話する方法を定義します。

サービス設計の推奨方法は、コードを書き込む前に WSDL および XML スキーマでサービスを定義することが推奨されます。WSDL ドキュメントの編集時に、ドキュメントが有効であることと正しいことを確認する必要があります。そのためには、WSDL を理解している必要があります。標準は、W3C の Web サイトである www.w3.org にあります。

1.1. WSDL ドキュメントの構造

概要

WSDL ドキュメントは、ルート definition 要素に含まれる要素のコレクションを指します。これらの要素は、サービスや、そのサービスにアクセスしたエンドポイントを実装する方法を記述します。

WSDL ドキュメントには、2 つの異なる部分があります。

  • 実装に中立的な言葉でサービスを定義する論理部分
  • サービスを実装するエンドポイントがネットワーク上で公開される方法を定義する具体的な部分

論理部分

WSDL ドキュメントの論理部分には、typesmessage、および portType 要素が含まれます。サービスのインターフェースと、サービスによって交換されるメッセージを記述します。types 要素内では、メッセージを構成するデータ構造を定義する XML スキーマが使用されます。サービスで使用されるメッセージの構造を定義するために、多くの message 要素が使用されます。portType 要素には、サービスによって公開される操作によって送信されるメッセージを定義する 1 つ以上の operation 要素が含まれます。

具体的な部分

WSDL ドキュメントの具体的な部分には、binding および service 要素が含まれています。サービスを実装するエンドポイントが外部環境に接続する方法を記述します。binding 要素は、message 要素によって記述されるデータユニットが、SOAP などの具体的なオンザワイヤデータフォーマットにどのようにマッピングされるかを記述します。service 要素には、サービスの実装エンドポイントを定義する 1 つ以上の port 要素が含まれます。

1.2. WSDL 要素

WSDL ドキュメントは、以下の要素で構成されています。

  • definitions - WSDL ドキュメントのルート要素。この要素の属性は、WSDL ドキュメントの名前、ドキュメントのターゲット namespace、および WSDL ドキュメントで参照される namespace の短縮定義を指定します。
  • types - サービスで使用されるメッセージのビルディングブロックを形成するデータユニットの XML スキーマ定義。データ型の定義に関する情報は、2章論理データユニットの定義 を参照してください。
  • message - サービス操作の呼び出し中に交換されるメッセージの説明。これらの要素は、サービスを構成する操作の引数を定義します。メッセージの定義に関する詳細は、3章サービスで使用される論理メッセージの定義 を参照してください。
  • portType - サービスの論理インターフェースを記述する operation 要素のコレクション。ポート型の定義に関する詳細は、4章論理インターフェースの定義 を参照してください。
  • operation - サービスによって実行されるアクションの説明。操作は、操作が呼び出される際に 2 つのエンドポイント間で渡されるメッセージによって定義されます。操作の定義に関する情報は、「操作」 を参照してください。
  • binding - エンドポイントの具体的なデータ形式の仕様。binding 要素は、抽象メッセージがエンドポイントによって使用される具体的なデータフォーマットにマップされる方法を定義します。この要素は、パラメーター順序や戻り値などの詳細が指定される場所です。
  • service - 関連する port 要素のコレクション。これらの要素は、エンドポイント定義を整理するためのリポジトリーです。
  • port - バインディングおよび物理アドレスによって定義されるエンドポイント。これらの要素は、トランスポート詳細の定義と組み合わされた抽象定義をすべてまとめ、サービスが公開される物理エンドポイントを定義します。

1.3. コントラクトの設計

サービスの WSDL コントラクトを設計するには、以下の手順を実行する必要があります。

  1. サービスによって使用されるデータ型の定義します。
  2. サービスによって使用されるメッセージを定義します。
  3. サービスのインターフェースを定義します。
  4. 各インターフェースによって使用されるメッセージと、ネットワーク上のデータの具体表現との間のバインディングを定義します。
  5. 各サービスのトランスポートの詳細を定義します。

第2章 論理データユニットの定義

概要

WSDL コントラクトでサービスを記述する場合、複合データ型は XML スキーマを使用して論理ユニットとして定義されます。

2.1. 論理データユニットの概要

サービスを定義する際に、最初に考慮する必要があるのは、公開された操作のパラメーターとして使用されるデータの表現方法です。固定データ構造を使用するプログラミング言語で書かれたアプリケーションとは異なり、サービスは任意の数のアプリケーションで使用できる論理ユニットでそのデータを定義する必要があります。これには 2 つのステップが含まれます。

  1. サービスの物理実装によって使用されるデータ型にマッピング可能なデータを論理ユニットに分割します。
  2. エンドポイント間で渡されるメッセージに論理ユニットを組み合わせて、操作を実行します。

本章では、最初のステップについて説明します。3章サービスで使用される論理メッセージの定義 では、2 番目のステップについて説明します。

2.2. データの論理データユニットへのマッピング

概要

サービスを実装するために使用されるインターフェースは、操作パラメーターを表すデータを XML ドキュメントとして定義します。すでに実装されているサービスのインターフェースを定義する場合は、実装した操作のデータ型を、メッセージにアセンブル可能な XML 要素に変換する必要があります。ゼロから作業を行う場合は、メッセージを構築するビルディングブロックを判断し、実装の観点から意味をなすようにします。

サービスデータユニットの定義に使用できる型システム

WSDL 仕様に従うと、任意の型システムを使用して、WSDL コントラクトでデータ型を定義できます。ただし、W3C 仕様では、XML スキーマが WSDL ドキュメントの推奨される標準的な型システムであると述べられています。そのため、XML スキーマは Apache CXF の固有型システムです。

型システムとしての XML スキーマ

XMLスキーマは、XML 文書がどのように構造化されるかを定義するために使用されます。これは、ドキュメントを構成する要素を定義して行います。これらの要素は、xsd:int などのネイティブ XML スキーマ型や、ユーザーが定義した型を使用できます。ユーザー定義型は、XML 要素の組み合わせを使用して構築されるか、または既存の型を制限することによって定義されます。型定義と要素定義を組み合わせることで、複合データを含むことができる複合 XML ドキュメントを作成できます。

WSDL で使用されると、サービスとの対話に使用されるデータを保持する XML ドキュメントの構造を定義します。サービスで使用するデータユニットを定義する際に、メッセージ部分の構造を指定するタイプとして定義できます。また、データユニットは、メッセージの一部を構成する要素として定義することも可能です。

データユニットを作成する際の注意点

サービスの実装時に、想定する型に直接マップする論理データユニットを作成することを検討してください。このアプローチは機能し、RPC 形式のアプリケーションのビルドモデルに密接に従っていますが、サービス指向のアーキテクチャーの一部を構築するには必ずしも理想的なわけではありません。

Web Services Interoperability Organization の WS-I 基本プロファイルは、データユニットを定義するガイドラインを提供し、http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html#WSDLTYPES からアクセスできます。さらに、W3C は、WSDL ドキュメントのデータ型を表すために XML スキーマを使用する以下のガイドラインも提供します。

  • 属性ではなく要素を使用します。
  • プロトコル固有の型はベース型として使用しません。

2.3. コントラクトへのデータユニットの追加

概要

WSDL コントラクトの作成方法の選択に応じて、新しいデータ定義の作成には、さまざまな知識が必要です。Apache CXF GUI ツールは、XML スキーマを使用してデータ型を記述するための支援を提供します。他の XML エディターは異なるレベルのサポートを提供します。選択したエディターに関係なく、結果として生じるコントラクトの内容を把握しておくと良いでしょう。

手順

WSDL コントラクトで使用されるデータを定義するには、以下の手順を行います。

  1. コントラクトで説明しているインターフェースで使用されるすべてのデータユニットを決定します。
  2. コントラクトに types 要素を作成します。
  3. 例2.1「WSDL コントラクトのスキーマエントリー」 のように、type 要素の子として schema 要素を作成します。

    targetNamespace 属性は、新しいデータ型が定義される namespace を指定します。ベストプラクティスでは、ターゲット namespace へのアクセスを提供する namespace も定義します。残りのエントリーは変更しないでください。

    例2.1 WSDL コントラクトのスキーマエントリー

    <schema targetNamespace="http://schemas.iona.com/bank.idl"
            xmlns="http://www.w3.org/2001/XMLSchema"
            xmlns:xsd1="http://schemas.iona.com/bank.idl"
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  4. 要素のコレクションである複合型ごとに、complexType 要素を使用してデータ型を定義します。「データ構造の定義」 を参照してください。
  5. 配列ごとに、complexType 要素を使用してデータ型を定義します。「配列の定義」 を参照してください。
  6. 単純型から派生する複合型ごとに、simpleType 要素を使用してデータ型を定義します。「制限による型の定義」 を参照してください。
  7. 列挙型ごとに、simpleType 要素を使用してデータ型を定義します。「列挙型の定義」 を参照してください。
  8. 要素ごとに、element 要素を使用して定義します。「要素の定義」 を参照してください。

2.4. XML スキーマの単純型

概要

メッセージ部分が単純型になる場合は、その型定義を作成する必要はありません。ただし、コントラクトで定義されたインターフェースが使用する複合型は、単純型を使用して定義されます。

単純型の入力

XML スキーマの単純型は、主にコントラクトの types セクションで使用される element 要素に配置されます。これらの要素は、restriction 要素および extension 要素の base 属性でも使用されます。

単純型は、常に xsd プレフィックスを使用して入力されます。たとえば、要素が int 型であることを指定するには、例2.2「単純型での要素の定義」 に示されるように type 属性に xsd:int を入力します。

例2.2 単純型での要素の定義

<element name="simpleInt" type="xsd:int" />

サポートされる XSD 単純型

Apache CXF は、以下の XML スキーマの単純型をサポートします。

  • xsd:string
  • xsd:normalizedString
  • xsd:int
  • xsd:unsignedInt
  • xsd:long
  • xsd:unsignedLong
  • xsd:short
  • xsd:unsignedShort
  • xsd:float
  • xsd:double
  • xsd:boolean
  • xsd:byte
  • xsd:unsignedByte
  • xsd:integer
  • xsd:positiveInteger
  • xsd:negativeInteger
  • xsd:nonPositiveInteger
  • xsd:nonNegativeInteger
  • xsd:decimal
  • xsd:dateTime
  • xsd:time
  • xsd:date
  • xsd:QName
  • xsd:base64Binary
  • xsd:hexBinary
  • xsd:ID
  • xsd:token
  • xsd:language
  • xsd:Name
  • xsd:NCName
  • xsd:NMTOKEN
  • xsd:anySimpleType
  • xsd:anyURI
  • xsd:gYear
  • xsd:gMonth
  • xsd:gDay
  • xsd:gYearMonth
  • xsd:gMonthDay

2.5. 複合データ型の定義

概要

XML スキーマは、単純データ型から複合データ構造を構築する、柔軟で強力なメカニズムを提供します。要素および属性のシーケンスを作成して、データ構造を作成できます。また、定義された型を拡張して、さらに複雑な複合型を作成することもできます。

複合データ構造を構築する他に、列挙型、特定の値の範囲を持つデータ型、プリミティブ型の拡張または制限を行って、特定のパターンに従ったデータ型などの特殊型を記述することもできます。

2.5.1. データ構造の定義

概要

XML スキーマでは、データフィールドのコレクションであるデータ型は、complexType 要素を使用して定義されます。複合型を指定するには、以下の 3 つの情報が必要です。

  1. 定義された型の名前は、complexType 要素の name 属性で指定されます。
  2. complexType の最初の子要素は、それが ネットワークに配置される際の構造のフィールドの動作を記述します。「複合型の差異」 を参照してください。
  3. 定義された構造の各フィールドは、complexType 要素の孫である element 要素で定義されます。「構造の一部の定義」 を参照してください。

たとえば、例2.3「単純構造」 の構造は、XML スキーマでは、2 つの要素を持つ複合型として定義されています。

例2.3 単純構造

struct personalInfo
{
  string name;
  int age;
};

例2.4「複合型」 は、例2.3「単純構造」 に記載されている構造の可能な XML スキーママッピングの 1 つを表しています。例2.4「複合型」 で定義された構造によって、nameage の 2 つの要素が含まれるメッセージが生成されます。

.

例2.4 複合型

<complexType name="personalInfo">
  <sequence>
    <element name="name" type="xsd:string" />
    <element name="age" type="xsd:int" />
  </sequence>
</complexType>

複合型の差異

XML スキーマには、XML ドキュメントとして表現され、ワイヤで渡される場合に複合型のフィールドがどのように編成されているかを記述する3つの方法があります。complexType 要素の最初の子要素は、どの複合型が使用されるかを判断します。表2.1「複合型記述子要素」 は、複合型の動作を定義するために使用される要素を示しています。

表2.1 複合型記述子要素

要素複合型の動作

sequence

複合型のフィールドはすべて存在し、型定義で指定されている順序である必要があります。

all

複合型のフィールドはすべて存在しますが、任意の順序にすることができます。

choice

構造内の要素の 1 つのみをメッセージに配置できます。

例2.5「単純複合 choice 型」 に示されるように choice 要素を使用して構造が定義されている場合には、name 要素または age 要素でメッセージを生成します。

例2.5 単純複合 choice 型

<complexType name="personalInfo">
  <choice>
    <element name="name" type="xsd:string"/>
    <element name="age" type="xsd:int"/>
  </choice>
</complexType>

構造の一部の定義

element 要素を使用して構造を構成するデータフィールドを定義します。すべての complexType 要素には、少なくとも 1 つの element 要素が含まれている必要があります。complexType 要素の各 element 要素は、定義されたデータ構造のフィールドを表します。

データ構造のフィールドを完全に説明するために、element 要素には 2 つの必須属性があります。

  • name 属性はデータフィールドの名前を指定し、定義された複合型内で一意である必要があります。
  • type 属性は、フィールドに保存されたデータの型を指定します。型は、XML スキーマの単純型の 1 つか、またはコントラクトで定義されている任意の名前付き複合型のいずれかになります。

name および type に加え、element 要素には、minOcurrsmaxOccurs の一般的に使用される 2 つのオプション属性があります。これらの属性は、構造でフィールドが発生する回数に制限を設けます。デフォルトでは、各フィールドは複合型で 1 回だけ発生します。これらの属性を使用して、構造でフィールドが発生する必要がある回数または発生できる回数を変更できます。たとえば、previousJobs に示されているように、例2.6「発生の制約がある単純複合型」 というフィールドを定義できます。これは 3 回以上、7 回以下発生します。

例2.6 発生の制約がある単純複合型

<complexType name="personalInfo">
  <all>
    <element name="name" type="xsd:string"/>
    <element name="age" type="xsd:int"/>
    <element name="previousJobs" type="xsd:string:
             minOccurs="3" maxOccurs="7"/>
  </all>
</complexType>

例2.7「minOccurs が 0 に設定されている単純複合型」 に記載のとおり minOccurs をゼロに設定し、minOccurs を使用して age フィールドをオプションにすることもできます。この場合、age は省略でき、データは引き続き有効です。

例2.7 minOccurs が 0 に設定されている単純複合型

<complexType name="personalInfo">
  <choice>
    <element name="name" type="xsd:string"/>
    <element name="age" type="xsd:int" minOccurs="0"/>
  </choice>
</complexType>

属性の定義

XML ドキュメントでは、属性は要素のタグに含まれます。たとえば、以下のコードの complexType 要素では name が属性になります。複合型の属性を指定するには、complexType 要素定義で attribute 要素を定義します。attribute 要素は、allsequence、または choice 要素の後でのみ使用できます。複合型の属性ごとに attribute 要素を 1 つ指定します。attribute 要素は complexType 要素の直接の子でなければなりません。

例2.8 属性のある複合型

<complexType name="personalInfo">
  <all>
    <element name="name" type="xsd:string"/>
    <element name="previousJobs" type="xsd:string"
             minOccurs="3" maxOccurs="7"/>
  </all>
  <attribute name="age" type="xsd:int" use="required" />
</complexType>

前述のコードでは、attribute 要素は personalInfo 複合型に age 属性があることを指定します。attribute 要素には以下の属性があります。

  • name - 属性を識別する文字列を指定する必須属性。
  • type - フィールドに保存されたデータの型を指定します。型は、XML スキーマの単純型のいずれかになります。
  • use - 複合型にこの属性が必要であるかを指定する任意の属性。有効な値は required または optional です。デフォルトではこの属性は任意です。

attribute 要素では、オプションの default 属性を指定でき、これにより、属性のデフォルト値を指定できます。

2.5.2. 配列の定義

概要

Apache CXF は、コントラクトで配列を定義するための 2 つのメソッドをサポートします。1 つ目は、値が 1 より大きい maxOccurs 属性のある 1 つの要素を持つ複合型を定義します。2 つ目は、SOAP 配列を使用することです。SOAP 配列は、多次元配列を簡単に定義する機能や、過疎な配列を送信する機能などの追加機能を提供します。

複合型配列

複合型配列は、シーケンスで複合型の特別なケースです。単一要素で複合型を定義し、maxOccurs 属性の値を指定するだけです。たとえば、twenty 浮動小数点数の配列を定義するには、例2.9「複合型配列」 に示されるように複合型を使用します。

例2.9 複合型配列

<complexType name="personalInfo">
  <element name="averages" type="xsd:float" maxOccurs="20"/>
</complexType>

minOccurs 属性の値を指定することもできます。

SOAP 配列

SOAP 配列は、wsdl:arrayType 要素を使用して SOAP-ENC:Array 基本型から派生することによって定義されます。この構文は 例2.10「wsdl:arrayType を使用して派生された SOAP 配列の構文」 にあります。definitions 要素が xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" を宣言していることを確認します。

例2.10 wsdl:arrayType を使用して派生された SOAP 配列の構文

<complexType name="TypeName">
  <complexContent>
    <restriction base="SOAP-ENC:Array">
      <attribute ref="SOAP-ENC:arrayType"
                 wsdl:arrayType="ElementType<ArrayBounds>"/>
    </restriction>
  </complexContent>
</complexType>

TypeName は、この構文を使用して、新しく定義された配列型の名前を指定します。ElementType は、配列の要素の型を指定します。ArrayBounds は、配列の次元数を指定します。1 次元配列を指定するには、[] を使用します。2 次元配列を指定するには、[][] または [,] を使用します。

たとえば、例2.11「SOAP 配列の定義」 に示されている SOAP Array、SOAPStrings は文字列の 1 次元配列を定義します。wsdl:arrayType 属性は、配列要素の型 xsd:string を指定し、次元の数 [] は 1 次元を意味します。

例2.11 SOAP 配列の定義

<complexType name="SOAPStrings">
  <complexContent>
    <restriction base="SOAP-ENC:Array">
      <attribute ref="SOAP-ENC:arrayType"
                 wsdl:arrayType="xsd:string[]"/>
    </restriction>
  </complexContent>
</complexType>

SOAP 1.1 仕様で説明されているように、単純な要素を使用して SOAP 配列を記述することもできます。この構文は 例2.12「要素を使用して派生された SOAP 配列の構文」 にあります。

例2.12 要素を使用して派生された SOAP 配列の構文

<complexType name="TypeName">
  <complexContent>
    <restriction base="SOAP-ENC:Array">
      <sequence>
        <element name="ElementName" type="ElementType"
                 maxOccurs="unbounded"/>
      </sequence>
    </restriction>
  </complexContent>
</complexType>

この構文を使用する場合は、要素の maxOccurs 属性は常に unbounded に設定する必要があります。

2.5.3. エクステンションによる型定義

ほとんどの主要なコーディング言語と同様に、XML スキーマでは、他のデータ型からその要素の一部を継承するデータ型を作成できます。これは、エクステンションによる型の定義と呼ばれます。たとえば、planet という新しい要素を追加して、例2.4「複合型」 で定義される personalInfo 構造を拡張する、alienInfo という新しいタイプを作成できます。

エクステンションで定義される型には 4 つの部分があります。

  1. 型の名前は、complexType 要素の name 属性で定義されます。
  2. complexContent 要素は、新しい型に複数の要素があることを指定します。

    注記

    複合型に新しい属性を追加する場合にのみ、simpleContent 要素を使用できます。

  3. 新しい型が派生される ベース 型と呼ばれる型は、extension 要素の base 属性で指定されます。
  4. 新しい型の要素と属性は、通常の複合型と同様に extension 要素で定義されます。

たとえば、alienInfo は、例2.13「エクステンションによって定義される型」 で以下のように定義されます。

例2.13 エクステンションによって定義される型

<complexType name="alienInfo">
  <complexContent>
    <extension base="xsd1:personalInfo">
      <sequence>
        <element name="planet" type="xsd:string"/>
      </sequence>
    </extension>
  </complexContent>
</complexType>

2.5.4. 制限による型の定義

概要

XML スキーマを使用すると、XML スキーマの単純型の許容値を制限することにより、新しい型を作成できます。たとえば、厳密に 9 文字の文字列である単純型 SSN を定義できます。単純型を制限することで定義された新しい型は、simpleType 要素を使用して定義されます。

制限による型の定義には、以下の 3 つが必要です。

  1. 新しい型の名前は、simpleType 要素の name 属性によって指定されます。
  2. ベース型と呼ばれる新しい型が派生される単純型は restriction 要素で指定されます。「ベース型の指定」 を参照してください。
  3. ベース型の制限を定義する facet というルールは 、restriction 要素の子として定義されます。「制限の定義」 を参照してください。

ベース型の指定

ベース型は、新規型を定義するために制限されている型です。これは restriction 要素を使用して指定されます。restriction 要素は simpleType 要素の唯一の子で、ベース型を指定する 1 つの属性 base を持ちます。ベース型は、XML スキーマの単純型のいずれかになります。

たとえば、xsd:int の値を制限して新しい型を定義するには、例2.14「ベース型として int を使用」 のように定義を使用します。

例2.14 ベース型として int を使用

<simpleType name="restrictedInt">
  <restriction base="xsd:int">
    ...
  </restriction>
</simpleType>

制限の定義

基本型に適用される制限を定義する規則は、ファセットと呼ばれます。ファセットとは、ファセットの適用方法を定義する 1 つの属性 value を持つ要素です。使用可能なファセットとその有効な value 設定は、ベース型によって異なります。たとえば、xsd:string では、次のような 6 つのファセットがサポートされています。

  • length
  • minLength
  • maxLength
  • pattern
  • whitespace
  • enumeration

各ファセット要素は、restriction 要素の子です。

例2.15「SSN 単純型の説明」 は、ソーシャルセキュリティー番号を表す単純型 SSN の例を示しています。作成される型は xxx-xx-xxxx 形式の文字列です。<SSN>032-43-9876<SSN> は、この型の要素に対する有効な値ですが、<SSN>032439876</SSN> は有効ではありません。

例2.15 SSN 単純型の説明

<simpleType name="SSN">
  <restriction base="xsd:string">
    <pattern value="\d{3}-\d{2}-\d{4}"/>
  </restriction>
</simpleType>

2.5.5. 列挙型の定義

概要

XML スキーマの列挙型は、制限による定義の特殊なケースです。これらは、すべての XML スキーマのプリミティブ型でサポートされる enumeration ファセットを使用して記述されます。最新のプログラミング言語の列挙型と同様に、この型の変数は、指定された値の 1 つだけを持つことができます。

XML スキーマでの列挙の定義

列挙を定義する構文は 例2.16「列挙の構文」 にあります。

例2.16 列挙の構文

<simpleType name="EnumName">
  <restriction base="EnumType">
    <enumeration value="Case1Value"/>
    <enumeration value="Case2Value"/>
    ...
    <enumeration value="CaseNValue"/>
  </restriction>
</simpleType>

EnumName は、列挙型の名前を指定します。EnumType は、ケース値の型を指定します。CaseNValue ( N は 1 以上の任意の数字) で、列挙の各特定ケースの値を指定します。列挙型には、任意の数のケース値を指定できますが、単純な型から派生しているため、一度に 1 つのケース値のみが有効になります。

たとえば、列挙 widgetSize で定義した XML ドキュメントは、例2.17「widgetSize 列挙」 のように、<widgetSize>big</widgetSize> が含まれている場合に有効ですが、<widgetSize>big,mungo</widgetSize> が含まれている場合は有効になりません。

例2.17 widgetSize 列挙

<simpleType name="widgetSize">
  <restriction base="xsd:string">
    <enumeration value="big"/>
    <enumeration value="large"/>
    <enumeration value="mungo"/>
  </restriction>
</simpleType>

2.6. 要素の定義

XML スキーマの要素は、スキーマから生成された XML ドキュメントの要素のインスタンスを表します。最も基本的な要素は、単一の element 要素で構成されます。複合型のメンバーを定義する element 要素と同様に、以下の 3 つの属性があります。

  • name - XML ドキュメントに表示される要素の名前を指定する必須属性。
  • type - 要素の型を指定します。型は、XML Schema プリミティブ型またはコントラクトで定義された名前付きの複合型になります。型にインライン定義がある場合は、この属性を省略できます。
  • nillable - ドキュメントから要素を完全に省略できるかどうかを指定します。nillabletrue に設定されている場合、スキーマを使用して生成された任意のドキュメントから要素を省略できます。

要素は インラインの型定義を持つこともできます。インライン型は、complexType 要素または simpleType 要素のいずれかを使用して指定します。データの種類が複合または単純であるかを指定したら、各タイプのデータで利用可能なツールを使用して必要なタイプのデータを定義できます。インラインの型の定義は再使用されないため、推奨されません。

第3章 サービスで使用される論理メッセージの定義

概要

サービスは、操作が呼び出されたときに交換されるメッセージによって定義されます。WSDL コントラクトでは、これらのメッセージは message 要素を使用して定義されます。メッセージは、part 要素を使用して定義される 1 つ以上のパーツで構成されます。

概要

サービスの操作は、オペレーションの呼び出し時に交換される論理メッセージを指定して定義します。これらの論理メッセージは、ネットワーク上に渡されたデータを XML ドキュメントとして定義します。これには、メソッド呼び出しの一部であるすべてのパラメーターが含まれます。 論理メッセージは、コントラクトの message 要素を使用して定義されます。各論理メッセージは、part 要素で定義された 1 つ以上のパーツで構成されます。

メッセージごとに各パラメーターを個別部分として一覧表示できますが、操作に必要なデータをカプセル化する 1 つの部分のみを使用することが推奨されます。

メッセージおよびパラメーターリスト

サービスによって公開される各操作には、1 つの入力メッセージと 1 つの出力メッセージのみを指定できます。入力メッセージは、操作が呼び出されたときにサービスが受信するすべての情報を定義します。出力メッセージは、操作の完了時にサービスが返すすべてのデータを定義します。障害メッセージは、エラーが発生した際にサービスが返すデータを定義します。

さらに、各操作は任意の数の障害メッセージを指定できます。障害メッセージは、サービスでエラーが発生したときに返されるデータを定義します。これらのメッセージには通常、コンシューマーがエラーを理解するために十分な情報を提供するパーツが 1 つのみ含まれます。

レガシーシステムとの統合に関するメッセージ設計

既存のアプリケーションをサービスとして定義する場合は、メソッドの操作の実装で使用される各パラメーターがメッセージで表されるようにする必要があります。また、戻り値が操作の出力メッセージに含まれていることを確認する必要があります。

メッセージを定義する方法の 1 つは RPC スタイルです。RPC スタイルを使用する場合、メソッドのパラメーターリストの各パラメーターに 1 つのパーツを使用してメッセージを定義します。各メッセージパーツは、コントラクトの types 要素で定義された型に基づきます。入力メッセージには、メソッドの入力パラメーターごとに 1 つのパーツが含まれます。アウトプットメッセージには、出力パラメーターごとに 1 つの部分が含まれ、また必要に応じて戻り値を表す部分が含まれます。パラメーターが入力パラメーターと出力パラメーターの両方である場合、これは入力メッセージと出力メッセージの両方のパーツとして一覧表示されます。

RPC スタイルのメッセージ定義は、Tibco や CORBA などのトランスポートを使用するレガシーシステムを有効にする場合に便利です。これらのシステムは、手順と方法を中心にして設計されています。そのため、呼び出される操作のパラメーターリストに似たメッセージを使用してモデル化するのが最も簡単です。RPC スタイルは、サービスと、公開しているアプリケーションとの間のよりクリーンなマッピングを作成します。

SOAP サービスのメッセージ設計

RPC スタイルは、既存のシステムをモデリングに便利ですが、サービスのコミュニティーではラップされたドキュメントスタイルが強く優先されます。ラップされたドキュメントスタイルでは各メッセージに 1 つのパーツがあります。メッセージのパーツは、コントラクトの types 要素で定義されたラッパー要素を参照します。wrapper 要素には、以下の特徴があります。

  • 要素シーケンスが含まれる複合型です。詳細は 「複合データ型の定義」 を参照してください。
  • 入力メッセージのラッパーの場合:

    • メソッドの入力パラメーターごとに 1 つの要素があります。
    • 名前は、関連付けられた操作の名前と同じです。
  • 出力メッセージのラッパーの場合:

    • メソッドの出力パラメーターごとに 1 つの要素があり、メソッドの inout パラメーターごとに 1 つの要素があります。
    • 最初の要素は、メソッドの戻りパラメーターを表します。
    • この名前は、ラッパーが関連付けられる操作の名前に Response を追加して生成されます。

メッセージの命名

コントラクトの各メッセージには、その namespace 内で一意となる名前を指定する必要があります。以下の命名規則を使用することが推奨されます。

  • メッセージは単一の操作でのみ使用する必要があります。
  • 入力メッセージ名は、操作名の前に Request を追加して形成されます。
  • 出力メッセージ名は、操作名の前に Response を追加して形成されます。
  • 障害メッセージ名は、障害の理由を表す必要があります。

メッセージ部分

メッセージ部分は、論理メッセージの正式のデータユニットです。各部分は part 要素を使用して定義され、name 属性と、データ型を指定する type 属性または element 属性によって識別されます。データ型属性は 表3.1「パーツデータ型属性」 に記載されています。

表3.1 パーツデータ型属性

属性説明

element="elem_name"

パーツのデータ型は、elem_name という要素で定義されます。

type="type_name"

パーツのデータ型は、type_name という型で定義されます。

メッセージは、パーツ名を再利用できます。たとえば、メソッドに参照により渡されるパラメーターまたは in/out の foo がある場合、例3.1「再利用部分」 のように要求メッセージと応答メッセージの両方の部分にすることができます

例3.1 再利用部分

<message name="fooRequest">
  <part name="foo" type="xsd:int"/>
<message>
<message name="fooReply">
  <part name="foo" type="xsd:int"/>
<message>

たとえば、ユーザーは個人情報を保存し、従業員の ID 番号を基にした従業員のデータを返すメソッドを提供するサーバーがあるとします。データを検索するメソッド署名は 例3.2「personalInfo 検索メソッド」 と似ています。

例3.2 personalInfo 検索メソッド

personalInfo lookup(long empId)

このメソッド署名は、例3.3「RPC WSDL メッセージ定義」 のように RPC スタイル WSDL フラグメントにマップできます。

例3.3 RPC WSDL メッセージ定義

<message name="personalLookupRequest">
  <part name="empId" type="xsd:int"/>
<message/>
<message name="personalLookupResponse>
  <part name="return" element="xsd1:personalInfo"/>
<message/>

例3.4「ラップされたドキュメント WSDL メッセージの定義」 のように、ラップされたドキュメントスタイルの WSDL フラグメントへマップすることもできます。

例3.4 ラップされたドキュメント WSDL メッセージの定義

<wsdl:types>
  <xsd:schema ... >
  ...
  <element name="personalLookup">
    <complexType>
      <sequence>
        <element name="empID" type="xsd:int" />
      </sequence>
    </complexType>
  </element>
  <element name="personalLookupResponse">
    <complexType>
      <sequence>
        <element name="return" type="personalInfo" />
      </sequence>
    </complexType>
  </element>
  </schema>
</types>
<wsdl:message name="personalLookupRequest">
  <wsdl:part name="empId" element="xsd1:personalLookup"/>
<message/>
<wsdl:message name="personalLookupResponse">
  <wsdl:part name="return" element="xsd1:personalLookupResponse"/>
<message/>

第4章 論理インターフェースの定義

概要

論理サービスインターフェースは portType 要素を使用して定義されます。

概要

論理サービスインターフェースは、WSDL portType 要素を使用して定義されます。portType 要素は、抽象操作定義のコレクションです。各操作は、操作が表すトランザクションを完了するために使用される入力、出力、および障害メッセージによって定義されます。portType 要素で定義されたサービスインターフェースを実装するためにコードが生成されると、各操作はコントラクトで指定された入力、出力、および障害メッセージで定義されたパラメーターが含まれるメソッドに変換されます。

処理

WSDL コントラクトで論理インターフェースを定義するには、以下を行う必要があります。

  1. インターフェース定義を含む portType 要素を作成し、一意の名前を付けます。「ポート型」 を参照してください。
  2. インターフェースで定義された各オペレーションに operation 要素を作成します。「操作」 を参照してください。
  3. それぞれの操作に対して、操作のパラメーターリスト、戻り値の型、および例外を表すために使用されるメッセージを指定します。「操作メッセージ」 を参照してください。

ポート型

WSDL portType 要素は、論理インターフェース定義のルート要素です。多くの Web サービス実装は、portType 要素を生成された実装オブジェクトに直接マップしますが、論理インターフェイス定義は、実装されたサービスによって提供される正確な機能を指定しません。たとえば、ticketSystem という名前の論理インターフェースを使用すると、コンサートチケットを販売したり、駐車券を発行したりする実装を行うことができます。

portType 要素は、バインディングにマッピングされ、定義されたサービスを公開するエンドポイントによって使用される物理データを定義する WSDL ドキュメントの単位です。

WSDL ドキュメントの の各 portType 要素には、name 属性を使用して指定された一意の名前が必要で、これは operation 要素に記載される操作のコレクションで構成されます。WSDL ドキュメントでは、任意の数のポート型を記述できます。

操作

WSDL operation 要素を使用して定義される論理操作は、2 つのエンドポイント間の対話を定義します。たとえば、口座の残高照会の要求と、ウィジェットの注文を操作として定義できます。

portType 要素内に定義された各操作には、name 属性を使用して指定された一意の名前が必要です。操作を定義するには、name 属性が必要です。

操作メッセージ

論理操作は、操作を実行するためにエンドポイント間で通信される論理メッセージを表す、要素のセットで構成されます。操作を記述できる要素のリストは、表4.1「操作メッセージの要素」 を参照してください。

表4.1 操作メッセージの要素

要素説明

input

リクエストの作成時に、クライアントエンドポイントがサービスプロバイダーに送信するメッセージを指定します。このメッセージの部分は、操作の入力パラメーターに対応します。

output

サービスプロバイダーがリクエストへの応答としてクライアントエンドポイントに送信するメッセージを指定します。このメッセージの部分は、参照によって渡される値など、サービスプロバイダーによって変更可能な操作パラメーターに対応します。これには、操作の戻り値が含まれます。

fault

エンドポイント間のエラー状態の通信に使用されるメッセージを指定します。

操作には、1 つ以上の input 要素または 1 つの output 要素が必要です。操作は inputoutput 要素の両方を持つことができますが、各要素 1 つだけです。操作に fault 要素は必要はありませんが、必要な場合は任意の数の fault 要素を持つことができます。

この要素には、表4.2「入力要素および出力要素の属性」 に記載されている 2 つの属性があります。

表4.2 入力要素および出力要素の属性

属性説明

name

操作を具体的なデータフォーマットにマッピングする際に参照できるようにメッセージを識別します。名前はエンクロージングポート型内で一意である必要があります。

message

送受信されるデータを記述する抽象メッセージを指定します。message 属性の値は、WSDL ドキュメントに定義された抽象メッセージの 1つの name 属性に対応している必要があります。

すべての input および output 要素の name 属性を指定する必要はありません。WSDL はエンクロージング操作の名前を基にデフォルトの命名スキームを提供します。操作で要素が 1 つだけ使用される場合、要素名はデフォルトで操作の名前になります。inputoutput 要素の両方が使用される場合、デフォルトの要素名は Request または Response のいずれか最初に付けられた操作の名前になります。

戻り値

operation 要素は操作中に渡されるデータの抽象定義であるため、WSDL は操作に指定された戻り値を提供しません。メソッドが値を返すと、そのメッセージの最後の部分として output 要素にマッピングされます。

たとえば、例4.1「personalInfo 検索インターフェース」 に記載されいるインターフェースと同様のインターフェースがあるとします。

例4.1 personalInfo 検索インターフェース

interface personalInfoLookup
{
  personalInfo lookup(in int empID)
  raises(idNotFound);
}

このインターフェースは、例4.2「personalInfo 検索ポート型」 のポート型にマッピングできます。

例4.2 personalInfo 検索ポート型

<message name="personalLookupRequest">
  <part name="empId" element="xsd1:personalLookup"/>
<message/>
<message name="personalLookupResponse">
  <part name="return" element="xsd1:personalLookupResponse"/>
<message/>
<message name="idNotFoundException">
  <part name="exception" element="xsd1:idNotFound"/>
<message/>
<portType name="personalInfoLookup">
  <operation name="lookup">
    <input name="empID" message="tns:personalLookupRequest"/>
    <output name="return" message="tns:personalLookupResponse"/>
    <fault name="exception" message="tns:idNotFoundException"/>
  </operation>
</portType>

パート II. Web サービスバインディング

ここでは、Apache CXF バインディングを WSDL ドキュメントに追加する方法を説明します。

第5章 WSDL のバインディングについて

概要

バインディングは、サービスの定義に使用される論理メッセージを、エンドポイントによって送受信できる具体的なペイロードフォーマットにマップします。

概要

バインディングは、サービスによって使用される論理メッセージと、エンドポイントが物理環境で使用する具体的なデータフォーマットとのブリッジを提供します。論理メッセージがエンドポイントによってネットワークで使用されるペイロード形式にマップされる方法を記述します。バインディング内では、パラメーターの順序、具体的なデータ型、戻り値などの詳細が指定されます。たとえば、RPC 呼び出しが必要とする順番を反映するために、メッセージの部分をバインディングで並べ替えることができます。バインディング型に応じて、どのメッセージの部分 (ある場合) がメソッドの戻り値の型を表すかを特定することもできます。

ポート型およびバインディング

ポート型およびバインディングは直接関連するものです。ポート型は、2 つの論理サービス間の対話セットの定義です。バインディングとは、論理サービスの実装に使用されるメッセージが物理環境でインスタンス化される方法の具体的な定義です。各バインディングは、ポート型によって定義された論理サービスを公開する 1 つのエンドポイントの定義を終了する一連のネットワーク詳細に関連付けられます。

エンドポイントが単一のサービスのみを定義するようにするには、WSDL では単一のポート型のみを表すことができる必要があります。たとえば、2 つのポート型を持つコントラクトがある場合は、これら両方を具体的なデータ形式にマッピングする単一のバインディングを作成することはできません。2 つのバインディングが必要です。

ただし、WSDL では、ポート型を複数のバインディングにマッピングできます。たとえば、コントラクトにポート型が 1 つある場合は、2 つ以上のバインディングにマップできます。各バインディングは、メッセージ部分のマッピング方法を変更したり、メッセージ用に完全に異なるペイロード形式を指定したりできます。

WSDL 要素

バインディングは、WSDL binding 要素を使用してコントラクトで定義されます。binding 要素は バインディングの名前を指定する name や PortType への参照を提供する type などの属性で構成されます。この属性の値は、4章論理インターフェースの定義 で説明されているように、バインディングをエンドポイントに関連付けるために使用されます。

実際のマッピングは、binding 要素の子で定義されます。これらの要素は、使用するペイロードフォーマットの種類によって異なります。異なるペイロードフォーマットと、それらのマッピングの指定に使用される要素は以降の章で説明します。

コントラクトへの追加

Apache CXF は、事前定義のサービスインターフェースのバインディングを生成できるコマンドラインツールを提供します。

ツールにより、コントラクトに適切な要素が追加されます。ただし、さまざまな種類のバインディングの仕組みをある程度理解しておくことが推奨されます。

テキストエディターを使用して、バインディングをコントラクトに追加することもできます。コントラクトの手動編集時に、コントラクトが有効であることを確認する責任があります。

サポートされているバインディング

Apache CXF は以下のバインディングをサポートします。

  • SOAP 1.1
  • SOAP 1.2
  • CORBA
  • Pure XML

第6章 SOAP 1.1 メッセージの使用

概要

Apache CXF は、SOAP ヘッダーを使用しない SOAP 1.1 バインディングを生成するツールを提供します。しかし、テキストまたは XML エディターを使用して SOAP ヘッダーをバインディングに追加できます。

6.1. SOAP 1.1 バインディングの追加

wsdl2soap の使用

wsdl2soap を使用して SOAP 1.1 バインディングを生成するには、コマンド wsdl2soap-iport-type-name-bbinding-name-doutput-directory-ooutput-file-nsoap-body-namespace-style (document/rpc)-use (literal/encoded)-v-verbose-quietwsdlurl を使用します。

注記

wsdl2soap を使用するには、Apache CXF ディストリビューションをダウンロードする必要があります。

このコマンドには、次のオプションがあります。

オプション解釈

-i port-type-name

バインディングが生成される portType 要素を指定します。

wsdlurl

portType 要素定義が含まれる WSDL ファイルのパスと名前。

ツールには、次のオプション引数があります。

オプション解釈

-b binding-name

生成された SOAP バインディングの名前を指定します。

-d output-directory

生成された WSDL ファイルを配置するディレクトリーを指定します。

-o output-file

生成された WSDL ファイルの名前を指定します。

-n soap-body-namespace

スタイルが RPC の場合、SOAP ボディー namespace を指定します。

-style (document/rpc)

SOAP バインディングで使用するエンコーディングスタイル (document または RPC) を指定します。デフォルトは document です。

-use (literal/encoded)

SOAP バインディングで使用するバインディングの使用 (エンコードまたはリテラル) を指定します。デフォルトは literal です。

-v

ツールのバージョン番号を表示します。

-verbose

コード生成プロセスでコメントを表示します。

-quiet

コード生成プロセス中のコメントを非表示にします。

-iport-type-name およびwsdlurl 引数が必要です。-style rpc 引数を指定すると、-nsoap-body-namspace 引数も必要になります。その他の引数はすべて任意であり、任意の順序でリストできます。

重要

wsdl2soapdocument/encoded SOAP バインディングの生成をサポートしません。

システムに、注文を受け取り、注文を処理するための 1 つのオペレーションを提供するインターフェイスがある場合、例6.1「注文システムインターフェース」 に示すような WSDL フラグメントで定義されます。

例6.1 注文システムインターフェース

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>
...
</definitions>

orderWidgets 用に生成された SOAP バインディングは 例6.2「orderWidgets の SOAP 1.1 バインティング」 にあります。

例6.2 orderWidgets の SOAP 1.1 バインティング

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap:operation soapAction="" style="document"/>
      <input name="order">
        <soap:body use="literal"/>
      </input>
      <output name="bill">
        <soap:body use="literal"/>
      </output>
      <fault name="sizeFault">
        <soap:body use="literal"/>
      </fault>
  </operation>
</binding>

このバインディングは、メッセージが document/literal メッセージスタイルを使用して送信されることを指定します。

6.2. SOAP ヘッダーの SOAP 1.1 バインディングへの追加

概要

SOAP ヘッダーは、soap:header 要素をデフォルトの SOAP 1.1 バインディングに追加して定義されます。soap:header 要素は、バインディングの inputoutput、および fault 要素のオプションの子です。SOAP ヘッダーは親メッセージの部分になります。SOAP ヘッダーは、メッセージとメッセージの部分を指定して定義されます。各 SOAP ヘッダーに含めることができるメッセージ部分は 1 つだけですが、SOAP ヘッダーは必要な数だけ挿入できます。

構文

SOAP ヘッダーを定義する構文は 例6.3「SOAP ヘッダー構文」 にあります。soap:headermessage 属性は、ヘッダーに挿入される部分が取得されたメッセージの修飾名です。part 属性は、SOAP ヘッダーに挿入されたメッセージ部分の名前です。SOAP ヘッダーは常にドキュメントスタイルであるため、SOAP ヘッダーに挿入された WSDL メッセージの部分を要素を使用して定義する必要があります。messagepart 属性はともに、SOAP ヘッダーに挿入するデータを完全に記述します。

例6.3 SOAP ヘッダー構文

<binding name="headwig">
  <soap:binding style="document"
                transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="weave">
      <soap:operation soapAction="" style="document"/>
      <input name="grain">
        <soap:body ... />
        <soap:header message="QName" part="partName"/>
      </input>
...
</binding>

soap:header は、必須の message および part 属性に加え、namespaceuse、および encodingStyle 属性もサポートします。これらの属性は、soap:body と同じように soap:header で機能します。

ボディーとヘッダー間のメッセージの分割

SOAP ヘッダーに挿入されたメッセージ部分は、コントラクトからの有効なメッセージ部分にすることができます。これは、SOAP ボディーとして使用されている親メッセージの一部であっても可能です。同じメッセージに情報を 2 回送信することはほとんどないため、SOAP バインディングは SOAP ボディーに挿入されるメッセージ部分を指定する手段を提供します。

soap:body 要素には、部分名のスペース区切りリストである任意の属性 parts があります。parts が定義されると、リストされたメッセージ部分のみが SOAP ボディーに挿入されます。その後、残りの部分を SOAP ヘッダーに挿入します。

注記

親メッセージの一部を使用して SOAP ヘッダーを定義すると、Apache CXF によって SOAP ヘッダーが自動的に入力されます。

例6.4「SOAP 1.1 バインディングと SOAP ヘッダー」 は、例6.1「注文システムインターフェース」 に記載されている orderWidgets サービスの変更バージョンを示しています。このバージョンが変更され、各注文のリクエストおよび応答の SOAP ヘッダーに xsd:base64binary 値を配置されます。SOAP ヘッダーは、widgetKey メッセージの keyVal 部分として定義されます。この場合、SOAP ヘッダーは入力メッセージまたは出力メッセージの一部ではないため、アプリケーションロジックに SOAP ヘッダーを追加する必要があります。

例6.4 SOAP 1.1 バインディングと SOAP ヘッダー

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>
<message name="widgetKey">
  <part name="keyVal" element="xsd1:keyElem"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap:operation soapAction="" style="document"/>
      <input name="order">
        <soap:body use="literal"/>
        <soap:header message="tns:widgetKey" part="keyVal"/>
      </input>
      <output name="bill">
        <soap:body use="literal"/>
        <soap:header message="tns:widgetKey" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

ヘッダー値が入力および出力メッセージの一部になるように、例6.4「SOAP 1.1 バインディングと SOAP ヘッダー」 を変更することもできます。

第7章 SOAP 1.2 メッセージの使用

概要

Apache CXF は、SOAP ヘッダーを使用しない SOAP 1.2 バインディングを生成するツールを提供します。テキストまたは XML エディターを使用して SOAP ヘッダーをバインディングに追加できます。

7.1. WSDL ドキュメントへの SOAP 1.2 バインディングの追加

wsdl2soap の使用

注記

wsdl2soap を使用するには、Apache CXF ディストリビューションをダウンロードする必要があります。

wsdl2soap を使用して SOAP 1.1 バインディングを生成するには、コマンド wsdl2soap-iport-type-name-bbinding-name-soap12-doutput-directory-ooutput-file-nsoap-body-namespace-style (document/rpc)-use (literal/encoded)-v-verbose-quietwsdlurl を使用します。ツールには以下の引数が必要です。

オプション解釈

-i port-type-name

バインディングが生成される portType 要素を指定します。

-soap12

生成されたバインディングが SOAP 1.2 を使用することを指定します。

wsdlurl

portType 要素定義が含まれる WSDL ファイルのパスと名前。

ツールには、次のオプション引数があります。

オプション解釈

-b binding-name

生成された SOAP バインディングの名前を指定します。

-soap12

生成されたバインディングが SOAP 1.2 を使用することを指定します。

-d output-directory

生成された WSDL ファイルを配置するディレクトリーを指定します。

-o output-file

生成された WSDL ファイルの名前を指定します。

-n soap-body-namespace

スタイルが RPC の場合、SOAP ボディー namespace を指定します。

-style (document/rpc)

SOAP バインディングで使用するエンコーディングスタイル (document または RPC) を指定します。デフォルトは document です。

-use (literal/encoded)

SOAP バインディングで使用するバインディングの使用 (エンコードまたはリテラル) を指定します。デフォルトは literal です。

-v

ツールのバージョン番号を表示します。

-verbose

コード生成プロセスでコメントを表示します。

-quiet

コード生成プロセスでコメントを非表示にします。

-i port-type-name および wsdlurl 引数が必要です。-style rpc 引数を指定すると、-n soap-body-namspace 引数も必要になります。その他の引数はすべて任意であり、任意の順序でリストできます。

重要

wsdl2soapdocument/encoded SOAP 1.2 バインディングの生成をサポートしません。

システムに、注文を受け取り、注文を処理するための 1 つのオペレーションを提供するインターフェイスがある場合、例7.1「注文システムインターフェース」 に示すような WSDL フラグメントで定義されます。

例7.1 注文システムインターフェース

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>
...
</definitions>

orderWidgets 用に生成された SOAP バインディングは 例7.2「orderWidgets の SOAP 1.2 バインディング」 に記載されています。

例7.2 orderWidgets の SOAP 1.2 バインディング

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal"/>
      </input>
      <output name="bill">
        <wsoap12:body use="literal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>

このバインディングは、メッセージが document/literal メッセージスタイルを使用して送信されることを指定します。

7.2. SOAP 1.2 メッセージへのヘッダーの追加

概要

SOAP メッセージヘッダーは、soap12:header 要素を SOAP 1.2 メッセージに追加して定義されます。soap12:header 要素は、バインディングの inputoutput、および fault 要素のオプションの子です。SOAP ヘッダーは親メッセージの部分になります。SOAP ヘッダーは、メッセージとメッセージの部分を指定して定義されます。各 SOAP ヘッダーに含めることができるメッセージ部分は 1 つだけですが、ヘッダーは必要な数だけ挿入できます。

構文

SOAP ヘッダーを定義する構文は 例7.3「SOAP ヘッダー構文」 にあります。

例7.3 SOAP ヘッダー構文

<binding name="headwig">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="weave">
      <soap12:operation soapAction="" style="documment"/>
      <input name="grain">
        <soap12:body ... />
        <soap12:header message="QName" part="partName"
                       use="literal|encoded"
                        encodingStyle="encodingURI"
                        namespace="namespaceURI" />
      </input>
...
</binding>

soap12:header 要素の属性は 表7.1「soap12:header 属性」 で説明されています。

表7.1 soap12:header 属性

属性説明

message

ヘッダーに挿入される部分の取得元となるメッセージの修飾名を指定する必須属性です。

part

SOAP ヘッダーに挿入されるメッセージ部分の名前を指定する必須属性です。

use

メッセージ部分がエンコーディングルールを使用してエンコードされるかどうかを指定します。encoded に設定すると、メッセージ部分は、encodingStyle 属性の値で指定されたエンコーディングルールを使用してエンコードされます。literal に設定すると、メッセージ部分は参照されるスキーマ型によって定義されます。

encodingStyle

メッセージの構築に使用されるエンコーディングルールを指定します。

namespace

use="encoded" でシリアライズされたヘッダー要素に割り当てる namespace を定義します。

ボディーとヘッダー間のメッセージの分割

SOAP ヘッダーに挿入されたメッセージ部分は、コントラクトからの有効なメッセージ部分にすることができます。これは、SOAP ボディーとして使用されている親メッセージの一部であっても可能です。同じメッセージに情報を 2 回送信することはほとんどないため、SOAP 1.2 バインディングは SOAP ボディーに挿入されるメッセージ部分を指定する手段を提供します。

soap12:body 要素には、部分名のスペース区切りリストである任意の属性 parts があります。parts が定義されると、リストされたメッセージ部分のみが SOAP 1.2 メッセージのボディーに挿入されます。その後、残りの部分をメッセージのヘッダーに挿入できます。

注記

親メッセージの一部を使用して SOAP ヘッダーを定義すると、Apache CXF によって SOAP ヘッダーが自動的に入力されます。

例7.4「SOAP 1.2 バインディングと SOAP ヘッダー」 は、例7.1「注文システムインターフェース」 に記載されている orderWidgets サービスの変更バージョンを示しています。このバージョンは変更され、各注文のリクエストおよび応答のヘッダーに xsd:base64binary 値が配置されるようになります。ヘッダーは、widgetKey メッセージからの keyVal 部分として定義されます。この場合、入力メッセージまたは出力メッセージの一部ではないため、アプリケーションロジックを追加してヘッダーを作成する必要があります。

例7.4 SOAP 1.2 バインディングと SOAP ヘッダー

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>
<message name="widgetKey">
  <part name="keyVal" element="xsd1:keyElem"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal"/>
        <soap12:header message="tns:widgetKey" part="keyVal"/>
      </input>
      <output name="bill">
        <soap12:body use="literal"/>
        <soap12:header message="tns:widgetKey" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

例7.5「SOAP ヘッダーのある orderWidgets の SOAP 1.2 バインディング」 に示されるように、ヘッダー値が入力および出力メッセージの一部であるように、例7.4「SOAP 1.2 バインディングと SOAP ヘッダー」 を変更することができます。この場合、keyVal は入出力メッセージの一部です。soap12:body 要素では、parts 属性によって、keyVal がボディーに挿入されてはならないことが指定されます。ただし、ヘッダーに挿入されます。

例7.5 SOAP ヘッダーのある orderWidgets の SOAP 1.2 バインディング

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal" parts="numOrdered"/>
        <soap12:header message="tns:widgetOrder" part="keyVal"/>
      </input>
      <output name="bill">
        <soap12:body use="literal" parts="bill"/>
        <soap12:header message="tns:widgetOrderBill" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

第8章 添付ファイル付き SOAP を使用したバイナリーデータの送信

概要

SOAP 添付ファイルは、SOAP メッセージの一部としてバイナリーデータを送信するメカニズムを提供します。添付ファイル付き SOAP を使用するには、SOAP メッセージを MIME マルチパートメッセージとして定義する必要があります。

概要

通常、SOAP メッセージにはバイナリーデータは含まれません。ただし、W3C SOAP 1.1 仕様では、MIME multipart/related メッセージを使用して SOAP メッセージのバイナリーデータを送信できます。この手法は、添付ファイル付き SOAP を使用して呼び出されます。SOAP 添付ファイルは、W3C の「SOAP Messages with Attachments Note」で定義されています。

namespace

MIME multipart/related メッセージの定義に使用される WSDL エクステンションは、namespace http://schemas.xmlsoap.org/wsdl/mime/ で定義されます。

以下の説明では、この namespace の前に mime プレフィックスが付くことを仮定しています。これを設定する WSDL definitions 要素のエントリーは 例8.1「コントラクトの MIME namespace 仕様」 にあります。

例8.1 コントラクトの MIME namespace 仕様

xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

メッセージバインディングの変更

デフォルトの SOAP バインディングでは、inputoutput、および fault 要素の最初の子要素は、データを表す SOAP メッセージのボディーを記述する soap:body 要素です。添付ファイル付き SOAP を使用する場合、soap:body 要素は mime:multipartRelated 要素に置き換えられます。

注記

WSDL は、fault メッセージへの mime:multipartRelated の使用をサポートしません。

mime:multipartRelated 要素は、メッセージボディーがバイナリーデータが含まれる可能性のあるマルチパートメッセージであることを Apache CXF に伝えます。要素の内容は、メッセージの一部とその内容を定義します。mime:multipartRelated 要素には、メッセージの個別部分を記述する 1 つ以上の mime:part 要素が含まれます。

最初の mime:part 要素には、通常デフォルトの SOAP バインディングに存在する soap:body 要素が含まれている必要があります。残りの mime:part 要素は、メッセージで送信される添付ファイルを定義します。

MIME マルチパートメッセージの記述

MIME マルチパートメッセージは、複数の mime:part 要素が含まれる mime:multipartRelated 要素を使用して記述されます。MIME マルチパートメッセージを完全に説明するには、以下を行う必要があります。

  1. MIME マルチパートメッセージとして送信する input または output メッセージで、エンクロージングメッセージの最初の子要素として mime:mulipartRelated 要素を追加します。
  2. mime:part 子要素を mime:multipartRelated 要素に追加し、その name 属性を一意の文字列に設定します。
  3. soap:body 要素を mime:part 要素の子として追加し、その属性を適切に設定します。

    注記

    コントラクトにデフォルトの SOAP バインディングがある場合、デフォルトのバインディングの対応するメッセージから soap:body 要素を MIME マルチパートメッセージにコピーできます。

  4. 別の mime:part 子要素を mime:multipartReleated 要素に追加し、その name 属性を一意の文字列に設定します。
  5. mime:content 子要素を mime:part 要素に追加して、メッセージのこの部分の内容を記述します。

    MIME メッセージ部分の内容を完全に記述するために、mime:content 要素には次の属性があります。

    表8.1 mime:content 属性

    属性説明

    part

    ネットワーク上の MIME マルチパートメッセージの内容として使用される、親メッセージ定義から WSDL メッセージ part の名前を指定します。

    +

    type

    このメッセージ部分のデータの MIME タイプ。MIME タイプは構文 type/subtype を使用してタイプまたはサブタイプとして定義されます。

    +

    image/jpeg および text/plain といった事前定義された MIME タイプは複数あります。MIME 型は、Internet Assigned Numbers Authority (IANA) で維持され、『Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies』および『Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types』に詳しく説明されています。

    +

  6. 追加の MIME 部分ごとに、ステップ [i303819] および [i303821] を繰り返します。

例8.2「添付ファイル付き SOAP を使用したコントラクト」 は、レントゲンを JPEG 形式で保存するサービスを定義する WSDL フラグメントを示しています。イメージデータ xRayxsd:base64binary として保存され、MIME マルチパートメッセージの 2 番目の部分 imageData にパッケージ化されます。入力メッセージの残り 2 つの部分であるpatientName および patientNumber は、SOAP ボディーの一部として MIME マルチパートイメージの最初の部分で送信されます。

例8.2 添付ファイル付き SOAP を使用したコントラクト

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="XrayStorage"
    targetNamespace="http://mediStor.org/x-rays"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://mediStor.org/x-rays"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <message name="storRequest">
    <part name="patientName" type="xsd:string"/>
    <part name="patientNumber" type="xsd:int"/>
    <part name="xRay" type="xsd:base64Binary"/>
  </message>
  <message name="storResponse">
    <part name="success" type="xsd:boolean"/>
  </message>

  <portType name="xRayStorage">
    <operation name="store">
      <input message="tns:storRequest" name="storRequest"/>
      <output message="tns:storResponse" name="storResponse"/>
    </operation>
  </portType>

  <binding name="xRayStorageBinding" type="tns:xRayStorage">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="store">
      <soap:operation soapAction="" style="document"/>
      <input name="storRequest">
        <mime:multipartRelated>
          <mime:part name="bodyPart">
            <soap:body use="literal"/>
          </mime:part>
          <mime:part name="imageData">
            <mime:content part="xRay" type="image/jpeg"/>
          </mime:part>
        </mime:multipartRelated>
      </input>
      <output name="storResponse">
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="xRayStorageService">
    <port binding="tns:xRayStorageBinding" name="xRayStoragePort">
      <soap:address location="http://localhost:9000"/>
    </port>
  </service>
</definitions>

第9章 SOAP MTOM によるバイナリーデータの送信

概要

SOAP Message Transmission Optimization Mechanism (MTOM) は、添付ファイル付き SOAP に置き換わる、XML メッセージの一部としてバイナリーデータを送信するメカニズムです。MTOM を Apache CXF で使用するには、正しいスキーマ型をサービスのコントラクトに追加し、MTOM 最適化を有効にする必要があります。

9.1. MTOM の概要

SOAP Message Transmission Optimization Mechanism (MTOM) は、SOAP メッセージの一部としてバイナリーデータ送信するための最適化の方法を指定します。添付ファイル付き SOAP とは異なり、MTOM では、バイナリーデータの送信に XML-binary Optimized Packaging (XOP) パッケージを使用する必要があります。MTOM を使用してバイナリーデータを送信する場合には、SOAP バインディングの一部として MIME Multipart/Related メッセージを完全に定義する必要はありません。ただし、以下を行う必要があります。

  1. 添付ファイルとして送信するデータにアノテーション を付けます。

    WSDL またはデータを実装する Java クラスにアノテーションを付けることができます。

  2. ランタイムの MTOM サポートを有効 にします。

    これは、プログラムまたは設定のいずれかで実行できます。

  3. 添付ファイルとして渡されるデータの DataHandler を開発します。

    注記

    DataHandler の開発は、本ガイドの対象外です。

9.2. MTOM を使用するためのデータ型へのアノテーション付け

概要

WSDL では、イメージファイルやサウンドファイルなど、バイナリーデータのブロックに渡すデータ型を定義する場合、xsd:base64Binary 型のデータの要素を定義します。デフォルトでは、xsd:base64Binary 型のすべての要素によって、MTOM を使用してシリアライズ可能な byte[] が生成されます。ただし、コードジェネレーターのデフォルト動作は、シリアル化を完全に活用しません。

MTOM を活用するには、アノテーションをサービスの WSDL ドキュメントまたはバイナリーデータ構造を実装する JAXB クラスに追加する必要があります。アノテーションを WSDL ドキュメントに追加すると、コードジェネレーターがバイナリーデータのストリーミングデータハンドラーを生成するように強制されます。JAXB クラスのアノテーションを付けるには、適切なコンテンツ型を指定し、バイナリーデータが含まれるフィールドの型指定を変更が必要になることもあります。

WSDL first

例9.1「MTOM のメッセージ」 は、1 つの文字列フィールド、1 つの整数フィールド、およびバイナリーフィールドが含まれるメッセージを使用する Web サービスの WSDL ドキュメントを示しています。バイナリーフィールドは、大きなイメージファイルを格納することを目的としているため、通常の SOAP メッセージのパートとして送信することは適切ではありません。

例9.1 MTOM のメッセージ

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="XrayStorage"
    targetNamespace="http://mediStor.org/x-rays"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://mediStor.org/x-rays"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:xsd1="http://mediStor.org/types/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <types>
    <schema targetNamespace="http://mediStor.org/types/"
            xmlns="http://www.w3.org/2001/XMLSchema">
      <complexType name="xRayType">
        <sequence>
          <element name="patientName" type="xsd:string" />
          <element name="patientNumber" type="xsd:int" />
          <element name="imageData" type="xsd:base64Binary" />
        </sequence>
      </complexType>
      <element name="xRay" type="xsd1:xRayType" />
    </schema>
  </types>

  <message name="storRequest">
    <part name="record" element="xsd1:xRay"/>
  </message>
  <message name="storResponse">
    <part name="success" type="xsd:boolean"/>
  </message>

  <portType name="xRayStorage">
    <operation name="store">
      <input message="tns:storRequest" name="storRequest"/>
      <output message="tns:storResponse" name="storResponse"/>
    </operation>
  </portType>

  <binding name="xRayStorageSOAPBinding" type="tns:xRayStorage">
    <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="store">
      <soap12:operation soapAction="" style="document"/>
      <input name="storRequest">
        <soap12:body use="literal"/>
      </input>
      <output name="storResponse">
        <soap12:body use="literal"/>
      </output>
    </operation>
  </binding>
  ...
</definitions>

MTOM を使用してメッセージのバイナリー部分を最適化された添付ファイルとして送信する場合は、xmime:expectedContentTypes 属性をバイナリデータが含まれる要素に属性を追加する必要があります。この属性は http://www.w3.org/2005/05/xmlmime namespace に定義され、要素に含まれることが予想される MIME タイプを指定します。MIME タイプのカンマ区切りの一覧を指定できます。この属性の設定により、コードジェネレーターによるデータの JAXB クラスの作成方法が変更されます。ほとんどの MIME タイプでは、コードジェネレーターは DataHandler を作成します。イメージ用のものなど、一部の MIME タイプには、マッピングが定義されています。

注記

MIME タイプは、Internet Assigned Numbers Authority (IANA) で維持され、『Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies』および『Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types』に詳しく説明されています。

ほとんどの場合は application/octet-stream を指定します。

例9.2「MTOM のバイナリーデータ」 は、MTOM の使用のするために 例9.1「MTOM のメッセージ」 から xRayType を変更する方法を表しています。

例9.2 MTOM のバイナリーデータ

...
  <types>
    <schema targetNamespace="http://mediStor.org/types/"
            xmlns="http://www.w3.org/2001/XMLSchema"
            xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
      <complexType name="xRayType">
        <sequence>
          <element name="patientName" type="xsd:string" />
          <element name="patientNumber" type="xsd:int" />
          <element name="imageData" type="xsd:base64Binary"
                   xmime:expectedContentTypes="application/octet-stream"/>
        </sequence>
      </complexType>
      <element name="xRay" type="xsd1:xRayType" />
    </schema>
  </types>
...

xRayType 用に生成された JAXB クラスには byte[] が含まれなくなりました。代わりに、コードジェネレーターは xmime:expectedContentTypes 属性を認識し、imageData フィールドの DataHandler を生成します。

注記

MTOM を使用するには binding 要素を変更する必要はありません。ランタイムは、データ送信時に適切な変更を加えます。

Java first

Java を初めて開発する場合は、以下を行うことで JAXB クラス MTOM を準備できます。

  1. バイナリーデータを保持するフィールドが DataHandler であることを確認します。
  2. MTOM 添付ファイルとしてストリーミングするデータを含むフィールドに @XmlMimeType() アノテーションを追加します。

例9.3「MTOM の JAXB クラス」 は、MTOM を使用するためにアノテーション付けされた JAXB クラスを表しています。

例9.3 MTOM の JAXB クラス

@XmlType
public class XRayType {
    protected String patientName;
    protected int patientNumber;
    @XmlMimeType("application/octet-stream")
    protected DataHandler imageData;
  ...
}

9.3. MTOM の有効化

デフォルトでは、Apache CXF ランタイムは MTOM サポートを有効にしません。これは、通常の SOAP メッセージの一部として、または最適化されていない添付ファイルとしてすべてのバイナリーデータを送信します。MTOM サポートを有効にするには、プログラムまたは設定を使用します。

9.3.1. JAX-WS API の使用

概要

サービスプロバイダーとコンシューマーの両方で、MTOM 最適化が有効になっている必要があります。JAX-WS API は、各型のエンドポイントに異なるメカニズムを提供します。

サービスプロバイダー

JAX-WS API を使用してサービスプロバイダーを公開した場合、以下のようにランタイムの MTOM サポートを有効にします。

  1. 公開されたサービスの Endpoint オブジェクトにアクセスします。

    Endpoint オブジェクトにアクセスするための最も簡単な方法として、エンドポイントをパブリッシュするときが挙げられます。詳細は 31章サービスの公開 を参照してください。

  2. 例9.4「エンドポイントからの SOAP バインディングの取得」 にあるように、getBinding() メソッドを使用して Endpoint から SOAP バインディングを取得します。

    例9.4 エンドポイントからの SOAP バインディングの取得

    // Endpoint ep is declared previously
    SOAPBinding binding = (SOAPBinding)ep.getBinding();

    MTOM プロパティーにアクセスするには、返されたバインディングオブジェクトを SOAPBinding オブジェクトにキャストする必要があります。

  3. 例9.5「サービスプロバイダーの MTOM が有効なプロパティーの設定」 に示されるように、バインディングの setMTOMEnabled() メソッドを使用してバインディングの MTOM enabled プロパティーを true に設定します。

    例9.5 サービスプロバイダーの MTOM が有効なプロパティーの設定

    binding.setMTOMEnabled(true);

コンシューマー

MTOM が JAX-WS コンシューマーを有効にするには、以下を行う必要があります。

  1. コンシューマーのプロキシーを BindingProvider オブジェクトにキャストします。

    コンシューマープロキシーを取得する方法は、25章WSDL コントラクトを使用しないコンシューマーの開発 または 28章WSDL コントラクトからのコンシューマーの開発 を参照してください。

  2. 例9.6「BindingProvider からの SOAP バインディングの取得」 にあるように、getBinding() メソッドを使用して BindingProvider から SOAP バインディングを取得します。

    例9.6 BindingProvider からの SOAP バインディングの取得

    // BindingProvider bp declared previously
    SOAPBinding binding = (SOAPBinding)bp.getBinding();
  3. 例9.7「コンシューマーの MTOM enabled プロパティーの設定」 にあるように、バインディングの setMTOMEnabled() メソッドを使用してバインディングの MTOM enabled プロパティーを true に設定します。

    例9.7 コンシューマーの MTOM enabled プロパティーの設定

    binding.setMTOMEnabled(true);

9.3.2. 設定の使用

概要

コンテナーへのデプロイ時に XML を使用してサービスを公開する場合は、エンドポイントの設定ファイルでエンドポイントの MTOM サポートを有効にできます。エンドポイントの設定に関する詳細は、パートIV「Web サービスのエンドポイントの設定」 を参照してください。

手順

MTOM プロパティーは、エンドポイントの jaxws:endpoint 要素で設定されます。MTOM を有効にするには、以下を実行します。

  1. jaxws:property 子要素をエンドポイントの jaxws:endpoint 要素に追加します。
  2. entry 子要素を jaxws:property 要素に追加します。
  3. entry 要素の key 属性を mtom-enabled に設定します。
  4. entry 要素の value 属性を true に設定します。

例9.8「MTOM を有効にする設定」 は、MTOM が有効になっているエンドポイントを示しています。

例9.8 MTOM を有効にする設定

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                           http://cxf.apache.org/jaxws http://cxf.apache.org/schema/jaxws.xsd">

  <jaxws:endpoint id="xRayStorage"
                  implementor="demo.spring.xRayStorImpl"
                  address="http://localhost/xRayStorage">
    <jaxws:properties>
      <entry key="mtom-enabled" value="true"/>
    </jaxws:properties>
  </jaxws:endpoint>
</beans>

第10章 XML ドキュメントの使用

概要

純粋な XML ペイロード形式は、SOAP エンベロープのオーバーヘッドなしでストレート XML ドキュメントを使用してサービスがデータを交換できるようにすることで、SOAP バインディングの代替手段を提供します。

XML バインディング namespace

XML 形式のバインディングの記述に使用されるエクステンションは、namespace http://cxf.apache.org/bindings/xformat で定義されています。Apache CXF ツールは、プレフィックス xformat を使用して XML バインディングエクステンションを表します。コントラクトに以下の行を追加します。

xmlns:xformat="http://cxf.apache.org/bindings/xformat"

手動編集

インターフェースを純粋な XML ペイロードフォーマットにマッピングするには、以下を行います。

  1. namespace 宣言を追加して XML バインディングを定義するエクステンションを含めます。「XML バインディング namespace」 を参照してください。
  2. XML バインディングを保持するための標準 WSDL binding 要素をコントラクトに追加し、バインディングに一意の name を付け、バインドされたインターフェースを表す WSDL portType 要素の名前を指定します。
  3. xformat:binding 子要素を binding 要素に追加し、メッセージが SOAP エンベロープなしで純粋な XML ドキュメントとして処理されることを特定します。
  4. 必要に応じて、xformat:binding 要素の rootNode 属性を有効な QName に設定します。rootNode 属性の影響の詳細は、「ネットワーク上の XML メッセージ」 を参照してください。
  5. バインドされたインターフェースで定義された各操作に対して、標準の WSDL operation 要素を追加して、操作のメッセージのバインディング情報を保持します。
  6. バインディングに追加された操作ごとに inputoutput、および fault 子要素を追加して、操作によって使用されるメッセージを表します。

    これらの要素は、論理操作のインターフェース定義で定義されたメッセージに対応します。

  7. 必要に応じて、有効な rootNode 属性がある xformat:body 要素を追加された inputoutput、および fault 要素に追加して、バインディングレベルで設定された rootNode の値を上書きします。
注記

void を返す操作の出力メッセージなど、メッセージのパートがない場合は、ネットワークで書き込んだメッセージが有効な空の XML ドキュメントであるように、メッセージの rootNode 属性を設定する必要があります。

ネットワーク上の XML メッセージ

SOAP エンベロープ を使用せずに、インターフェースのメッセージが XML ドキュメントとして渡されるよう指定する場合、メッセージがネットワークで書き込まれるときにメッセージが有効な XML ドキュメントの形式になるように注意する必要があります。また、XML ドキュメントを受信する Apache CXF 以外の参加者が Apache CXF によって生成されたメッセージを理解していることを確認する必要があります。

両問題を解決する簡単な方法は、グローバル xformat:binding 要素または個別のメッセージの xformat:body 要素でオプションの rootNode 属性を使用することです。rootNode 属性は、Apache CXF が生成した XML ドキュメントのルートノードとして機能する要素の QName を指定します。rootNode 属性が設定されていない場合、Apache CXF は doc スタイルのメッセージを使用する場合はメッセージ部分のルート要素として使用し、rpc スタイルのメッセージを使用する場合はルート要素としてメッセージパート名を使用する要素を使用します。

たとえば、rootNode 属性が 例10.1「有効な XML バインディングメッセージ」 で定義されたメッセージを設定しないと、ルート要素 lineNumber を持つ XML ドキュメントが生成されます。

例10.1 有効な XML バインディングメッセージ

<type ... >
  ...
  <element name="operatorID" type="xsd:int"/>
  ...
</types>
<message name="operator">
  <part name="lineNumber" element="ns1:operatorID"/>
</message>

1 つのパートを持つメッセージでは、rootNode 属性が設定されていなくても Apache CXF は常に有効な XML ドキュメントを生成します。ただし、例10.2「無効な XML バインディングメッセージ」 のメッセージは無効な XML ドキュメントを生成します。

例10.2 無効な XML バインディングメッセージ

<types>
  ...
  <element name="pairName" type="xsd:string"/>
  <element name="entryNum" type="xsd:int"/>
  ...
</types>

<message name="matildas">
  <part name="dancing" element="ns1:pairName"/>
  <part name="number" element="ns1:entryNum"/>
</message>

XML バインディングで指定された rootNode 属性がない場合、Apache CXF は 例10.2「無効な XML バインディングメッセージ」 で定義されたメッセージに対して 例10.3「無効な XML ドキュメント」 のような XML ドキュメントを生成します。生成された XML ドキュメントは pairNameentryNum の 2 つのルート要素があるため無効です。

例10.3 無効な XML ドキュメント

<pairName>
  Fred&Linda
</pairName>
<entryNum>
  123
</entryNum>

例10.4「rootNode が設定された XML バインディング」 に示されているように、rootNode 属性を設定すると、Apache CXF は指定されたルート要素で要素をラップします。この例では、rootNode 属性はバインディング全体に対して定義され、ルート要素に entrants という名前を指定しています。

例10.4 rootNode が設定された XML バインディング

<portType name="danceParty">
  <operation name="register">
    <input message="tns:matildas" name="contestant"/>
  </operation>
</portType>

<binding name="matildaXMLBinding" type="tns:dancingMatildas">
  <xmlformat:binding rootNode="entrants"/>
  <operation name="register">
    <input name="contestant"/>
    <output name="entered"/>
</binding>

入力メッセージから生成された XML ドキュメントは 例10.5「rootNode 属性を使用して生成された XML ドキュメント」 と似ています。XML ドキュメントに、ルート要素が 1 つしかないことに注意してください。

例10.5 rootNode 属性を使用して生成された XML ドキュメント

<entrants>
  <pairName>
    Fred&Linda
  <entryNum>
    123
  </entryNum>
</entrants>

バインドの rootNode 属性設定の上書き

また、メッセージバインディング内の xformat:body 要素を使用して、個別のメッセージの rootNode 属性を設定したり、特定のメッセージのグローバル設定をオーバーライドすることもできます。たとえば、例10.4「rootNode が設定された XML バインディング」 で定義した出力メッセージに、入力メッセージとは異なるルート要素を持たせる場合は、例10.6「xformat:body の使用」 に示すように、バインディングのルート要素をオーバーライドできます。

例10.6 xformat:body の使用

<binding name="matildaXMLBinding" type="tns:dancingMatildas">
  <xmlformat:binding rootNode="entrants"/>
  <operation name="register">
    <input name="contestant"/>
    <output name="entered">
      <xformat:body rootNode="entryStatus" />
    </output>
  </operation>
</binding>

パート III. Web サービストランスポート

ここでは、Apache CXF トランスポートを WSDL ドキュメントに追加する方法を説明します。

第11章 WSDL でのエンドポイントの定義方法の理解

概要

エンドポイントは、インスタンス化されたサービスを表します。これらは、バインディングと、エンドポイントの公開に使用されるネットワークの詳細を組み合わせることで定義されます。

概要

エンドポイントは、サービスの物理マニフェストとして考えることができます。これは、サービスによって使用される論理データの物理表現を指定するバインディングと、他のエンドポイントによってサービスを通信可能にするために使用される物理接続の詳細を定義するネットワークの詳細を組み合わせたものです。

注記

CXF プロバイダーは、クライアントに対応する CXF コンシューマーのサーバーです。ルートの開始エンドポイントとして CXF (camel-cxf) コンポーネントを使用している場合、エンドポイントは Camel コンシューマーと CXF プロバイダーの両方になります。ルートの終了エンドポイントとして Camel CXF コンポーネントを使用している場合、エンドポイントは Camel プロデューサーと CXF コンシューマーの両方になります。

エンドポイントおよびサービス

バインディングが 1 つのインターフェースのみをマップできるのと同様に、エンドポイントは 1 つのサービスにのみマッピングできます。ただし、サービスは任意の数のエンドポイントでマニフェストできます。たとえば、4 つの異なるエンドポイントによってマニフェストされたチケット販売サービスを定義できます。ただし、チケットの販売サービスとウィジェット販売サービスの両方がマニフェストされた単一のエンドポイントを持つことはできません。

WSDL 要素

エンドポイントは、WSDL service 要素と WSDL port 要素の組み合わせを使用してコントラクトに定義されます。service 要素は、関連する port 要素のコレクションです。port 要素は、実際のエンドポイントを定義します。

WSDL service 要素には一意の名前を指定する 1 つの属性 name があります。service 要素は、関連する port 要素のコレクションの親要素として使用されます。WSDL では、port 要素の関連性について何も指定しません。適切であると見なされる方法で port 要素を関連付けることができます。

WSDL port 要素には、エンドポイントで使用されるバインディングを指定する binding 属性があり、これは wsdl:binding 要素への参照です。また、name 属性も含まれます。これは、すべてのポート間で一意の名前を提供する必須の属性です。port 要素は、エンドポイントによって使用される実際のトランスポートの詳細を指定する要素の親要素です。トランスポートの詳細を指定するために使用される要素は、以下のセクションで説明します。

コントラクトへのエンドポイントの追加

Apache CXF は、事前定義されたサービスインターフェースおよびバインディング組み合わせのエンドポイントを生成できるコマンドラインツールを提供します。

このツールにより、コントラクトに適切な要素が追加されます。ただし、エンドポイントの定義に使用されるさまざまなトランスポートがどのように機能するかについて、ある程度理解しておくことが推奨されます。

テキストエディターを使用して、エンドポイントをコントラクトに追加することもできます。コントラクトを編集する場合は、コントラクトが有効であることを確認する必要があります。

サポートされるトランスポート

エンドポイント定義は、Apache CXF がサポートするトランスポートごとに定義されたエクステンションを使用して構築されます。これには、以下のトランスポートが含まれます。

  • HTTP
  • CORBA
  • Java Messaging Service

第12章 HTTP の使用

概要

HTTP は Web の基盤となるトランスポートです。エンドポイント間の通信に、標準化された、堅牢かつ柔軟なプラットフォームを提供します。これらの要因により、ほとんどの WS-* 仕様で想定されるトランスポートであり、RESTful アーキテクチャーに不可欠です。

12.1. 基本的な HTTP エンドポイントの追加

代替 HTTP ランタイム

Apache CXF は、以下の代替 HTTP ランタイム実装をサポートします。

Netty HTTP URL

通常、HTTP エンドポイントは、クラスパスに含まれている HTTP ランタイム (Undertow または Netty のいずれか) を使用します。ただし、Undertow ランタイムと Netty ランタイムの両方がクラスパスに含まれている場合は、デフォルトで Undertow ランタイムが使用されるため、Netty ランタイムを使用するタイミングを明示的に指定する必要があります。

複数の HTTP ランタイムがクラスパスで利用可能な場合は、以下の形式でエンドポイント URL を指定して Undertow ランタイムを選択できます。

netty://http://RestOfURL

ペイロード型

HTTP エンドポイントのアドレスを指定するには、使用しているペイロード形式に応じて 3 つの方法があります。

  • SOAP 1.1 は標準化された soap:address 要素を使用します。
  • SOAP 1.2 は soap12:address 要素を使用します。
  • その他のペイロード形式はすべて http:address element. を使用します。
注記

Camel 2.16.0 リリース以降、Apache Camel CXF Payload はそのままのストリームキャッシュをサポートします。

SOAP 1.1

HTTP で SOAP 1.1 メッセージを送信する場合は、SOAP 1.1address 要素を使用してエンドポイントのアドレスを指定する必要があります。エンドポイントのアドレスを URL として指定する 1 つの属性 location があります。SOAP 1.1 address 要素は、namespace http://schemas.xmlsoap.org/wsdl/soap/ に定義されています。

例12.1「SOAP 1.1 port 要素」 は、HTTP で SOAP 1.1 メッセージを送信するために使用される port 要素を示しています。

例12.1 SOAP 1.1 port 要素

<definitions ...
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" ...>
  ...
  <service name="SOAP11Service">
    <port binding="SOAP11Binding" name="SOAP11Port">
      <soap:address location="http://artie.com/index.xml">
    </port>
  </service>
  ...
<definitions>

SOAP 1.2

HTTP で SOAP 1.2 メッセージを送信する場合は、SOAP 1.2address 要素を使用してエンドポイントのアドレスを指定する必要があります。エンドポイントのアドレスを URL として指定する 1 つの属性 location があります。SOAP 1.2 address 要素は namespace http://schemas.xmlsoap.org/wsdl/soap12/ に定義されています。

例12.2「SOAP 1.2 port 要素」 は、HTTP で SOAP 1.2 メッセージを送信するために使用される port 要素を示しています。

例12.2 SOAP 1.2 port 要素

<definitions ...
             xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" ... >
  <service name="SOAP12Service">
    <port binding="SOAP12Binding" name="SOAP12Port">
      <soap12:address location="http://artie.com/index.xml">
    </port>
  </service>
  ...
</definitions>

その他のメッセージ型

メッセージが SOAP 以外のペイロードフォーマットにマッピングされている場合は、HTTP address 要素を使用してエンドポイントのアドレスを指定する必要があります。エンドポイントのアドレスを URL として指定する 1 つの属性 location があります。HTTP address 要素は namespace http://schemas.xmlsoap.org/wsdl/http/ で定義されます。

例12.3「HTTP port 要素」 は、XML メッセージの送信に使用される port 要素を示しています。

例12.3 HTTP port 要素

<definitions ...
             xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" ... >
  <service name="HTTPService">
    <port binding="HTTPBinding" name="HTTPPort">
      <http:address location="http://artie.com/index.xml">
    </port>
  </service>
  ...
</definitions>

12.2. コンシューマーの設定

12.2.1. HTTP コンシューマーエンドポイントのメカニズム

HTTP コンシューマエンドポイントは、エンドポイントがリダイレクト応答を自動的に受け入れるかどうか、エンドポイントがチャンクを使用できるかどうか、エンドポイントがキープアライブを要求するかどうか、エンドポイントがプロキシーと対話する方法など、複数の HTTP コネクション属性を指定できます。HTTP コネクションプロパティーのほかに、HTTP コンシューマーエンドポイントでセキュア化の方法を指定できます。

コンシューマーエンドポイントは 2 つのメカニズムを使用して設定できます。

12.2.2. 設定の使用

namespace

HTTP コンシューマーエンドポイントの設定に使用される要素は、namespace http://cxf.apache.org/transports/http/configuration で定義されます。通常、プレフィックス http-conf を使用して参照されます。HTTP 設定要素を使用するには、例12.4「HTTP コンシューマー設定 namespace」 にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.4 HTTP コンシューマー設定 namespace

<beans ...
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
       ...
       xsi:schemaLocation="...
                           http://cxf.apache.org/transports/http/configuration
                              http://cxf.apache.org/schemas/configuration/http-conf.xsd
                          ...">

Undertow ランタイムまたは Netty ランタイム

http-conf namespace の要素を使用して、Undertow ランタイムまたは Netty ランタイムを設定できます。

conduit 要素

http-conf:conduit 要素およびその子を使用して HTTP コンシューマーエンドポイントを設定します。http-conf:conduit 要素は、エンドポイントに対応する WSDL port 要素を指定する単一の属性 name を取ります。name 属性の値は、portQName`.http-conduit` の形式を取ります。例12.5「http-conf:conduit 要素」 は、エンドポイントのターゲット namespace が http://widgets.widgetvendor.net の場合に WSDL フラグメント <port binding="widgetSOAPBinding" name="widgetSOAPPort> によって指定されるエンドポイントの設定を追加するために使用される http-conf:conduit 要素を示しています。

例12.5 http-conf:conduit 要素

...
  <http-conf:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-conduit">
    ...
  </http-conf:conduit>
...

http-conf:conduit 要素には設定情報を指定する子要素があります。これらについては、表12.1「HTTP コンシューマーエンドポイントの設定に使用される要素」 を参照してください。

表12.1 HTTP コンシューマーエンドポイントの設定に使用される要素

要素説明

http-conf:client

タイムアウト、キープアライブリクエスト、コンテンツ型など、HTTP コネクションプロパティーを指定します。「client 要素」 を参照してください。

http-conf:authorization

エンドポイントが先行で使用する Basic 認証方法を設定するパラメーターを指定します。優先される方法は http-conf:basicAuthSupplier オブジェクトを提供することです。

http-conf:proxyAuthorization

送信 HTTP プロキシーサーバーに対して Basic 認証を設定するパラメーターを指定します。

http-conf:tlsClientParameters

SSL/TLS の設定に使用されるパラメーターを指定します。

http-conf:basicAuthSupplier

先制的または 401 HTTP チャレンジに応答して、エンドポイントによって使用される Basic 認証情報を提供するオブジェクトの Bean 参照またはクラス名を指定します。

http-conf:trustDecider

情報送信前に HTTPS サービスプロバイダーとのコネクションに対して信頼を確立するために HTTP(S) URLConnection オブジェクトをチェックするオブジェクトの Bean 参照またはクラス名を指定します。

client 要素

http-conf:client 要素は、コンシューマーエンドポイントの HTTP コネクションのセキュリティー以外のプロパティーを設定するために使用されます。表12.2「HTTP コンシューマー設定属性」 に記載されているその属性は、コネクションのプロパティーを指定します。

表12.2 HTTP コンシューマー設定属性

属性説明

ConnectionTimeout

コンシューマーがタイムアウトするまでにコネクションを確立しようとする時間 (ミリ秒単位) を指定します。デフォルトは 30000 です。

0 を指定すると、コンシューマーはリクエストの送信を無期限に続行します。

ReceiveTimeout

応答がタイムアウトするまでコンシューマーが待機する時間をミリ秒単位で指定します。デフォルトは 30000 です。

0 を指定するとコンシューマーは無期限に待機します。

AutoRedirect

コンシューマがサーバー発行のリダイレクトを自動的にフォローするかどうかを指定します。デフォルトは false です。

MaxRetransmits

コンシューマがリダイレクトを満たすためにリクエストを再送信する最大回数を指定します。デフォルトは -1 で、無制限の再送信を許可します。

AllowChunking

コンシューマーがチャンクを使用してリクエストを送信するかどうかを指定します。デフォルトは true で、リクエストの送信時にコンシューマーがチャンクを使用することを指定します。

次のいずれかに当てはまる場合、チャンクは使用できません。

  • http-conf:basicAuthSupplier が、クレデンシャルを先制的に提供するように設定されている。
  • AutoRedirecttrue に設定されている。

いずれの場合も、AllowChunking の値は無視され、チャンクは禁止されます。

Accept

コンシューマが処理する準備ができているメディア型を指定します。値は HTTP Accept プロパティーの値として使用されます。属性の値は、MIME (Multipurpose Internet Mail Extensions) 型を使用して指定されます。

AcceptLanguage

コンシューマが応答を受信する目的で優先される言語 (アメリカ英語など) を指定します。値は HTTP AcceptLanguage プロパティーの値として使用されます。

言語タグは、国際標準化機構 (ISO) によって規制されており、通常は ISO-639 規格で定められた言語コードと、ISO-3166 規格で定められた国コードをハイフンで区切って組み合わせて形成されます。たとえば、en-US はアメリカ英語を表します。

AcceptEncoding

コンシューマが処理する準備ができているコンテンツエンコーディングを指定します。コンテンツエンコーディングラベルは、Internet Assigned Numbers Authority (IANA) によって規制されています。値は HTTP AcceptEncoding プロパティーの値として使用されます。

ContentType

メッセージのボディーで送信されるデータのメディア型を指定します。メディア型は、MIME 型を使用して指定されます。値は HTTP ContentType プロパティーの値として使用されます。デフォルトは text/xml です。

Web サービスの場合、これを text/xml に設定する必要があります。クライアントが CGI スクリプトに HTML フォームデータを送信している場合、これを application/x-www-form-urlencoded に設定する必要があります。HTTP POST リクエストが固定されたペイロードフォーマットにバインドされている場合 (SOAP ではなく)、コンテンツ型は通常 application/octet-stream に設定されます。

Host

要求が呼び出されるリソースのインターネットホストおよびポート番号を指定します。値は HTTP Host プロパティーの値として使用されます。

通常、この属性は必要ありません。これは、特定の DNS シナリオまたはアプリケーション設計でのみ必要です。たとえば、クライアントがクラスターでどのホストを優先するか (つまり、仮想サーバーの同じインターネットプロトコル (IP) アドレスへのマッピング) を示します。

Connection

各要求/応答ダイアログの後で、特定のコネクションを開いたままにするか、閉じるかを指定します。有効な値は 2 つあります。

  • Keep-Alive - 最初のリクエスト/応答シーケンスの後にコンシューマーが開いたままにするように指定します。サーバーがこれを有効にする場合、コンシューマーがそれを閉じるまでコネクションは開いた状態になります。
  • close (デフォルト) - 各リクエスト/応答シーケンスの後にサーバーへのコネクションが閉じられるよう指定します。

CacheControl

コンシューマからサービスプロバイダーへのリクエストで構成されるチェーンに関与するキャッシュが厳守しなければならない動作に関するディレクティブを指定します。「コンシューマーキャッシュ制御ディレクティブ」 を参照してください。

Cookie

すべてのリクエストで送信される静的クッキーを指定します。

BrowserType

リクエストの発信元のブラウザーに関する情報を指定します。World Wide Web Consortium (W3C) からの HTTP 仕様では、ユーザーエージェント とも呼ばれます。一部のサーバーは、リクエストを送信しているクライアントを基にして最適化されています。

Referer

特定のサービスでリクエストを行うようにコンシューマに指示したリソースの URL を指定します。値は HTTP Referer プロパティーの値として使用されます。

この HTTP プロパティーは、ブラウザユーザーが URL を入力した結果のリクエストではなく、ハイパーリンクをクリックした結果のリクエストである場合に使用されます。これにより、サーバーは以前のタスクフローに基づいて処理を最適化でき、ロギング、最適化されたキャッシュ、廃止されたリンクや入力ミスのリンクの追跡などのために、リソースへのバックリンクの一覧を生成できます。ただし、通常は web サービスアプリケーションでは使用されません。

AutoRedirect 属性が true に設定され、リクエストがリダイレクトされると、Referer 属性で指定された値が上書きされます。HTTP Referer プロパティーの値は、コンシューマーの元のリクエストをリダイレクトしたサービスの URL に設定されます。

DecoupledEndpoint

個別のプロバイダー→コンシューマーコネクション上で応答を受信するための分離エンドポイントの URL を指定します。分離されたエンドポイントの使用に関する詳細は、「分離モードでの HTTP トランスポートの使用」 を参照してください。

分散されたエンドポイントが機能するには、コンシューマーエンドポイントとサービスプロバイダーエンドポイントの両方を WS-Addressing を使用するように設定する必要があります。

ProxyServer

要求がルーティングされるプロキシーサーバーの URL を指定します。

ProxyServerPort

要求がルーティングされるプロキシーサーバーのポート番号を指定します。

ProxyServerType

要求をルーティングするために使用されるプロキシーサーバーの型を指定します。有効な値は次のとおりです。

  • HTTP(デフォルト)
  • SOCKS

例12.6「HTTP コンシューマーエンドポイントの設定」 は、リクエスト間で、プロバイダーへのコネクションを開いたままにする HTTP コンシューマーエンドポイントの設定を示しています。これは、呼び出しごとにリクエストを 1 度だけ再送信し、チャンキングストリームを使用できません。

例12.6 HTTP コンシューマーエンドポイントの設定

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
       xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
                             http://cxf.apache.org/schemas/configuration/http-conf.xsd
                           http://www.springframework.org/schema/beans
                             http://www.springframework.org/schema/beans/spring-beans.xsd">

  <http-conf:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit">
    <http-conf:client Connection="Keep-Alive"
                      MaxRetransmits="1"
                      AllowChunking="false" />
  </http-conf:conduit>
</beans>

詳細情報

HTTP コンジットの詳細は、16章コンジット を参照してください。

12.2.3. WSDL の使用

namespace

HTTP コンシューマーエンドポイントの設定に使用される WSDL エクステンション要素は namespace http://cxf.apache.org/transports/http/configuration で定義されます。通常、プレフィックス http-conf を使用して参照されます。HTTP 設定要素を使用するには、例12.7「HTTP コンシューマー WSDL 要素の namespace」 にある行をエンドポイントの WSDL ドキュメントの definitions 要素に追加する必要があります。

例12.7 HTTP コンシューマー WSDL 要素の namespace

<definitions ...
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"

Undertow ランタイムまたは Netty ランタイム

http-conf namespace の要素を使用して、Undertow ランタイムまたは Netty ランタイムを設定できます。

client 要素

http-conf:client 要素は、WSDL ドキュメントで HTTP コンシューマーのコネクションプロパティーを指定するために使用されます。http-conf:client 要素は WSDL port 要素の子です。設定ファイルで使用される client 要素と同じ属性があります。属性は 表12.2「HTTP コンシューマー設定属性」 に記載されています。

例12.8「HTTP コンシューマーエンドポイントを設定する WSDL」 は、HTTP コンシューマーエンドポイントがキャッシュと対話しないよう指定する WSDL フラグメントを示しています。

例12.8 HTTP コンシューマーエンドポイントを設定する WSDL

<service ... >
  <port ... >
    <soap:address ... />
    <http-conf:client CacheControl="no-cache" />
  </port>
</service>

12.2.4. コンシューマーキャッシュ制御ディレクティブ

表12.3「http-conf:client キャッシュ制御ディレクティブ」 は、HTTP コンシューマーによってサポートされるキャッシュ制御ディレクティブを表しています。

表12.3 http-conf:client キャッシュ制御ディレクティブ

ディレクティブ動作

no-cache

キャッシュは、サーバーで応答を再検証せずに、後続のリクエストを満たすために特定の応答を使用することはできません。特定の応答ヘッダーフィールドがこの値で指定された場合、制限は応答内のこれらのヘッダーフィールドにのみ適用されます。応答ヘッダーフィールドが指定されていない場合、制限は応答全体に適用されます。

no-store

キャッシュは、応答の一部またはこれを呼び出したリクエストの一部を保存してはいけません。

max-age

コンシューマーは、経過時間が指定された秒数を超えないレスポンスを受け入れることができます。

max-stale

コンシューマーは、有効期限を超えたレスポンスを受け取ることができます。値が max-stale に割り当てられる場合、コンシューマーはその応答を許可できる応答の有効期限を超える秒数を表します。値が割り当てられない場合、コンシューマーはあらゆる経過時間の陳腐応答を受け入れることができます。

min-fresh

コンシューマーは、少なくとも指定された秒数間は新しい状態である応答を要求します。

no-transform

キャッシュは、プロバイダーとコンシューマー間の応答にあるコンテンツのメディア型または場所を変更してはなりません。

only-if-cached

キャッシュは現在キャッシュに格納されている応答のみを返す必要があり、再読み込みまたは再検証が必要な応答を返してはなりません。

cache-extension

他のキャッシュディレクティブへの追加のエクステンションを指定します。エクステンションは情報または動作です。拡張されたディレクティブは、標準ディレクティブのコンテキストで指定されるため、拡張されたディレクティブを理解しないアプリケーションは、標準ディレクティブで義務付けられる動作に準拠することができます。

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

12.3.1. HTTP サービスプロバイダーのメカニズム

HTTP サービスプロバイダーのエンドポイントは、キープアライブ要求を尊重するかどうか、キャッシュとの対話方法、コンシューマとの通信におけるエラーの許容度など、複数の HTTP コネクション属性を指定できます。

サービスプロバイダーのエンドポイントは、2 つのメカニズムを使用して設定できます。

12.3.2. 設定の使用

namespace

HTTP プロバイダーエンドポイントの設定に使用される要素は、namespace http://cxf.apache.org/transports/http/configuration で定義されます。通常、プレフィックス http-conf を使用して参照されます。HTTP 設定要素を使用するには、例12.9「HTTP プロバイダー設定 namespace」 にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.9 HTTP プロバイダー設定 namespace

<beans ...
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
       ...
       xsi:schemaLocation="...
                           http://cxf.apache.org/transports/http/configuration
                              http://cxf.apache.org/schemas/configuration/http-conf.xsd
                          ...">

Undertow ランタイムまたは Netty ランタイム

http-conf namespace の要素を使用して、Undertow ランタイムまたは Netty ランタイムを設定できます。

destination 要素

http-conf:destination 要素およびその子を使用して HTTP サービスプロバイダーエンドポイントを設定します。http-conf:destination 要素は、エンドポイントに対応する WSDL port 要素を指定する単一の属性 name を取ります。name 属性の値は、portQName`.http-destination` の形式を取ります。例12.10「http-conf:destination 要素」 は、エンドポイントのターゲット namespace が http://widgets.widgetvendor.net の場合に WSDL フラグメント <port binding="widgetSOAPBinding" name="widgetSOAPPort> によって指定されるエンドポイントの設定を追加するために使用される http-conf:destination 要素を示しています。

例12.10 http-conf:destination 要素

...
  <http-conf:destination name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-destination">
    ...
  </http-conf:destination>
...

http-conf:destination 要素には、設定情報を指定する複数の子要素があります。これらについては、表12.4「HTTP サービスプロバイダーエンドポイントの設定に使用される要素」 で説明されています。

表12.4 HTTP サービスプロバイダーエンドポイントの設定に使用される要素

要素説明

http-conf:server

HTTP コネクションプロパティーを指定します。「server 要素」 を参照してください。

http-conf:contextMatchStrategy

HTTP リクエストを処理するコンテキスト一致ストラテジーを設定するパラメーターを指定します。

http-conf:fixedParameterOrder

この宛先によって処理される HTTP リクエストのパラメーターの順序が固定されるかどうかを指定します。

server 要素

http-conf:server 要素は、サービスプロバイダーエンドポイントの HTTP コネクションのプロパティーを設定するために使用されます。表12.5「HTTP サービスプロバイダー設定属性」 に記載されているその属性は、コネクションのプロパティーを指定します。

表12.5 HTTP サービスプロバイダー設定属性

属性説明

ReceiveTimeout

コネクションがタイムアウトするまでにサービスプロバイダーがリクエストの受信を試みる時間をミリ秒単位で設定します。デフォルトは 30000 です。

0 はプロバイダーがタイムアウトしないことを指定します。

SuppressClientSendErrors

リクエストの受信時にエラーが発生したときに例外をスローするかどうかを指定します。デフォルトは false で、エラーが発生すると例外がスローされます。

SuppressClientReceiveErrors

コンシューマーへの応答の送信時にエラーが発生した場合に、例外がスローされるかどうかを指定します。デフォルトは false で、エラーが発生すると例外がスローされます。

HonorKeepAlive

応答が送信された後にコネクションを開いたままにする要求をサービスプロバイダーが受け入れるかどうかを指定します。デフォルトは false で、キープアライブ要求は無視されます。

RedirectURL

クライアント要求で指定された URL が要求されたリソースに適切ではなくなった場合に、クライアント要求のリダイレクト先となる URL を指定します。この場合、ステータスコードがサーバー応答の最初の行に自動的に設定されないと、ステータスコードは 302 に設定され、ステータスの説明は Object Moved に設定されます。値は HTTP RedirectURL プロパティーの値として使用されます。

CacheControl

サービスプロバイダーからコンシューマーへの応答で構成されるチェーンに関与するキャッシュが厳守しなければならない動作に関するディレクティブを指定します。「サービスプロバイダーキャッシュ制御ディレクティブ」 を参照してください。

ContentLocation

応答で送信されるリソースがある URL を設定します。

ContentType

応答で送信される情報のメディア型を指定します。メディア型は、MIME 型を使用して指定されます。値は HTTP ContentType の場所の値として使用されます。

ContentEncoding

サービスプロバイダーによって送信される情報に適用される追加のコンテンツエンコーディングを指定します。コンテンツエンコーディングラベルは、Internet Assigned Numbers Authority (IANA) によって規制されています。使用できるコンテンツエンコーディングの値には、zip、gzip、compress、deflate、identity があります。この値は HTTP ContentEncoding プロパティーの値として使用されます。

コンテンツエンコーディングの主な用途は、zip や gzip などのエンコードメカニズムを使用してドキュメントを圧縮できるようにすることです。Apache CXF は、コンテンツコーディングに対して検証を行いません。特定のコンテンツコーディングがアプリケーションレベルでサポートされていることを確認するのは、ユーザーの責任です。

ServerType

レスポンスを送信するサーバーの型を指定します。値は program-name/version という形式を取ります (例: Apache/1.2.5)。

例12.11「HTTP サービスプロバイダーエンドポイント設定」 は、キープアライブリクエストを受け入れ、すべての通信エラーを抑制する HTTP サービスプロバイダーエンドポイントの設定を示しています。

例12.11 HTTP サービスプロバイダーエンドポイント設定

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
       xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
                             http://cxf.apache.org/schemas/configuration/http-conf.xsd
                           http://www.springframework.org/schema/beans
                             http://www.springframework.org/schema/beans/spring-beans.xsd">

  <http-conf:destination name="{http://apache.org/hello_world_soap_http}SoapPort.http-destination">
    <http-conf:server SuppressClientSendErrors="true"
                      SuppressClientReceiveErrors="true"
                      HonorKeepAlive="true" />
  </http-conf:destination>
</beans>

12.3.3. WSDL の使用

namespace

HTTP プロバイダーエンドポイントの設定に使用される WSDL エクステンション要素は namespace http://cxf.apache.org/transports/http/configuration で定義されます。通常、プレフィックス http-conf を使用して参照されます。HTTP 設定要素を使用するには、例12.12「HTTP プロバイダー WSDL 要素の namespace」 にある行をエンドポイントの WSDL ドキュメントの definitions 要素に追加する必要があります。

例12.12 HTTP プロバイダー WSDL 要素の namespace

<definitions ...
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"

Undertow ランタイムまたは Netty ランタイム

http-conf namespace の要素を使用して、Undertow ランタイムまたは Netty ランタイムを設定できます。

server 要素

http-conf:server 要素は、WSDL ドキュメントで HTTP サービスプロバイダーのコネクションプロパティーを指定するために使用されます。http-conf:server 要素は WSDL port 要素の子です。設定ファイルで使用される server 要素と同じ属性があります。属性は 表12.5「HTTP サービスプロバイダー設定属性」 に記載されています。

例12.13「HTTP サービスプロバイダーエンドポイントを設定するための WSDL」 は、キャッシュと対話しないことを指定する HTTP サービスプロバイダーのエンドポイントを設定する WSDL フラグメントを示めしています。

例12.13 HTTP サービスプロバイダーエンドポイントを設定するための WSDL

<service ... >
  <port ... >
    <soap:address ... />
    <http-conf:server CacheControl="no-cache" />
  </port>
</service>

12.3.4. サービスプロバイダーキャッシュ制御ディレクティブ

表12.6「http-conf:server キャッシュ制御ディレクティブ」 は、HTTP サービスプロバイダーによってサポートされるキャッシュ制御ディレクティブを表しています。

表12.6 http-conf:server キャッシュ制御ディレクティブ

ディレクティブ動作

no-cache

キャッシュは、サーバーで応答を再検証せずに、後続のリクエストを満たすために特定の応答を使用することはできません。特定の応答ヘッダーフィールドがこの値で指定された場合、制限は応答内のこれらのヘッダーフィールドにのみ適用されます。応答ヘッダーフィールドが指定されていない場合、制限は応答全体に適用されます。

public

すべてのキャッシュは応答を保存できます。

private

応答は 1 人のユーザーを対象としているため、パブリック (共有) キャッシュでは応答を格納できません。特定の応答ヘッダーフィールドがこの値で指定された場合、制限は応答内のこれらのヘッダーフィールドにのみ適用されます。応答ヘッダーフィールドが指定されていない場合、制限は応答全体に適用されます。

no-store

キャッシュは、応答の一部またはこれを呼び出したリクエストの一部を保存してはいけません。

no-transform

キャッシュは、サーバーとクライアント間の応答にあるコンテンツのメディア型または場所を変更してはなりません。

must-revalidate

キャッシュは、後続の応答でエントリーを使用する前に、応答に関連する期限切れのエントリーを再検証する必要があります。

proxy-revalidate

must-revalidate と同じですが、共有キャッシュにのみ適用でき、プライベートの非共有キャッシュでは無視されます。このディレクティブを使用する場合は、パブリックキャッシュディレクティブも使用する必要があります。

max-age

クライアントは、経過時間が指定された秒数を超えないレスポンスを受け入れることができます。

s-max-age

max-age と同じですが、共有キャッシュにのみ適用でき、プライベートの非共有キャッシュでは無視されます。s-max-age で指定される経過時間は max-age で指定される経過時間を上書きします。このディレクティブを使用する場合は、proxy-revalidate ディレクティブも使用する必要があります。

cache-extension

他のキャッシュディレクティブへの追加のエクステンションを指定します。エクステンションは情報または動作です。拡張されたディレクティブは、標準ディレクティブのコンテキストで指定されるため、拡張されたディレクティブを理解しないアプリケーションは、標準ディレクティブで義務付けられる動作に準拠することができます。

12.4. Undertow ランタイムの設定

概要

Undertow ランタイムは、分離されたエンドポイントを使用する HTTP サービスプロバイダーと HTTP コンシューマーによって使用されます。ランタイムのスレッドプールを設定できます。また、Undertow ランタイムを使用して HTTP サービスプロバイダーのセキュリティー設定を複数設定することもできます。

Maven 依存関係

Apache Maven をビルドシステムとして使用する場合は、プロジェクトの pom.xml ファイルに以下の依存関係を追加して、Undertow ランタイムをプロジェクトに追加できます。

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-undertow</artifactId>
    <version>${cxf-version}</version>
</dependency>

namespace

Undertow ランタイムの設定に使用される要素は、namespace http://cxf.apache.org/transports/http-undertow/configuration で定義されます。Undertow 設定要素を使用するには、例12.14「Undertow ランタイム設定 namespace」 にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。この例では、namespace にプレフィックス httpu が割り当てられます。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.14 Undertow ランタイム設定 namespace

<beans ...
       xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration"
       ...
       xsi:schemaLocation="...
                           http://cxf.apache.org/transports/http-undertow/configuration
                              http://cxf.apache.org/schemas/configuration/http-undertow.xsd
                          ...">

engine-factory 要素

httpu:engine-factory 要素は、アプリケーションによって使用される Undertow ランタイムの設定に使用されるルート要素です。この属性には単一の必須属性 bus があり、その値は、設定されている Undertow インスタンスを管理する Bus の名前です。

注記

値は通常、デフォルトの Bus インスタンスの名前である cxf です。

http:engine-factory 要素には、Undertow ランタイムファクトリーによってインスタンス化された HTTP ポートの設定に使用される情報が含まれる 3 つの子があります。子は 表12.7「Undertow ランタイムファクトリーを設定するための要素」 に記載されています。

表12.7 Undertow ランタイムファクトリーを設定するための要素

要素説明

httpu:engine

特定の Undertow ランタイムインスタンスの設定を指定します。「engine 要素」 を参照してください。

httpu:identifiedTLSServerParameters

HTTP サービスプロバイダーを保護するための再利用可能なプロパティーのセットを指定します。これには、プロパティーセットを参照できる一意な識別子を指定する単一の属性 id があります。

httpu:identifiedThreadingParameters

Undertow インスタンスのスレッドプールを制御するための再利用可能なプロパティーセットを指定します。これには、プロパティーセットを参照できる一意な識別子を指定する単一の属性 id があります。

「スレッドプールの設定」 を参照してください。

engine 要素

httpu:engine 要素は、Undertow ランタイムの特定のインスタンスを設定するために使用されます。これには、Undertow インスタンスによって管理されるポートの数を指定する単一の属性 port があります。

注記

port 属性の 0 の値を指定できます。port 属性が 0 に設定された httpu:engine 要素に指定されたスレッド化プロパティーは、明示的に設定されていないすべての Undertow リスナーの設定として使用されます。

httpu:engine 要素には 2 つの子を設定できます。1 つはセキュリティープロパティーの設定用で、もう 1 つは Undertow インスタンスのスレッドプールの設定用です。各種類の設定に対して、設定情報を直接提供するか、親の httpu:engine-factory 要素で定義された設定プロパティーのセットへの参照を提供できます。

設定プロパティーを提供するために使用される子要素については、表12.8「Undertow ランタイムインスタンスを設定するための要素」 を参照してください。

表12.8 Undertow ランタイムインスタンスを設定するための要素

要素説明

httpu:tlsServerParameters

特定の Undertow インスタンスに使用されるセキュリティーを設定するためのプロパティーセットを指定します。

httpu:tlsServerParametersRef

identifiedTLSServerParameters 要素によって定義されたセキュリティープロパティーのセットを参照します。id 属性は、参照される identifiedTLSServerParameters 要素の ID を提供します。

httpu:threadingParameters

特定の Undertow インスタンスによって使用されるスレッドプールのサイズを指定します。「スレッドプールの設定」 を参照してください。

httpu:threadingParametersRef

identifiedThreadingParameters 要素によって定義されたプロパティーのセットを参照します。id 属性は、参照される identifiedThreadingParameters 要素の ID を提供します。

スレッドプールの設定

Undertow インスタンスのスレッドプールのサイズは、次のいずれかの方法で設定できます。

  • engine-factory 要素の identifiedThreadingParameters 要素を使用してスレッドプールのサイズを指定します。その後、threadingParametersRef 要素を使用して要素を参照します。
  • threadingParameters 要素を使用して、スレッドプールのサイズを直接指定します。

threadingParameters には、スレッドプールのサイズを指定する属性が 2 つあります。属性は 表12.9「Undertow スレッドプールを設定するための属性」 に記載されています。

注記

httpu:identifiedThreadingParameters 要素には単一の子要素 threadingParameters があります。

表12.9 Undertow スレッドプールを設定するための属性

属性説明

workerIOThreads

ワーカーに対して作成される I/O スレッドの数を指定します。指定しない場合、デフォルト値が選択されます。デフォルト値は、CPU コアごとに 1 つの I/O スレッドです。

minThreads

リクエストを処理するために Undertow インスタンスが使用できるスレッドの最小数を指定します。

maxThreads

リクエストを処理するために Undertow インスタンスが使用できるスレッドの最大数を指定します。

例12.15「Undertow インスタンスの設定」 は、ポート番号 9001 で Undertow インスタンスを設定する設定フラグメントを示しています。

例12.15 Undertow インスタンスの設定

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration"
  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
  xsi:schemaLocation="http://cxf.apache.org/configuration/security
  		      http://cxf.apache.org/schemas/configuration/security.xsd
            http://cxf.apache.org/transports/http/configuration
            http://cxf.apache.org/schemas/configuration/http-conf.xsd
            http://cxf.apache.org/transports/http-undertow/configuration
            http://cxf.apache.org/schemas/configuration/http-undertow.xsd
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
  ...

  <httpu:engine-factory bus="cxf">
    <httpu:identifiedTLSServerParameters id="secure">
      <sec:keyManagers keyPassword="password">
        <sec:keyStore type="JKS" password="password"
                      file="certs/cherry.jks"/>
      </sec:keyManagers>
    </httpu:identifiedTLSServerParameters>

    <httpu:engine port="9001">
      <httpu:tlsServerParametersRef id="secure" />
      <httpu:threadingParameters minThreads="5"
                                 maxThreads="15" />
    </httpu:engine>
  </httpu:engine-factory>
 </beans>

同時要求およびキューサイズの制限

同時接続リクエストの最大数の制限を設定する Request Limiting Handler と、Undertow サーバーインスタンスで処理できるキューサイズを設定できます。この設定の例を 例12.16「接続要求およびキューサイズの制限」 に示します。

表12.10 Request Limiting Handler を設定するための属性

属性説明

maximumConcurrentRequests

Undertow インスタンスが処理できる同時リクエストの最大数を指定します。要求の数がこの制限を超える場合、要求はキューに置かれます。

queueSize

Undertow インスタンスによる処理のためにキューに入れられる可能性のあるリクエストの総数を指定します。要求の数がこの制限を超える場合、要求は拒否されます。

例12.16 接続要求およびキューサイズの制限

<httpu:engine-factory>
     <httpu:engine port="8282">
         <httpu:handlers>
             <bean class="org.jboss.fuse.quickstarts.cxf.soap.CxfRequestLimitingHandler">
                 <property name="maximumConcurrentRequests" value="1" />
                 <property name="queueSize" value="1"/>
             </bean>
         </httpu:handlers>
     </httpu:engine>
</httpu:engine-factory>

12.5. Netty ランタイムの設定

概要

Netty ランタイムは、分離されたエンドポイントを使用する HTTP サービスプロバイダーと HTTP コンシューマーによって使用されます。ランタイムのスレッドプールを設定できます。また、Netty ランタイムを使用して HTTP サービスプロバイダーのセキュリティー設定を複数設定することもできます。

Maven 依存関係

Apache Maven をビルドシステムとして使用する場合は、プロジェクトの pom.xml ファイルに以下の依存関係を追加し、Netty ランタイムのサーバー側の実装 (Web サービスエンドポイントを定義するため) をプロジェクトに追加できます。

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-netty-server</artifactId>
    <version>${cxf-version}</version>
</dependency>

プロジェクトの pom.xml ファイルに次の依存関係を含めることで、Netty ランタイムのクライアント側実装 (Web サービスクライアントの定義用) をプロジェクトに追加できます。

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-netty-client</artifactId>
    <version>${cxf-version}</version>
</dependency>

namespace

Netty ランタイムの設定に使用される要素は、namespace http://cxf.apache.org/transports/http-netty-server/configuration で定義されます。通常、プレフィックス httpn を使用して参照されます。Netty 設定要素を使用するには、例12.17「Netty ランタイム設定 namespace」 にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.17 Netty ランタイム設定 namespace

<beans ...
       xmlns:httpn="http://cxf.apache.org/transports/http-netty-server/configuration"
       ...
       xsi:schemaLocation="...
               http://cxf.apache.org/transports/http-netty-server/configuration
            http://cxf.apache.org/schemas/configuration/http-netty-server.xsd
               ...">

engine-factory 要素

httpn:engine-factory 要素は、アプリケーションによって使用される Netty ランタイムの設定に使用されるルート要素です。この属性には単一の必須属性 bus があり、その値は、設定されている Netty インスタンスを管理する Bus の名前です。

注記

値は通常、デフォルトの Bus インスタンスの名前である cxf です。

httpn:engine-factory 要素には、Netty ランタイムファクトリーによってインスタンス化された HTTP ポートの設定に使用される情報が含まれる 3 つの子があります。子は 表12.11「Netty ランタイムファクトリを設定するための要素」 に記載されています。

表12.11 Netty ランタイムファクトリを設定するための要素

要素説明

httpn:engine

特定の Netty ランタイムインスタンスの設定を指定します。「engine 要素」 を参照してください。

httpn:identifiedTLSServerParameters

HTTP サービスプロバイダーを保護するための再利用可能なプロパティーのセットを指定します。これには、プロパティーセットを参照できる一意な識別子を指定する単一の属性 id があります。

httpn:identifiedThreadingParameters

Netty インスタンスのスレッドプールを制御するための再利用可能なプロパティーセットを指定します。これには、プロパティーセットを参照できる一意な識別子を指定する単一の属性 id があります。

「スレッドプールの設定」 を参照してください。

engine 要素

httpn:engine 要素は、Netty ランタイムの特定のインスタンスを設定するために使用されます。表12.12「Netty ランタイムインスタンスの設定するための属性」 は、httpn:engine 要素によってサポートされる属性を示しています。

表12.12 Netty ランタイムインスタンスの設定するための属性

属性説明

port

Netty HTTP サーバーインスタンスによって使用されるポートを指定します。port 属性に 0 の値を指定することができます。port 属性が 0 に設定された engine 要素に指定されたスレッド化プロパティーは、明示的に設定されていないすべての Netty リスナーの設定として使用されます。

host

Netty HTTP サーバーインスタンスによって使用されるリッスンアドレスを指定します。値は、ホスト名または IP アドレスになります。指定されていない場合、Netty HTTP サーバーはすべてのローカルアドレスをリッスンします。

readIdleTime

Netty コネクションの最大読み取りアイドル時間を指定します。このタイマーは、基盤になるストリームに読み取りアクションがあるときはいつでもリセットされます。

writeIdleTime

Netty コネクションの最大書き込みアイドル時間を指定します。このタイマーは、基盤になるストリームに書き込みアクションがあるときはいつでもリセットされます。

maxChunkContentSize

Netty コネクションの集約されたコンテンツの最大サイズを指定します。デフォルト値は 10MB です。

httpn:engine 要素には、セキュリティープロパティーを設定するための子要素が 1 つと、Netty インスタンスのスレッドプールを設定するための子要素が 1 つあります。各種類の設定に対して、設定情報を直接提供するか、親の httpn:engine-factory 要素で定義された設定プロパティーのセットへの参照を提供できます。

httpn:engine のサポートされる子要素を、表12.13「Netty ランタイムインスタンスを設定するための要素」 に示します。

表12.13 Netty ランタイムインスタンスを設定するための要素

要素説明

httpn:tlsServerParameters

特定の Netty インスタンスに使用されるセキュリティーを設定するためのプロパティーセットを指定します。

httpn:tlsServerParametersRef

identifiedTLSServerParameters 要素によって定義されたセキュリティープロパティーのセットを参照します。id 属性は、参照される identifiedTLSServerParameters 要素の ID を提供します。

httpn:threadingParameters

特定の Netty インスタンスによって使用されるスレッドプールのサイズを指定します。「スレッドプールの設定」 を参照してください。

httpn:threadingParametersRef

identifiedThreadingParameters 要素によって定義されたプロパティーのセットを参照します。id 属性は、参照される identifiedThreadingParameters 要素の ID を提供します。

httpn:sessionSupport

true の場合、HTTP セッションのサポートを有効にします。デフォルトは false です。

httpn:reuseAddress

ReuseAddress TCP ソケットオプションを設定するブール値を指定します。デフォルトは false です。

スレッドプールの設定

Netty インスタンスのスレッドプールのサイズは、次のいずれかの方法で設定できます。

  • engine-factory 要素の identifiedThreadingParameters 要素を使用してスレッドプールのサイズを指定します。その後、threadingParametersRef 要素を使用して要素を参照します。
  • threadingParameters 要素を使用して、スレッドプールのサイズを直接指定します。

threadingParameters 要素には、表12.14「Netty スレッドプールを設定するための属性」 に記載されているように、スレッドプールのサイズを指定する 1 つの属性があります。

注記

httpn:identifiedThreadingParameters 要素には単一の子要素 threadingParameters があります。

表12.14 Netty スレッドプールを設定するための属性

属性説明

threadPoolSize

リクエストを処理するために Netty インスタンスが使用できるスレッドの数を指定します。

例12.18「Netty インスタンスの設定」 は、さまざまな Netty ポートを設定する設定フラグメントを示しています。

例12.18 Netty インスタンスの設定

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:beans="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:h="http://cxf.apache.org/transports/http/configuration"
       xmlns:httpn="http://cxf.apache.org/transports/http-netty-server/configuration"
       xmlns:sec="http://cxf.apache.org/configuration/security"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans.xsd
        http://cxf.apache.org/configuration/security
            http://cxf.apache.org/schemas/configuration/security.xsd
        http://cxf.apache.org/transports/http/configuration
            http://cxf.apache.org/schemas/configuration/http-conf.xsd
        http://cxf.apache.org/transports/http-netty-server/configuration
            http://cxf.apache.org/schemas/configuration/http-netty-server.xsd"
>
    ...
    <httpn:engine-factory bus="cxf">
       <httpn:identifiedTLSServerParameters id="sample1">
         <httpn:tlsServerParameters jsseProvider="SUN" secureSocketProtocol="TLS">
            <sec:clientAuthentication want="false" required="false"/>
         </httpn:tlsServerParameters>
       </httpn:identifiedTLSServerParameters>

       <httpn:identifiedThreadingParameters id="sampleThreading1">
          <httpn:threadingParameters threadPoolSize="120"/>
       </httpn:identifiedThreadingParameters>

       <httpn:engine port="9000" readIdleTime="30000" writeIdleTime="90000">
          <httpn:threadingParametersRef id="sampleThreading1"/>
       </httpn:engine>

       <httpn:engine port="0">
          <httpn:threadingParameters threadPoolSize="400"/>
       </httpn:engine>

       <httpn:engine port="9001" readIdleTime="40000" maxChunkContentSize="10000">
         <httpn:threadingParameters threadPoolSize="99" />
         <httpn:sessionSupport>true</httpn:sessionSupport>
       </httpn:engine>

       <httpn:engine port="9002">
         <httpn:tlsServerParameters>
           <sec:clientAuthentication want="true" required="true"/>
         </httpn:tlsServerParameters>
       </httpn:engine>

       <httpn:engine port="9003">
          <httpn:tlsServerParametersRef id="sample1"/>
       </httpn:engine>

    </httpn:engine-factory>
</beans>

12.6. 分離モードでの HTTP トランスポートの使用

概要

通常の HTTP リクエスト/応答シナリオでは、リクエストと応答は同じ HTTP コネクションを使用して送信されます。サービスプロバイダーはリクエストを処理し、適切な HTTP ステータスコードおよび応答の内容が含まれるレスポンスで応答します。リクエストが正常に行われると、HTTP ステータスコードは 200 に設定されます。

WS-RM を使用する場合やリクエストの実行に長時間かかる場合など、場合によっては、リクエストとレスポンスメッセージを切り離すのが妥当です。この場合、サービスプロバイダーはリクエストが受信された HTTP コネクションのバックチャネルを通じてコンシューマーに 202 Accepted 応答を送信します。次に、リクエストを処理し、新しい分離サーバー→クライアント HTTP コネクションを使用してレスポンスをコンシューマに送り返します。コンシューマーのランタイムは、受信応答を受け取り、アプリケーションコードに戻る前にこれを適切なリクエストと関連付けます。

分離された対話の設定

分離モードで HTTP トランスポートを使用するには、以下を行う必要があります。

  1. WS-Addressing を使用するようにコンシューマーを設定します。

    「WS-Addressing を使用するようにエンドポイントを設定」 を参照してください。

  2. 分離されたエンドポイントを使用するようにコンシューマーを設定します。

    「コンシューマーの設定」 を参照してください。

  3. WS-Addressing を使用するように、コンシューマーが対話するサービスプロバイダーを設定します。

    「WS-Addressing を使用するようにエンドポイントを設定」 を参照してください。

WS-Addressing を使用するようにエンドポイントを設定

コンシューマーとコンシューマーが対話するサービスプロバイダーが WS-Addressing を使用するように指定します。

エンドポイントが WS-Addressing を使用するように指定するには、以下の 2 つの方法の 1 つを使用します。

  • 例12.19「WSDL を使用した WS-Addressing のアクティブ化」 のように、エンドポイントの WSDL port 要素に wswa:UsingAddressing 要素を追加します。

    例12.19 WSDL を使用した WS-Addressing のアクティブ化

    ...
    <service name="WidgetSOAPService">
      <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding">
        <soap:address="http://widgetvendor.net/widgetSeller" />
        <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2005/02/addressing/wsdl"/>
      </port>
    </service>
    ...
  • 例12.20「ポリシー使用した WS-Addressing のアクティブ化」 のように、WS-Addressing ポリシーをエンドポイントの WSDL port 要素に追加します。

    例12.20 ポリシー使用した WS-Addressing のアクティブ化

    ...
    <service name="WidgetSOAPService">
      <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding">
        <soap:address="http://widgetvendor.net/widgetSeller" />
        <wsp:Policy xmlns:wsp="http://www.w3.org/2006/07/ws-policy"> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> </wsp:Policy>
      </port>
    </service>
    ...
注記

WS-Addressing ポリシーは wswa:UsingAddressing WSDL 要素よりも優先されます。

コンシューマーの設定

http-conf:conduit 要素の DecoupledEndpoint 属性を使用して、分離されたエンドポイントを使用するようにコンシューマエンドポイントを設定します。

例12.21「分離された HTTP エンドポイントを使用するようにコンシューマを設定」 は、分離されたエンドポイントを使用するために 例12.19「WSDL を使用した WS-Addressing のアクティブ化」 に定義されるエンドポイントの設定を示しています。コンシューマーは http://widgetvendor.net/widgetSellerInbox ですべてのレスポンスを受け取るようになります。

例12.21 分離された HTTP エンドポイントを使用するようにコンシューマを設定

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:http="http://cxf.apache.org/transports/http/configuration"
       xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
                             http://cxf.apache.org/schemas/configuration/http-conf.xsd
                           http://www.springframework.org/schema/beans
                             http://www.springframework.org/schema/beans/spring-beans.xsd">

  <http:conduit name="{http://widgetvendor.net/services}WidgetSOAPPort.http-conduit">
    <http:client DecoupledEndpoint="http://widgetvendor.net:9999/decoupled_endpoint" />
  </http:conduit>
</beans>

メッセージの処理方法

分離モードで HTTP トランスポートを使用すると、HTTP メッセージの処理がより複雑になります。追加された複雑さはアプリケーションの実装レベルのコードに対して透過的ですが、デバッグの理由から何が起こるかを理解することが重要になる場合があります。

図12.1「分離された HTTP トランスポートのメッセージフロー」 は、分離モードで HTTP を使用する場合のメッセージのフローを示しています。

図12.1 分離された HTTP トランスポートのメッセージフロー

There are fifteen steps in a decoupled message exchange.

リクエストは、次のプロセスを開始します。

  1. コンシューマー実装は操作を呼び出して、リクエストメッセージが生成されます。
  2. WS-Addressing レイヤーは WS-A ヘッダーをメッセージに追加します。

    分離されたエンドポイントがコンシューマー設定に指定された場合、分離されたエンドポイントのアドレスは WS-A ReplyTo ヘッダーに配置されます。

  3. メッセージはサービスプロバイダーに送信されます。
  4. サービスプロバイダーはメッセージを受信します。
  5. コンシューマーからのリクエストメッセージはプロバイダーの WS-A レイヤーにディスパッチされます。
  6. WS-A ReplyTo ヘッダーは匿名に設定されていないため、プロバイダーは HTTP ステータスコードが 202 に設定されたメッセージを送り返し、リクエストが受信されたことを確認します。
  7. HTTP 層は、元のコネクションのバックチャネルを使用して 202 Accepted メッセージをコンシューマーに送り返します。
  8. コンシューマーは、元のメッセージを送信するために使用された HTTP コネクションのバックチャネルで 202 Accepted 応答を受信します。

    コンシューマーが 202 Accepted の返信を受信すると、HTTP コネクションが閉じます。

  9. リクエストは、リクエストが処理されるサービスプロバイダーの実装に渡されます。
  10. 応答の準備ができると、WS-A 層にディスパッチされます。
  11. WS-A 層は、応答メッセージに WS-Addressing ヘッダーを追加します。
  12. HTTP トランスポートは応答をコンシューマーの分離されたエンドポイントに送信します。
  13. コンシューマーの分離されたエンドポイントは、サービスプロバイダーから応答を受信します。
  14. レスポンスは、WS-A relateSto ヘッダーを使用して適切なリクエストと相関するコンシューマーの WS-A 層にディスパッチされます。
  15. 相関応答がクライアント実装に返され、呼び出しのブロックが解除されます。

第13章 SOAP Over JMS の使用

概要

Apache CXF は、W3C 標準 SOAP/JMS トランスポートを実装します。この標準は、SOAP/HTTP サービスより堅牢な方法を提供することを目的としています。このトランスポートを使用する Apache CXF アプリケーションは、SOAP/JMS 標準を実装するアプリケーションと相互運用できる必要があります。トランスポートはエンドポイントの WSDL に直接設定されます。

注記: JMS 1.0.2 API のサポートは CXF 3.0 で削除されました。Red Hat JBoss Fuse 6.2 以降 (CXF 3.0 を含む) を使用している場合、JMS プロバイダーは JMS 1.1 API をサポートする必要があります。

13.1. 基本設定

概要

SOAP over JMS プロトコル は、ほとんどのサービスで使用される慣習的な SOAP/HTTP プロトコルに、より信頼性の高いトランスポート層を提供する方法として、World Wide Web Consortium (W3C) によって定義されています。Apache CXF の実装は、仕様に完全に準拠しており、準拠しているフレームワークと互換性があるはずです。

このトランスポートは JNDI を使用して JMS 宛先を検索します。操作が呼び出されると、リクエストは SOAP メッセージとしてパッケージ化され、JMS メッセージのボディーで指定の宛先に送信されます。

SOAP/JMS トランスポートを使用するには、以下を実行します。

  1. トランスポート型が SOAP/JMS であることを指定します。
  2. JMS URI を使用してターゲット宛先を指定します。
  3. 必要に応じて、JNDI 接続を設定します。
  4. 必要に応じて、JMS 設定をさらに追加します。

JMS トランスポート型の指定

WSDL バインディングを指定する際に、SOAP バインディングが JMS トランスポートを使用するように設定します。soap:binding 要素の transport 属性を http://www.w3.org/2010/soapjms/ に設定します。例13.1「SOAP over JMS バインディングの指定」 は、SOAP/JMS を使用する WSDL バインディングを示しています。

例13.1 SOAP over JMS バインディングの指定

<wsdl:binding ... >
  <soap:binding style="document"
                transport="http://www.w3.org/2010/soapjms/" />
  ...
</wsdl:binding>

ターゲット宛先の指定

エンドポイントの WSDL ポートを指定するときに JMS ターゲット宛先のアドレスを指定します。SOAP/JMS エンドポイントのアドレス指定では、SOAP/HTTP エンドポイントと同じ soap:address 要素および属性を使用します。違いはアドレスの指定です。JMS エンドポイントは、JMS 1.0 の URI スキーム で定義された JMS URI を使用します。例13.2「JMS URI 構文」 は、JMS URI の構文を示しています。

例13.2 JMS URI 構文

jms:variant:destination?options

表13.1「JMS URI バリアント」 で、JMS URI で使用できるバリアントを説明します。

表13.1 JMS URI バリアント

バリアント説明

jndi

宛先名が JNDI キュー名であることを指定します。このバリアントを使用する場合は、JNDI プロバイダーにアクセスするための設定を指定する必要があります。

jndi-topic

宛先名が JNDI トピック名であることを指定します。このバリアントを使用する場合は、JNDI プロバイダーにアクセスするための設定を指定する必要があります。

queue

宛先が JMS を使用して解決されるキュー名であることを指定します。指定の文字列は Session.createQueue() に渡され、宛先の表現が作成されます。

topic

宛先が JMS を使用して解決されるトピック名であることを指定します。指定の文字列は Session.createTopic() に渡され、宛先の表現が作成されます。

JMS URI の オプション 部分はトランスポートの設定に使用され、「JMS URI」 で説明されています。

例13.3「SOAP/JMS エンドポイントアドレス」 は、JNDI を使用してターゲット宛先が検索される SOAP/JMS エンドポイントの WSDL ポートエントリーを示しています。

例13.3 SOAP/JMS エンドポイントアドレス

<wsdl:port ... >
  ...
  <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
</wsdl:port>

JNDI と JMS トランスポートの設定

SOAP/JMS には、JNDI コネクションと JMS トランスポートを設定するための複数の方法が用意されています。

13.2. JMS URI

概要

SOAP/JMS を使用する場合、JMS URI を使用してエンドポイントのターゲット宛先を指定します。JMS URI は、URI に 1 つ以上のオプションを追加して JMS コネクションを設定するために使用することもできます。これらのオプションは、IETF 標準仕様である Java Message Service 1.0 の URI スキーム で詳しく説明されています。それらは JNDI システム、応答宛先、使用する配信モード、およびその他の JMS プロパティーを設定するために使用できます。

構文

例13.4「JMS URI オプションの構文」 のように、JMS URI の末尾に 1 つ以上のオプションを追加するには、疑問符 (?) で区切って宛先アドレスから分離します。複数のオプションはアンパサンド (&) で区切られます。例13.4「JMS URI オプションの構文」 は、JMS URI で複数のオプションを使用するための構文を示しています。

例13.4 JMS URI オプションの構文

jms:variant:jmsAddress?option1=value1&option2=value2&_optionN_=valueN

JMS プロパティー

表13.2「URI オプションとして設定可能な JMS プロパティー」 は、JMS トランスポート層に影響する URI オプションを示しています。

表13.2 URI オプションとして設定可能な JMS プロパティー

プロパティーデフォルト説明

conduitIdSelectorPrefix

 

[任意] コンジットが作成するすべての相関 ID の前に付けられる文字列値です。セレクターはこれを使用して返信をリッスンできます。

deliveryMode

PERSISTENT

JMS PERSISTENT または NON_PERSISTENT メッセージセマンティクスを使用するかどうかを指定します。PERSISTENT 配信モードの場合、JMS ブローカーはメッセージを承認する前に永続ストレージに保存します。一方、NON_PERSISTENT メッセージはメモリーにのみ保持されます。

durableSubscriptionClientID

 

[任意] コネクションのクライアント識別子を指定します。このプロパティーは、クライアントの代わりにプロバイダーが管理する状態とコネクションを関連付けるために使用されます。これにより、同じアイデンティティーを持つ後続のサブスクライバーは、前のサブスクライバーが残した状態でサブスクリプションを再開できます。

durableSubscriptionName

 

[任意] サブスクリプションの名前を指定します。

messageType

byte

CXF によって使用される JMS メッセージ型を指定します。有効な値は次のとおりです。

  • byte
  • text
  • binary

password

 

[任意] コネクション作成のパスワードを指定します。URI にこのプロパティーを追加することは推奨されません。

priority

4

0 (最低) から 9 (最高) までの範囲で JMS メッセージの優先度を指定します。

receiveTimout

60000

リクエスト/リプライエクスチェンジが使用されるときにクライアントがリプライを待つ時間 (ミリ秒単位) を指定します。

reconnectOnException

true

[CXF 3.0 で非推奨] 例外が発生したときにトランスポートを再接続するかどうかを指定します。

3.0 以降、例外が発生すると、トランスポートは常に再接続されます。

replyToName

 

[任意] キューメッセージの返信先を指定します。返信先が JMSReplyTo ヘッダーに表示されます。一時返信キューの指定がない場合に、JMS プロバイダーが一時返信キューを割り当てるため、リクエスト/リプライセマンティクスを持つアプリケーションでは、このプロパティーの設定が推奨されます。

このプロパティーの値は、JMS URI で指定されたバリアントに従って解釈されます。

  • jndi バリアント - JNDI によって解決された宛先キューの名前
  • queue バリアント - JMS を使用して解決された宛先キューの名前

sessionTransacted

false

トランザクション型を指定します。有効な値は次のとおりです。

  • true - リソースローカルトランザクション
  • false - JTA トランザクション

timeToLive

0

JMS プロバイダーがメッセージを破棄するまでの時間 (ミリ秒単位) を指定します。0 の値は無限に存在することを示します。

topicReplyToName

 

[任意] トピックメッセージの返信先を指定します。このプロパティーの値は、JMS URI で指定されたバリアントに従って解釈されます。

  • jndi-topic- JNDI によって解決される宛先トピックの名前
  • topic- JMS によって解決される宛先トピックの名前

useConduitIdSelector

true

コンジットの UUID をすべての相関 ID のプレフィックスとして使用するかどうかを指定します。

すべてのコンジットには一意の UUID が割り当てられるため、このプロパティーを true に設定すると、複数のエンドポイントが JMS キューまたはトピックを共有できるようになります。

username

 

[任意] コネクションの作成に使用するユーザー名を指定します。

JNDI プロパティー

表13.3「URI オプションとして設定可能な JNDI プロパティー」 は、このエンドポイントの JNDI の設定に使用できる URI オプションを示しています。

表13.3 URI オプションとして設定可能な JNDI プロパティー

プロパティー説明

jndiConnectionFactoryName

JMS コネクションファクトリーの JNDI 名を指定します。

jndiInitialContextFactory

JNDI プロバイダーの完全修飾 Java クラス名を指定します (javax.jms.InitialContextFactory 型である必要があります)。java.naming.factory.initial Java システムプロパティーの設定と同等です。

jndiTransactionManagerName

Spring、Blueprint、または JNDI で検索される JTA トランザクションマネージャーの名前を指定します。トランザクションマネージャーが見つかった場合、JTA トランザクションが有効になります。sessionTransacted JMS プロパティーを参照してください。

jndiURL

JNDI プロバイダーを初期化する URL を指定します。java.naming.provider.url Java システムプロパティーの設定と同等です。

追加の JNDI プロパティー

プロパティー java.naming.factory.initial および java.naming.provider.url は、JNDI プロバイダーの初期化に必要な標準プロパティーです。しかし、JNDI プロバイダーは標準のプロパティーに加えて、カスタムプロパティーをサポートする場合があります。この場合、jndi-PropertyName 形式の URI オプションを設定することで、任意の JNDI プロパティーを設定できます。

たとえば、JNDI の SUN の LDAP 実装を使用している場合は、例13.5「JMS URI での JNDI プロパティーの設定」 のように JMS URI で JNDI プロパティー java.naming.factory.control を設定できます。

例13.5 JMS URI での JNDI プロパティーの設定

jms:queue:FOO.BAR?jndi-java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory

JMS プロバイダーがまだ設定されていない 場合は、オプションを使用して必要な JNDI 設定の詳細を URI に提供できます (表13.3「URI オプションとして設定可能な JNDI プロパティー」 を参照)。たとえば、Apache ActiveMQ JMS プロバイダを使用し、test.cxf.jmstransport.queue というキューに接続するようにエンドポイントを設定するには、例13.6「JNDI コネクションを設定する JMS URI」 に示す URI を使用します。

例13.6 JNDI コネクションを設定する JMS URI

jms:jndi:dynamicQueues/test.cxf.jmstransport.queue
?jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory
&jndiConnectionFactoryName=ConnectionFactory
&jndiURL=tcp://localhost:61616

サービスのパブリッシュ

JAX-WS 標準 publish() メソッドを使用して SOAP/JMS サービスをパブリッシュできません。その代わりに、例13.7「SOAP/JMS サービスの公開」 のように Apache CXF の JaxWsServerFactoryBean クラスを使用する必要があります。

例13.7 SOAP/JMS サービスの公開

String address = "jms:jndi:dynamicQueues/test.cxf.jmstransport.queue3"
    + "?jndiInitialContextFactory"
    + "=org.apache.activemq.jndi.ActiveMQInitialContextFactory"
    + "&jndiConnectionFactoryName=ConnectionFactory"
    + "&jndiURL=tcp://localhost:61500";
Hello implementor = new HelloImpl();
JaxWsServerFactoryBean svrFactory = new JaxWsServerFactoryBean();
svrFactory.setServiceClass(Hello.class);
svrFactory.setAddress(address);
svrFactory.setTransportId(JMSSpecConstants.SOAP_JMS_SPECIFICIATION_TRANSPORTID);
svrFactory.setServiceBean(implementor);
svrFactory.create();

例13.7「SOAP/JMS サービスの公開」 のコードは、以下を行います。

エンドポイントのアドレスを表す JMS URI を作成します。

JaxWsServerFactoryBean をインスタンス化してサービスをパブリッシュします。

ファクトリー Bean の address フィールドをサービスの JMS URI に設定します。

ファクトリーによって作成されたサービスが SOAP/JMS トランスポートを使用することを指定します。

サービスの消費

標準的な JAX-WS API は、SOAP/JMS サービスの消費には使用できません。その代わりに、例13.8「SOAP/JMS サービスの消費」 のように、Apache CXF の JaxWsProxyFactoryBean クラスを使用する必要があります。

例13.8 SOAP/JMS サービスの消費

// Java
public void invoke() throws Exception {
    String address = "jms:jndi:dynamicQueues/test.cxf.jmstransport.queue3"
        + "?jndiInitialContextFactory"
        + "=org.apache.activemq.jndi.ActiveMQInitialContextFactory"
        + "&jndiConnectionFactoryName=ConnectionFactory&jndiURL=tcp://localhost:61500";
    JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
    factory.setAddress(address);
    factory.setTransportId(JMSSpecConstants.SOAP_JMS_SPECIFICIATION_TRANSPORTID);
    factory.setServiceClass(Hello.class);
    Hello client = (Hello)factory.create();
    String reply = client.sayHi(" HI");
    System.out.println(reply);
}

例13.8「SOAP/JMS サービスの消費」 のコードは、以下を行います。

エンドポイントのアドレスを表す JMS URI を作成します。

JaxWsProxyFactoryBean をインスタンス化してプロキシーを作成します。

ファクトリー Bean の address フィールドをサービスの JMS URI に設定します。

ファクトリーによって作成されたプロキシーが SOAP/JMS トランスポートを使用することを指定します。

13.3. WSDL エクステンション

概要

バインディングスコープ、サービススコープ、またはポートスコープのいずれかで WSDL エクステンション要素をコントラクトに挿入して、JMS トランスポートの基本設定を指定できます。WSDL エクステンションを使用すると、JNDI InitialContext をブートストラップするためのプロパティーを指定できます。これは JMS 宛先を検索するために使用できます。JMS トランスポート層の動作に影響を与えるプロパティーをいくつか設定することもできます。

SOAP/JMS namespace

SOAP/JMS WSDL エクステンションは http://www.w3.org/2010/soapjms/ namespace で定義されます。WSDL コントラクトで使用するには、以下の設定を wsdl:definitions 要素に追加します。

<wsdl:definitions ...
    xmlns:soapjms="http://www.w3.org/2010/soapjms/"
  ... >

WSDL エクステンション要素

表13.4「SOAP/JMS WSDL エクステンション要素」 は、JMS トランスポートを設定するために使用できる WSDL エクステンション要素をすべて示しています。

表13.4 SOAP/JMS WSDL エクステンション要素

要素デフォルト説明

soapjms:jndiInitialContextFactory

 

JNDI プロバイダーの完全修飾 Java クラス名を指定します。java.naming.factory.initial Java システムプロパティーの設定と同等です。

soapjms:jndiURL

 

JNDI プロバイダーを初期化する URL を指定します。java.naming.provider.url Java システムプロパティーの設定と同等です。

soapjms:jndiContextParameter

 

JNDI InitialContext を作成するための追加のプロパティーを指定します。name および value 属性を使用してプロパティーを指定します。

soapjms:jndiConnectionFactoryName

 

JMS コネクションファクトリーの JNDI 名を指定します。

soapjms:deliveryMode

PERSISTENT

JMS PERSISTENT または NON_PERSISTENT メッセージセマンティクスを使用するかどうかを指定します。PERSISTENT 配信モードの場合、JMS ブローカーはメッセージを承認する前に永続ストレージに保存します。一方、NON_PERSISTENT メッセージはメモリーにのみ保持されます。

soapjms:replyToName

 

[任意] キューメッセージの返信先を指定します。返信先が JMSReplyTo ヘッダーに表示されます。一時返信キューの指定がない場合に、JMS プロバイダーが一時返信キューを割り当てるため、リクエスト/リプライセマンティクスを持つアプリケーションでは、このプロパティーの設定が推奨されます。

このプロパティーの値は、JMS URI で指定されたバリアントに従って解釈されます。

  • jndi バリアント - JNDI によって解決された宛先キューの名前
  • queue バリアント - JMS を使用して解決された宛先キューの名前

soapjms:priority

4

0 (最低) から 9 (最高) までの範囲で JMS メッセージの優先度を指定します。

soapjms:timeToLive

0

JMS プロバイダーがメッセージを破棄するまでの時間 (ミリ秒単位)。0 の値は無限の有効期間を表します。

設定スコープ

WSDL コントラクト内の WSDL 要素の配置は、コントラクトで定義されたエンドポイントの設定変更のスコープに影響します。SOAP/JMS WSDL 要素は、wsdl:binding 要素、wsdl:service 要素、または wsdl:port 要素の子として配置できます。SOAP/JMS 要素の親によって、設定が配置されるスコープが次のうちどれであるかが決まります。

バインディングスコープ
バインディングスコープ で JMS トランスポートを設定するには、エクステンション要素を wsdl:binding 要素内に配置します。このスコープの要素は、このバインディングを使用するすべてのエンドポイントのデフォルト設定を定義します。バインディングスコープの設定は、サービススコープまたはポートスコープで上書きできます。
サービススコープ
サービススコープ で JMS トランスポートを設定するには、エクステンション要素を wsdl:service 要素内に配置します。このスコープの要素は、このサービス内のすべてのエンドポイントのデフォルト設定を定義します。サービススコープの設定は、ポートスコープで上書きできます。
ポートスコープ
ポートスコープ で JMS トランスポートを設定するには、エクステンション要素を wsdl:port 要素内に配置します。ポートスコープの要素は、このポートの設定を定義します。これらは、サービススコープまたはバインディングスコープで定義されている同じエクステンション要素のデフォルトを上書きします。

例13.9「WSDL コントラクトと SOAP/JMS 設定」 は、SOAP/JMS サービスの WSDL コントラクトを示しています。バインディングスコープの JNDI 層、サービススコープ内のメッセージ配信の詳細、およびポートスコープ内の応答先を設定します。

例13.9 WSDL コントラクトと SOAP/JMS 設定

<wsdl:definitions ...
    xmlns:soapjms="http://www.w3.org/2010/soapjms/"
  ... >
  ...
  <wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType">
    ...
    <soapjms:jndiInitialContextFactory>
      org.apache.activemq.jndi.ActiveMQInitialContextFactory
    </soapjms:jndiInitialContextFactory>
    <soapjms:jndiURL>tcp://localhost:61616</soapjms:jndiURL>
    <soapjms:jndiConnectionFactoryName>
      ConnectionFactory
    </soapjms:jndiConnectionFactoryName>
    ...
  </wsdl:binding>
  ...
  <wsdl:service name="JMSGreeterService">
    ...
    <soapjms:deliveryMode>NON_PERSISTENT</soapjms:deliveryMode>
    <soapjms:timeToLive>60000</soapjms:timeToLive>
    ...
    <wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort">
      <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
      <soapjms:replyToName>
        dynamicQueues/greeterReply.queue
      </soapjms:replyToName>
      ...
    </wsdl:port>
    ...
  </wsdl:service>
  ...
</wsdl:definitions>

例13.9「WSDL コントラクトと SOAP/JMS 設定」 の WSDL では以下を行います。

SOAP/JMS エクステンションの namespace を宣言します。

バインディングスコープで JNDI コネクションを設定します。

JMS 配信スタイルを非永続的に設定し、各メッセージを 1 分間存在させます。

ターゲット宛先を指定します。

リプライメッセージが greeterReply.queue キューに配信されるように JMS トランスポートを設定します。

第14章 汎用 JMS の使用

概要

Apache CXF は JMS トランスポートの汎用実装を提供します。汎用 JMS トランスポートは SOAP メッセージの使用に制限されず、JMS を使用する任意のアプリケーションに接続できます。

注記: JMS 1.0.2 API のサポートは CXF 3.0 で削除されました。Red Hat JBoss Fuse 6.2 以降 (CXF 3.0 を含む) を使用している場合、JMS プロバイダーは JMS 1.1 API をサポートする必要があります。

14.1. JMS 設定方法

Apache CXF 汎用 JMS トランスポートは JMS プロバイダーに接続し、JMS メッセージを TextMessage または ByteMessage のいずれかのボディーで交換するアプリケーションと動作します。

JMS トランスポートを有効または無効にする方法は 2 つあります。

14.2. JMS 設定 Bean の使用

概要

JMS 設定を簡素化し、より強力にするために Apache CXF は単一の JMS 設定 Bean を使用して JMS エンドポイントを設定します。Bean は org.apache.cxf.transport.jms.JMSConfiguration クラスによって実装されます。エンドポイントを直接設定したり、JMS コンジットと宛先を設定するために使用できます。

設定 namespace

JMS 設定 Bean は Spring p-namespace を使用して設定を簡単にします。この namespace を使用するには、例14.1「Spring p-namespace の宣言」 のように、設定のルート要素でこれを宣言する必要があります。

例14.1 Spring p-namespace の宣言

<beans ...
  xmlns:p="http://www.springframework.org/schema/p"
  ... >
  ...
</beans>

設定の指定

クラス org.apache.cxf.transport.jms.JMSConfiguration の Bean を定義して JMS 設定を指定します。Bean のプロパティーは、トランスポートの設定設定を提供します。

重要

CXF 3.0 では、JMS トランスポートが Spring JMS の依存関係を使用しなくなったため、Spring JMS 関連のオプションの一部が削除されました。

表14.1「一般的な JMS 設定プロパティー」 はプロバイダーとコンシューマーに共通するプロパティーを示しています。

表14.1 一般的な JMS 設定プロパティー

プロパティーデフォルト説明

connectionFactory

 

[必須] JMS ConnectionFactory を定義する Bean への参照を指定します。

wrapInSingleConnectionFactory

true [v3.0 未満]

CXF 3.0 で削除された機能

pre CXF 3.0 は、ConnectionFactory を Spring SingleConnectionFactory でラップするかどうかを指定します。

このプロパティーは、JMS トランスポートのパフォーマンスを向上させるため、プールコネクションを使用しない ConnectionFactory を使用する場合にこのプロパティーを有効にします。これは、JMS トランスポートがメッセージごとに新しいコネクションを作成し、コネクションをキャッシュして再利用できるようにするために SingleConnectionFactory が必要であるためです。

reconnectOnException

false

CXF 3.0 で非推奨 CXF は、例外が発生したときに常に再接続します。

pre CXF 3.0 は、例外が発生するときに新しいコネクションを作成するかどうかを指定します。

ConnectionFactory を Spring SingleConnectionFactory でラップする場合:

  • true - 例外で、新しいコネクションを作成します。

    PooledConnectionFactory を使用する場合、このオプションを使用すると、プールされたコネクションのみが返されますが、再接続されません。

  • false - 例外で、再接続を試行しません。

targetDestination

 

宛先の JNDI 名またはプロバイダー固有の名を指定します。

replyDestination

 

応答が送信される JMS 宛先の JMS 名を指定します。このプロパティーでは、応答にユーザー定義の宛先を使用できます。詳細は、「名前付き返信先の使用」 を参照してください。

destinationResolver

DynamicDestinationResolver

Spring DestinationResolver への参照を指定します。

このプロパティーにより、宛先名がどのように JMS 宛先に解決されるかを定義できます。有効な値は次のとおりです。

  • DynamicDestinationResolver - JMS プロバイダーの機能を使用して宛先名を解決します。
  • JndiDestinationResolver - JNDI を使用して宛先名を解決します。

transactionManager

 

Spring トランザクションマネージャーへの参照を指定します。これにより、サービスは JTA トランザクションに参加できるようになります。

taskExecutor

SimpleAsyncTaskExecutor

CXF 3.0 で削除された機能

CXF 3.0 未満 Spring TaskExecutor への参照を指定します。これは、受信メッセージの処理方法を決定するリスナーで使用されます。

useJms11

false

CXF 3.0 で削除 CXF 3.0 は JMS 1.1 機能のみをサポートします。

CXF 3.0 未満 JMS 1.1 機能を使用するかどうかを指定します。有効な値は次のとおりです。

  • true - JMS 1.1 機能
  • false - JMS 1.0.2 機能

messageIdEnabled

true

CXF 3.0 で削除された機能

CXF 3.0 未満 JMS トランスポートが JMS ブローカにメッセージ ID を提供するかどうかを指定します。有効な値は次のとおりです。

  • true - ブローカーはメッセージ ID を提供する必要があります。
  • false — ブローカーはメッセージ ID を提供する必要がありません

    この場合、エンドポイントはメッセージプロデューサーの setDisableMessageID() メソッドを true の値で呼び出します。ブローカーは、メッセージ ID を生成したり、エンドポイントのメッセージに追加したりする必要がないというヒントが与えられます。ブローカーはヒントを受け入れるか、無視します。

messageTimestampEnabled

true

CXF 3.0 で削除された機能

CXF 3.0 未満 JMS トランスポートが JMS ブローカにメッセージタイムスタンプを提供するかどうかを指定します。有効な値は次のとおりです。

  • true - ブローカーはメッセージのタイムスタンプを提供する必要があります。
  • false — ブローカーはメッセージのタイムスタンプを提供する必要はありません。

    この場合、エンドポイントはメッセージプロデューサーの setDisableMessageTimestamp() メソッドを true の値で呼び出します。ブローカーは、タイムスタンプを生成したり、エンドポイントのメッセージに追加したりする必要がないというヒントが与えられます。ブローカーはヒントを受け入れるか、無視します。

cacheLevel

-1 (機能無効)

CXF 3.0 で削除された機能

CXF 3.0 未満 JMS リスナーコンテナーが適用されるキャッシュのレベルを指定します。有効な値は次のとおりです。

  • 0 — CACHE_NONE
  • 1 — CACHE_CONNECTION
  • 2 — CACHE_SESSION
  • 3 — CACHE_CONSUMER
  • 4 — CACHE_AUTO

詳細は、「Class DefaultMessageListenerContainer」を参照してください。

pubSubNoLocal

false

トピックを使用する際に独自のメッセージを受信するかどうかを指定します。

  • true - 独自のメッセージを受信しない
  • false — 独自のメッセージを受け取る

receiveTimeout

60000

応答メッセージを待つ時間 (ミリ秒単位) を指定します。

explicitQosEnabled

false

QoS 設定 (優先度、永続性、存続可能時間など) を各メッセージに明示的に設定するか (true)、デフォルト値 (false) を使用するかを指定します。

deliveryMode

2

メッセージが永続化されるかどうかを指定します。有効な値は次のとおりです。

  • 1 (NON_PERSISTENT) -メッセージはメモリーのみを保持します。
  • 2 (PERSISTENT) -メッセージははディスクに永続化されます。

priority

4

メッセージの優先度を指定します。JMS 優先度の値範囲は、0 (最低) から 9 (最高) までです。詳細は、JMS プロバイダーのドキュメントを参照してください。

timeToLive

0 (無期限)

送信されたメッセージが破棄されるまでの時間 (ミリ秒単位) を指定します。

sessionTransacted

false

JMS トランザクションが使用されるかどうかを指定します。

concurrentConsumers

1

CXF 3.0 で削除された機能

CXF 3.0 未満 は、リスナーの同時コンシューマーの最小数を指定します。

maxConcurrentConsumers

1

CXF 3.0 で削除された機能

CXF 3.0 未満 リスナーの同時コンシューマーの最大数を指定します。

messageSelector

 

受信メッセージのフィルターに使用されるセレクターの文字列値を指定します。このプロパティーにより、複数のコネクションがキューを共有できるようになります。メッセージセレクターを指定するために使用される構文の詳細は、「JMS 1.1 仕様」を参照してください。

subscriptionDurable

false

サーバーが永続サブスクリプションを使用するかどうかを指定します。

durableSubscriptionName

 

永続サブスクリプションの登録に使用する名前 (文字列) を指定します。

messageType

text

メッセージデータが JMS メッセージとしてパッケージ化する方法を指定します。有効な値は次のとおりです。

  • text — データを TextMessage としてパッケージ化することを指定します。
  • byte — データをバイト配列としてパッケージ化することを指定します (byte[])
  • binary — データを ByteMessage としてパッケージ化することを指定します。

pubSubDomain

false

ターゲット宛先がトピックまたはキューであるかを指定します。有効な値は次のとおりです。

  • true — topic
  • false — queue

jmsProviderTibcoEms

false

JMS プロバイダーが Tibco EMS であるかを指定します。

true に設定すると、セキュリティーコンテキストのプリンシパルが JMS_TIBCO_SENDER ヘッダーから設定されます。

useMessageIDAsCorrelationID

false

CXF 3.0 で削除された機能

JMS がメッセージ ID を使用してメッセージを関連付けるかどうかを指定します。

true に設定すると、クライアントは生成された相関 ID を設定します。

maxSuspendedContinuations

-1 (機能無効)

CXF 3.0 JMS 宛先が所有できる一時停止の最大継続数を指定します。現在の数が指定の最大値を超えると、JMSListenerContainer が停止します。

reconnectPercentOfMax

70

CXF 3.0 maxSuspendedContinuations を超える場合に JMSListenerContainer を再起動するタイミングを指定します。

現在の一時停止された競合の数が (maxSuspendedContinuations * reconnectPercentOfMax/100) の値を下回ると、リスナーコンテナーが再起動されます。

例14.2「JMS 設定 Bean」 が示すように、Bean プロパティーは bean 要素の属性として指定されます。これらはすべて Spring p namespace で宣言されます。

例14.2 JMS 設定 Bean

<bean id="jmsConfig"
      class="org.apache.cxf.transport.jms.JMSConfiguration"
      p:connectionFactory="jmsConnectionFactory"
      p:targetDestination="dynamicQueues/greeter.request.queue"
      p:pubSubDomain="false" />

エンドポイントへの設定を適用

JMSConfiguration Bean は、Apache CXF 機能メカニズムを使用してサーバーとクライアントエンドポイントに直接適用することができます。そのためには、以下の手順を実施します。

  1. エンドポイントの address 属性を jms:// に設定します。
  2. エンドポイント設定に jaxws:feature 要素を追加します。
  3. org.apache.cxf.transport.jms.JMSConfigFeature 型の Bean を機能に追加します。
  4. bean 要素の p:jmsConfig-ref 属性を JMSConfiguration Bean の ID に設定します。

例14.3「JMS 設定の JAX-WS クライアントへの追加」 は、例14.2「JMS 設定 Bean」 の JMS 設定を使用する JAX-WS クライアントを示しています。

例14.3 JMS 設定の JAX-WS クライアントへの追加

<jaxws:client id="CustomerService"
              xmlns:customer="http://customerservice.example.com/"
              serviceName="customer:CustomerServiceService"
              endpointName="customer:CustomerServiceEndpoint"
              address="jms://"
              serviceClass="com.example.customerservice.CustomerService">
  <jaxws:features>
    <bean xmlns="http://www.springframework.org/schema/beans"
          class="org.apache.cxf.transport.jms.JMSConfigFeature"
          p:jmsConfig-ref="jmsConfig"/>
  </jaxws:features>
</jaxws:client>

トランスポートへの設定を適用

JMSConfiguration Bean は、jms:jmsConfig-ref 要素を使用して JMS 連結と JMS 宛先に適用できます。jms:jmsConfig-ref 要素の値は JMSConfiguration Bean の ID です。

例14.4「JMS コンジットへの JMS 設定の追加」 は、例14.2「JMS 設定 Bean」 の JMS 設定を使用する JMS コンジットを示しています。

例14.4 JMS コンジットへの JMS 設定の追加

<jms:conduit name="{http://cxf.apache.org/jms_conf_test}HelloWorldQueueBinMsgPort.jms-conduit">
  ...
  <jms:jmsConfig-ref>jmsConf</jms:jmsConfig-ref>
</jms:conduit>

14.3. クライアント側 JMS パフォーマンスの最適化

概要

2 つの主要な設定は、プーリングと同期の受信などのクライアントの JMS パフォーマンスに影響します。

プーリング

クライアント側では、CXF は各メッセージに新しい JMS セッションと JMS プロデューサーを作成します。これは、セッションとプロデューサーオブジェクトはスレッドセーフではないためです。プロデューサーの作成は特にサーバーとの通信が必要になるため、特に時間がかかります。

プーリングコネクションファクトリーは、コネクション、セッション、プロデューサーをキャッシュすることでパフォーマンスが向上します。

ActiveMQ の場合、プーリングの設定はシンプルです。以下に例を示します。

import org.apache.activemq.ActiveMQConnectionFactory;
import org.apache.activemq.pool.PooledConnectionFactory;

ConnectionFactory cf = new ActiveMQConnectionFactory("tcp://localhost:61616");
PooledConnectionFactory pcf = new PooledConnectionFactory();

//Set expiry timeout because the default (0) prevents reconnection on failure
pcf.setExpiryTimeout(5000);
pcf.setConnectionFactory(cf);

JMSConfiguration jmsConfig = new JMSConfiguration();

jmsConfig.setConnectionFactory(pdf);

プーリングの詳細は、『Red Hat JBoss Fuse Transaction Guide』の「Appendix A Optimizing Performance of JMS Single- and Multiple-Resource Transactions」を参照してください。

同期受信の回避

リクエスト/リプライエクスチェンジでは、JMS トランスポートがリクエストを送信して応答を待機します。可能な限り、リクエスト/リプライメッセージングは JMSMessageListener を使用して非同期に実装されます。

しかし、CXF はエンドポイント間でキューを共有する必要がある場合に、同期 Consumer.receive() メソッドを使用する必要があります。このシナリオでは、MessageListener がメッセージセレクターを使用してメッセージをフィルターする必要があります。メッセージセレクターは事前に把握する必要があるため、MessageListener は 1 回だけ開かれます。

メッセージセレクターが事前に認識できない場合、次の 2 つのケースは回避してください。

  • JMSMessageIDJMSCorrelationID として使用される場合。

    JMS プロパティー useConduitIdSelector および conduitSelectorPrefix が JMS トランスポートに設定されていない場合、クライアントは JMSCorrelationId を設定しません。これにより、サーバーはリクエストメッセージの JMSMessageIdJMSCorrelationId として使用します。JMSMessageID は事前に分からないため、クライアントは同期 Consumer.receive() メソッドを使用する必要があります。

    IBM JMS エンドポイント (デフォルト) で Consumer.receive() メソッドを使用する必要があることに注意してください。

  • ユーザーはリクエストメッセージに JMStype を設定し、カスタム JMSCorrelationID を設定します。

    ここでも、カスタム JMSCorrelationID は事前に認識できないため、クライアントは同期 Consumer.receive() メソッドを使用する必要があります。

したがって、一般的なルールは、同期受信を使用する必要がある設定を使用しないようにすることです。

14.4. JMS トランザクションの設定

概要

CXF 3.0 は、一方向メッセージングを使用する場合、CXF エンドポイントでローカル JMS トランザクションと JTA トランザクションの両方をサポートします。

ローカルトランザクション

例外が発生した場合のみ、ローカルリソースを使用するトランザクションは JMS メッセージをロールバックします。データベーストランザクションなどの他のリソースを直接調整しません。

ローカルトランザクションを設定するには、通常通りエンドポイントを設定し、sessionTrasnsacted プロパティーを true に設定します。

注記

トランザクションとプーリングの詳細は『Red Hat JBoss Fuse Transaction Guide』を参照してください。

JTA トランザクション

JTA トランザクションを使用すると、任意の数の XA リソースを調整できます。CXF エンドポイントが JTA トランザクション用に設定されている場合、サービス実装を呼び出す前にトランザクションが開始されます。例外が発生しなかった場合、トランザクションはコミットされます。それ以外の場合はロールバックされます。

JTA トランザクションでは、JMS メッセージが消費され、データがデータベースに書き込まれます。例外が発生すると、両方のリソースがロールバックされるため、メッセージが消費されてデータがデータベースに書き込まれるか、メッセージがロールバックされてデータがデータベースに書き込まれません。

JTA トランザクションを設定するには、以下の 2 つの手順が必要です。

  1. トランザクションマネージャーの定義

    • Bean メソッド

      • トランザクションマネージャーの定義

        <bean id="transactionManager"
           class="org.apache.geronimo.transaction.manager.GeronimoTransactionManager"/>
      • JMS URI にトランザクションマネージャーの名前を設定

        jms:queue:myqueue?jndiTransactionManager=TransactionManager

        この例では、ID TransactionManager の Bean を検索します。

    • OSGi リファレンスメソッド

      • Blueprint を使用してトランザクションマネージャーを OSGi サービスとして検索

        <reference id="TransactionManager" interface="javax.transaction.TransactionManager"/>
      • JMS URI にトランザクションマネージャーの名前を設定

        jms:jndi:myqueue?jndiTransactionManager=java:comp/env/TransactionManager

        この例では、JNDI でトランザクションマネージャーを検索します。

  2. JCA プールされたコネクションファクトリーの設定

    Spring を使用して JCA のプールされたコネクションファクトリーを定義します。

    <bean id="xacf" class="org.apache.activemq.ActiveMQXAConnectionFactory">
      <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>
    
    <bean id="ConnectionFactory" class="org.apache.activemq.jms.pool.JcaPooledConnectionFactory">
      <property name="transactionManager" ref="transactionManager" />
      <property name="connectionFactory" ref="xacf" />
    </bean>

    この例では、最初の Bean は JcaPooledConnectionFactory に渡されたされた ActiveMQ XA コネクションファクトリーを定義します。その後、JcaPooledConnectionFactory は id ConnectionFactory のデフォルトの Bean として提供されます。

    JcaPooledConnectionFactory は通常の ConnectionFactory のようになります。しかし、新しいコネクションおよびセッションが開かれると、XA トランザクションがチェックされ、見つかった場合は JMS セッションを XA リソースとして自動的に登録します。これにより、JMS セッションが JMS トランザクションに参加できるようになります。

    重要

    JMS トランスポートに XA ConnectionFactory を直接設定しても動作しません。

14.5. WSDL を使用した JMS の設定

14.5.1. JMS WSDL エクステンション namespance

JMS エンドポイントを定義するための WSDL エクステンションは、namespace http://cxf.apache.org/transports/jms で定義されます。。JMS エクステンションを使用するには、例14.5「JMS WSDL エクステンション namespance」 に示す行をコントラクトの definitions 要素に追加する必要があります。

例14.5 JMS WSDL エクステンション namespance

xmlns:jms="http://cxf.apache.org/transports/jms"

14.5.2. 基本的な JMS 設定

概要

JMS アドレス情報は、jms:address 要素とその子である jms:JMSNamingProperties 要素を使用して提供されます。jms:address要素の属性は、JMS ブローカーと宛先を識別するために必要な情報を指定します。jms:JMSNamingProperties 要素は、JNDI サービスへのコネクションに使用される Java プロパティーを指定します。

重要

JMS 機能を使用して指定された情報は、エンドポイントの WSDL ファイルの情報をオーバーライドします。

JMS アドレスの指定

JMS エンドポイントの基本設定は、jms:address 要素をサービスの port 要素の子要素として使用して行われます。WSDL で使用される jms:address 要素は、設定ファイルで使用されるものと同じです。その属性は 表14.2「JMS エンドポイント属性」 にリストされています。

表14.2 JMS エンドポイント属性

属性説明

destinationStyle

JMS 宛先が JMS キューまたは JMS トピックであるかどうかを指定します。

jndiConnectionFactoryName

JMS 宛先への接続時に使用する JMS コネクションファクトリーにバインドされた JNDI 名を指定します。

jmsDestinationName

リクエストが送信される JMS 宛先の JMS 名を指定します。

jmsReplyDestinationName

応答が送信される JMS 宛先の JMS 名を指定します。この属性を使用すると、返信にユーザー定義の送信先を使用できます。詳細は、「名前付き返信先の使用」 を参照してください。

jndiDestinationName

リクエストが送信される JMS 宛先にバインドされた JNDI 名を指定します。

jndiReplyDestinationName

応答が送信される JMS 宛先にバインドされた JNDI 名を指定します。この属性を使用すると、返信にユーザー定義の送信先を使用できます。詳細は、「名前付き返信先の使用」 を参照してください。

connectionUserName

JMS ブローカーへの接続時に使用するユーザー名を指定します。

connectionPassword

JMS ブローカーへの接続時に使用するパスワードを指定します。

jms:address WSDL 要素は jms:JMSNamingProperties 子要素を使用して、JNDI プロバイダーへの接続に必要な追加情報を指定します。

JNDI プロパティーの指定

JMS および JNDI プロバイダーとの相互運用性を高めるために、jms:address 要素には子要素 jms:JMSNamingProperties があり、JNDI プロバイダーへの接続時に使用されるプロパティーの設定に使用される値を指定できます。jms:JMSNamingProperties 要素には namevalue の 2 つの属性があります。name は設定するプロパティーの名前を指定します。value 属性は、指定されたプロパティーの値を指定します。jms:JMSNamingProperties 要素は、プロバイダー固有のプロパティーの指定にも使用できます。

以下に、設定できる一般的な JNDI プロパティーのリストを示します。

  1. java.naming.factory.initial
  2. java.naming.provider.url
  3. java.naming.factory.object
  4. java.naming.factory.state
  5. java.naming.factory.url.pkgs
  6. java.naming.dns.url
  7. java.naming.authoritative
  8. java.naming.batchsize
  9. java.naming.referral
  10. java.naming.security.protocol
  11. java.naming.security.authentication
  12. java.naming.security.principal
  13. java.naming.security.credentials
  14. java.naming.language
  15. java.naming.applet

これらの属性で使用する情報の詳細は、JNDI プロバイダーのドキュメントを参照し、Java API リファレンス資料を参照してください。

例14.6「JMS WSDL ポート指定」 は、JMS WSDL port 指定の例を示しています。

例14.6 JMS WSDL ポート指定

<service name="JMSService">
  <port binding="tns:Greeter_SOAPBinding" name="SoapPort">
    <jms:address jndiConnectionFactoryName="ConnectionFactory"
                 jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" >
      <jms:JMSNamingProperty name="java.naming.factory.initial"
                             value="org.activemq.jndi.ActiveMQInitialContextFactory" />
      <jms:JMSNamingProperty name="java.naming.provider.url"
                             value="tcp://localhost:61616" />
    </jms:address>
  </port>
</service>

14.5.3. JMS クライアント設定

概要

JMS コンシューマーエンドポイントは、使用するメッセージの型を指定します。JMS コンシューマーエンドポイントは、JMS ByteMessage または JMS TextMessage のいずれかを使用できます。

ByteMessage を使用する場合、コンシューマーエンドポイントは byte[] を、JMS メッセージボディーからデータを保存し、取得する方法として使用します。メッセージが送信されると、フォーマット情報を含むメッセージデータは byte[] にパッケージ化され、ネットワークに置かれる前にメッセージボディーに配置されます。メッセージが受信されると、コンシューマーエンドポイントは、メッセージボディーに格納されているデータを byte[] にパックしたかのようにアンマーシャルしようとします。

TextMessage を使用する場合、コンシューマーエンドポイントはメッセージボディーからデータを保存および取得するためのメソッドとして文字列を使用します。メッセージが送信されると、形式固有の情報を含むメッセージ情報は文字列に変換され、JMS メッセージボディーに配置されます。メッセージが受信されると、コンシューマーエンドポイントは、JMS メッセージボディーに格納されているデータを文字列にパックしたかのようにアンマーシャルしようとします。

ネイティブ JMS アプリケーションが Apache CXF コンシューマーと対話する場合、JMS アプリケーションはメッセージとフォーマット情報を解釈します。たとえば、Apache CXF コントラクトで JMS エンドポイントに使用されるバインディングが SOAP であると指定され、メッセージが TextMessage としてパッケージ化されている場合、受信側の JMS アプリケーションは、すべての SOAP エンベロープ情報を含むテキストメッセージを取得します。

メッセージ型の指定

JMS コンシューマーエンドポイントによって許可されるメッセージの型は、オプションの jms:client 要素を使用して設定されます。jms:client 要素は WSDL port 要素の子であり、属性が 1 つあります。

表14.3 JMS クライアント WSDL エクステンション

messageType

メッセージデータが JMS メッセージとしてパッケージ化する方法を指定します。text はデータが TextMessage としてパッケージ化されることを指定します。binary はデータが ByteMessage としてパッケージ化されることを指定します。

例14.7「JMS コンシューマーエンドポイントの WSDL」 は、JMS コンシューマーエンドポイントを設定するための WSDL を示しています。

例14.7 JMS コンシューマーエンドポイントの WSDL

<service name="JMSService">
  <port binding="tns:Greeter_SOAPBinding" name="SoapPort">
    <jms:address jndiConnectionFactoryName="ConnectionFactory"
                 jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" >
      <jms:JMSNamingProperty name="java.naming.factory.initial"
                             value="org.activemq.jndi.ActiveMQInitialContextFactory" />
      <jms:JMSNamingProperty name="java.naming.provider.url"
                             value="tcp://localhost:61616" />
    </jms:address>
    <jms:client messageType="binary" />
  </port>
</service>

14.5.4. JMS プロバイダーの設定

概要

JMS プロバイダーエンドポイントには設定可能な動作が多数あります。これらには以下が含まれます。

  • メッセージを相関する方法
  • 永続サブスクリプションの使用
  • サービスがローカルの JMS トランザクションを使用する場合
  • エンドポイントによって使用されるメッセージセレクター

設定の指定

プロバイダーエンドポイントの動作は、オプションの jms:server 要素を使用して設定されます。jms:server 要素は WSDL wsdl:port 要素の子で、以下の属性があります。

表14.4 JMS プロバイダーエンドポイント WSDL エクステンション

属性説明

useMessageIDAsCorrealationID

JMS がメッセージ ID を使用してメッセージを関連付けるかどうかを指定します。デフォルトは false です。

durableSubscriberName

永続サブスクリプションの登録に使用する名前を指定します。

messageSelector

使用するメッセージセレクターの文字列値を指定します。メッセージセレクターを指定するために使用される構文の詳細は、JMS 1.1 仕様を参照してください。

transactional

ローカル JMS ブローカーがメッセージ処理にトランザクションを作成するかどうかを指定します。デフォルトは false です。[a]

[a] 現在、transactional 属性を true に設定することは、ランタイムによってサポートされません。

例14.8「JMS プロバイダーエンドポイントの WSDL」 は、JMS プロバイダーエンドポイントを設定するための WSDL を示しています。

例14.8 JMS プロバイダーエンドポイントの WSDL

<service name="JMSService">
  <port binding="tns:Greeter_SOAPBinding" name="SoapPort">
    <jms:address jndiConnectionFactoryName="ConnectionFactory"
                 jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" >
      <jms:JMSNamingProperty name="java.naming.factory.initial"
                             value="org.activemq.jndi.ActiveMQInitialContextFactory" />
      <jms:JMSNamingProperty name="java.naming.provider.url"
                             value="tcp://localhost:61616" />
    </jms:address>
    <jms:server messageSelector="cxf_message_selector"
                useMessageIDAsCorrelationID="true"
                transactional="true"
                durableSubscriberName="cxf_subscriber" />
  </port>
</service>

14.6. 名前付き返信先の使用

概要

デフォルトでは、JMS を使用する Apache CXF エンドポイントは、応答の送受信するための一時キューを作成します。名前付きキューを使用する場合は、エンドポイントの JMS 設定の一部として応答を送信するために使用されるキューを設定できます。

返信先名の設定

返信先は、jmsReplyDestinationName 属性またはエンドポイントの JMS 設定の jndiReplyDestinationName 属性を使用して指定します。クライアントエンドポイントは、指定された宛先で応答をリッスンし、すべての送信要求の ReplyTo フィールドに属性の値を指定します。サービスエンドポイントは、リクエストの ReplyTo フィールドに宛先が指定されていない場合に、応答の送信先として jndiReplyDestinationName 属性の値を使用します。

例14.9「名前付き返信キューを使用した JMS コンシューマー指定」 は、JMS クライアントエンドポイントの設定を示しています。

例14.9 名前付き返信キューを使用した JMS コンシューマー指定

<jms:conduit name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-conduit">
    <jms:address destinationStyle="queue"
                 jndiConnectionFactoryName="myConnectionFactory"
                 jndiDestinationName="myDestination"
                 jndiReplyDestinationName="myReplyDestination" >
      <jms:JMSNamingProperty name="java.naming.factory.initial"
                             value="org.apache.cxf.transport.jms.MyInitialContextFactory" />
      <jms:JMSNamingProperty name="java.naming.provider.url"
                             value="tcp://localhost:61616" />
    </jms:address>
  </jms:conduit>

第15章 Apache ActiveMQ との統合

概要

Apache ActiveMQ を JMS プロバイダーとして使用する場合は、宛先の JNDI 名を、キューまたはトピックの JNDI バインディングを動的に作成する特別な形式で指定できます。つまり、キューまたはトピックの JNDI バインディングを使用して JMS プロバイダーを事前に設定する必要はありません

最初のコンテキストファクトリー

Apache ActiveMQ と JNDI を統合するキーは ActiveMQInitialContextFactory クラスです。このクラスは、JNDI InitialContext インスタンスを作成するために使用され、JMS ブローカーの JMS 宛先にアクセスするために使用できます。

例15.1「Apache ActiveMQ に接続する SOAP/JMS WSDL」 は、Apache ActiveMQ と統合された JNDI InitialContext を作成するための SOAP/JMS WSDL エクステンションを示しています。

例15.1 Apache ActiveMQ に接続する SOAP/JMS WSDL

<soapjms:jndiInitialContextFactory>
  org.apache.activemq.jndi.ActiveMQInitialContextFactory
</soapjms:jndiInitialContextFactory>
<soapjms:jndiURL>tcp://localhost:61616</soapjms:jndiURL>

例15.1「Apache ActiveMQ に接続する SOAP/JMS WSDL」 では、Apache ActiveMQ クライアントは tcp://localhost:61616 にあるブローカーポートに接続します。

コネクションファクトリーの検索

JNDI InitialContext インスタンスの作成も、javax.jms.ConnectionFactory インスタンスにバインドされる JNDI 名を指定する必要があります。Apache ActiveMQ の場合、InitialContext インスタンスに事前定義されたバインディングがあり、JNDI 名 ConnectionFactoryActiveMQConnectionFactory インスタンスにマッピングします。例15.2「Apache ActiveMQ コネクションファクトリーを指定するための SOAP/JMS WSDL」 は Apache ActiveMQ 接続ファクトリーを指定するための SOAP/JMS エクステンション要素を示しています。

例15.2 Apache ActiveMQ コネクションファクトリーを指定するための SOAP/JMS WSDL

<soapjms:jndiConnectionFactoryName>
  ConnectionFactory
</soapjms:jndiConnectionFactoryName>

動的宛先の構文

キューまたはトピックに動的にアクセスするには、宛先の JNDI 名を、以下のいずれかの形式で JNDI 複合名として指定します。

dynamicQueues/QueueName
dynamicTopics/TopicName

QueueName および TopicName は、Apache ActiveMQ ブローカーが使用する名前です。これらは抽象 JNDI 名では ありません

例15.3「動的に作成されたキューを持つ WSDL ポートの指定」 は、動的に作成されたキューを使用する WSDL ポートを示しています。

例15.3 動的に作成されたキューを持つ WSDL ポートの指定

<service name="JMSService">
  <port binding="tns:GreeterBinding" name="JMSPort">
    <jms:address jndiConnectionFactoryName="ConnectionFactory"
                 jndiDestinationName="dynamicQueues/greeter.request.queue" >
      <jms:JMSNamingProperty name="java.naming.factory.initial"
                             value="org.activemq.jndi.ActiveMQInitialContextFactory" />
      <jms:JMSNamingProperty name="java.naming.provider.url"
                             value="tcp://localhost:61616" />
    </jms:address>
  </port>
</service>

アプリケーションが JMS コネクションを開こうとすると、Apache ActiveMQ は JNDI 名 greeter.request.queue を持つキューが存在するかどうかを確認します。存在しない場合は、新しいキューを作成し、JNDI 名 greeter.request.queue にバインドします。

第16章 コンジット

概要

コンジットは、アウトバウンド接続を実装するために使用されるトランスポートアーキテクチャーの低レベルの部分です。これらの動作とライフサイクルは、システムのパフォーマンスと処理負荷に影響を与える可能性があります。

概要

コンジットは、Apache CXF ランタイムのクライアント側またはアウトバウンドトランスポートの詳細を管理します。これらは、ポートを開き、アウトバウンドコネクションの確立やメッセージの送信を行い、アプリケーションと 1 つの外部エンドポイント間の応答のリッスンします。アプリケーションが複数のエンドポイントに接続する場合、各エンドポイントに 1 つのコンジットインスタンスがあります。

各トランスポート型は、Conduit インターフェースを使用して独自のコンジットを実装します。これにより、アプリケーションレベルの機能およびトランスポート間の標準化されたインターフェースを使用できます。

一般的に、クライアント側のトランスポート情報を設定する際に、アプリケーションによって使用されるコンジットについてのみ検討する必要があります。ランタイムがコンジットを処理する方法の基本的なセマンティクスは、一般に、開発者が検討する必要はありません。

ただし、コンジットを理解していると便利な場合があります。

  • カスタムトランスポートの実装
  • 限られたリソースを管理するための高度なアプリケーションチューニング

コンジットのライフサイクル

コンジットは、クライアント実装オブジェクトによって管理されます。コンジットが作成されると、クライアント実装オブジェクトの期間、コンジットが存続します。コンジットのライフサイクルは、以下のとおりです。

  1. クライアント実装オブジェクトが作成されると、ConduitSelector オブジェクトへの参照が指定されます。
  2. クライアントがメッセージを送信する必要がある場合は、コンジットセレクターからのコンジットへの参照が要求されます。

    メッセージが新しいエンドポイント用である場合、コンジットセレクターは新しいコンジットを作成し、それをクライアント実装に渡します。それ以外の場合は、ターゲットエンドポイントのコンジットへの参照をクライアントに渡します。

  3. コンジットは、必要に応じてメッセージを送信します。
  4. クライアント実装オブジェクトが破棄されると、それに関連付けられたすべてのコンジットが破棄されます。

コンジットの重み

コンジットオブジェクトの重みは、トランスポート実装により異なります。HTTP コンジットは非常に軽量です。JMS コンジットは、JMS Session オブジェクトと 1 つ以上の JMSListenerContainer オブジェクトに関連付けられるため重くなります。

パート IV. Web サービスのエンドポイントの設定

本書では、Red Hat Fuse で Apache CXF エンドポイントを作成する方法を説明します。

第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 の形式で提供されます。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 の設定

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 の形式で提供されます。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 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 プロパティーで使用できる値のリストは、「スキーマ検証の型の値」を参照してください。

17.2. コンシューマーエンドポイントの設定

概要

JAX-WS コンシューマーエンドポイントは jaxws:client 要素を使用して設定されます。要素の属性は、コンシューマーの作成に必要な基本的な情報を提供します。

WS-RM などのその他の機能をコンシューマーに追加するには、子を jaxws:client 要素に追加します。子要素は、エンドポイントのロギング動作を設定するためや、他のプロパティーをエンドポイントの実装に注入するためにも使用されます。

基本的な設定プロパティ

表17.4「JAX-WS コンシューマーの設定に使用される属性」で説明されている属性は、JAX-WS コンシューマーの設定に必要な基本情報を提供します。設定する特定のプロパティーの値のみを指定する必要があります。ほとんどのプロパティーには実用的なデフォルトがあります。または、エンドポイントのコントラクトによって提供される情報に依存します。

表17.4 JAX-WS コンシューマーの設定に使用される属性

属性説明

address

コンシューマーがリクエストを行うエンドポイントの HTTP アドレスを指定します。この値は、コントラクトで設定された値をオーバーライドします。

bindingId

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

bus

エンドポイントを管理するバスを設定する Spring Bean の ID を指定します。

endpointName

コンシューマーがリクエストを行うサービスの wsdl:port 要素の name 属性の値を指定します。これは、ns:name 形式を使用して QName として指定されます。ここで、nswsdl:port 要素の namespace です。

serviceName

コンシューマーがリクエストを行うサービスの wsdl:service 要素の name 属性の値を指定します。これは、ns:name 形式を使用して QName として指定されます。ここで、nswsdl:service 要素の namespace です。

username

単純なユーザー名/パスワード認証に使用されるユーザー名を指定します。

password

単純なユーザー名/パスワード認証に使用されるパスワードを指定します。

serviceClass

サービスエンドポイントインターフェース (SEI) の名前を指定します。

wsdlLocation

エンドポイントの WSDL コントラクトの場所を指定します。WSDL コントラクトの場所は、クライアントがデプロイされるフォルダーに対する相対パスです。

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

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

デフォルトは false です。

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

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

表17.4「JAX-WS コンシューマーの設定に使用される属性」に一覧表示される属性の他に、複数の xmlns:shortName 属性を使用して endpointName および serviceName 属性によって使用される namespace を宣言する必要がある場合があります。

機能の追加

コンシューマーに機能を追加したり、高度な設定を実施するには、設定に子要素を追加する必要があります。

子要素を使用すると、以下を実行できます。

表17.5「コンシューマーエンドポイント設定用の要素」に、JAX-WS コンシューマーの設定に使用できる子要素をまとめます。

表17.5 コンシューマーエンドポイント設定用の要素

要素説明

jaxws:binding

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

jaxws:dataBinding

エンドポイントによって使用されるデータバインディングを実装するクラスを指定します。埋め込み Bean 定義を使用してこれを指定します。JAXB データバインディングを実装するクラスは org.apache.cxf.jaxb.JAXBDataBinding です。

jaxws:features

Apache CXF の高度な機能を設定する Bean のリストを指定します。Bean 参照のリストまたは組み込み Bean のリストを指定できます。

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:properties

エンドポイントに渡されるプロパティーのマップを指定します。

jaxws:conduitSelector

クライアントが使用する org.apache.cxf.endpoint.ConduitSelector 実装を指定します。ConduitSelector 実装は、アウトバウンドリクエストの処理に使用される Conduit オブジェクトを選択するために使用されるデフォルトのプロセスを上書きします。

[a] SOAP バインディングは soap:soapBinding Bean を使用して設定されます。

例17.5「単純なコンシューマー設定」に単純なコンシューマー設定を示します。

例17.5 単純なコンシューマー設定

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:client id="bookClient"
                serviceClass="org.apache.cxf.demo.BookClientImpl"
                address="http://localhost:8080/books"/>
  ...
</beans>

JAX-WS コンシューマーでのスキーマ検証の有効化

JAX-WS コンシューマーでスキーマ検証を有効にするには、jaxws:client 要素の jaxws:properties 子要素の schema-validation-enabled プロパティーを設定します。以下に例を示します。

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

schema-validation-enabled プロパティーで使用できる値のリストは、「スキーマ検証の型の値」を参照してください。

第18章 JAX-RS エンドポイントの設定

概要

本章では、Blueprint XML と Spring XML で JAX-RS サーバーエンドポイントをインスタンス化して設定する方法や、XML で JAX-RS クライアントエンドポイント (クライアントプロキシー Bean) をインスタンス化して設定する方法を説明します。

18.1. JAX-RS サーバーエンドポイントの設定

18.1.1. JAX-RS サーバーエンドポイントの定義

基本的なサーバーエンドポイント定義

XML で JAX-RS サーバーエンドポイントを定義するには、少なくとも以下の項目を指定する必要があります。

  1. XML でエンドポイントを定義するために使用される jaxrs:server 要素。jaxrs: namespace のプレフィックスは、Blueprint と Spring のそれぞれ 異なる namespace にマッピングされることに注意してください。
  2. jaxrs:server 要素の address 属性を使用した JAX-RS サービスのベース URL。アドレス URL を指定する方法は 2 つあり、エンドポイントがどのようにデプロイされるかに影響を及ぼします。

    • 相対 URL として (例: /customers)。この場合、エンドポイントはデフォルトの HTTP コンテナーにデプロイされます。また、CXF サーブレットベース URL と指定の相対パス URL を組み合わせることで、エンドポイントのベース URL が暗黙的に取得されます。

      たとえば、JAX-RS エンドポイントを Fuse コンテナーにデプロイする場合、指定の /customers URL は URL http://Hostname:8181/cxf/customers に解決されます (コンテナーがデフォルトの 8181 ポートを使用していることを前提とします)。

    • 絶対 URL として (例: http://0.0.0.0:8200/cxf/customers)。この場合、新しい HTTP リスナーポートが JAX-RS エンドポイントに対して開きます (まだ開かていない場合は)。たとえば、Fuse のコンテキストでは、JAX-RS エンドポイントをホストするために新しい Undertow コンテナーが暗黙的に作成されます。特別な IP アドレス 0.0.0.0 はワイルドカードとして動作し、現在のホストに割り当てられた任意のホスト名にマッチします (マルチホームのホストマシンで便利です)。
  3. JAX-RS サービスの実装を提供する 1 つまたは複数の JAX-RS ルートリソースクラス。リソースクラスを指定する最も簡単な方法は、jaxrs:serviceBeans 要素内でリソースクラスをリストすることです。

Blueprint の例

以下の 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 XML の namespace

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

Spring の例

以下の 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 XML の namespace

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

Spring XML での自動検出

(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 XML でのライフサイクル管理

(Spring のみ) Spring XML では、bean 要素の scope 属性を設定することで、Bean のライフサイクルを制御できます。以下のスコープ値が Spring によってサポートされます。

singleton
(デフォルト) 単一の Bean インスタンスを作成します。このインスタンスはどこででも使用され、Spring コンテナーの全ライフタイム期間中存在します。
prototype
Bean が別の Bean に注入されるたびに、または Bean レジストリーで getBean() を呼び出して Bean を取得する際に、新しい Bean インスタンスを作成します。
request
(Web 対応コンテナーでのみ利用可能) Bean で呼び出されるすべてのリクエストに対して、新しい Bean インスタンスを作成します。
session
(Web 対応コンテナーでのみ利用可能) 単一の HTTP セッションのライフタイム期間中、新しい Bean を作成します。
globalSession
(Web 対応コンテナーでのみ利用可能) ポートレット間で共有される単一の HTTP セッションのライフタイム期間中、新しい Bean を作成します。

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>

上記の例では、customerBean1customerBean2 の 2 つのリソース Bean を設定します。beanNames 属性は、リソース Bean ID のスペース区切りリストとして指定されます。

JAX-RS サーバーエンドポイントを設定する際に最高の柔軟性を確保するために、jaxrs:serviceFactories 要素を使用してサービスファクトリーオブジェクトを 明示的に 定義するオプションがあります。このより詳細なアプローチには、デフォルトのサービスファクトリーの実装をカスタム実装に置き換えることができるため、Bean のライフサイクルを厳密に制御できるというメリットがあります。以下の例は、このアプローチを使用して、2 つのリソース Bean (customerBean1customerBean2) を設定する方法を示しています。

<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>
注記

シングルトン以外のライフサイクルを指定する場合は、org.apache.cxf.service.Invoker Bean を実装および登録することが推奨されます (インスタンスは jaxrs:server/jaxrs:invoker 要素から参照して登録できます)。

WADL ドキュメントの割り当て

任意で、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>

JMS トランスポートの使用

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>

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

  • JMS 実装: JMS 実装は ConnectionFactory Bean によって提供され、Apache ActiveMQ 接続ファクトリーオブジェクトをインスタンス化します。接続ファクトリーをインスタンス化すると、デフォルトの JMS 実装レイヤーとして自動的にインストールされます。
  • JMS 経路オブジェクトまたは宛先オブジェクト: Apache CXF は、JMS 経路オブジェクト (JMS コンシューマーを表すため) または JMS 宛先オブジェクト (JMS プロバイダーを表すため) を暗黙的にインスタンス化します。このオブジェクトは、属性設定 xmlns:s="http://books.com" (namespace のプレフィックスを定義) と serviceName="s:BookService" (QName を定義) で定義される QName によって一意に識別される必要があります。
  • トランスポート ID: JMS トランスポートを選択するには、transportId 属性を http://cxf.apache.org/transports/jms に設定する必要があります。
  • JMS アドレス: jaxrs:server/@address 属性は標準化された構文を使用して送信する JMS キューまたは JMS トピックを指定します。この構文の詳細については、「URI Scheme for Java(tm) Message Service 1.0 draft-merrick-jms-uri-06」を参照してください。

拡張マッピングおよび言語マッピング

ファイルサフィックス (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.2. jaxrs:server 属性

属性

表18.1「JAX-RS サーバーエンドポイント属性」jaxrs:server 要素で利用可能な属性をまとめます。

表18.1 JAX-RS サーバーエンドポイント属性

属性説明

id

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

address

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

basePackages

(Spring のみ) Java パッケージのコンマ区切りリストを指定して、自動検出を有効にします。パッケージを検索して JAX-RS ルートリソースクラスや JAX-RS プロバイダークラスを検出します。

beanNames

JAX-RS ルートリソース Bean の Bean ID のスペース区切りリストを指定します。Spring XML のコンテキストでは、ルートリソース bean 要素に scope 属性を設定することで、ルートリソース Bean のライフサイクルを定義できます。

bindingId

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

bus

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

docLocation

外部 WADL ドキュメントの場所を指定します。

modelRef

モデルスキーマをクラスパスリソースとして指定します (例: classpath:/path/to/model.xml 形式の URL)。JAX-RS モデルスキーマの定義方法に関する詳細は、「モデルスキーマを使用した REST サービスの定義」を参照してください。

publish

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

publishedEndpointUrl

自動生成される WADL インターフェースの wadl:resources/@base 属性に挿入される URL ベースアドレスを指定します。

serviceAnnotation

(Spring のみ) Spring の自動検出用に、サービスアノテーションのクラス名を指定します。basePackages プロパティーと組み合わせると、このオプションは自動検出されたクラスのコレクションにこのアノテーション型でアノテーションが付けられたクラス だけ を含めるように制限します。考えてください!!正しいですか?

serviceClass

(JAX-RS サービスを実装する) JAX-RS ルートリソースクラスの名前を指定します。この場合、クラスは Blueprint または Spring ではなく、Apache CXF によってインスタンス化されます。Blueprint または Spring でクラスをインスタンス化する場合は、代わりに jaxrs:serviceBeans 子要素を使用します。

serviceName

JMS トランスポートが使用される特別なケースの JAX-RS エンドポイントのサービス QName を指定します (ns:name の形式を使用)。詳細は、「JMS トランスポートの使用」を参照してください。

staticSubresourceResolution

true の場合、静的なサブリソースの動的解決を無効にします。デフォルトは false です。

transportId

(HTTP の代わりに) 非標準のトランスポート層を選択します。特に、このプロパティーを http://cxf.apache.org/transports/jms に設定すると、JMS トランスポートを選択できます。詳細は、「JMS トランスポートの使用」を参照してください。

abstract

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

depends-on

(Spring のみ) エンドポイントをインスタンス化する前に、エンドポイントがインスタンス化されることに依存する Bean のリストを指定します。

18.1.3. jaxrs:server 子要素

子要素

表18.2「JAX-RS サーバーエンドポイントの子要素」jaxrs:server 要素の子要素をまとめます。

表18.2 JAX-RS サーバーエンドポイントの子要素

要素説明

jaxrs:executor

サービスに使用される Java Executor (スレッドプール実装) を指定します。これは組み込み Bean 定義を使用して指定されます。

jaxrs:features

Apache CXF の高度な機能を設定する Bean のリストを指定します。Bean 参照のリストまたは組み込み Bean のリストを指定できます。

jaxrs:binding

使用されていない。

jaxrs:dataBinding

エンドポイントによって使用されるデータバインディングを実装するクラスを指定します。これは組み込み Bean 定義を使用して指定されます。詳細は、「データバインディングの指定」を参照してください。

jaxrs:inInterceptors

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

jaxrs:inFaultInterceptors

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

jaxrs:outInterceptors

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

jaxrs:outFaultInterceptors

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

jaxrs:invoker

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

jaxrs:serviceFactories

このエンドポイントに関連付けられた JAX-RS ルートリソースのライフサイクルに対する最大レベルの制御を提供します。この要素の子 (org.apache.cxf.jaxrs.lifecycle.ResourceProvider 型のインスタンスでなければならない) は、JAX-RS ルートリソースインスタンスを作成するために使用されます。

jaxrs:properties

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

jaxrs:serviceBeans

この要素の子は、JAX-RS ルートリソースのインスタンス (bean 要素) または JAX-RS ルートリソースへの参照 (ref 要素) です。この場合、scope 属性 (Spring のみ)bean 要素にある場合、この属性は無視される点に注意してください。

jaxrs:modelBeans

1 つまたは複数の org.apache.cxf.jaxrs.model.UserResource Bean への参照のリストで構成されます。この参照はリソースモデルの基本要素です (jaxrs:resource 要素に対応)。詳細は、「モデルスキーマを使用した REST サービスの定義」を参照してください。

jaxrs:model

このエンドポイントに直接リソースモデルを定義します (つまり、この jaxrs:model 要素には 1 つまたは複数の jaxrs:resource 要素を含めることができます)。詳細は、「モデルスキーマを使用した REST サービスの定義」を参照してください。

jaxrs:providers

このエンドポイントに 1 つまたは複数のカスタム JAX-RS プロバイダーを登録できます。この要素の子は、JAX-RS プロバイダーのインスタンス (bean 要素) または JAX-RS プロバイダーへの参照 (ref 要素) です。

jaxrs:extensionMappings

REST 呼び出しの URL がファイル拡張子で終わる場合、この要素を使用して、自動的に特定のコンテンツ型に関連付けることができます。たとえば、.xml ファイル拡張子は application/xml コンテンツ型に関連付けることができます。詳細は、「拡張マッピングおよび言語マッピング」を参照してください。

jaxrs:languageMappings

REST 呼び出しの URL が言語サフィックスで終わる場合、この要素を使用して、これを特定の言語にマッピングすることができます。たとえば、.en 言語サフィックスは en-GB 言語に関連付けることができます。詳細は、「拡張マッピングおよび言語マッピング」を参照してください。

jaxrs:schemaLocations

XML メッセージコンテンツの検証に使用する 1 つまたは複数の XML スキーマを指定します。この要素には、1 つまたは複数の jaxrs:schemaLocation 要素を含めることができます。各要素は、XML スキーマファイルの場所を指定します (通常は classpath URL として)。詳細は、「スキーマの検証」を参照してください。

jaxrs:resourceComparator

カスタムリソースコンパレーターを登録できます。このコンパレーターは、受信 URL パスを特定のリソースクラスまたはメソッドと照合するのに使用するアルゴリズムを実装します。

jaxrs:resourceClasses

(Blueprint のみ) クラス名から複数のリソースを作成する場合には、jaxrs:server/@serviceClass 属性の代わりに使用することができます。jaxrs:resourceClasses の子は、name 属性がリソースクラスの名前に設定された class 要素でなければなりません。この場合、クラスは Blueprint または Spring ではなく、Apache CXF によってインスタンス化されます。

[a] Invoker 実装は、サービスがどのように呼び出されれるかを制御します。たとえば、各リクエストがサービス実装の新規インスタンスによって処理されるかどうか、あるいは次回の呼び出し時に状態が保持されるかどうかを制御します。

18.2. JAX-RS クライアントエンドポイントの設定

18.2.1. JAX-RS クライアントエンドポイントの定義

クライアントプロキシーの注入

XML 言語 (Blueprint XML または Spring XML) でクライアントプロキシー Bean をインスタンス化する主なポイントは、別の Bean に注入することです。続いてクライアントプロキシーを使用して REST サービスを呼び出すことができます。XML でクライアントプロキシー Bean を作成するには、jaxrs:client 要素を使用します。

namespace

JAX-RS クライアントエンドポイントは、サーバーエンドポイントとは 異なる XML namespace を使用して定義されます。以下の表で、それぞれの XML 言語に使用する namespace を説明します。

XML 言語クライアントエンドポイントの namespace

Blueprint

http://cxf.apache.org/blueprint/jaxrs-client

Spring

http://cxf.apache.org/jaxrs-client

基本的なクライアントエンドポイント定義

以下の例は、Blueprint XML または Spring XML でクライアントプロキシー Bean を作成する方法を示しています。

<jaxrs:client id="restClient"
       address="http://localhost:8080/test/services/rest"
       serviceClass="org.apache.cxf.systest.jaxrs.BookStoreJaxrsJaxws"/>

基本的なクライアントエンドポイントを定義するには、以下の属性を設定する必要があります。

id
クライアントプロキシーの Bean ID を使用すると、XML 設定の他の Bean にクライアントプロキシーを注入できます。
address
address 属性は REST 呼び出しのベース URL を指定します。
serviceClass
serviceClass 属性は、ルートリソースクラス (@Path によりアノテーションが付けられる) を指定して、REST サービスの説明を提供します。実際、これは サーバー クラスですが、クライアントによって直接使用されません。指定のクラスは、クライアントプロキシーを動的に構築するために使用されるメタデータにのみ使用されます (Java リフレクションおよび JAX-RS アノテーションを使用して)。

ヘッダーの指定

以下のように、jaxrs:headers 子要素を使用して、HTTP ヘッダーをクライアントプロキシーの呼び出しに追加できます。

<jaxrs:client id="restClient"
       address="http://localhost:8080/test/services/rest"
       serviceClass="org.apache.cxf.systest.jaxrs.BookStoreJaxrsJaxws"
       inheritHeaders="true">
       <jaxrs:headers>
           <entry key="Accept" value="text/xml"/>
       </jaxrs:headers>
</jaxrs:client>

18.2.2. jaxrs:client 属性

属性

表18.3「JAX-RS クライアントエンドポイント属性」jaxrs:client 要素で利用可能な属性をまとめます。

表18.3 JAX-RS クライアントエンドポイント属性

属性説明

address

コンシューマーがリクエストを行うエンドポイントの HTTP アドレスを指定します。この値は、コントラクトで設定された値をオーバーライドします。

bindingId

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

bus

エンドポイントを管理するバスを設定する Spring Bean の ID を指定します。

inheritHeaders

サブリソースプロキシーがこのプロキシーから作成される場合に、このプロキシーに設定されたヘッダーが継承されるかどうかを指定します。デフォルトは false です。

username

単純なユーザー名/パスワード認証に使用されるユーザー名を指定します。

password

単純なユーザー名/パスワード認証に使用されるパスワードを指定します。

modelRef

モデルスキーマをクラスパスリソースとして指定します (例: classpath:/path/to/model.xml 形式の URL)。JAX-RS モデルスキーマの定義方法に関する詳細は、「モデルスキーマを使用した REST サービスの定義」を参照してください。

serviceClass

サービスインターフェースまたはリソースクラス ( @PATH によりアノテーションが付けられる) の名前を指定し、JAX-RS サーバー実装から再利用します。この場合、指定されたクラスは直接 呼び出されません (実際にはサーバークラスです)。指定のクラスは、クライアントプロキシーを動的に構築するために使用されるメタデータにのみ使用されます (Java リフレクションおよび JAX-RS アノテーションを使用して)。

serviceName

JMS トランスポートが使用される特別なケースの JAX-RS エンドポイントのサービス QName を指定します (ns:name の形式を使用)。詳細は、「JMS トランスポートの使用」を参照してください。

threadSafe

クライアントプロキシーがスレッドセーフかどうかを指定します。デフォルトは false です。

transportId

(HTTP の代わりに) 非標準のトランスポート層を選択します。特に、このプロパティーを http://cxf.apache.org/transports/jms に設定すると、JMS トランスポートを選択できます。詳細は、「JMS トランスポートの使用」を参照してください。

abstract

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

depends-on

(Spring のみ) インスタンス化する前に、エンドポイントがインスタンス化されることに依存する Bean のリストを指定します。

18.2.3. jaxrs:client 子要素

子要素

表18.4「JAX-RS クライアントエンドポイントの子要素」jaxrs:client 要素の子要素をまとめます。

表18.4 JAX-RS クライアントエンドポイントの子要素

要素説明

jaxrs:executor

 

jaxrs:features

Apache CXF の高度な機能を設定する Bean のリストを指定します。Bean 参照のリストまたは組み込み Bean のリストを指定できます。

jaxrs:binding

使用されていない。

jaxrs:dataBinding

エンドポイントによって使用されるデータバインディングを実装するクラスを指定します。これは組み込み Bean 定義を使用して指定されます。詳細は、「データバインディングの指定」を参照してください。

jaxrs:inInterceptors

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

jaxrs:inFaultInterceptors

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

jaxrs:outInterceptors

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

jaxrs:outFaultInterceptors

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

jaxrs:properties

エンドポイントに渡されるプロパティーのマップを指定します。

jaxrs:providers

このエンドポイントに 1 つまたは複数のカスタム JAX-RS プロバイダーを登録できます。この要素の子は、JAX-RS プロバイダーのインスタンス (bean 要素) または JAX-RS プロバイダーへの参照 (ref 要素) です。

jaxrs:modelBeans

1 つまたは複数の org.apache.cxf.jaxrs.model.UserResource Bean への参照のリストで構成されます。この参照はリソースモデルの基本要素です (jaxrs:resource 要素に対応)。詳細は、「モデルスキーマを使用した REST サービスの定義」を参照してください。

jaxrs:model

このエンドポイントに直接リソースモデルを定義します (つまり、jaxrs:model 要素には 1 つまたは複数の jaxrs:resource 要素が含まれます)。詳細は、「モデルスキーマを使用した REST サービスの定義」を参照してください。

jaxrs:headers

送信メッセージへのヘッダー設定に使用します。詳細は、「ヘッダーの指定」を参照してください。

jaxrs:schemaLocations

XML メッセージコンテンツの検証に使用する 1 つまたは複数の XML スキーマを指定します。この要素には、1 つまたは複数の jaxrs:schemaLocation 要素を含めることができます。各要素は、XML スキーマファイルの場所を指定します (通常は classpath URL として)。詳細は、「スキーマの検証」を参照してください。

18.3. モデルスキーマを使用した REST サービスの定義

アノテーションのない RESTful サービス

JAX-RS モデルスキーマにより、Java クラスのアノテーションを 付けずに RESTful サービスを定義できます。つまり、Java クラス (またはインターフェース) に直接 @Path@PathParam@Consumes@Produces などのアノテーションを追加する代わりに、モデルスキーマを使用して、関連する REST メタデータをすべて別の XML ファイルで指定できます。これは、たとえば、サービスを実装する Java ソースを変更できない場合に役立ちます。

モデルスキーマの例

例18.1「JAX-RS モデルスキーマの例」は、BookStoreNoAnnotations ルートリソースクラスのサービスメタデータを定義するモデルスキーマの例を示しています。

例18.1 JAX-RS モデルスキーマの例

<model xmlns="http://cxf.apache.org/jaxrs">
  <resource name="org.apache.cxf.systest.jaxrs.BookStoreNoAnnotations" path="bookstore"
    produces="application/json" consumes="application/json">
    <operation name="getBook" verb="GET" path="/books/{id}" produces="application/xml">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="getBookChapter" path="/books/{id}/chapter">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="updateBook" verb="PUT">
       <param name="book" type="REQUEST_BODY"/>
    </operation>
  </resource>
  <resource name="org.apache.cxf.systest.jaxrs.ChapterNoAnnotations">
    <operation name="getItself" verb="GET"/>
    <operation name="updateChapter" verb="PUT" consumes="application/xml">
        <param name="content" type="REQUEST_BODY"/>
    </operation>
  </resource>
</model>

namespace

モデルスキーマの定義に使用する XML namespace は、該当する JAX-RS エンドポイントを Blueprint XML または Spring XML のどちらで定義するかによって異なります。以下の表で、それぞれの XML 言語に使用する namespace を説明します。

モデルスキーマのエンドポイントへの割り当て方法

モデルスキーマを定義してエンドポイントに割り当てるには、以下の手順を実行します。

  1. 選択した注入プラットフォーム (Blueprint XML または Spring XML) に適した XML namespace を使用して、モデルスキーマを定義します。
  2. モデルスキーマファイルをプロジェクトのリソースに追加して、スキーマファイルを最終的なパッケージ (JAR、WAR、または OSGi バンドルファイル) のクラスパスで利用できるようにします。

    注記

    あるいは、エンドポイントの jaxrs:model 子要素を使用して、モデルスキーマを直接 JAX-RS エンドポイントに組み込むこともできます。

  3. エンドポイントの modelRef 属性をクラスパス上のモデルスキーマの場所に設定し (クラスパス URL を使用)、モデルスキーマを使用するようにエンドポイントを設定します。
  4. 必要な場合は、jaxrs:serviceBeans 要素を使用して、ルートリソースを明示的にインスタンス化します。モデルスキーマが (ベースインターフェースを参照せずに) ルートリソースクラスを直接参照する場合は、この手順を省略できます。

クラスを参照するモデルスキーマの設定

モデルスキーマがルートリソースクラスに直接適用される場合、モデルスキーマは自動的にルートリソース Bean をインスタンス化するため、jaxrs:serviceBeans 要素を使用してルートリソース Bean を定義する必要はありません。

たとえば、customer-resources.xml がメタデータをカスタマーリソースクラスに関連付けるモデルスキーマの場合、以下のように customerService サービスエンドポイントをインスタンス化できます。

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-resources.xml" />

インターフェースを参照するモデルスキーマの設定

モデルスキーマが Java インターフェース (ルートリソースのベースインターフェース) に適用される場合、エンドポイントの jaxrs:serviceBeans 要素を使用してルートリソースクラスをインスタンス化する必要があります。

たとえば、customer-interfaces.xml がメタデータをカスタマーインターフェースに関連付けるモデルスキーマの場合、以下のように customerService サービスエンドポイントをインスタンス化できます。

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-interfaces.xml">
    <jaxrs:serviceBeans>
       <ref component-id="serviceBean" />
    </jaxrs:serviceBeans>
</jaxrs:server>

<bean id="serviceBean" class="service.CustomerService"/>

モデルスキーマの参照

モデルスキーマは以下の XML 要素を使用して定義されます。

model
モデルスキーマのルート要素。モデルスキーマを参照する必要がある場合は (たとえば、modelRef 属性を使用して JAX-RS エンドポイントから)、この要素の id 属性を設定する必要があります。
model/resource

resource 要素は、メタデータを特定のルートリソースクラス (または対応するインターフェース) に関連付けるために使用されます。resource 要素に以下の属性を定義できます。

属性説明

name

このリソースモデルが適用されるリソースクラス (または対応するインターフェース) の名前。

+

path

このリソースにマッピングされる REST URL パスのコンポーネント。

+

consumes

このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xmlapplication/json)。

+

produces

このリソースによって生成されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xmlapplication/json)。

+

model/resource/operation

operation 要素は、メタデータを Java メソッドに関連付けるために使用されます。operation 要素に以下の属性を定義できます。

属性説明

name

この要素が適用される Java メソッドの名前。

+

path

このメソッドにマッピングされる REST URL パスのコンポーネント。この属性値には、パラメーターの参照を含めることができます (例: path="/books/{id}/chapter")。ここで、{id} はパスから id パラメーターの値を抽出します。

+

verb

このメソッドにマッピングされる HTTP の動詞を指定します。通常、GETPOSTPUT、または DELETE のいずれかです。HTTP の動詞が指定されて いない 場合、Java メソッドは サブリソースロケーター と考えられ、サブリソースオブジェクトへの参照を返します (サブリソースクラスにも resource 要素を使用してメタデータを指定する必要があります)。

+

consumes

この操作によって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xmlapplication/json)。

+

produces

この操作によって生成されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/xmlapplication/json)。

+

oneway

true の場合、この操作を 一方向 として設定します。つまり、応答メッセージは必要ありません。デフォルトは false です。

+

model/resource/operation/param

param 要素は、REST URL から値を抽出し、それをメソッドパラメーターのいずれかに注入するのに使用されます。param 要素に以下の属性を定義できます。

属性説明

name

この要素が適用される Java メソッドパラメーターの名前。

+

type

REST URL またはメッセージからパラメーター値を抽出する方法を指定します。PATHQUERYMATRIXHEADERCOOKIEFORMCONTEXTREQUEST_BODY のいずれかの値に設定できます。

+

defaultValue

値を REST URL またはメッセージから抽出できなかった場合に、パラメーターに注入するデフォルト値。

+

encoded

true の場合、パラメーター値は URI でエンコードされた形式で注入されます (つまり、%nn エンコーディングを使用)。デフォルトは false です。たとえば、URL パス (/name/Joe%20Bloggs) からパラメーターを抽出する際に、エンコードが true に設定されると、パラメーターは Joe%20Bloggs として注入されます。そうでない場合は、パラメーターは Joe Bloggs として注入されます。

+

第19章 Apache CXF ロギング

概要

本章では、Apache CXF ランタイムでロギングを設定する方法を説明します。

19.1. Apache CXF ロギングの概要

概要

Apache CXF は Java ロギングユーティリティー java.util.logging を使用します。ロギングは、標準の java.util.Properties 形式を使用して記述されるロギング設定ファイルで設定されます。アプリケーションでロギングを実行するには、ロギングをプログラムで指定するか、アプリケーションの起動時にロギング設定ファイルをポイントするコマンドでプロパティーを定義します。

デフォルトのプロパティーファイル

Apache CXF には、InstallDir/etc ディレクトリーにデフォルトの logging.properties ファイルが含まれています。このファイルは、ログメッセージの出力先とパブリッシュされるメッセージレベルの両方を設定します。デフォルト設定では、ロガーは WARNING レベルのフラグが付いたメッセージをコンソールに出力するように設定されます。構成設定を変更せずにデフォルトのファイルを使用することも、特定のアプリケーションに合わせて構成設定を変更することもできます。

ロギング機能

Apache CXF には、クライアントまたはサービスにプラグインできるロギング機能が含まれ、ロギングを有効にすることができます。例19.1「ロギングを有効にする設定」に、ロギング機能を有効にする設定を示します。

例19.1 ロギングを有効にする設定

<jaxws:endpoint...>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>

詳細は、「メッセージコンテンツのロギング」を参照してください。

まず始めに

単純なロギングの例を実行するには、「ロギング使用の単純な例」に記載の手順に従います。

Apache CXF でのロギングがどのように機能するかについての詳細は、本章全体を参照してください。

java.util.logging の詳細情報

java.util.logging ユーティリティーは、もっとも広く使用されている Java ロギングフレームワークの 1 つです。オンラインで、このフレームワークの使用方法や拡張方法を説明する情報が多くあります。ただし、手始めとしては、以下のドキュメントに java.util.logging の概要が説明されています。

19.2. ロギング使用の単純な例

ログレベルと出力先の変更

wsdl_first サンプルアプリケーションでログメッセージのログレベルおよび出力先を変更するには、以下の手順を実行します。

  1. InstallDir/samples/wsdl_first ディレクトリーの README.txt ファイルの Running the demo using java セクションで説明されているように、サンプルサーバーを実行します。server start コマンドは、以下のようにデフォルトの logging.properties ファイルを指定することに注意してください。

    プラットフォームコマンド

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties demo.hw.server.Server &

    +

    デフォルトの logging.properties ファイルは InstallDir/etc ディレクトリーにあります。コンソールに WARNING レベルのログメッセージを出力するように Apache CXF ロガーを設定します。これにより、コンソールにはほとんど何も出力されません。

  2. README.txt ファイルで説明されているようにサーバーを停止します。
  3. デフォルトの logging.properties ファイルのコピーを作成し、その名前を mylogging.properties ファイルに変更し、デフォルトの logging.properties ファイルと同じディレクトリーに保存します。
  4. 以下の設定行を編集して、mylogging.properties ファイルのグローバルロギングレベルおよびコンソールロギングレベルを INFO に変更します。

    .level= INFO
    java.util.logging.ConsoleHandler.level = INFO
  5. 以下のコマンドを使用してサーバーを再起動します。

    プラットフォームコマンド

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &

    +

    レベル INFO のメッセージをログに記録するようにグローバルロギングとコンソールロガーを設定しているため、コンソールに多くのログメッセージが表示されます。

19.3. デフォルトのロギング設定ファイル

19.3.1. ロギング設定の概要

デフォルトのログ設定ファイル logging.properties は、InstallDir/etc ディレクトリーにあります。コンソールに WARNING レベルのメッセージを出力するように Apache CXF ロガーを設定します。このレベルのロギングがアプリケーションに適した場合は、使用する前にファイルに変更を加える必要はありません。ただし、ログメッセージの詳細レベルを変更することができます。たとえば、ログメッセージがコンソールまたはファイルのいずれかに送信されるか、または両方に送信されるかを変更できます。さらに、個々のパッケージレベルでロギングを指定できます。

注記

このセクションでは、デフォルトの logging.properties ファイルに表示される設定プロパティーについて説明します。ただし、設定できる java.util.logging 設定プロパティーは他にもたくさんあります。java.util.logging API についての詳細は、http://download.oracle.com/javase/1.5/docs/api/java/util/logging/package-summary.htmljava.util.logging javadoc を参照してください。

19.3.2. ロギング出力の設定

概要

Java ロギングユーティリティー java.util.logging は、ハンドラークラスを使用してログメッセージを出力します。表19.1「java.util.logging ハンドラークラス」に、デフォルトの logging.properties ファイルで設定されているハンドラーを示します。

表19.1 java.util.logging ハンドラークラス

ハンドラークラス出力先

ConsoleHandler

ログメッセージをコンソールに出力します

FileHandler

ログメッセージをファイルに出力します

重要

Java VM の起動時にインストールするには、ハンドラークラスがシステムクラスパス上にある必要があります。これは、Apache CXF 環境の設定時に行われます。

コンソールハンドラーの設定

例19.2「コンソールハンドラーの設定」に、コンソールロガーを設定するためのコードを示します。

例19.2 コンソールハンドラーの設定

handlers= java.util.logging.ConsoleHandler

コンソールハンドラーは、例19.3「コンソールハンドラープロパティー」に記載されている設定プロパティーもサポートします。

例19.3 コンソールハンドラープロパティー

java.util.logging.ConsoleHandler.level = WARNING
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

例19.3「コンソールハンドラープロパティー」の設定プロパティーは、以下のように記述できます。

コンソールハンドラーは、個別のログレベル設定プロパティーをサポートします。これにより、コンソールに出力されるログメッセージを制限する一方で、グローバルロギング設定を変えることができます (「ロギングレベルの設定」を参照)。デフォルト設定は WARNING です。

コンソールハンドラークラスがログメッセージのフォーマットに使用する java.util.logging フォーマッタークラスを指定します。デフォルト設定は java.util.logging.SimpleFormatter です。

ファイルハンドラーの設定

例19.4「ファイルハンドラーの設定」に、ファイルハンドラを設定するコードを示します。

例19.4 ファイルハンドラーの設定

handlers= java.util.logging.FileHandler

ファイルハンドラーは、例19.5「ファイルハンドラーの設定プロパティー」に記載されている設定プロパティーもサポートします。

例19.5 ファイルハンドラーの設定プロパティー

java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

例19.5「ファイルハンドラーの設定プロパティー」の設定プロパティーは、以下のように記述できます。

出力ファイルの場所とパターンを指定します。デフォルト設定はホームディレクトリーです。

ロガーが 1 つのファイルに書き込む最大量 (バイト単位) を指定します。デフォルト設定は 50000 です。これをゼロに設定すると、ロガーが 1 つのファイルに書き込む量に制限はありません。

サイクルする出力ファイルの数を指定します。デフォルト設定は 1 です。

ファイルハンドラークラスがログメッセージのフォーマットに使用する java.util.logging フォーマッタークラスを指定します。デフォルト設定は java.util.logging.XMLFormatter です。

コンソールハンドラーとファイルハンドラー両方の設定

コンソールロギングとファイルロギングの両方の設定」に示されているように、コンソールハンドラーとファイルハンドラーをコンマで区切って指定することで、コンソールとファイルの両方にログメッセージを出力するようにロギングユーティリティーを設定することができます。

コンソールロギングとファイルロギングの両方の設定

Logging

handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

19.3.3. ロギングレベルの設定

ロギングレベル

java.util.logging フレームワークは、最も詳細度の高いものから低いものまで、以下のレベルのロギングをサポートします。

  • SEVERE
  • WARNING
  • INFO
  • CONFIG
  • FINE
  • FINER
  • FINEST

グローバルロギングレベルの設定

すべてのロガーでログ記録されるイベントの型を設定するには、例19.6「グローバルログレベルの設定」に記載されているようにグローバルロギングレベルを設定します。

例19.6 グローバルログレベルの設定

.level= WARNING

個々のパッケージでのロギング設定

level

java.util.logging フレームワークは、個々のパッケージレベルでのロギング設定をサポートします。たとえば、例19.7「パッケージレベルでのロギングの設定」のコード行は、com.xyz.foo パッケージのクラスで SEVERE レベルのロギングを設定します。

例19.7 パッケージレベルでのロギングの設定

com.xyz.foo.level = SEVERE

19.4. コマンドラインでのロギングの有効化

概要

アプリケーションの起動時に java.util.logging.config.file プロパティーを定義することで、アプリケーションでロギングユーティリティーを実行できます。デフォルトの logging.properties ファイルまたは、そのアプリケーションに固有の logging.properties ファイルを指定することができます。

アプリケーションでのログ設定ファイルの指定

start-up

アプリケーションの起動時にロギングを指定するには、アプリケーションの起動時に 例19.8「コマンドラインでロギングを開始するフラグ」に示されるフラグを追加します。

例19.8 コマンドラインでロギングを開始するフラグ

-Djava.util.logging.config.file=myfile

19.5. サブシステムおよびサービスのロギング

概要

「個々のパッケージでのロギング設定」で説明されている com.xyz.foo.level 設定プロパティーを使用して、指定された Apache CXF ロギングサブシステムの詳細なロギングを設定できます。

Apache CXF ロギングサブシステム

表19.2「Apache CXF ロギングサブシステム」に、利用可能な Apache CXF ロギングサブシステムのリストを表示します。

表19.2 Apache CXF ロギングサブシステム

サブシステム説明

org.apache.cxf.aegis

保護バインディング

org.apache.cxf.binding.coloc

コロケートバインディング

org.apache.cxf.binding.http

HTTP バインディング

org.apache.cxf.binding.jbi

JBI バインディング

org.apache.cxf.binding.object

Java オブジェクトバインディング

org.apache.cxf.binding.soap

SOAP バインディング

org.apache.cxf.binding.xml

XML バインディング

org.apache.cxf.bus

Apache CXF バス

org.apache.cxf.configuration

設定フレームワーク

org.apache.cxf.endpoint

サーバーおよびクライアントエンドポイント

org.apache.cxf.interceptor

インターセプター

org.apache.cxf.jaxws

JAX-WS スタイルメッセージ変換、JAX-WS ハンドラー処理、および JAX-WS や設定に関連するインターセプターのフロントエンド

org.apache.cxf.jbi

JBI コンテナーインテグレーションクラス

org.apache.cxf.jca

JCA コンテナーインテグレーションクラス

org.apache.cxf.js

JavaScript フロントエンド

org.apache.cxf.transport.http

HTTP トランスポート

org.apache.cxf.transport.https

HTTPS を使用した HTTP トランスポートのセキュアバージョン

org.apache.cxf.transport.jbi

JBI トランスポート

org.apache.cxf.transport.jms

JMS トランスポート

org.apache.cxf.transport.local

ローカルファイルシステムを使用したトランスポート実装

org.apache.cxf.transport.servlet

JAX-WS エンドポイントをサーブレットコンテナーに読み込むための HTTP トランスポートおよびサーブレット実装

org.apache.cxf.ws.addressing

WS-Addressing 実装

org.apache.cxf.ws.policy

WS-Policy 実装

org.apache.cxf.ws.rm

WS-ReliableMessaging (WS-RM) 実装

org.apache.cxf.ws.security.wss4j

WSS4J セキュリティー実装

WS-Addressing のサンプルは InstallDir/samples/ws_addressing ディレクトリーに含まれています。ロギングは、そのディレクトリーにある logging.properties ファイルで設定します。該当する設定行を 例19.9「WS-Addressing のロギングの設定」に示します。

例19.9 WS-Addressing のロギングの設定

java.util.logging.ConsoleHandler.formatter = demos.ws_addressing.common.ConciseFormatter
...
org.apache.cxf.ws.addressing.soap.MAPCodec.level = INFO

例19.9「WS-Addressing のロギングの設定」の設定は、WS-Addressing ヘッダーに関連するログメッセージのスヌーピングを有効にし、簡潔な形式でコンソールに表示します。

このサンプルの実行の詳細については、InstallDir/samples/ws_addressing ディレクトリの README.txt ファイルを参照してください。

19.6. メッセージコンテンツのロギング

概要

サービスとコンシューマー間で送信されるメッセージのコンテンツをログに記録できます。たとえば、サービスとコンシューマー間で送信されている SOAP メッセージの内容をログに記録する場合があります。

メッセージコンテンツロギングの設定

サービスとコンシューマー間で送信されるメッセージをログに記録するには、以下の手順を実行します。

エンドポイントへのロギング機能の追加

例19.10「エンドポイントの設定へのロギングの追加」に示すように、ロギング機能をエンドポイントの設定に追加します。

例19.10 エンドポイントの設定へのロギングの追加

<jaxws:endpoint ...>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>

例19.10「エンドポイントの設定へのロギングの追加」に示す XML の例では、SOAP メッセージのロギングを有効にします。

コンシューマーへのロギング機能の追加

例19.11「クライアントの設定へのロギングの追加」に示すように、ロギング機能をクライアントの設定に追加します。

例19.11 クライアントの設定へのロギングの追加

<jaxws:client ...>
   <jaxws:features>
      <bean class="org.apache.cxf.feature.LoggingFeature"/>
    </jaxws:features>
</jaxws:client>

例19.11「クライアントの設定へのロギングの追加」に示す XML の例では、SOAP メッセージのロギングを有効にします。

INFO レベルのメッセージをログに記録するロギングの設定

例19.12「ログレベルの INFO への設定」に示すように、サービスに関連付けられた logging.properties ファイルを設定して、INFO レベルのメッセージをログに記録するようにします。

例19.12 ログレベルの INFO への設定

.level= INFO
java.util.logging.ConsoleHandler.level = INFO

SOAP メッセージのロギング

SOAP メッセージのロギングを表示するには、InstallDir/samples/wsdl_first ディレクトリにある wsdl_first サンプルアプリケーションを以下のように変更します。

  1. 例19.13「SOAP メッセージをログに記録するためのエンドポイントの設定」に示される jaxws:features 要素を、wsdl_first サンプルのディレクトリーにある cxf.xml 設定ファイルに追加します。

    例19.13 SOAP メッセージをログに記録するためのエンドポイントの設定

    <jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort"
                    createdFromAPI="true">
      <jaxws:properties>
        <entry key="schema-validation-enabled" value="true" />
      </jaxws:properties>
      <jaxws:features>
        <bean class="org.apache.cxf.feature.LoggingFeature"/>
      </jaxws:features>
    </jaxws:endpoint>
  2. サンプルでは、InstallDir/etc ディレクトリーにあるデフォルトの logging.properties ファイルが使用されます。このファイルのコピーを作成し、mylogging.properties という名前を付けます。
  3. mylogging.properties ファイルで以下のように .level および java.util.logging.ConsoleHandler.level 設定プロパティーを編集して、ログレベルを INFO に変更します。

    .level= INFO
    java.util.logging.ConsoleHandler.level = INFO
  4. 以下のように、cxf.xml ファイルと mylogging.properties ファイル両方の新しい構成設定を使用してサーバーを起動します。

    プラットフォームコマンド

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &

    +

  5. 以下のコマンドを使用して hello world クライアントを起動します。

    プラットフォームコマンド

    Windows

    java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.client.Client .\wsdl\hello_world.wsdl

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.client.Client ./wsdl/hello_world.wsdl

    +

SOAP メッセージがコンソールにログとして記録されます。

第20章 WS-Addressing のデプロイ

概要

Apache CXF は JAX-WS アプリケーションの WS-Addressing をサポートします。本章では、Apache CXF ランタイム環境で WS-Addressing をデプロイする方法について説明します。

20.1. WS-Addressing の概要

概要

WS-Addressing は、サービスがトランスポートに依存しない方法でアドレス設定情報を通信できるようにする仕様です。これは 2 つの部分で構成されます。

  • Web サービスエンドポイントへの参照を伝達するための構造
  • アドレス設定情報を特定のメッセージに関連付けるメッセージアドレッシングプロパティー (MAP) のセット

サポートされる仕様

Apache CXF は、WS-Addressing 2004/08 仕様と WS-Addressing 2005/03 仕様の両方をサポートします。

詳細情報

WS-Addressing の詳細は、「Web Services Addressing (WS-Addressing)」で 2004/08 の投稿を参照してください。

20.2. WS-Addressing インターセプター

概要

Apache CXF では、WS-Addressing 機能はインターセプターとして実装されます。Apache CXF ランタイムは、インターセプターを使用して送受信されている未処理のメッセージをインターセプトして処理します。トランスポートがメッセージを受信すると、メッセージオブジェクトを作成し、インターセプターチェーンを介してそのメッセージを送信します。WS-Addressing インターセプターがアプリケーションのインターセプターチェーンに追加されると、メッセージに含まれるすべての WS-Addressing 情報が処理されます。

WS-Addressing インターセプター

WS-Addressing の実装は、表20.1「WS-Addressing インターセプター」で説明するように、2 つのインターセプターで構成されます。

表20.1 WS-Addressing インターセプター

インターセプター説明

org.apache.cxf.ws.addressing.MAPAggregator

送信メッセージのメッセージアドレッシングプロパティー (MAP) を集約する論理インターセプター。

org.apache.cxf.ws.addressing.soap.MAPCodec

メッセージアドレッシングプロパティー (MAP) を SOAP ヘッダーとしてエンコードおよびデコードする、プロトコル固有のインターセプター。

20.3. WS-Addressing の有効化

概要

WS-Addressing を有効にするには、WS-Addressing インターセプタをインバウンドおよびアウトバウンドインターセプタチェーンに追加する必要があります。これは、以下のいずれかの方法で行います。

  • Apache CXF の機能
  • RMAssertion および WS-Policy フレームワーク
  • WS-Addressing 機能での Policy Assertion の使用

WS-Addressing の機能としての追加

WS-Addressing を有効にするには、それぞれ 例20.1「client.xml およびクライアント設定への WS-Addressing 機能の追加」および 例20.2「server.xml およびサーバー設定への WS-Addressing 機能の追加」に示すように、WS-Addressing 機能をクライアントおよびサーバー設定に追加します。

例20.1 client.xml およびクライアント設定への WS-Addressing 機能の追加

<?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:jaxws="http://cxf.apache.org/jaxws"
       xmlns:wsa="http://cxf.apache.org/ws/addressing"
       xsi:schemaLocation="
          http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://cxf.apache.org/ws/addressing
          http://cxf.apache.org/schemas/ws-addr-conf.xsd">

    <jaxws:client ...>
        <jaxws:features>
            <wsa:addressing/>
        </jaxws:features>
    </jaxws:client>
</beans>

例20.2 server.xml およびサーバー設定への WS-Addressing 機能の追加

<?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:jaxws="http://cxf.apache.org/jaxws"
       xmlns:wsa="http://cxf.apache.org/ws/addressing"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

    <jaxws:endpoint ...>
        <jaxws:features>
            <wsa:addressing/>
        </jaxws:features>
    </jaxws:endpoint>
</beans>

20.4. WS-Addressing 属性の設定

概要

Apache CXF WS-Addressing 機能要素は、http://cxf.apache.org/ws/addressing という namespace で定義されます。表20.2「WS-Addressing 属性」に記載されている 2 つの属性をサポートします。

表20.2 WS-Addressing 属性

属性名

allowDuplicates

重複する MessageID が許容されるかどうかを決定するブール値。デフォルト設定は true です。

usingAddressingAdvisory

WSDL に UsingAddressing 要素が存在することがアドバイザリーのみ (つまり、要素が存在しなくても WS-Addressing ヘッダーのエンコードは阻止されない) かどうかを示すブール値。

WS-Addressing 属性の設定

WS-Addressing 属性を設定するには、サーバーまたはクライアント設定ファイルで、WS-Addressing 機能に設定する属性と値を追加します。たとえば、以下の設定の抜粋では、サーバーエンドポイントで allowDuplicates 属性を false に設定します。

<beans ... xmlns:wsa="http://cxf.apache.org/ws/addressing" ...>
    <jaxws:endpoint ...>
        <jaxws:features>
            <wsa:addressing allowDuplicates="false"/>
        </jaxws:features>
    </jaxws:endpoint>
</beans>

機能に組み込まれた WS-Policy アサーションの使用

例20.3「ポリシーを使用した WS-Addressing の設定」では、非匿名応答を有効にするためのアドレス設定ポリシーアサーションが policies 要素に組み込まれています。

例20.3 ポリシーを使用した WS-Addressing の設定

<?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:wsa="http://cxf.apache.org/ws/addressing"
        xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
        xmlns:policy="http://cxf.apache.org/policy-config"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:jaxws="http://cxf.apache.org/jaxws"
        xsi:schemaLocation="
http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd
http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

    <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort"
                    createdFromAPI="true">
        <jaxws:features>
            <policy:policies>
                <wsp:Policy xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
                    <wsam:Addressing>
                        <wsp:Policy>
                            <wsam:NonAnonymousResponses/>
                        </wsp:Policy>
                    </wsam:Addressing>
                </wsp:Policy>
            <policy:policies>
        </jaxws:features>
    </jaxws:endpoint>
</beans>

第21章 Reliable Messaging の有効化

概要

Apache CXF は WS-Reliable Messaging (WS-RM) をサポートします。本章では、Apache CXF で WS-RM を有効化および設定する方法を説明します。

21.1. WS-RM の概要

概要

WS-Reliable Messaging (WS-RM) は、分散環境で信頼性の高いメッセージ配信を確保するプロトコルです。ソフトウェア、システム、またはネットワークの障害の発生時に、分散アプリケーション間でメッセージを確実に配信できます。

たとえば、WS-RM を使用して、正しいメッセージがネットワークに 1 度だけ正しい順序で配信されるようにすることができます。

WS-RM の仕組み

WS-RM は、ソースと宛先エンドポイント間の信頼性の高いメッセージ配信を確保します。図21.1「Web サービスの Reliable Messaging」に示されているように、ソースはメッセージの最初の送信者で、宛先は最終的な受信者です。

図21.1 Web サービスの Reliable Messaging

reliable message exchange

WS-RM メッセージのフローは、以下のようになります。

  1. RM ソースは CreateSequence プロトコルメッセージを RM 宛先に送信します。これには、確認応答を受け取るエンドポイント (wsrm:AcksTo エンドポイント) の参照が含まれます。
  2. RM 宛先は RM ソースに CreateSequenceResponse プロトコルメッセージを返信します。このメッセージには、RM シーケンスセッションのシーケンス ID が含まれます。
  3. RM ソースは、アプリケーションソースから送信する各メッセージに RM Sequence ヘッダーを追加します。このヘッダーには、シーケンス ID と一意のメッセージ ID が含まれます。
  4. RM ソースは、各メッセージを RM 宛先に送信します。
  5. RM 宛先は、RM SequenceAcknowledgement ヘッダーが含まれるメッセージを送信して、RM ソースからのメッセージの受信を通知します。
  6. RM 宛先は、メッセージをアプリケーションの宛先に 1 度だけ正しい順序で配信します。
  7. RM ソースは、まだ確認応答を受け取っていないメッセージを再送信します。

    最初の再送信は、ベースの再送信間隔の後に行われます。その後の再送信の試行は、デフォルトの指数バックオフ間隔、あるいは一定の間隔で行われます。詳細は、「WS-RM の設定」を参照してください。

このプロセス全体は、リクエストとレスポンスメッセージの両方に対して対称的に行われます。つまり、レスポンスメッセージの場合、サーバは RM ソースとして機能し、クライアントは RM 宛先として機能します。

WS-RM 配信の保証

WS-RM は、使用するトランスポートプロトコルに関係なく、分散環境で信頼性の高いメッセージ配信を保証します。信頼性の高い配信を確保できない場合、ソースまたは宛先エンドポイントのいずれかがエラーを記録します。

サポートされる仕様

Apache CXF は、WS-RM 仕様の以下のバージョンをサポートします。

WS-ReliableMessaging 1.0

(デフォルト) 現在では旧式の 2005 年 2 月投稿バージョン に対応します。ただし、後方互換性の理由から、このバージョンがデフォルトとして使用されます。

WS-RM のバージョン 1.0 は以下の namespace を使用します。

http://schemas.xmlsoap.org/ws/2005/02/rm/

このバージョンの WS-RM は、以下の WS-Addressing バージョンのいずれかで使用できます。

http://schemas.xmlsoap.org/ws/2004/08/addressing (default)
http://www.w3.org/2005/08/addressing

厳密に言うと、WS-RM の 2005 年 2 月 投稿バージョンに準拠するには、この WS-Addressing バージョンの最初のもの (Apache CXF でのデフォルト) を使用する必要があります。しかし、他のほとんどの Web サービス実装では、より最新の WS-Addressing 仕様に切り替えられているため、Apache CXF では相互運用性を容易にするために WS-A バージョンを選択することができます (「ランタイム制御」を参照)。

WS-ReliableMessaging 1.1/1.2

公式の 1.1/1.2 Web サービス Reliable Messaging 仕様に対応します。

WS-RM のバージョン 1.1 および 1.2 は、以下の namespace を使用します。

http://docs.oasis-open.org/ws-rx/wsrm/200702

WS-RM のバージョン 1.1 および 1.2 は、以下の WS-Addressing バージョンを使用します。

http://www.w3.org/2005/08/addressing

WS-RM バージョンの選択

以下のように、使用する WS-RM 仕様のバージョンを選択できます。

サーバー側
プロバイダー側では、Apache CXF はクライアントによってどのバージョンの WS-reliable Messaging が使用されていても対応し、適切に応答します。
クライアント側
クライアント側では、クライアント設定で使用する namespace によって (「WS-RM の設定」を参照)、あるいはランタイム制御オプションを使用してランタイム時に WS-RM バージョンを上書きして (「ランタイム制御」を参照)、WS-RM バージョンが決定されます。

21.2. WS-RM インターセプター

概要

Apache CXF では、WS-RM 機能はインターセプターとして実装されます。Apache CXF ランタイムは、インターセプターを使用して送受信されている未処理のメッセージをインターセプトして処理します。トランスポートがメッセージを受信すると、メッセージオブジェクトを作成し、インターセプターチェーンを介してそのメッセージを送信します。アプリケーションのインターセプターチェーンに WS-RM インターセプターが含まれる場合、アプリケーションは信頼性の高いメッセージングセッションに参加できます。WS-RM インターセプターは、メッセージチャンクの収集および集約を処理します。また、確認応答および再送信のロジックもすべて処理します。

Apache CXF WS-RM インターセプター

Apache CXF WS-RM の実装は、表21.1「Apache CXF WS-ReliableMessaging インターセプター」で説明するように、4 つのインターセプターで構成されます。

表21.1 Apache CXF WS-ReliableMessaging インターセプター

インターセプター説明

org.apache.cxf.ws.rm.RMOutInterceptor

送信メッセージに対する信頼性の保証を提供する論理的な側面に対応します。

CreateSequence リクエストを送信し、CreateSequenceResponse レスポンスを待ちます。

また、アプリケーションメッセージのシーケンスプロパティー (ID とメッセージ番号) を集約します。

org.apache.cxf.ws.rm.RMInInterceptor

アプリケーションメッセージに付随する RMプロトコルメッセージおよび SequenceAcknowledgement メッセージをインターセプトして処理します。

org.apache.cxf.ws.rm.RMCaptureInInterceptor

永続ストレージ用に受信メッセージをキャッシュします。

org.apache.cxf.ws.rm.RMDeliveryInterceptor

メッセージが順序どおりにアプリケーションに配信されるようにします。

org.apache.cxf.ws.rm.soap.RMSoapInterceptor

信頼性プロパティーを SOAP ヘッダーとしてエンコードおよびデコードします。

org.apache.cxf.ws.rm.RetransmissionInterceptor

今後の再送信のために、アプリケーションメッセージのコピーを作成します。

WS-RM の有効化

インターセプターチェーンに WS-RM インターセプターが存在すると、必要に応じて WS-RM プロトコルメッセージが変換されるようになります。たとえば、アウトバウンドインターセプターチェーンで最初のアプリケーションメッセージをインターセプトすると、RMOutInterceptorCreateSequence リクエストを送信し、CreateSequenceResponse 応答を受信するまで元のアプリケーションメッセージを処理するのを待ちます。さらに、WS-RM インターセプターはシーケンスヘッダーをアプリケーションメッセージに追加し、宛先側でそれをメッセージから抽出します。メッセージの交換を信頼できるものにするために、アプリケーションコードを変更する必要はありません。

WS-RM を有効にする方法の詳細は、「WS-RM の有効化」を参照してください。

WS-RM 属性の設定

設定を通じて、信頼性の高い変換のシーケンス境界やその他の側面を制御します。たとえば、デフォルトでは Apache CXF はシーケンスのライフタイムを最大化することを試みます。そのため、アウトオブバンドの WS-RM プロトコルメッセージにより発生するオーバーヘッドを削減します。アプリケーションメッセージごとに個別のシーケンスを使用するようにするには、WS-RM ソースのシーケンス終了ポリシーを設定します (最大シーケンス長を 1 に設定します)。

WS-RM 動作の設定に関する詳細は、「WS-RM の設定」を参照してください。

21.3. WS-RM の有効化

概要

信頼性の高いメッセージングを有効にするには、インバウンドおよびアウトバウンド両方のメッセージおよび障害について、WS-RM インターセプターをインターセプターチェーンに追加する必要があります。WS-RM インターセプターは WS-Addressing を使用するため、WS-Addressing インターセプターもインターセプターチェーンに存在している必要があります。

これらのインターセプターは、以下のいずれかの方法で存在させることができます。

  • 明示的に: Spring Bean を使用してディスパッチチェーンに追加する。
  • 暗黙的に: WS-Policy アサーションを使用することで、Apache CXF ランタイムにインターセプターを透過的に追加させる。

Spring Bean: インターセプターの明示的な追加

WS-RM を有効にするには、Spring Bean 設定を使用して、WS-RM および WS-Addressing インターセプターを Apache CXF バスに追加するか、コンシューマーまたはサービスエンドポイントに追加します。これは、InstallDir/samples/ws_rm ディレクトリーにある WS-RM のサンプルにおけるアプローチです。設定ファイル ws-rm.cxf では、WS-RM と WS-Addressing インターセプターが Spring Bean として 1 つずつ追加されています (例21.1「Spring Beans を使用した WS-RM の有効化」を参照)。

例21.1 Spring Beans を使用した WS-RM の有効化

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/
   beans http://www.springframework.org/schema/beans/spring-beans.xsd">
   <bean id="mapAggregator" class="org.apache.cxf.ws.addressing.MAPAggregator"/>
   <bean id="mapCodec" class="org.apache.cxf.ws.addressing.soap.MAPCodec"/>
   <bean id="rmLogicalOut" class="org.apache.cxf.ws.rm.RMOutInterceptor">
        <property name="bus" ref="cxf"/>
   </bean>
   <bean id="rmLogicalIn" class="org.apache.cxf.ws.rm.RMInInterceptor">
        <property name="bus" ref="cxf"/>
   </bean>
   <bean id="rmCodec" class="org.apache.cxf.ws.rm.soap.RMSoapInterceptor"/>
   <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl">
        <property name="inInterceptors">
            <list>
                <ref bean="mapAggregator"/>
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalIn"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
        <property name="inFaultInterceptors">
            <list>
                <ref bean="mapAggregator"/>
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalIn"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
        <property name="outInterceptors">
            <list>
                <ref bean="mapAggregator"/>
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalOut"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
        <property name="outFaultInterceptors">
            <list>
                <ref bean="mapAggregator">
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalOut"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
    </bean>
</beans>

例21.1「Spring Beans を使用した WS-RM の有効化」に表示されているコードは、以下のように記述できます。

Apache CXF 設定ファイルは Spring XML ファイルです。beans 要素によってカプセル化される子要素の namespace およびスキーマファイルを宣言するオープニング Spring beans 要素を含める必要があります。

各 WS-Addressing インターセプター (MAPAggregator および MAPCodec) を設定します。WS-Addressing の詳細は、「20章WS-Addressing のデプロイ」を参照してください。

各 WS-RM インターセプター (RMOutInterceptorRMInInterceptor、および RMSoapInterceptor) を設定します。

WS-Addressing および WS-RM インターセプターをインバウンドメッセージのインターセプターチェーンに追加します。

WS-Addressing および WS-RM インターセプターをインバウンド障害のインターセプターチェーンに追加します。

WS-Addressing および WS-RM インターセプターをアウトバウンドメッセージのインターセプターチェーンに追加します。

WS-Addressing および WS-RM インターセプターをアウトバウンド障害のインターセプターチェーンに追加します。

WS-Policy フレームワーク: インターセプターの暗黙的な追加

WS-Policy フレームワークは、WS-Policy の使用を可能にするインフラストラクチャーおよび API を提供します。Web Services Policy 1.5 - Framework および Web Services Policy 1.5 - Attachment 仕様の 2006 年 11 月ドラフト公開版に準拠しています。

Apache CXF WS-Policy フレームワークを使用して WS-RM を有効にするには、以下を実行します。

  1. クライアントおよびサーバーエンドポイントにポリシー機能を追加します。例21.2「WS-Policy を使用した WS-RM の設定」は、jaxws:feature 要素内にネストされた参照 Bean を示しています。参照 Bean は、同じ設定ファイル内に個別の要素として定義される AddressingPolicy を指定します。

    例21.2 WS-Policy を使用した WS-RM の設定

    <jaxws:client>
        <jaxws:features>
          <ref bean="AddressingPolicy"/>
        </jaxws:features>
    </jaxws:client>
    <wsp:Policy wsu:Id="AddressingPolicy" xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
        <wsam:Addressing>
          <wsp:Policy>
            <wsam:NonAnonymousResponses/>
          </wsp:Policy>
        </wsam:Addressing>
    </wsp:Policy>
  2. 例21.3「WSDL ファイルへの RM ポリシーの追加」に示されるように、wsdl:service 要素 (または、ポリシーもしくはポリシー参照要素の添付ポイントとして使用できるその他の WSDL 要素) に対する信頼性の高いメッセージングポリシーを、WSDL ファイルに追加します。

    例21.3 WSDL ファイルへの RM ポリシーの追加

    <wsp:Policy wsu:Id="RM"
       xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
       xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
            <wsp:Policy/>
        </wsam:Addressing>
        <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
            <wsrmp:BaseRetransmissionInterval Milliseconds="10000"/>
        </wsrmp:RMAssertion>
    </wsp:Policy>
    ...
    <wsdl:service name="ReliableGreeterService">
        <wsdl:port binding="tns:GreeterSOAPBinding" name="GreeterPort">
            <soap:address location="http://localhost:9020/SoapContext/GreeterPort"/>
            <wsp:PolicyReference URI="#RM" xmlns:wsp="http://www.w3.org/2006/07/ws-policy"/>
        </wsdl:port>
    </wsdl:service>

21.4. ランタイム制御

概要

org.apache.cxf.ws.rm.RMManager クラスのパブリック定数によって定義されたキー/値を使用すると、クライアントコードで複数のメッセージコンテキストプロパティーの値を設定して、ランタイム時に WS-RM を制御できます。

ランタイム制御オプション

以下の表は、org.apache.cxf.ws.rm.RMManager クラスで定義されるキーの一覧です。

キー説明

WSRM_VERSION_PROPERTY

文字列 WS-RM バージョン namespace (http://schemas.xmlsoap.org/ws/2005/02/rm/ または http://docs.oasis-open.org/ws-rx/wsrm/200702)。

WSRM_WSA_VERSION_PROPERTY

文字列 WS-Addressing バージョン namespace (http://schemas.xmlsoap.org/ws/2004/08/addressing または http://www.w3.org/2005/08/addressing)。http://schemas.xmlsoap.org/ws/2005/02/rm/ RM namespace を使用していない限り、このプロパティーは無視されます。

WSRM_LAST_MESSAGE_PROPERTY

最後のメッセージが送信されていることを WS-RM コードに通知するブール値 true より、コードは WS-RM シーケンスを終了し、リソースを解放することができます (CXF バージョン 3.0.0 の場合、クライアントを終了すると、WS-RM はデフォルトで RM シーケンスを閉じます)。

WSRM_INACTIVITY_TIMEOUT_PROPERTY

長い非アクティブタイムアウト (ミリ秒単位)。

WSRM_RETRANSMISSION_INTERVAL_PROPERTY

長いベース再送信の間隔 (ミリ秒単位)。

WSRM_EXPONENTIAL_BACKOFF_PROPERTY

ブール値の指数バックオフフラグ。

WSRM_ACKNOWLEDGEMENT_INTERVAL_PROPERTY

長い確認応答の間隔 (ミリ秒単位)。

JMX による WS-RM の制御

Apache CXF の JMX 管理機能を使用して、WS-RM の多くの要素を監視および制御することもできます。JMX 操作の完全なリストは、org.apache.cxf.ws.rm.ManagedRMManager および org.apache.cxf.ws.rm.ManagedRMEndpoint で定義されますが、これらの操作には、現在の RM の状態を個々のメッセージレベルにまで表示することが含まれます。JXM を使用して WS-RM シーケンスを閉じたり終了したり、以前に送信されたメッセージがリモート RM エンドポイントによっていつ受信確認されたかの通知を受け取ることもできます。

JMX 制御の例

たとえば、クライアント設定で JMX サーバーを有効にしている場合、以下のコードを使用して、受信した最後の確認応答番号を追跡できます。

// Java
private static class AcknowledgementListener implements NotificationListener {
    private volatile long lastAcknowledgement;

    @Override
    public void handleNotification(Notification notification, Object handback) {
        if (notification instanceof AcknowledgementNotification) {
            AcknowledgementNotification ack = (AcknowledgementNotification)notification;
            lastAcknowledgement = ack.getMessageNumber();
        }
    }

    // initialize client
...
    // attach to JMX bean for notifications
    //  NOTE: you must have sent at least one message to initialize RM before executing this code
    Endpoint ep = ClientProxy.getClient(client).getEndpoint();
    InstrumentationManager im = bus.getExtension(InstrumentationManager.class);
    MBeanServer mbs = im.getMBeanServer();
    RMManager clientManager = bus.getExtension(RMManager.class);
    ObjectName name = RMUtils.getManagedObjectName(clientManager, ep);
    System.out.println("Looking for endpoint name " + name);
    AcknowledgementListener listener = new AcknowledgementListener();
    mbs.addNotificationListener(name, listener, null, null);

    // send messages using RM with acknowledgement status reported to listener
...

21.5. WS-RM の設定

21.5.1. Apache CXF 固有の WS-RM 属性の設定

概要

Apache CXF 固有の属性を設定するには、rmManager Spring Bean を使用します。以下の項目を設定ファイルに追加します。

例21.4「Apache CXF 固有の WS-RM 属性の設定」は、簡単な例を示しています。

例21.4 Apache CXF 固有の WS-RM 属性の設定

&lt;beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
      xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
 http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd"&gt;
...
&lt;wsrm-mgr:rmManager&gt;
&lt;!--
  ...Your configuration goes here
--&gt;
&lt;/wsrm-mgr:rmManager&gt;

rmManager Spring Bean の子

表21.2「rmManager Spring Bean の子」に、http://cxf.apache.org/ws/rm/manager namespace で定義された rmManager Spring Bean の子要素を示します。

表21.2 rmManager Spring Bean の子

要素説明

RMAssertion

RMAssertion の要素

deliveryAssurance

適用する配信保証を記述する型 DeliveryAssuranceType の要素

sourcePolicy

RM ソースの詳細を設定できる型 SourcePolicyType の要素

destinationPolicy

RM 宛先の詳細を設定できる型 DestinationPolicyType の要素

例については、「未確認メッセージのしきい値の最大値」を参照してください。

21.5.2. 標準の WS-RM ポリシー属性の設定

概要

標準の WS-RM ポリシー属性は、以下のいずれかの方法で設定できます。

WS-Policy RMAssertion の子

表21.3「WS-Policy RMAssertion 要素の子」に、http://schemas.xmlsoap.org/ws/2005/02/rm/policy namespace で定義された要素を示します。

表21.3 WS-Policy RMAssertion 要素の子

名前説明

InactivityTimeout

RM シーケンスが非アクティブであるため、シーケンスが終了しているとエンドポイントが判断する前に、メッセージを受信せずに経過する必要がある時間を指定します。

BaseRetransmissionInterval

RMソースが特定のメッセージに対する確認応答を受け取る必要がある間隔を設定します。BaseRetransmissionInterval によって設定された時間内に確認応答を受け取らない場合、RM ソースはメッセージを再送信します。

ExponentialBackoff

再送信間隔が一般的に知られている指数バックオフアルゴリズム (Tanenbaum) を使用して調整されることを示します。

詳細は、Computer Networks, Andrew S. Tanenbaum, Prentice Hall PTR, 2003 を参照してください。

AcknowledgementInterval

WS-RM では、確認応答は返信メッセージと共に、またはスタンドアロンで送信されます。返信メッセージで確認応答を送信できない場合、RM 宛先は、スタンドアロンの確認応答を送信する前に、最長で確認応答の間隔を待機できます。未確認メッセージがない場合、RM 宛先は確認応答を送信しないことを選択できます。

より詳細な参考情報

各要素のサブ要素と属性の説明など、より詳細な参考情報は、http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd を参照してください。

rmManager Spring Bean の RMAssertion

Apache CXF rmManager Spring Bean に RMAssertion を追加して、標準の WS-RM ポリシー属性を設定できます。すべての WS-RM 設定を同じ設定ファイルに維持したい場合 (つまり、Apache CXF 固有の属性と標準の WS-RM ポリシー属性を同じファイルに設定する必要がある場合)、これが最適な方法です。

たとえば、例21.5「rmManager Spring Bean の RMAssertion を使用した WS-RM 属性の設定」の設定は以下を示しています。

  • rmManager Spring Bean 内の RMAssertion を使用して設定された標準の WS-RM ポリシー属性 BaseRetransmissionInterval
  • 同じ設定ファイルに設定された Apache CXF 固有の RM 属性 intraMessageThreshold

例21.5 rmManager Spring Bean の RMAssertion を使用した WS-RM 属性の設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
       xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/>
    </wsrm-policy:RMAssertion>
    <wsrm-mgr:destinationPolicy>
        <wsrm-mgr:acksPolicy intraMessageThreshold="0" />
    </wsrm-mgr:destinationPolicy>
</wsrm-mgr:rmManager>
</beans>

機能内のポリシー

例21.6「機能内でのポリシーとしての WS-RM 属性の設定」に示すように、機能内の標準 WS-RM ポリシー属性を設定できます。

例21.6 機能内でのポリシーとしての WS-RM 属性の設定

<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:wsa="http://cxf.apache.org/ws/addressing"
        xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:jaxws="http://cxf.apache.org/jaxws"
        xsi:schemaLocation="
http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd
http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
    <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort" createdFromAPI="true">
        <jaxws:features>
               <wsp:Policy>
                   <wsrm:RMAssertion xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
                     <wsrm:AcknowledgementInterval Milliseconds="200" />
                   </wsrm:RMAssertion>
                   <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
                       <wsp:Policy>
                            <wsam:NonAnonymousResponses/>
                       </wsp:Policy>
                   </wsam:Addressing>
              </wsp:Policy>
        </jaxws:features>
    </jaxws:endpoint>
</beans>

WSDL ファイル

WS-Policy フレームワークを使用して WS-RM を有効にする場合、WSDL ファイルで標準 WS-RM ポリシー属性を設定できます。サービスを相互運用して、他のポリシー対応の Web サービススタックにデプロイされたコンシューマーと WS-RM をシームレスに使用する場合、この手法が適しています。

「WS-Policy フレームワーク: インターセプターの暗黙的な追加」の例を参照してください。ここでは、ベースの再送信間隔が WSDL ファイルで設定されます。

外部添付

外部の添付ファイルで、標準の WS-RM ポリシー属性を設定できます。WSDL ファイルを変更できない場合や変更したくない場合、この手法が適しています。

例21.7「外部添付での WS-RM の設定」は、特定の EPR で WS-A および WS-RM (30 秒のベース再送信間隔) の両方を有効にする外部添付を示しています。

例21.7 外部添付での WS-RM の設定

<attachments xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsp:PolicyAttachment>
        <wsp:AppliesTo>
           <wsa:EndpointReference>
                <wsa:Address>http://localhost:9020/SoapContext/GreeterPort</wsa:Address>
            </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wsp:Policy>
            <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
                <wsp:Policy/>
            </wsam:Addressing>
            <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
                <wsrmp:BaseRetransmissionInterval Milliseconds="30000"/>
            </wsrmp:RMAssertion>
        </wsp:Policy>
    </wsp:PolicyAttachment>
</attachments>/

21.5.3. WS-RM 設定のユースケース

概要

このサブセクションでは、ユースケースの観点から WS-RM 属性を設定することに焦点を当てています。ここでは、属性は http://schemas.xmlsoap.org/ws/2005/02/rm/policy/ namespace で定義された標準の WS-RM ポリシー属性で、rmManager Spring Bean 内の RMAssertion で設定する例だけが示されています。このような属性を WSDL ファイルまたは外部添付で機能内のポリシーとして設定する方法の詳細は、「標準の WS-RM ポリシー属性の設定」を参照してください。

以下のユースケースについて説明します。

ベースの再送信間隔

BaseRetransmissionInterval 要素は、RM ソースがまだ受信確認を受け取っていないメッセージを再送信する間隔を指定します。http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd スキーマファイルで定義されます。デフォルト値は 3000 ミリ秒です。

例21.8「WS-RM ベース再送信間隔の設定」で、WS-RM ベース再送信間隔の設定方法を説明します。

例21.8 WS-RM ベース再送信間隔の設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/>
    </wsrm-policy:RMAssertion>
</wsrm-mgr:rmManager>
</beans>

再送信の指数バックオフ

ExponentialBackoff 要素は、未確認メッセージのその後の再送信試行が指数間隔で実行されるかどうかを決定します。

ExponentialBackoff 要素が存在する場合は、この機能が有効になります。デフォルトでは、2 の指数バックオフ比率が使用されます。ExponentialBackoff はフラグです。要素が存在する場合、指数バックオフが有効になります。要素がない場合、指数バックオフは無効になっています。値は必要ありません。

例21.9「WS-RM 指数バックオフプロパティーの設定」で、再送信の WS-RM 指数バックオフを設定する方法を説明します。

例21.9 WS-RM 指数バックオフプロパティーの設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:ExponentialBackoff/>
    </wsrm-policy:RMAssertion>
</wsrm-mgr:rmManager>
</beans>

確認応答の間隔

AcknowledgementInterval 要素は、WS-RM 宛先が非同期確認応答を送信する間隔を指定します。これらは、受信メッセージの受信時に送信する同期確認応答に追加されるものです。デフォルトの非同期確認応答間隔は 0 ミリ秒です。つまり、AcknowledgementInterval が特定の値に設定されていない場合、確認応答はすぐに (つまり、最初に利用可能な機会に) 送信されます。

非同期の確認応答は、以下の両方の条件が満たされる場合に限り RM 宛先によって送信されます。

  • RM 宛先が非匿名 wsrm:acksTo エンドポイントを使用している。
  • 確認応答期間が期限切れになる前に、レスポンスメッセージと共に確認応答を送信する機会がない。

例21.10「WS-RM 確認応答間隔の設定」で、WS-RM 確認応答間隔の設定方法を説明します。

例21.10 WS-RM 確認応答間隔の設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:AcknowledgementInterval Milliseconds="2000"/>
    </wsrm-policy:RMAssertion>
</wsrm-mgr:rmManager>
</beans>

未確認メッセージのしきい値の最大値

maxUnacknowledged 属性は、シーケンスが終了するまでに累積可能な、シーケンスごとの未確認メッセージの最大数を設定します。

例21.11「WS-RM の最大未確認メッセージのしきい値の設定」で、WS-RM の最大未確認メッセージのしきい値の設定方法を説明します。

例21.11 WS-RM の最大未確認メッセージのしきい値の設定

<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager
...>
<wsrm-mgr:reliableMessaging>
    <wsrm-mgr:sourcePolicy>
        <wsrm-mgr:sequenceTerminationPolicy maxUnacknowledged="20" />
    </wsrm-mgr:sourcePolicy>
</wsrm-mgr:reliableMessaging>
</beans>

RM シーケンスの最大長さ

maxLength 属性は、WS-RM シーケンスの最大長さを設定します。デフォルト値は 0 です。これは、WS-RM シーケンスの長さに制限がないことを意味します。

この属性が設定されている場合、制限に達し、以前に送信されたメッセージの確認応答をすべて受信すると、RM エンドポイントは新しい RM シーケンスを作成します。新しいメッセージは、新しいシーケンスを使用して送信されます。

例21.12「WS-RM メッセージシーケンスの最大長さの設定」で、RM シーケンスの最大長さを設定する方法を説明します。

例21.12 WS-RM メッセージシーケンスの最大長さの設定

<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager
...>
<wsrm-mgr:reliableMessaging>
    <wsrm-mgr:sourcePolicy>
        <wsrm-mgr:sequenceTerminationPolicy maxLength="100" />
    </wsrm-mgr:sourcePolicy>
</wsrm-mgr:reliableMessaging>
</beans>

メッセージ配信保証ポリシー

以下の配信の保証ポリシーを使用するように RM 宛先を設定できます。

  • AtMostOnce: RM 宛先は、メッセージをアプリケーションの宛先に 1 度だけ配信します。メッセージが複数回配信されると、エラーが発生します。シーケンス内の一部のメッセージは配信されない可能性があります。
  • AtLeastOnce: RM 宛先は、少なくとも 1 度メッセージをアプリケーションの宛先に配信します。送信されるメッセージはすべて配信されるか、エラーが発生します。一部のメッセージは複数回配信される可能性があります。
  • InOrder: RM 宛先は、送信された順番にメッセージをアプリケーションの宛先に配信します。この配信の保証は、AtMostOnce または AtLeastOnce の保証と組み合わせることができます。

例21.13「WS-RM メッセージ配信保証ポリシーの設定」で、WS-RM メッセージ配信保証の設定方法を説明します。

例21.13 WS-RM メッセージ配信保証ポリシーの設定

<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager
...>
<wsrm-mgr:reliableMessaging>
    <wsrm-mgr:deliveryAssurance>
        <wsrm-mgr:AtLeastOnce />
    </wsrm-mgr:deliveryAssurance>
</wsrm-mgr:reliableMessaging>
</beans>

21.6. WS-RM 永続性の設定

概要

本章ですでに説明した Apache CXF WS-RM 機能は、ネットワーク障害などが発生した場合の信頼性を提供します。WS-RM の永続性は、RM ソースや RM 宛先のクラッシュなど、他のタイプの障害に対して信頼性を提供します。

WS-RM の永続性では、さまざまな RM エンドポイントの状態を永続ストレージに保存します。これにより、エンドポイントが復帰すると、メッセージの送受信を継続できます。

Apache CXF では、設定ファイルで WS-RM 永続性を有効にします。デフォルトの WS-RM 永続性ストアは JDBC ベースです。利便性のために、Apache CXF には直ちにデプロイできるように Derby が含まれています。さらに、永続ストアも Java API を使用して公開されます。専用の永続性メカニズムを実装するには、任意の DB と共にこの API を使用して実装できます。

重要

WS-RM の永続性は一方向呼び出しにのみ対応し、デフォルトで無効になっています。

その仕組み

Apache CXF WS-RM の永続性は以下のように動作します。

  • RM ソースエンドポイントでは、送信前に送信メッセージが永続化されます。確認応答を受け取ると、永続ストアからエビクトされます。
  • クラッシュからの復帰後、永続化されたメッセージを復元し、すべてのメッセージが確認されるまで再送信します。この時点で、RM シーケンスが閉じられます。
  • RM 宛先エンドポイントでは、受信メッセージが永続化され、ストアに成功した場合、確認応答が送信されます。メッセージが正常にディスパッチされると、永続ストアからエビクトされます。
  • クラッシュからの復帰後、永続化されたメッセージを復元し、それらをディスパッチします。また、RM シーケンスを新しいメッセージの受け取り、確認および配信ができる状態にします。

WS 永続性の有効化

WS-RM の永続性を有効にするには、WS-RM の永続ストアを実装するオブジェクトを指定する必要があります。専用のストアを開発することや、Apache CXF に同梱される JDBC ベースのストアを使用することができます。

例21.14「デフォルトの WS-RM 永続性ストアの設定」に記載されている設定では、Apache CXF に同梱される JDBC ベースのストアを有効にします。

例21.14 デフォルトの WS-RM 永続性ストアの設定

<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore"/>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <property name="store" ref="RMTxStore"/>
</wsrm-mgr:rmManager>

WS 永続性の設定

Apache CXF に含まれた JDBC ベースのストアは、表21.4「JDBC ストアのプロパティー」にあるプロパティーをサポートします。

表21.4 JDBC ストアのプロパティー

属性名デフォルト設定

driverClassName

String

org.apache.derby.jdbc.EmbeddedDriver

userName

String

null

passWord

String

null

url

String

jdbc:derby:rmdb;create=true

例21.15「WS-RM 永続性の JDBC ストアの設定」に記載されている設定では、Apache CXF に同梱される JDBC ベースのストアを有効にし、driverClassName および url をデフォルト以外の値に設定します。

例21.15 WS-RM 永続性の JDBC ストアの設定

<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore">
    <property name="driverClassName" value="com.acme.jdbc.Driver"/>
    <property name="url" value="jdbc:acme:rmdb;create=true"/>
</bean>

第22章 高可用性の有効化

概要

本章では、Apache CXF ランタイムで高可用性を有効化および設定する方法を説明します。

22.1. 高可用性について

概要

拡張性が高く信頼性の高いアプリケーションでは、分散システムで単一障害点を避けるために高可用性が必要です。以下を使用して、システムを単一障害点から保護できます。 レプリケートされたサービス

レプリケートされたサービスは、同じサービスの複数のインスタンスまたは レプリカ で構成されています。これらは 1 つの論理サービスとして機能します。クライアントがレプリケートされたサービスでリクエストを呼び出すと、Apache CXF はリクエストをメンバーレプリカの 1 つに配信します。クライアントがレプリカへのルーティングを意識することはありません。

静的フェイルオーバーによる HA

Apache CXF は、サービス WSDL ファイルでレプリカの詳細がエンコードされる静的フェイルオーバーにより高可用性 (HA) をサポートします。WSDL ファイルには複数のポートが含まれ、同じサービスについて複数のホストを含めることができます。WSDL ファイルが変更されない限り、クラスター内のレプリカ数は一定のままです。クラスターサイズを変更するには、WSDL ファイルを編集する必要があります。

22.2. 静的フェイルオーバーによる HA の有効化

概要

静的フェイルオーバーによる HA を有効にするには、以下を行う必要があります。

サービス WSDL ファイルでのレプリカ詳細のエンコード

サービス WSDL ファイルで、クラスター内のレプリカ詳細をエンコードする必要があります。例22.1「静的フェイルオーバーによる HA の有効化: WSDL ファイル」に、3 つのレプリカのサービスクラスターを定義する WSDL ファイルの抜粋を示します。

例22.1 静的フェイルオーバーによる HA の有効化: WSDL ファイル

<wsdl:service name="ClusteredService">
    <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica1">
        <soap:address location="http://localhost:9001/SoapContext/Replica1"/>
    </wsdl:port>

    <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica2">
        <soap:address location="http://localhost:9002/SoapContext/Replica2"/>
    </wsdl:port>

    <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica3">
        <soap:address location="http://localhost:9003/SoapContext/Replica3"/>
    </wsdl:port>

</wsdl:service>

例22.1「静的フェイルオーバーによる HA の有効化: WSDL ファイル」に記載されている WSDL の抜粋は、以下のように記述できます。

3 つのポートで公開されるサービス ClusterService を定義します。

  1. Replica1
  2. Replica2
  3. Replica3

Replica1 を定義し、ClusterService を SOAP over HTTP エンドポイントとしてポート 9001 で公開します。

Replica2 を定義し、ClusterService を SOAP over HTTP エンドポイントとしてポート 9002 で公開します。

Replica3 を定義し、ClusterService を SOAP over HTTP エンドポイントとしてポート 9003 で公開します。

クライアント設定へのクラスタリング機能の追加

例22.2「静的フェイルオーバーによる HA の有効化: クライアント設定」に示すように、クライアント設定ファイルにクラスタリング機能を追加します。

例22.2 静的フェイルオーバーによる HA の有効化: クライアント設定

<?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:jaxws="http://cxf.apache.org/jaxws"
       xmlns:clustering="http://cxf.apache.org/clustering"
         xsi:schemaLocation="http://cxf.apache.org/jaxws
         http://cxf.apache.org/schemas/jaxws.xsd
         http://www.springframework.org/schema/beans
         http://www.springframework.org/schema/beans/spring-beans.xsd">

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica1"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover/>
        </jaxws:features>
    </jaxws:client>

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica2"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover/>
        </jaxws:features>
    </jaxws:client>

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica3"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover/>
        </jaxws:features>
    </jaxws:client>

</beans>

22.3. 静的フェイルオーバーによる HA の設定

概要

クライアントが通信する元のサービスが利用できなくなったり障害が発生したりすると、デフォルトでは、静的フェイルオーバーによる HA は、レプリカサービスを選択する際にシーケンシャル手法を使用します。シーケンシャル手法では、使用するたびに同じ順序でレプリカサービスが選択されます。選択は Apache CXF の内部サービスモデルによって決定され、決定論的なフェイルオーバーパターンとなります。

ランダム手法の設定

レプリカを選択する際にシーケンシャル手法ではなくランダム手法を使用するように、静的フェイルオーバーによる HA を設定することができます。ランダム手法では、サービスが利用できなくなるか、または失敗するたびに、ランダムなレプリカサービスを選択します。クラスターで生き残っているメンバーからのフェイルオーバーターゲットの選択は、完全にランダムです。

ランダム手法を設定するには、例22.3「静的フェイルオーバーへのランダム手法の設定」に示された設定をクライアント設定ファイルに追加します。

例22.3 静的フェイルオーバーへのランダム手法の設定

<beans ...>
    <bean id="Random" class="org.apache.cxf.clustering.RandomStrategy"/>

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica3"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover>
                <clustering:strategy>
                    <ref bean="Random"/>
                </clustering:strategy>
            </clustering:failover>
        </jaxws:features>
    </jaxws:client>
</beans>

例22.3「静的フェイルオーバーへのランダム手法の設定」の設定は、以下のように記述できます。

Random Bean およびランダム手法を実装する実装クラスを定義します。

レプリカを選択する際にランダム手法を使用することを指定します。

第23章 Apache CXF バインディング ID

バインディング ID の表

付録A Maven OSGi ツールの使用

概要

大規模なプロジェクトで、バンドルまたはバンドルのコレクションを手動で作成するのは面倒です。Maven バンドルプラグインは、プロセスを自動化し、バンドルマニフェストの内容を指定するための多くのショートカットを提供することで、ジョブを容易に行うことができます。

A.1. Maven バンドルプラグイン

Red Hat Fuse OSGi ツールは、Apache Felix からの Maven バンドルプラグイン を使用します。バンドルプラグインは、Peter Kriens の bnd ツールに基づいています。バンドルにパッケージ化されているクラスの内容をイントロスペクションすることで、OSGi バンドルマニフェストの構築を自動化します。バンドルに含まれるクラスに関する知識を使用して、プラグインはバンドルマニフェストの Import-Packages および Export-Package プロパティーを設定するのに適切な値を計算することができます。プラグインには、バンドルマニフェストの他の必要なプロパティーに使用されるデフォルト値もあります。

バンドルプラグインを使用するには、以下を実行します。

  1. プロジェクトの POM ファイルへのバンドルプラグインの「Red Hat Fuse OSGi プロジェクトの設定」
  2. バンドルのマニフェストを正しく設定するためのプラグインの「Bundle プラグインの設定」

A.2. Red Hat Fuse OSGi プロジェクトの設定

概要

OSGi バンドルをビルドするための Maven プロジェクトは、単純な単一レベルプロジェクトです。サブプロジェクトは必要ありません。ただし、以下を行う必要があります。

  1. バンドルプラグインを POM に 追加する
  2. 結果を OSGi バンドルとしてパッケージ化するように Maven に 指示する
注記

適切な設定でプロジェクトを設定するために使用できる Maven アーキタイプが複数あります。

ディレクトリー構造

OSGi バンドルを構築するプロジェクトは、単一レベルプロジェクトです。最上位の POM ファイルと src フォルダーのみが必要です。すべての Maven プロジェクトと同様に、すべての Java ソースコードを src/java フォルダーに配置し、Java 以外のリソースを src/resources フォルダーに配置します。

Java 以外のリソースには、Spring 設定ファイル、JBI エンドポイント設定ファイル、および WSDL コントラクトが含まれます。

注記

Apache CXF、Apache Camel、または別の Spring が設定されている Bean を使用する Red Hat Fuse OSGi プロジェクトには、src/resources/META-INF/spring フォルダーに beans.xml ファイルも含まれます。

バンドルプラグインの追加

バンドルプラグインを使用する前に、Apache Felix に依存関係を追加する必要があります。依存関係を追加したら、バンドルプラグインを POM のプラグイン部分に追加できます。

例A.1「OSGi バンドルプラグインの POM への追加」に、バンドルプラグインをプロジェクトに追加するために必要な POM エントリーを示します。

例A.1 OSGi バンドルプラグインの POM への追加

...
<dependencies>
  <dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.osgi.core</artifactId>
    <version>1.0.0</version>
  </dependency>
...
</dependencies>
...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.felix</groupId>
      <artifactId>maven-bundle-plugin</artifactId>
      <configuration>
        <instructions>
          <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
          <Import-Package>*,org.apache.camel.osgi</Import-Package>
          <Private-Package>org.apache.servicemix.examples.camel</Private-Package>
        </instructions>
      </configuration>
    </plugin>
  </plugins>
</build>
...

例A.1「OSGi バンドルプラグインの POM への追加」のエントリーは以下を行います。

Apache Felix に依存関係を追加する

プロジェクトにバンドルプラグインを追加する

バンドルのシンボリック名としてプロジェクトのアーティファクト ID を使用するようにプラグインを設定する

バンドルされたクラスによってインポートされたすべての Java パッケージを含めるようにプラグインを設定する。また、org.apache.camel.osgi パッケージをインポートする

一覧表示されたクラスをバンドル化するが、エクスポートしたパッケージの一覧には含めないようにプラグインを設定する

注記

プロジェクトの要件を満たすように設定を編集します。

バンドルプラグインの設定に関する詳細は、「Bundle プラグインの設定」を参照してください。

バンドルプラグインのアクティベート

Maven がバンドルプラグインを使用するには、プロジェクトの結果をバンドルとしてパッケージ化するよう指示します。そのためには、POM ファイルの packaging 要素を bundle に設定します。

有用な Maven アーキタイプ

バンドルプラグインを使用するよう事前設定されたプロジェクトを生成するには、複数の Maven アーキタイプを使用できます。

Spring OSGi アーキタイプ

Spring OSGi アーキタイプは、以下のように Spring DM を使用して OSGi プロジェクトを構築するための汎用プロジェクトを作成します。

org.springframework.osgi/spring-bundle-osgi-archetype/1.1.2

以下のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.springframework.osgi -DarchetypeArtifactId=spring-osgi-bundle-archetype -DarchetypeVersion=1.1.2 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

Apache CXF コードファーストアーキタイプ

Apache CXF コードファーストアーキタイプは、以下のように Java からサービスを構築するためのプロジェクトを作成します。

org.apache.servicemix.tooling/servicemix-osgi-cxf-code-first-archetype/2010.02.0-fuse-02-00

以下のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-code-first-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

Apache CXF wsdl ファーストアーキタイプ

Apache CXF wsdl ファーストアーキタイプは、以下のように WSDL からサービスを作成するためのプロジェクトを作成します。

org.apache.servicemix.tooling/servicemix-osgi-cxf-wsdl-first-archetype/2010.02.0-fuse-02-00

以下のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-wsdl-first-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

Apache Camel アーキタイプ

Apache Camel アーキタイプは、以下のように Red Hat Fuse にデプロイされたルートを構築するためのプロジェクトを作成します。

org.apache.servicemix.tooling/servicemix-osgi-camel-archetype/2010.02.0-fuse-02-00

以下のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-camel-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

A.3. Bundle プラグインの設定

概要

バンドルプラグインが機能するために必要な情報はほとんどありません。必要なすべてのプロパティーは、デフォルト設定を使用して有効な OSGi バンドルを生成します。

デフォルト値のみを使用して有効なバンドルを作成することは可能ですが、いくつかの値を変更する必要がある可能性があります。プラグインの instructions 要素内のほとんどのプロパティーを指定できます。

設定プロパティー

一般的に使用される設定プロパティーには、以下のものがあります。

バンドルのシンボリック名の設定

デフォルトでは、バンドルプラグインは Bundle-SymbolicName プロパティの値を groupId + "." + artifactId に設定します。ただし、以下の例外があります。

  • groupId にセクションが 1 つしかない場合は (ピリオドなし)、クラスを含む最初のパッケージ名が返されます。

    たとえば、グループ ID が commons-logging:commons-logging の場合、バンドルのシンボリック名は org.apache.commons.logging になります。

  • artifactIdgroupId の最後のセクションと同じ場合は、groupId が使用されます。

    たとえば、POM がグループ ID およびアーティファクト ID を org.apache.maven:maven として指定すると、バンドルのシンボリック名は org.apache.maven になります。

  • artifactIdgroupId の最後のセクションで始まる場合は、その部分が削除されます。

    たとえば、POM がグループ ID およびアーティファクト ID を org.apache.maven:maven-core として指定すると、バンドルのシンボリック名は org.apache.maven.core になります。

バンドルのシンボリック名に独自の値を指定するには、例A.2「バンドルのシンボリック名の設定」に示すように、プラグインの instructions 要素に Bundle-SymbolicName の子を追加します。

例A.2 バンドルのシンボリック名の設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
     ...
    </instructions>
  </configuration>
</plugin>

バンドル名の設定

デフォルトでは、バンドルの名前は ${project.name} に設定されます。

バンドル名に独自の値を指定するには、例A.3「バンドル名の設定」に示すように、プラグインの instructions 要素に Bundle-Name の子を追加します。

例A.3 バンドル名の設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Name>JoeFred</Bundle-Name>
     ...
    </instructions>
  </configuration>
</plugin>

バンドルのバージョンの設定

デフォルトでは、バンドルのバージョンは ${project.version} に設定されます。ダッシュ (-) はピリオド (.) に置き換えられ、数字は 4 桁に変換されます。たとえば、4.2-SNAPSHOT4.2.0.SNAPSHOT になります。

バンドルのバージョンに独自の値を指定するには、例A.4「バンドルのバージョンの設定」に示すように、プラグインの instructions 要素に Bundle-Version の子を追加します。

例A.4 バンドルのバージョンの設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Version>1.0.3.1</Bundle-Version>
     ...
    </instructions>
  </configuration>
</plugin>

エクスポートされるパッケージの指定

デフォルトでは、OSGi マニフェストの Export-Package リストには、ローカルの Java ソースコード (src/main/java 下) のすべてのパッケージが反映されます。ただし、デフォルトのパッケージ、.、および .impl または .internal が含まれるすべてのパッケージを 除きます

重要

プラグイン設定で Private-Package 要素を使用し、エクスポートするパッケージの一覧を指定しない場合、デフォルトの動作ではバンドルの Private-Package 要素にリストされているパッケージのみが含まれます。パッケージはエクスポートされません。

デフォルトの動作では、パッケージが非常に大きくなり、プライベートにしておくべきパッケージがエクスポートされることになります。エクスポートされるパッケージの一覧を変更するには、Export-Package の子をプラグインの instructions 要素に追加します。

Export-Package 要素は、バンドルに含まれるパッケージとエクスポートされるパッケージの一覧を指定します。パッケージ名は、* ワイルドカードシンボルを使用して指定できます。たとえば、エントリー com.fuse.demo.* は、プロジェクトのクラスパスにある com.fuse.demo で始まるすべてのパッケージが含まれます。

除外するパッケージを指定するには、エントリーに ! のプレフィックスを追加します。たとえば、!com.fuse.demo.private のエントリーは、パッケージ com.fuse.demo.private を除外します。

パッケージを除外する場合は、リスト内でのエントリーの順序が重要です。リストは最初から順番に処理され、以降の矛盾するエントリーは無視されます。

たとえば、パッケージ com.fuse.demo.private を除く com.fuse.demo で始まるすべてのパッケージを含めるには、以下のようにパッケージのリストを指定します。

!com.fuse.demo.private,com.fuse.demo.*

ただし、com.fuse.demo.*,!com.fuse.demo.private のようにパッケージのリストを指定すると、最初のパターンに一致するため、com.fuse.demo.private がバンドルに含まれます。

プライベートパッケージの指定

バンドルに追加するパッケージの一覧を指定してそれらをエクスポート しない 場合、バンドルプラグイン設定に Private-Package 命令を追加できます。デフォルトでは、Private-Package 命令を指定しないと、ローカルの Java ソースのすべてのパッケージがバンドルに含まれます。

重要

パッケージが Private-Package 要素と Export-Package 要素の両方のエントリーと一致する場合は、Export-Package 要素が優先されます。パッケージがバンドルに追加され、エクスポートされます。

Private-Package 要素は、バンドルに含まれるパッケージの一覧を指定する点で Export-Package 要素と同様に機能します。バンドルプラグインはリストを使用して、バンドルに含めるプロジェクトのクラスパスにあるすべてのクラスを検索します。これらのパッケージはバンドルにパッケージ化されますが、(Export-Package 命令で選択されない限り) エクスポートされません。

例A.5「バンドルへのプライベートパッケージの追加」に、バンドルにプライベートパッケージを含める設定を示します

例A.5 バンドルへのプライベートパッケージの追加

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Private-Package>org.apache.cxf.wsdlFirst.impl</Private-Package>
     ...
    </instructions>
  </configuration>
</plugin>

インポートされるパッケージの指定

デフォルトでは、バンドルプラグインは OSGi マニフェストの Import-Package プロパティーに、バンドルのコンテンツによって参照されるすべてのパッケージのリストを反映させます。

デフォルトの動作は通常、ほとんどのプロジェクトでは十分ですが、リストに自動的には追加されないパッケージをインポートする場合があります。デフォルトの動作では、不要なパッケージがインポートされる可能性もあります。

バンドルによってインポートされるパッケージの一覧を指定するには、Import-Package の子をプラグインの instructions 要素に追加します。パッケージ一覧の構文は、Export-Package 要素および Private-Package 要素の場合と同じです。

重要

Import-Package 要素を使用する場合、必要なインポートの有無を判断するのにプラグインはバンドルの内容を自動的にスキャンしません。バンドルの内容がスキャンされるようにするには、パッケージリストの最後のエントリーとして * を配置する必要があります。

例A.6「バンドルによってインポートされるパッケージの指定」に、バンドルによってインポートされるパッケージを指定する設定を示します。

例A.6 バンドルによってインポートされるパッケージの指定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Import-Package>javax.jws, javax.wsdl, org.apache.cxf.bus, org.apache.cxf.bus.spring, org.apache.cxf.bus.resource, org.apache.cxf.configuration.spring, org.apache.cxf.resource, org.springframework.beans.factory.config, * </Import-Package>
     ...
   </instructions>
  </configuration>
</plugin>

補足情報

バンドルプラグインの設定に関する詳細は、以下を参照してください。

パート V. JAX-WS を使用したアプリケーションの開発

本ガイドでは、標準の JAX-WS API を使用して Web サービスを開発する方法を説明します。

第24章 ボトムアップのサービス開発

概要

サービス指向アプリケーションの一部として公開する機能セットを既に実装している Java コードが存在するインスタンスが多数あります。また、インターフェースを定義するのに WSDL を使用するのを避けたい場合もあります。JAX-WS アノテーションを使用して、Java クラスを有効にするのに必要な情報を追加できます。WSDL コントラクトの代わりに使用できる サービスエンドポイントインターフェース (SEI) を作成することもできます。WSDL コントラクトが必要な場合は、Apache CXF はアノテーション付き Java コードからコントラクトを生成するツールを提供します。

24.1. JAX-WS サービス開発の概要

Java からサービスを作成するには、次の操作を行う必要があります。

  1. サービスとして公開するメソッドを定義するサービスエンドポイントインターフェース (SEI) の「SEI の作成」を行う。

    注記

    Java クラスから直接作業できますが、インターフェイスからの作業が推奨される方法です。インターフェースは、サービスを使用するアプリケーションの開発を担当する開発者との共有に適しています。このインターフェースのサイズは小さく、サービスの実装情報は提供されません。

  2. コードに必要なアノテーションの「コードのアノテーション」を行う。
  3. サービスの WSDL コントラクトの「WSDL の生成」を行う。

    注記

    サービスのコントラクトとして SEI を使用する予定がある場合は、WSDL コントラクトを生成する必要はありません。

  4. サービスプロバイダーとしてサービスの「31章サービスの公開」を行う。

24.2. SEI の作成

概要

サービスエンドポイントインターフェース (SEI) は、サービス実装とそのサービスに対してリクエストを行うコンシューマーとの間で共有される Java コードの一部です。SEI はサービスによって実装されるメソッドを定義し、サービスがエンドポイントとしてどのように公開されるかの詳細を提供します。WSDL コントラクトで開始すると、SEI がコードジェネレーターによって生成されます。ただし、Java から開始すると、開発者は SEI を作成する責任があります。 SEI の作成には、以下の 2 つの基本的なパターンがあります。

  • グリーンフィールド開発: このパターンでは、既存の Java コードまたは WSDL なしで新しいサービスを開発します。SEI を作成することから始めるのが最善です。その後、その SEI を使用するサービスプロバイダーおよびコンシューマーを実装する開発者に SEI を配布できます。

    注記

    グリーンフィールドサービス開発を行うための推奨される方法は、サービスとそのインターフェースを定義する WSDL コントラクトを作成することから始めることです。「26章WSDL コントラクト作成の開始」を参照してください。

  • サービスイネーブルメント: このパターンでは、通常、Java クラスとして実装されている既存の機能セットがあり、サービスでそれを有効にします。したがって、以下の 2 つのことが必要になります。

    1. サービスの一部として公開される操作 のみ が含まれる SEI を作成する。
    2. SEI を実装するように既存の Java クラスを変更する。

      注記

      JAX-WS アノテーションを Java クラスに追加できますが、これは推奨されません。

インターフェースの作成

SEI は標準の Java インターフェースです。これは、クラスが実装するメソッドのセットを定義します。また、実装するクラスがアクセスできるさまざまなメンバーフィールドや定数を定義することもできます。

SEI の場合、定義されたメソッドはサービスによって公開される操作にマッピングされることを意図しています。SEI は wsdl:portType 要素に対応します。SEI で定義されたメソッドは、wsdl:portType 要素の wsdl:operation 要素に対応します。

注記

JAX-WS は、サービスの一部として公開されないメソッドを指定できるようにするアノテーションを定義します。ただし、ベストプラクティスは、これらのメソッドを SEI から除外することです。

例24.1「単純な SEI」は、株式更新サービスの単純な SEI を示しています。

例24.1 単純な SEI

package com.fusesource.demo;

public interface quoteReporter
{
  public Quote getQuote(String ticker);
}

インターフェースの実装

SEI は標準の Java インターフェースであるため、これを実装するクラスは標準の Java クラスです。Java クラスから始める場合は、インターフェイスを実装するためにクラスを変更する必要があります。SEI から始める場合は、実装クラスが SEI を実装します。

例24.2「単純な実装クラス」は、例24.1「単純な SEI」のインターフェースを実装するクラスを示しています。

例24.2 単純な実装クラス

package com.fusesource.demo;

import java.util.*;

public class stockQuoteReporter implements quoteReporter
{
  ...
public Quote getQuote(String ticker)
  {
    Quote retVal = new Quote();
    retVal.setID(ticker);
    retVal.setVal(Board.check(ticker));[1]
    Date retDate = new Date();
    retVal.setTime(retDate.toString());
    return(retVal);
  }
}


[1] Board is an assumed class whose implementation is left to the reader.

24.3. コードのアノテーション

24.3.1. JAX-WS アノテーションの概要

JAX-WS アノテーションは、SEI を完全に指定されたサービス定義にマッピングするためのメタデータを指定します。アノテーションで提供される情報には以下が含まれます。

  • サービスのターゲット namespace
  • リクエストメッセージを保持するためのクラス名
  • 応答メッセージを保持するための使用されるクラス名
  • 操作が 1 方向操作かどうか
  • サービスが使用するバインディングスタイル
  • カスタム例外に使用されるクラス名
  • サービスによって使用される型が定義される namespace
注記

ほとんどのアノテーションには実用的なデフォルトがあり、それらの値を指定する必要はありません。ただし、アノテーションで指定する情報が多いほど、サービス定義がより適切に指定されます。サービス定義を適切に指定すると、分散アプリケーションのすべての部分が連携する可能性が高まります。

24.3.2. 必要なアノテーション

概要

Java コードからサービスを作成するには、1 つのアノテーションをコードに追加するだけで済みます。SEI および実装クラスの両方に @WebService アノテーションを追加する必要があります。

@WebService アノテーション

@WebService アノテーションは javax.jws.WebService インターフェースによって定義され、インターフェースまたはサービスとして使用するクラスに配置されます。@WebService には、表24.1「@WebService プロパティー」で説明されるプロパティーがあります。

表24.1 @WebService プロパティー

プロパティー説明

name

サービスインターフェースの名前を指定します。このプロパティーは、WSDL コントラクトのサービスのインターフェースを定義する wsdl:portType 要素の name 属性にマッピングされます。デフォルトでは、実装クラスの名前に PortType を追加します。[a]

targetNamespace

サービスが定義されるターゲット namespace を指定します。このプロパティーが指定されていない場合には、ターゲット namespace はパッケージ名から派生します。

serviceName

公開するサービスの名前を指定します。このプロパティーは、公開するサービスを定義する wsdl:service 要素の name 属性にマッピングされます。デフォルトでは、サービスの実装クラスの名前が使用されます。

wsdlLocation

サービスの WSDL コントラクトの保存先 URL を指定します。これは、相対 URL を使用して指定する必要があります。デフォルトは、サービスがデプロイされる URL です。

endpointInterface

実装クラスが実装する SEI の完全な名前を指定します。このプロパティーは、サービス実装クラスで属性が使用される場合にのみ指定されます。

portName

サービスが公開されるエンドポイントの名前を指定します。このプロパティーは、公開するサービスのエンドポイント情報を定義する wsdl:port 要素の name 属性にマッピングされます。デフォルトでは、サービスの実装クラスの名前に Port を追加します。

[a] SEI から WSDL を生成すると、実装クラスの名前の代わりにインターフェースの名前が使用されます。
注記

@WebService アノテーションのプロパティーに値を指定する必要はありません。ただし、できるだけ多くの情報を提供することが推奨されます。

SEI へのアノテーション

SEI では、@WebService アノテーションを追加する必要があります。SEI はサービスを定義するコントラクトなので、@WebService アノテーションのプロパティーにサービスの詳細をできるだけ多く指定する必要があります。

例24.3「@WebService アノテーションによるインターフェース」は、@WebService アノテーションにより 例24.1「単純な SEI」で定義したインターフェースを示しています。

例24.3 @WebService アノテーションによるインターフェース

package com.fusesource.demo;

import javax.jws.*;

@WebService(name="quoteUpdater",
            targetNamespace="http:\\demos.redhat.com",
	        serviceName="updateQuoteService",
            wsdlLocation="http:\\demos.redhat.com\quoteExampleService?wsdl",
            portName="updateQuotePort")
public interface quoteReporter
{
  public Quote getQuote(String ticker);
}

例24.3「@WebService アノテーションによるインターフェース」@WebService アノテーションは、以下を行います。

サービスインターフェースを定義する wsdl:portType 要素の name 属性の値を quoteUpdater に指定する。

サービスのターゲット namespace を http:\\demos.redhat.com に指定する。

公開するサービスを定義する wsdl:service 要素の name の値を updateQuoteService に指定する。

サービスが http:\\demos.redhat.com\quoteExampleService?wsdl で WSDL コントラクトを公開することを指定する。

サービスを公開するエンドポイントを定義する wsdl:port 要素の name 属性の値を updateQuotePort に指定する。

サービス実装へのアノテーション

SEI への @WebService アノテーションの追加に加えて、サービス実装クラスにも @WebService アノテーションを付ける必要があります。アノテーションをサービス実装クラスに追加する場合は、endpointInterface プロパティーを指定するだけで済みます。例24.4「アノテーションが追加されたサービス実装クラス」で示されているように、プロパティーには SEI の完全な名前を設定する必要があります。

例24.4 アノテーションが追加されたサービス実装クラス

package org.eric.demo;

import javax.jws.*;

@WebService(endpointInterface="com.fusesource.demo.quoteReporter")
public class stockQuoteReporter implements quoteReporter
{
public Quote getQuote(String ticker)
  {
  ...
  }
}

24.3.3. オプションのアノテーション

概要

Java インターフェースまたは Java クラスを有効にするサービスには @WebService アノテーションで十分ですが、サービスがサービスプロバイダーとして公開される方法を十分には説明していません。JAX-WS プログラミングモデルは、使用するバインディングなど、サービスの詳細を Java コードに追加するために、多くの任意のアノテーションを使用します。これらのアノテーションをサービスの SEI に追加します。

SEI で詳細を提供すればするほど、定義する機能を使用するアプリケーションを開発者が実装するのが容易になります。また、ツールで生成される WSDL ドキュメントもより具体的になります。

概要

アノテーションによるバインディングプロパティーの定義

サービスに SOAP バインディングを使用している場合、JAX-WS アノテーションを使用して多くのバインディングプロパティーを指定できます。これらのプロパティーは、サービスの WSDL コントラクトで指定できるプロパティーに直接対応します。パラメータースタイルなどの設定の一部では、メソッドの実装方法を制限できます。これらの設定は、メソッドパラメータにアノテーションを追加する時に使用できるアノテーションにも影響を及ぼします。

@SOAPBinding アノテーション

@SOAPBinding アノテーションは、javax.jws.soap.SOAPBinding インターフェースによって定義されます。これにより、サービスのデプロイ時に使用される SOAP バインディングの詳細が提供されます。@SOAPBinding アノテーションが指定されていない場合、サービスはラップされた doc/literal SOAP バインディングを使用して公開されます。

@SOAPBinding アノテーションを SEI および SEI の任意のメソッドに追加できます。メソッドで使用される場合は、メソッドの @SOAPBinding アノテーションの設定が優先されます。

表24.2「@SOAPBinding プロパティー」に、@SOAPBinding アノテーションのプロパティーを示します。

表24.2 @SOAPBinding プロパティー

プロパティー説明

style

Style.DOCUMENT (デフォルト)

Style.RPC

SOAP メッセージのスタイルを指定します。RPC スタイルが指定されている場合、SOAP ボディーの各メッセージ部分はパラメーターまたは戻り値で、soap:body 要素内のラッパー要素に表示されます。ラッパー要素内のメッセージ部分は操作パラメーターに対応し、操作のパラメーターと同じ順番に表示される必要があります。DOCUMENT スタイルが指定されている場合は、SOAP ボディーのコンテンツは有効な XML ドキュメントである必要がありますが、その形式にはそれほど厳しく制約はありません。

use

Use.LITERAL (デフォルト)

Use.ENCODED[a]

SOAP メッセージのデータをストリーミングする方法を指定します。

parameterStyle [b]

ParameterStyle.BARE

ParameterStyle.WRAPPED (デフォルト)

WSDL コントラクトのメッセージ部分に対応するメソッドパラメーターを SOAP メッセージボディーに配置する方法を指定します。BARE が指定されている場合は、各パラメーターはメッセージルートの子要素としてメッセージボディーに配置されます。WRAPPED が指定されている場合、すべての入力パラメーターはリクエストメッセージの単一要素にラップされ、すべての出力パラメーターは応答メッセージの単一要素にラップされます。

[a] Use.ENCODED は現在サポートされていません。
[b] style を RPC に設定する場合は、WRAPPED パラメータースタイルを使用する必要があります。

ドキュメントベアスタイルパラメーター

ドキュメントベアスタイルは、Java コードと結果となるサービスの XML 表現との間の最も直接的なマッピングです。このスタイルを使用する場合、スキーマ型は、操作のパラメーターリストで定義される入出力パラメーターから直接生成されます。

ベア document\literal スタイルを使用するには、@SOAPBinding アノテーションの style プロパティを Style.DOCUMENT に設定し、parameterStyle プロパティを ParameterStyle.BARE に設定します。

ベアパラメーターを使用する際に、操作がドキュメントスタイル使用の制限に違反しないように、操作は以下の条件を満たしている必要があります。

  • 操作は複数の入力または入出力パラメーターを持たない。
  • 操作の戻り値の型が void 以外の場合、出力または入出力パラメータを持たない。
  • 操作の戻り値の型が void である場合、複数の出力または入出力パラメーターを持たない。
注記

@WebParam アノテーションまたは @WebResult アノテーションを使用して SOAP ヘッダーに配置されるパラメーターは、許可されるパラメーターの数にカウントされません。

ドキュメントラップパラメーター

ドキュメントラップスタイルにより、Java コードと結果となるサービスの XML 表現との間で、より RPC 的なマッピングを使用でます。このスタイルを使用する場合、メソッドのパラメーター一覧のパラメーターはバインディングによって単一の要素にラップされます。この手法の欠点は、Java 実装と伝送時のメッセージ配置方法との間に、新たな間接性のレイヤーが生じることです。

ラップ document\literal スタイルを使用するには、@SOAPBinding アノテーションの style プロパティを Style.DOCUMENT に設定し、parameterStyle プロパティを ParameterStyle.WRAPPED に設定します。

「@RequestWrapper アノテーション」アノテーションと「@ResponseWrapper アノテーション」アノテーションを使用して、ラッパーの生成方法の一部を制御することができます。

例24.5「SOAP バインディングアノテーションによるドキュメントベア SOAP バインディングの指定」に、ドキュメントベア SOAP メッセージを使用する SEI を示します。

例24.5 SOAP バインディングアノテーションによるドキュメントベア SOAP バインディングの指定

package org.eric.demo;

import javax.jws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;

@WebService(name="quoteReporter")
@SOAPBinding(parameterStyle=ParameterStyle.BARE)
public interface quoteReporter
{
  ...
}

概要

アノテーションによる操作プロパティーの定義

ランタイムが Java メソッド定義を XML オペレーション定義にマッピングする場合、以下のような詳細を提供します。

  • 変換されたメッセージが XML でどのように見えるか
  • メッセージを一方向片道メッセージとして最適化できるかどうか
  • メッセージが定義される namespace

@WebMethod アノテーション

@WebMethod アノテーションは、javax.jws.WebMethod インターフェースによって定義されます。これは SEI のメソッドに配置されます。@WebMethod アノテーションは、メソッドが関連付けられる操作を記述する wsdl:operation 要素に通常表される情報を提供します。

表24.3「@WebMethod プロパティー」に、@WebMethod アノテーションのプロパティーを示します。

表24.3 @WebMethod プロパティー

プロパティー説明

operationName

関連する wsdl:operation 要素の name の値を指定します。デフォルト値はメソッドの名前です。

action

メソッド用に生成される soap:operation 要素の soapAction 属性の値を指定します。デフォルト値は空の文字列です。

exclude

メソッドをサービスインターフェースから除外するかどうかを指定します。デフォルトは false です。

@RequestWrapper アノテーション

@RequestWrapper アノテーションは、javax.xml.ws.RequestWrapper インターフェースによって定義されます。これは SEI のメソッドに配置されます。@RequestWrapper アノテーションは、メッセージ変換を開始するリクエストメッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、リクエストメッセージをマーシャリングおよびアンマーシャリングする際にランタイムによって使用される要素名および namespace も指定します。

表24.4「@RequestWrapper プロパティー」に、@RequestWrapper アノテーションのプロパティーを示します。

表24.4 @RequestWrapper プロパティー

プロパティー説明

localName

リクエストメッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値はメソッドの名前、または「@WebMethod アノテーション」アノテーションの operationName プロパティーの値のいずれかです。

targetNamespace

XML ラッパー要素が定義される namespace を指定します。デフォルト値は SEI のターゲット namespace です。

className

ラッパー要素を実装する Java クラスの完全な名前を指定します。

注記

className プロパティーのみが必須です。

重要

メソッドに @SOAPBinding アノテーションも付けられ、その parameterStyle プロパティーが ParameterStyle.BARE に設定されている場合、このアノテーションは無視されます。

@ResponseWrapper アノテーション

@ResponseWrapper アノテーションは、javax.xml.ws.ResponseWrapper インターフェースによって定義されます。これは SEI のメソッドに配置されます。@ResponseWrapper は、メッセージ変換の応答メッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、応答メッセージをマーシャリングおよびアンマーシャリングする際にランタイムによって使用される要素名および namespace も指定します。

表24.5「@ResponseWrapper プロパティー」に、@ResponseWrapper アノテーションのプロパティーを示します。

表24.5 @ResponseWrapper プロパティー

プロパティー説明

localName

応答メッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値は、Response が追加されたメソッドの名前、または Response が追加された「@WebMethod アノテーション」アノテーションの operationName プロパティーの値のいずれかです。

targetNamespace

XML ラッパー要素が定義される namespace を指定します。デフォルト値は SEI のターゲット namespace です。

className

ラッパー要素を実装する Java クラスの完全な名前を指定します。

注記

className プロパティーのみが必須です。

重要

メソッドに @SOAPBinding アノテーションも付けられ、その parameterStyle プロパティーが ParameterStyle.BARE に設定されている場合、このアノテーションは無視されます。

@WebFault アノテーション

@WebFault アノテーションは、javax.xml.ws.WebFault インターフェースによって定義されます。これは、SEI によってスローされる例外に置かれます。@WebFault アノテーションを使用して、Java 例外を wsdl:fault 要素にマッピングします。この情報は、例外をサービスとそのコンシューマーの両方によって処理できる表現にマーシャリングするのに使用されます。

表24.6「@WebFault プロパティー」に、@WebFault アノテーションのプロパティーを示します。

表24.6 @WebFault プロパティー

プロパティー説明

name

fault 要素のローカル名を指定します。

targetNamespace

fault 要素が定義される namespace を指定します。デフォルト値は SEI のターゲット namespace です。

faultName

例外を実装する Java クラスの完全な名前を指定します。

重要

name プロパティーは必須です。

@Oneway アノテーション

@Oneway アノテーションは、javax.jws.Oneway インターフェースによって定義されます。これは、サービスからの応答を必要としない SEI のメソッドに配置されます。@Oneway アノテーションは、ランタイムに対し、応答を待たず、レスポンスの処理にリソースを確保しないことで、メソッドの実行を最適化できることを指示します。

このアノテーションは、以下の基準を満たすメソッドにのみ使用できます。

  • void を戻す
  • Holder インターフェースを実装するパラメーターを持たない
  • コンシューマーに戻すことのできる例外を発生しない

例24.6「メソッドにアノテーションが付けられた SEI」に、メソッドにアノテーションが付けられた SEI を表示します。

例24.6 メソッドにアノテーションが付けられた SEI

package com.fusesource.demo;

import javax.jws.*;
import javax.xml.ws.*;

@WebService(name="quoteReporter")
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
                   className="org.eric.demo.Quote")
  public Quote getQuote(String ticker);
}

概要

アノテーションによるパラメータープロパティーの定義

SEI のメソッドパラメーターは、wsdl:part 要素およびその wsdl:message 要素に対応します。JAX-WS は、メソッドパラメーター用に生成された wsdl:part 要素を記述することのできるアノテーションを提供します。

@WebParam アノテーション

@WebParam アノテーションは、javax.jws.WebParam インターフェースによって定義されます。これは、SEI で定義されるメソッドのパラメーターに配置されます。@WebParam アノテーションを使用すると、パラメーターの方向、パラメーターが SOAP ヘッダーに配置されるかどうか、および生成された wsdl:part の他のプロパティーを指定できます。

表24.7「@WebParam プロパティー」に、@WebParam アノテーションのプロパティーを示します。

表24.7 @WebParam プロパティー

プロパティー説明

name

 

生成された WSDL ドキュメントに表示されるパラメーターの名前を指定します。RPC バインディングの場合、これはパラメーターを表す wsdl:part の名前です。ドキュメントバインディングの場合、これはパラメーターを表す XML 要素のローカル名です。JAX-WS 仕様によると、デフォルトは argN です。ここで、N はゼロベースの引数インデックスに置き換えてください (例: arg0、arg1 など)。

targetNamespace

 

パラメーターの namespace を指定します。これは、パラメーターが XML 要素にマッピングされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの namespace が使用されます。

mode

Mode.IN (デフォルト)[a]

Mode.OUT

Mode.INOUT

パラメーターの方向を指定します。

header

false (デフォルト)

true

パラメーターが SOAP ヘッダーの一部として渡されるかどうかを指定します。

partName

 

パラメーターの wsdl:part 要素の name 属性の値を指定します。このプロパティーは、ドキュメントスタイルの SOAP バインディングに使用されます。

[a] Holder インターフェースを実装するパラメーターは、デフォルトで Mode.INOUT にマッピングされます。

@WebResult アノテーション

@WebResult アノテーションは、javax.jws.WebResult インターフェースによって定義されます。これは SEI で定義されるメソッドに配置されます。@WebResult アノテーションを使用すると、メソッドの戻り値に生成される wsdl:part のプロパティーを指定できます。

表24.8「@WebResult プロパティー」に、@WebResult アノテーションのプロパティーを示します。

表24.8 @WebResult プロパティー

プロパティー説明

name

生成された WSDL ドキュメントに表示される戻り値の名前を指定します。RPC バインディングの場合、これは戻り値を表す wsdl:part の名前です。ドキュメントバインディングの場合、これは戻り値を表す XML 要素のローカル名です。デフォルト値は return です。

targetNamespace

戻り値の namespace を指定します。これは、戻り値が XML 要素にマッピングされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの namespace が使用されます。

header

戻り値が SOAP ヘッダーの一部として渡されるかどうかを指定します。

partName

戻り値の wsdl:part 要素の name 属性の値を指定します。このプロパティーは、ドキュメントスタイルの SOAP バインディングに使用されます。

例24.7「すべてのアノテーションが付けられた SEI」に、すべてのアノテーションが付けられた SEI を表示します。

例24.7 すべてのアノテーションが付けられた SEI

package com.fusesource.demo;

import javax.jws.*;
import javax.xml.ws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;
import javax.jws.WebParam.*;

@WebService(targetNamespace="http://demo.redhat.com",
            name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
                   className="org.eric.demo.Quote")
  @WebResult(targetNamespace="http://demo.redhat.com/types",
             name="updatedQuote")
  public Quote getQuote(
                        @WebParam(targetNamespace="http://demo.redhat.com/types",
                                  name="stockTicker",
                                  mode=Mode.IN)
                        String ticker
  );
}

24.3.4. Apache CXF アノテーション

24.3.4.1. WSDL ドキュメント

@WSDLDocumentation アノテーション

@WSDLDocumentation アノテーションは、org.apache.cxf.annotations.WSDLDocumentation インターフェースによって定義されます。これは SEI または SEI のメソッドに配置できます。

このアノテーションを使用するとドキュメントを追加でき、SEI が WSDL に変換された後に wsdl:documentation 要素内に表示されます。デフォルトでは、ドキュメント要素はポート型内に表示されますが、配置プロパティーを指定して、ドキュメントを WSDL ファイルの他の場所に表示することができます。「@WSDLDocumentation プロパティー」に、@WSDLDocumentation アノテーションでサポートされるプロパティを示します。

24.3.4.2. @WSDLDocumentation プロパティー

プロパティー説明

value

(必須) ドキュメントのテキストが含まれる文字列。

placement

(任意) このドキュメントを WSDL ファイルのどこに表示するかを指定します。使用できる配置値の一覧は、「WSDL コントラクトでの配置」を参照してください。

faultClass

(任意) 配置が FAULT_MESSAGEPORT_TYPE_OPERATION_FAULT、または BINDING_OPERATION_FAULT に設定されている場合、このプロパティーも障害を表す Java クラスに設定する必要があります。

@WSDLDocumentationCollection アノテーション

@WSDLDocumentationCollection アノテーションは、org.apache.cxf.annotations.WSDLDocumentationCollection インターフェースによって定義されます。これは SEI または SEI のメソッドに配置できます。

このアノテーションは、複数のドキュメント要素を 1 つの配置場所またはさまざまな配置場所に挿入するのに使用されます。

WSDL コントラクトでの配置

ドキュメントが WSDL コントラクトのどこに表示されるかを指定するには、WSDLDocumentation.Placement 型である placement プロパティーを指定します。配置には、以下のいずれかの値を使用できます。

  • WSDLDocumentation.Placement.BINDING
  • WSDLDocumentation.Placement.BINDING_OPERATION
  • WSDLDocumentation.Placement.BINDING_OPERATION_FAULT
  • WSDLDocumentation.Placement.BINDING_OPERATION_INPUT
  • WSDLDocumentation.Placement.BINDING_OPERATION_OUTPUT
  • WSDLDocumentation.Placement.DEFAULT
  • WSDLDocumentation.Placement.FAULT_MESSAGE
  • WSDLDocumentation.Placement.INPUT_MESSAGE
  • WSDLDocumentation.Placement.OUTPUT_MESSAGE
  • WSDLDocumentation.Placement.PORT_TYPE
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_FAULT
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_INPUT
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_OUTPUT
  • WSDLDocumentation.Placement.SERVICE
  • WSDLDocumentation.Placement.SERVICE_PORT
  • WSDLDocumentation.Placement.TOP
@WSDLDocumentation の例

「@WSDLDocumentation の使用」に、@WSDLDocumentation アノテーションを SEI およびそのメソッドの 1 つに追加する方法を示します。

24.3.4.3. @WSDLDocumentation の使用

@WebService
@WSDLDocumentation("A very simple example of an SEI")
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of greeting")
    String sayHi(@WebParam(name = "text") String text);
}

「ドキュメントで生成される WSDL」に示す WSDL が「@WSDLDocumentation の使用」の SEI から生成されると、documentation 要素のデフォルトの配置は、それぞれ、PORT_TYPE および PORT_TYPE_OPERATION になります。

24.3.4.4. ドキュメントで生成される WSDL

<wsdl:definitions ... >
  ...
  <wsdl:portType name="HelloWorld">
    <wsdl:documentation>A very simple example of an SEI</wsdl:documentation>
    <wsdl:operation name="sayHi">
      <wsdl:documentation>A traditional form of greeting</wsdl:documentation>
      <wsdl:input name="sayHi" message="tns:sayHi">
    </wsdl:input>
      <wsdl:output name="sayHiResponse" message="tns:sayHiResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>
@WSDLDocumentationCollection の例

「@WSDLDocumentationCollection の使用」に、@WSDLDocumentationCollection アノテーションを SEI に追加する方法を示します。

24.3.4.5. @WSDLDocumentationCollection の使用

@WebService
@WSDLDocumentationCollection(
    {
        @WSDLDocumentation("A very simple example of an SEI"),
        @WSDLDocumentation(value = "My top level documentation",
                           placement = WSDLDocumentation.Placement.TOP),
        @WSDLDocumentation(value = "Binding documentation",
                           placement = WSDLDocumentation.Placement.BINDING)
    }
)
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of Geeky greeting")
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.6. メッセージのスキーマ検証

@SchemaValidation アノテーション

@SchemaValidation アノテーションは、org.apache.cxf.annotations.SchemaValidation インターフェースによって定義されます。これは SEI および個々の SEI のメソッドに配置できます。

このアノテーションは、このエンドポイントに送信された XML メッセージのスキーマ検証を有効にします。これは、受信 XML メッセージの形式に問題があると思われる場合に、テストの目的で役立ちます。デフォルトでは、パフォーマンスに大きな影響があるため、検証は無効になっています。

スキーマ検証の型

スキーマ検証の動作は、値が org.apache.cxf.annotations.SchemaValidation.SchemaValidationType 型を列挙した type パラメーターによって制御されます。「スキーマ検証の型の値」に、使用可能な検証の型のリストを示します。

24.3.4.7. スキーマ検証の型の値

説明

IN

スキーマ検証を、クライアントとサーバーの受信メッセージに適用します。

OUT

スキーマ検証を、クライアントとサーバーの発信メッセージに適用します。

BOTH

スキーマ検証を、クライアントとサーバーの受信および発信両方のメッセージに適用します。

NONE

すべてのスキーマ検証は無効です。

REQUEST

スキーマ検証をリクエストメッセージに適用します。つまり、発信クライアントメッセージおよび受信サーバーメッセージに検証が適用されます。

RESPONSE

スキーマ検証を応答メッセージに適用します。つまり、受信クライアントメッセージおよび発信サーバーメッセージに検証が適用されます。

以下の例は、MyService SEI に基づくエンドポイントのメッセージのスキーマ検証を有効にする方法を示しています。アノテーションを SEI 全体および SEI の個々のメソッドに適用する方法に注目してください。

@WebService
@SchemaValidation(type = SchemaValidationType.BOTH)
public interface MyService {
    Foo validateBoth(Bar data);

    @SchemaValidation(type = SchemaValidationType.NONE)
    Foo validateNone(Bar data);

    @SchemaValidation(type = SchemaValidationType.IN)
    Foo validateIn(Bar data);

    @SchemaValidation(type = SchemaValidationType.OUT)
    Foo validateOut(Bar data);

    @SchemaValidation(type = SchemaValidationType.REQUEST)
    Foo validateRequest(Bar data);

    @SchemaValidation(type = SchemaValidationType.RESPONSE)
    Foo validateResponse(Bar data);
}

24.3.4.8. データバインディングの指定

@DataBinding アノテーション

@DataBinding アノテーションは、org.apache.cxf.annotations.DataBinding インターフェースによって定義されます。これは SEI に配置されます。

このアノテーションは、データバインディングを SEI に関連付け、デフォルトの JAXB データバインディングを置き換えるのに使用されます。@DataBinding アノテーションの値は、データバインディングを提供するクラス ClassName.class である必要があります。

サポートされるデータバインディング

現在、Apache CXF では以下のデータバインディングがサポートされています。

  • org.apache.cxf.jaxb.JAXBDataBinding

    (デフォルト) 標準の JAXB データバインディング

  • org.apache.cxf.sdo.SDODataBinding

    Service Data Objects (SDO) データバインディングは、Apache Tuscany SDO 実装に基づいています。Maven ビルドのコンテキストでこのデータバインディングを使用する場合は、cxf-rt-databinding-sdo アーティファクトに依存関係を追加する必要があります。

  • org.apache.cxf.aegis.databinding.AegisDatabinding

    Maven ビルドのコンテキストでこのデータバインディングを使用する場合は、cxf-rt-databinding-aegis アーティファクトに依存関係を追加する必要があります。

  • org.apache.cxf.xmlbeans.XmlBeansDataBinding

    Maven ビルドのコンテキストでこのデータバインディングを使用する場合は、cxf-rt-databinding-xmlbeans アーティファクトに依存関係を追加する必要があります。

  • org.apache.cxf.databinding.source.SourceDataBinding

    このデータバインディングは Apache CXF コアに属します。

  • org.apache.cxf.databinding.stax.StaxDataBinding

    このデータバインディングは Apache CXF コアに属します。

「データバインディングの設定」で、SDO バインディングを HelloWorld SEI に関連付ける方法を説明します。

24.3.4.9. データバインディングの設定

@WebService
@DataBinding(org.apache.cxf.sdo.SDODataBinding.class)
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.10. メッセージの圧縮

@GZIP アノテーション

@GZIP アノテーションは、org.apache.cxf.annotations.GZIP インターフェースによって定義されます。これは SEI に配置されます。

メッセージの GZIP 圧縮を有効にします。GZIP はネゴシエートされる機能拡張です。つまり、クライアントからの初期リクエストは gzip されませんが、Accept ヘッダーが追加され、サーバーが GZIP 圧縮をサポートする場合、応答は gzip され、後続のリクエストも gzip されます。

「@GZIP プロパティー」に、@GZIP アノテーションでサポートされるオプションプロパティーを示します。

24.3.4.11. @GZIP プロパティー

プロパティー説明

threshold

このプロパティーで指定されたサイズよりも小さいメッセージは gzip されません。デフォルトは -1 (制限なし) です。

@FastInfoset

@FastInfoset アノテーションは、org.apache.cxf.annotations.FastInfoset インターフェースによって定義されます。これは SEI に配置されます。

メッセージに FastInfoset 形式を使用できるようにします。FastInfoset は XML のバイナリーエンコーディング形式です。これは、XML メッセージのメッセージサイズと処理パフォーマンスの両方を最適化することを目的としています。詳細は、Fast Infoset で Sun のアーティクルを参照してください。

FastInfoset はネゴシエートされる機能拡張です。つまり、クライアントからの初期リクエストは FastInfoset 形式ではありませんが、Accept ヘッダーが追加され、サーバーが FastInfoset をサポートする場合、応答は FastInfoset 形式になり、後続のリクエストも FastInfoset 形式になります。

「@FastInfoset プロパティー」に、@FastInfoset アノテーションでサポートされるオプションプロパティーを示します。

24.3.4.12. @FastInfoset プロパティー

プロパティー説明

force

ネゴシエートではなく FastInfoset 形式の使用を強制するブール値プロパティー。true の場合、強制的に FastInfoset 形式を使用します。そうでない場合は、ネゴシエートを行います。デフォルトは false です。

@GZIP の例

「GZIP の有効化」に、HelloWorld SEI で GZIP 圧縮を有効にする方法を示します。

24.3.4.13. GZIP の有効化

@WebService
@GZIP
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}
@FastInfoset の例

「FastInfoset の有効化」に、HelloWorld SEI で FastInfoset 形式を有効にする方法を説明します。

24.3.4.14. FastInfoset の有効化

@WebService
@FastInfoset
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.15. エンドポイントでのロギングの有効化

@Logging アノテーション

@Logging アノテーションは、org.apache.cxf.annotations.Logging インターフェースによって定義されます。これは SEI に配置されます。

このアノテーションにより、SEI に関連付けられたすべてのエンドポイントのロギングが有効になります。「@Logging プロパティー」に、このアノテーションで設定できるオプションプロパティーを示します。

24.3.4.16. @Logging プロパティー

プロパティー説明

limit

これを超えるメッセージがログで切り捨てられるサイズ制限を指定します。デフォルトは 64 K です。

inLocation

受信メッセージをログに記録する場所を指定します。<stderr><stdout><logger>、またはファイル名のいずれかです。デフォルトは <logger> です。

outLocation

発信メッセージをログに記録する場所を指定します。<stderr><stdout><logger>、またはファイル名のいずれかです。デフォルトは <logger> です。

「アノテーションを使用したロギングの設定」で、HelloWorld SEI でロギングを有効にする方法を説明します。ここでは、受信メッセージは <stdout> に送信され、発信メッセージは <logger> に送信されます。

24.3.4.17. アノテーションを使用したロギングの設定

@WebService
@Logging(limit=16000, inLocation="<stdout>")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.18. エンドポイントへのプロパティとポリシーの追加

概要

プロパティとポリシーの両方を使用して、設定データをエンドポイントに関連付けることができます。これらの間の基本的な違いは、プロパティー が Apache CXF 固有の設定メカニズムであるのに対して、ポリシー は標準の WSDL 設定メカニズムであることです。ポリシーは通常 WS 仕様および標準に基づいており、通常は WSDL コントラクトに表示される wsdl:policy 要素を定義して設定されます。これとは対照的に、プロパティーは Apache CXF 固有のもので、通常は Apache CXF Spring 設定ファイルで jaxws:properties 要素を定義して設定されます。

ただし、ここで説明するように、アノテーションを使用して Java でプロパティー設定および WSDL ポリシー設定を定義することも可能です。

24.3.4.19. プロパティーの追加

@EndpointProperty アノテーション

@EndpointProperty アノテーションは、org.apache.cxf.annotations.EndpointProperty インターフェースによって定義されます。これは SEI に配置されます。

このアノテーションにより、Apache CXF 固有の設定がエンドポイントに追加されます。エンドポイントプロパティーは、Spring 設定ファイルでも指定できます。たとえば、エンドポイントに WS-Security を設定するには、以下のように Spring 設定ファイルの jaxws:properties 要素を使用してエンドポイントプロパティーを追加できます。

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:jaxws="http://cxf.apache.org/jaxws"
   ... >

   <jaxws:endpoint
      id="MyService"
      address="https://localhost:9001/MyService"
      serviceName="interop:MyService"
      endpointName="interop:MyServiceEndpoint"
      implementor="com.foo.MyService">

      <jaxws:properties>
         <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
         <entry key="ws-security.signature.properties" value="etc/keystore.properties"/>
         <entry key="ws-security.encryption.properties" value="etc/truststore.properties"/>
         <entry key="ws-security.encryption.username" value="useReqSigCert"/>
      </jaxws:properties>

   </jaxws:endpoint>
</beans>

あるいは、「@EndpointProperty アノテーションを使用した WS-Security の設定」に示すように、@EndpointProperty アノテーションを SEI に追加して、Java で前述の設定を指定できます。

24.3.4.20. @EndpointProperty アノテーションを使用した WS-Security の設定

@WebService
@EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback")
@EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties")
@EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties")
@EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}
@EndpointProperties アノテーション

@EndpointProperties アノテーションは、org.apache.cxf.annotations.EndpointProperties インターフェースによって定義されます。これは SEI に配置されます。

このアノテーションは、複数の @EndpointProperty アノテーションをリストにグループ化する方法を提供します。@EndpointProperties を使用すると、「@EndpointProperties アノテーションを使用した WS-Security の設定」に示すように「@EndpointProperty アノテーションを使用した WS-Security の設定」を再書き込みできます。

24.3.4.21. @EndpointProperties アノテーションを使用した WS-Security の設定

@WebService
@EndpointProperties(
  {
  @EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback"),
  @EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties"),
  @EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties"),
  @EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
})
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.22. ポリシーの追加

@Policy アノテーション

@Policy アノテーションは、org.apache.cxf.annotations.Policy インターフェースによって定義されます。これは SEI または SEI のメソッドに配置できます。

このアノテーションは、WSDL ポリシーを SEI または SEI メソッドに関連付けるために使用されます。このポリシーは、標準の wsdl:policy 要素が含まれる XML ファイルを参照する URI を指定して指定されます。SEI から WSDL コントラクトが生成される場合は (たとえば、java2ws コマンドラインツールを使用して)、WSDL にこのポリシーを追加するかどうかを指定できます。

「@Policy プロパティー」に、@Policy アノテーションでサポートされるプロパティを示します。

24.3.4.23. @Policy プロパティー

プロパティー説明

uri

(必須) ポリシー定義が含まれるファイルの場所。

includeInWSDL

(任意) WSDL を生成するときに生成されたコントラクトにポリシーを含めるかどうか。デフォルトは true です。

placement

(任意) このドキュメントを WSDL ファイルのどこに表示するかを指定します。使用できる配置値の一覧は、「WSDL コントラクトでの配置」を参照してください。

faultClass

(任意) 配置が BINDING_OPERATION_FAULT または PORT_TYPE_OPERATION_FAULT に設定されている場合、このプロパティーを設定して、このポリシーが適用される障害を指定する必要があります。値は、障害を表す Java クラスです。

@Policies アノテーション

@Policies アノテーションは、org.apache.cxf.annotations.Policies インターフェースによって定義されます。これは SEI または SEI のメソッドに配置できます。

このアノテーションは、複数の @Po