Apache CXF 開発ガイド

Red Hat Fuse 7.10

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

Red Hat Fuse Documentation Team

概要

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

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

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

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

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

第1章 WSDL コントラクトの紹介

概要

WSDL ドキュメントは、Web サービス記述言語といくつかの可能な拡張機能を使用してサービスを定義します。ドキュメントには論理的な部分と具体的な部分があります。コントラクトの抽象的な部分は、実装に中立なデータ型とメッセージの観点からサービスを定義します。ドキュメントの具体的な部分は、サービスを実装するエンドポイントがシステム外の世界とどのように相互作用するかを定義します。

サービスを設計するための推奨されるアプローチは、コードを記述する前に、WSDL および XML スキーマでサービスを定義することです。WSDL ドキュメントを手動で編集するときは、ドキュメントが有効であり、正しいことを確認する必要があります。これを行うには、WSDL にある程度精通している必要があります。この規格は、W3C Web サイト (www.w3.org) にあります。

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

概要

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

WSDL ドキュメントには次の 2 つが含まれます。

実装中立的な用語でサービスを定義する論理部分
サービスを実装するエンドポイントがネットワーク上でどのように公開されるかを定義する具体的な部分

論理部分

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

具体的な部分

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

1.2. WSDL 要素

WSDL ドキュメントは、次の要素で設定されています。

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

1.3. コントラクトの設計

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

サービスで使用されるデータ型を定義します。
サービスで使用されるメッセージを定義します。
サービスのインターフェイスを定義します。
各インターフェイスで使用されるメッセージと、ネットワーク上のデータの具体的な表現との間のバインディングを定義します。
各サービスのトランスポートの詳細を定義します。

第2章論理データ単位の定義

概要

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

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 スキーマで使用される場合は、サービスとの対話に使用されるデータを保持する XML ドキュメントの構造を定義します。サービスで使用されるデータユニットを定義するときに、メッセージ部分の構造を指定するタイプとしてそれらを定義できます。データユニットをメッセージ部分を設定する要素として定義することもできます。

データユニットを作成する際の考慮事項

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

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

属性ではなく要素を使用します。
基本型としてプロトコル固有のタイプを使用しないでください。

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

概要

WSDL コントラクトの作成方法に応じて、新しいデータ定義を作成するには、さまざまな知識が必要です。Apache CXF GUI ツールは、XML スキーマを使用してデータ型を記述するための多くの支援を提供します。他の XML エディターは、さまざまなレベルの支援を提供します。選択するエディターに関係なく、結果として得られるコントラクトがどのようになるかについてある程度の知識を得ることが推奨されます。

手順

WSDL コントラクトで使用されるデータの定義には、次の手順が含まれます。

コントラクトで記述されているインターフェイスで使用されているすべてのデータ単位を判別します。
コントラクトに types 要素を作成します。
例2.1「WSDL コントラクトのスキーマエントリー」のように、type 要素の子として schema 要素を作成します。
targetNamespace 属性は、新規データタイプを定義する 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/">
```
要素のコレクションである複合型ごとに、complexType 要素を使用してデータ型を定義します。「データ構造の定義」を参照してください。
各配列について、complexType 要素を使用してデータタイプを定義します。「配列の定義」を参照してください。
単純型から派生する複合型ごとに、simpleType 要素を使用してデータ型を定義します。「制限によるタイプの定義」を参照してください。
各列挙型について、simpleType 要素を使用してデータタイプを定義します。「列挙型の定義」を参照してください。
要素ごとに、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 つの情報が必要です。

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

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

例2.3 簡易構造

struct personalInfo
{
  string name;
  int age;
};

例2.4「複合型」は、例2.3「簡易構造」に記載されている構造の可能な XML スキーママッピングの 1 つを表しています。例2.4「複合型」で定義された構造によって、name および age の 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 スキーマの単純タイプのいずれか、またはコントラクトで定義されている任意の名前付き複合タイプのいずれかです。

name と type 以外に、element 要素には、minOcurrs と maxOccurs の 2 つの一般的に使用される任意の属性があります。これらの属性は、構造内でフィールドが発生する回数に制限を設けます。デフォルトでは、各フィールドは複合型で 1 回だけ発生します。これらの属性を使用して、フィールドが構造体に表示される必要がある回数、または表示される回数を変更できます。たとえば、例2.6「発生制約のある簡易複合型」に示されているように、previousJobs というフィールドを定義できます。これは 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 がゼロに設定された単純な複合型」で示すように、minOccurs をゼロに設定することにより、minOccurs を使用して age フィールドを任意にすることもできます。この場合、age は省略できますが、データは引き続き有効となります。

例2.7 minOccurs がゼロに設定された単純な複合型

<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 要素は、all、sequence、または 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 スキーマの単純型の 1 つにすることができます。
use - 複合型にこの属性が必要であるかを指定する任意の属性。有効な値は required または optional です。デフォルトでは、この属性はオプションです。

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

2.5.2. 配列の定義

概要

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

複合型配列

複合型配列は、シーケンス複合型の特殊なケースです。単一要素で複合型を定義し、maxOccurs 属性の値を指定するだけです。たとえば、20 個の浮動小数点数の配列を定義するには、例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 配列、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 つの部分があります。

型の名前は、complexType 要素の name 属性によって定義されます。
complexContent 要素は、新しい型に複数の要素があることを指定します。
注記
複合型に新しい属性を追加する場合にのみ、simpleContent 要素を使用できます。
新しい型が派生される ベース 型と呼ばれる型は、extension 要素の base 属性で指定されます。
新しい型の要素と属性は、通常の複合型と同様に 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 つのことが必要です。

新しい型の名前は、simpleType 要素の name 属性によって指定されます。
ベース型 と呼ばれる新しい型が派生される単純型は、restriction 要素で指定されます。「基本型の指定」を参照してください。
ベース型の制限を定義する 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 つのファセットをサポートします。

長さ
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 スキーマプリミティブ型またはコントラクトで定義された任意の名前付き複合型にすることができます。タイプにインライン定義がある場合、この属性は省略できます。
nillable - ドキュメントから要素を完全に省略できるかどうかを指定します。nillable が true に設定されている場合、要素はスキーマを使用して生成したドキュメントから省略できます。

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

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

概要

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

概要

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

メッセージには各パラメーターを個別の部分としてリストできますが、推奨される方法は、操作に必要なデータをカプセル化する単一の部分のみを使用することです。

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

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

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

レガシーシステムと統合するためのメッセージデザイン

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

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

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

SOAP サービスのメッセージデザイン

RPC スタイルは既存のシステムのモデリングに役立ちますが、サービスのコミュニティーはラップされたドキュメントスタイルを強く支持しています。ラップされたドキュメントスタイルでは、各メッセージは 1 つの部分で設定されます。メッセージのパーツは、コントラクトの types 要素で定義されたラッパー要素を参照します。ラッパー要素には次の特徴があります。

これは、一連の要素を含む複合型です。詳細は、「複雑なデータ型の定義」を参照してください。
入力メッセージのラッパーの場合:
- メソッドの入力パラメーターごとに 1 つの要素があります。
- その名前は、関連付けられている操作の名前と同じです。
出力メッセージのラッパーの場合:
- メソッドの出力パラメーターごとに 1 つの要素があり、メソッドの inout パラメーターごとに 1 つの要素があります。
- その最初の要素は、メソッドの戻りパラメーターを表します。
- この名前は、ラッパーが関連付けられる操作の名前に Response を追加して生成されます。

メッセージの命名

コントラクト内の各メッセージは、その名前空間内で一意の名前を持っている必要があります。次の命名規則を使用することをお勧めします。

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

メッセージ部分

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

表3.1 part データ型の属性
属性	説明
`element`="elem_name"	パーツのデータ型は、elem_name という要素によって定義されます。
`type=`"type_name"	part のデータ型は、type_name と呼ばれる型によって定義されます。

メッセージは part の名前を再利用できます。たとえば、メソッドに参照によって渡されるか、または入力/出力であるパラメーター 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 要素で定義されたサービスインターフェイスを実装するためにコードが生成されると、各操作はコントラクトで指定された入力、出力、および障害メッセージで定義されたパラメーターが含まれるメソッドに変換されます。

Process

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

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

ポートタイプ

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 要素を持つ必要があります。操作は input 要素と output 要素の両方を持つことができますが、各要素 1 つだけです。操作に fault 要素は必要はありませんが、必要な場合は任意の数の fault 要素を持つことができます。

要素には、表4.2「入力要素と出力要素の属性」にリストされている 2 つの属性があります。

表4.2 入力要素と出力要素の属性
属性	説明
`name`	操作を具体的なデータ形式にマッピングするときに参照できるように、メッセージを識別します。名前は、囲んでいるポートタイプ内で一意である必要があります。
`message`	送信または受信されるデータを説明する抽象メッセージを指定します。`message` 属性の値は、WSDL ドキュメントに定義された抽象メッセージの 1 つの `name` 属性に対応している必要があります。

すべての input および output 要素の name 属性を指定する必要はありません。WSDL はエンクロージング操作の名前を基にデフォルトの命名スキームを提供します。操作で使用される要素が 1 つだけの場合、要素名はデフォルトで操作の名前になります。input および output 要素の両方が使用される場合、デフォルトの要素名は、名前にそれぞれ 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 では、ポートタイプを複数のバインディングにマップできます。たとえば、コントラクトのポートタイプが単一の場合、それを 2 つ以上のバインディングにマップできます。各バインディングは、メッセージの一部のマッピング方法を変更したり、メッセージにまったく異なるペイロード形式を指定したりする可能性があります。

WSDL 要素

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

実際のマッピングは、binding 要素の子で定義されます。これらの要素は、使用するペイロード形式のタイプによって異なります。次の章では、さまざまなペイロード形式とそれらのマッピングを指定するために使用される要素について説明します。

コントラクトへの追加

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

ツールにより、コントラクトに適切な要素が追加されます。ただし、さまざまなタイプのバインディングがどのように機能するかについてある程度の知識を得ることが推奨されます。

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

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

Apache CXF は、次のバインディングをサポートしています。

SOAP 1.1
SOAP 1.2
CORBA
Pure XML

第6章 SOAP1.1 メッセージの使用

概要

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

6.1. SOAP1.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` バインディング名	生成される SOAP バインディングの名前を指定します。
`-d` 出力ディレクトリー	生成される WSDL ファイルを配置するディレクトリーを指定します。
`-o` 出力ファイル	生成される WSDL ファイルの名前を指定します。
`-n` SOAP ボディー namespace	スタイルが RPC の場合は、SOAP ボディーの名前空間を指定します。
`-style` (document/rpc)	SOAP バインディングで使用するエンコードスタイル (ドキュメントまたは RPC) を指定します。デフォルトはドキュメントです。
`-use` (literal/encoded)	SOAP バインディングで使用するバインディングの使用 (エンコードまたはリテラル) を指定します。デフォルトはリテラルです。
`-v`	ツールのバージョン番号を表示します。
`-verbose`	コード生成プロセス中にコメントを表示します。
`-quiet`	コード生成プロセス中のコメントを非表示にします。

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

重要

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

例

システムに、注文を受け取り、注文を処理するための単一の操作を提供するインターフェイスがある場合、例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. SOAP1.1 バインディングへの SOAP ヘッダーの追加

概要

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

構文

SOAP ヘッダーを定義するための構文を例6.3「SOAP ヘッダー構文」に示します。soap:header の message 属性は、ヘッダーに挿入される部分が取得されたメッセージの修飾名です。part 属性は、SOAP ヘッダーに挿入されたメッセージ部分の名前です。SOAP ヘッダーは常にドキュメントスタイルであるため、SOAP ヘッダーに挿入される WSDL メッセージ部分は要素を使用して定義する必要があります。message と part 属性はともに、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>

必須の message と part 属性と同様に、soap:header は、namespace、use、および 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.2 バインディングを生成するには、コマンド 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` バインディング名	生成される SOAP バインディングの名前を指定します。
`-soap12`	生成されたバインディングが SOAP 1.2 を使用することを指定します。
`-d` 出力ディレクトリー	生成される WSDL ファイルを配置するディレクトリーを指定します。
`-o` 出力ファイル	生成される WSDL ファイルの名前を指定します。
`-n` SOAP ボディー namespace	スタイルが RPC の場合は、SOAP ボディーの名前空間を指定します。
`-style` (document/rpc)	SOAP バインディングで使用するエンコードスタイル (ドキュメントまたは RPC) を指定します。デフォルトはドキュメントです。
`-use` (literal/encoded)	SOAP バインディングで使用するバインディングの使用 (エンコードまたはリテラル) を指定します。デフォルトはリテラルです。
`-v`	ツールのバージョン番号を表示します。
`-verbose`	コード生成プロセス中にコメントを表示します。
`-quiet`	コード生成プロセス中のコメントを非表示にします。

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

重要

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

例

システムに、注文を受け取り、注文を処理するための単一の操作を提供するインターフェイスがある場合、例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 要素は、バインディングの input、output、および 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 ヘッダーを使用した SOAP 1.2 バインディング」は、例7.1「注文システムインターフェイス」に示されている orderWidgets サービスの変更バージョンを示しています。このバージョンは変更され、各注文のリクエストおよび応答のヘッダーに xsd:base64binary 値が配置されるようになります。ヘッダーは、widgetKey メッセージの keyVal 部分として定義されます。この場合、ヘッダーは入力メッセージまたは出力メッセージの一部ではないため、ヘッダーを作成するためのアプリケーションロジックを追加する必要があります。

例7.4 SOAP ヘッダーを使用した 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"/>
</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.4「SOAP ヘッダーを使用した SOAP 1.2 バインディング」を変更して、例7.5「SOAP ヘッダーを使用した orderWidgets の SOAP 1.2 バインディング」に示すように、ヘッダー値が入力メッセージと出力メッセージの一部になるようにします。この場合、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 マルチパート/関連メッセージを使用して SOAP メッセージでバイナリーデータを送信できます。この手法は、添付ファイル付きの SOAP を使用して呼び出されます。SOAP 添付ファイルは、W3C の SOAP Messages with Attachments Note で定義されています。

Namespace

MIME マルチパート/関連メッセージの定義に使用される WSDL 拡張機能は、名前空間 http://schemas.xmlsoap.org/wsdl/mime/ で定義されています。

以下の説明では、この namespace の前に mime 接頭辞が付くことを仮定しています。これを設定する WSDL definitions 要素のエントリーは例8.1「コントラクトの MIME 名前空間の仕様」に表示されます。

例8.1 コントラクトの MIME 名前空間の仕様

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

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

デフォルトの SOAP バインディングでは、input、output、および 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 マルチパートメッセージを完全に説明するには、次の手順を実行する必要があります。

MIME マルチパートメッセージとして送信する input または output メッセージで、エンクロージングメッセージの最初の子要素として mime:mulipartRelated 要素を追加します。
mime:part 子要素を mime:multipartRelated 要素に追加し、その name 属性を一意の文字列に設定します。
soap:body 要素を mime:part 要素の子として追加し、その属性を適切に設定します。
注記
コントラクトにデフォルトの SOAP バインディングがある場合、デフォルトのバインディングの対応するメッセージから soap:body 要素を MIME マルチパートメッセージにコピーできます。
別の mime:part 子要素を mime:multipartReleated 要素に追加し、その name 属性を一意の文字列に設定します。

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) パート 1: インターネットメッセージ本文と Multipurpose Internet Mail Extensions (MIME) パート 2: メディアタイプで詳細に説明されています。 +

追加の MIME 部分ごとに、手順 [i303819] および [i303821] を繰り返します。

例

例8.2「添付ファイル付きの SOAP を使用したコントラクト」は、X 線を JPEG 形式で保存するサービスを定義する WSDL フラグメントを示しています。イメージデータ xRay は、xsd: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) は、XML メッセージの一部としてバイナリーデータを送信するためのメカニズムとして、SOAP を添付ファイルに置き換えます。Apache CXF で MTOM を使用するには、サービスのコントラクトに正しいスキーマタイプを追加し、MTOM の最適化を有効にする必要があります。

9.1. MTOM の概要

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

添付ファイルとして送信するデータに注釈を付けます。
データを実装する WSDL または Java クラスのいずれかに注釈を付けることができます。
ランタイムの MTOM サポートを有効にします。
これは、プログラムで、または設定を通して行うことができます。
添付ファイルとして渡されるデータの DataHandler を開発します。
注記
DataHandler の開発は、本ガイドの対象外です。

9.2. MTOM を使用するためのデータ型への注釈

概要

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

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

最初に WSDL

例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 名前空間で定義され、要素に含まれると予想される MIME タイプを指定します。MIME タイプのコンマ区切りリストを指定できます。この属性の設定により、コードジェネレーターがデータの JAXB クラスを作成する方法が変更されます。ほとんどの MIME タイプでは、コードジェネレーターが DataHandler を作成します。イメージ用などの一部の MIME タイプには、マッピングが定義されています。

注記

MIME タイプは、Internet Assigned Numbers Authority (IANA) によって維持され、Multipurpose Internet Mail Extensions (MIME) パート 1: インターネットメッセージ本文と Multipurpose Internet Mail Extensions (MIME) パート 2: メディアタイプで詳細に説明されています。

ほとんどの場合、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

Java の最初の開発を行っている場合は、次のようにして JAXB クラス MTOM を準備できます。

バイナリーデータを保持するフィールドが DataHandler であることを確認してください。
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 は、各タイプのエンドポイントに異なるメカニズムを提供します。

Service provider

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

公開されたサービスの Endpoint オブジェクトにアクセスします。
Endpoint オブジェクトにアクセスするための最も簡単な方法として、エンドポイントをパブリッシュするときが挙げられます。詳細は、31章サービスの公開 を参照してください。
例9.4「エンドポイントからの SOAP バインディングの取得」で示すように、getBinding() メソッドを使用して Endpoint から SOAP バインディングを取得します。
例9.4 エンドポイントからの SOAP バインディングの取得
```
// Endpoint ep is declared previously
SOAPBinding binding = (SOAPBinding)ep.getBinding();
```
MTOM プロパティーにアクセスするには、返されたバインディングオブジェクトを SOAPBinding オブジェクトにキャストする必要があります。
例9.5「サービスプロバイダーの MTOM 有効プロパティーの設定」に示されるように、バインディングの setMTOMEnabled() メソッドを使用して、バインディングの MTOM enabled プロパティーを true に設定します。
例9.5 サービスプロバイダーの MTOM 有効プロパティーの設定
```
binding.setMTOMEnabled(true);
```

コンシューマー

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

コンシューマーのプロキシーを BindingProvider オブジェクトにキャストします。
コンシューマープロキシーの取得は、25章WSDL コントラクトなしでコンシューマーの開発 または 28章WSDL コントラクトからのコンシューマーの開発 を参照してください。
例9.6「BindingProvider からの SOAP バインディングの取得」で示すように、getBinding() メソッドを使用して BindingProvider から SOAP バインディングを取得します。
例9.6 BindingProvider からの SOAP バインディングの取得
```
// BindingProvider bp declared previously
SOAPBinding binding = (SOAPBinding)bp.getBinding();
```
例9.7「コンシューマーの MTOM 有効プロパティーの設定」に示されるように、バインディングの setMTOMEnabled() メソッドを使用して、バインディングの MTOM enabled プロパティーを true に設定します。
例9.7 コンシューマーの MTOM 有効プロパティーの設定
```
binding.setMTOMEnabled(true);
```

9.3.2. 設定の使用

概要

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

手順

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

jaxws:property 子要素をエンドポイントの jaxws:endpoint 要素に追加します。
entry 子要素を jaxws:property 要素に追加します。
entry 要素の key 属性を mtom-enabled に設定します。
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 ドキュメントの使用

概要

Pure XML ペイロードフォーマットは、SOAP エンベロープのオーバーヘッドなしでシンプルな XML ドキュメントを使用してサービスをデータの交換を可能にすることで、SOAP バインディングの代替手段を提供します。

XML バインディング名前空間

XML 形式のバインディングを記述するために使用される拡張機能は namespace http://cxf.apache.org/bindings/xformat で定義されます。Apache CXF ツールは、接頭辞 xformat を使用して XML バインディングエクステンションを表します。コントラクトに次の行を追加します。

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

ハンドエディティング

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

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

注記

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

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

インターフェイスのメッセージを SOAP エンベロープを使わずに XML 文書として渡すように指定する場合、メッセージがワイヤー上に書かれるときに有効な XML 文書を形成するように注意する必要があります。また、XML ドキュメントを受信する Apache CXF 参加者が Apache CXF によって生成されたメッセージを認識できるようにする必要があります。

両問題を解決する簡単な方法は、グローバル xformat:binding 要素または個別のメッセージの xformat:body 要素のいずれかで、オプションの rootNode 属性を使用することです。rootNode 属性は、Apache CXF が生成した XML ドキュメントの root ノードとして機能する要素の 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 ドキュメントは、pairName および entryNum の 2 つのルート要素があるため無効です。

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

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

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

例10.4 rootNode が設定された XML Binding

<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 Binding」で定義した出力メッセージに、入力メッセージとは異なるルート要素がある場合、例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 コンシューマーの両方になります。

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

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

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 ランタイム実装をサポートします。

Undertow: 「Undertow ランタイムの設定」で詳しく説明されています。
Netty (「Netty ランタイムの設定」) で詳細に説明されています。

Netty HTTP URL

通常、HTTP エンドポイントはクラスパス (Undertow または Netty のいずれか) に含まれる HTTP ランタイムを使用します。ただし、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.1 address 要素を使用してエンドポイントのアドレスを指定する必要があります。エンドポイントのアドレスを URL として指定する 1 つの属性 location があります。SOAP 1.1 address 要素は、namespace http://schemas.xmlsoap.org/wsdl/soap/ で定義されています。

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

例12.1 SOAP 1.1 ポート要素

<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.2 address 要素を使用してエンドポイントのアドレスを指定する必要があります。エンドポイントのアドレスを URL として指定する 1 つの属性 location があります。SOAP 1.2 address 要素は、namespace http://schemas.xmlsoap.org/wsdl/soap12/ で定義されています。

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

例12.2 SOAP 1.2 ポート要素

<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 ポート要素」は、XML メッセージの送信に使用される port 要素を示しています。

例12.3 HTTP ポート要素

<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 つのメカニズムを使用して設定できます。

設定
WSDL

12.2.2. 設定の使用

Namespace

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

例12.4 HTTP コンシューマー設定名前空間

<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 接続プロパティーを指定します。「クライアント要素」を参照してください。
`http-conf:authorization`	エンドポイントがプリエンプションで使用する Basic 認証方法を設定するためのパラメーターを指定します。`http-conf:basicAuthSupplier` オブジェクトを指定することが推奨されます。
`http-conf:proxyAuthorization`	送信 HTTP プロキシーサーバーに対して Basic 認証を設定するためのパラメーターを指定します。
`http-conf:tlsClientParameters`	SSL/TLS の設定に使用するパラメーターを指定します。
`http-conf:basicAuthSupplier`	エンドポイントによって使用される基本認証情報または 401 HTTP チャレンジへの応答として、エンドポイントによって使用される基本認証情報を提供するオブジェクトの Bean 参照またはクラス名を指定します。
`http-conf:trustDecider`	情報送信前に HTTPS サービスプロバイダーとのコネクションに対して信頼を確立するために HTTP(S) `URLConnection` オブジェクトをチェックするオブジェクトの Bean 参照またはクラス名を指定します。

クライアント要素

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

表12.2 HTTP コンシューマー設定の属性
属性	説明
`ConnectionTimeout`	コンシューマーがタイムアウトするまでの接続の確立を試みる期間 (ミリ秒単位) を指定します。デフォルトは `30000` です。 `0` を指定すると、コンシューマーはリクエストの送信を無期限に続行します。
`ReceiveTimeout`	コンシューマーがタイムアウトするまでの応答を待つ期間 (ミリ秒単位) を指定します。デフォルトは `30000` です。 `0` を指定すると、コンシューマーは無期限に待機します。
`AutoRedirect`	コンシューマーが自動的に発行されたリダイレクトに従うかどうかを指定します。デフォルトは `false` です。
`MaxRetransmits`	コンシューマーがリダイレクトを満たすリクエストを再送信する最大回数を指定します。デフォルトは `-1` で、無制限の再送信が許可されることを指定します。
`AllowChunking`	コンシューマーがチャンクを使用して要求を送信するかどうかを指定します。デフォルトは `true` で、リクエストの送信時にコンシューマーがチャンクを使用することを指定します。以下のいずれかが true の場合、チャンクは使用できません。 `http-conf:basicAuthSupplier` が、クレデンシャルを先制的に提供するように設定されている。 `AutoRedirect` は `true` に設定されている。いずれの場合も、`AllowChunking` の値は無視され、チャンクは許可されません。
`Accept`	コンシューマーを処理する用意があるメディアタイプを指定します。値は HTTP `Accept` プロパティーの値として使用されます。属性の値は、多目的インターネットメール拡張 (MIME) タイプを使用して指定されます。
`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) アドレスへのマッピング) を示します。
`接続`	各リクエスト/レスポンスダイアログの後に、特定の接続を開いたままにするか、閉じるかどうかを指定します。有効な値は 2 つあります。 `Keep-Alive` - 最初のリクエスト/応答シーケンスの後に、コネクションを開いたままにしておくことをコンシューマーが希望することを指定します。サーバーがそれに従うと、コンシューマーが閉じられるまで接続が開かれます。 `close` (デフォルト) - 各リクエスト/応答シーケンスの後に、サーバーへのコネクションが閉じられるよう指定します。
`CacheControl`	コンシューマーからサービスプロバイダーへの要求を設定するチェーンに含まれるキャッシュが順守する必要のある動作に関するディレクティブを指定します。「コンシューマーキャッシュ制御ディレクティブ」を参照してください。
`cookie`	すべての要求で送信される静的クッキーを指定します。
`BrowserType`	要求の発信元のブラウザーに関する情報を指定します。World Wide Web コンソーシアム (W3C) の HTTP 仕様では、これはユーザーエージェントとも呼ばれます。一部のサーバーは、リクエストを送信するクライアントに基づいて最適化されます。
`Referer`	特定のサービスで要求を行うようにコンシューマーに指示するリソースの URL を指定します。この値は、HTTP `Referer` プロパティーの値として使用されます。この HTTP プロパティーは、要求が URL を入力せずにハイパーリンクの結果をクリックすると、使用されます。これにより、サーバーは以前のタスクフローに基づいて処理を最適化し、ログ記録、最適化されたキャッシュ、廃止されたリンクやタイプミスのあるリンクのトレースなどの目的でリソースへのバックリンクのリストを生成できます。ただし、通常は Web サービスアプリケーションでは使用されません。 `AutoRedirect` 属性が `true` に設定されていて、リクエストがリダイレクトされた場合、`Referer` 属性で指定された値はすべてオーバーライドされます。HTTP 参照プロパティーの値は、コンシューマーの元のリクエストをリダイレクトするサービスの URL に設定されます。
`DecoupledEndpoint`	別のプロバイダー→コンシューマー接続を介して応答を受信するための分離されたエンドポイントの URL を指定します。分離されたエンドポイントの使用の詳細については、「分離モードでの HTTP トランスポートの使用」を参照してください。分離されたエンドポイントが機能するには、WS-Addressing を使用するようにコンシューマーエンドポイントとサービスプロバイダーエンドポイントの両方を設定する必要があります。
`ProxyServer`	要求がルーティングされるプロキシーサーバーの URL を指定します。
`ProxyServerPort`	要求がルーティングされるプロキシーサーバーのポート番号を指定します。
`ProxyServerType`	要求のルーティングに使用されるプロキシーサーバータイプを指定します。有効な値は以下のとおりです。 `HTTP`(デフォルト) `SOCKS`

例

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

例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 要素は、名前空間 http://cxf.apache.org/transports/http/configuration で定義されています。通常、接頭辞 http-conf を使用して参照されます。HTTP 設定要素を使用するには、例12.7「HTTP Consumer WSDL Element の名前空間」にある行をエンドポイントの WSDL ドキュメントの definitions 要素に追加する必要があります。

例12.7 HTTP Consumer WSDL Element の名前空間

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

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

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

クライアント要素

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 つのメカニズムを使用して設定できます。

設定
WSDL

12.3.2. 設定の使用

Namespace

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

例12.9 HTTP プロバイダー設定名前空間

<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 接続プロパティーを指定します。「サーバー要素」を参照してください。
`http-conf:contextMatchStrategy`	HTTP リクエストを処理するためにコンテキスト一致ストラテジーを設定するパラメーターを指定します。
`http-conf:fixedParameterOrder`	この宛先によって処理される HTTP リクエストのパラメーター順序が固定されるかどうかを指定します。

サーバー要素

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

表12.5 HTTP サービスプロバイダー設定属性
属性	説明
`ReceiveTimeout`	接続がタイムアウトする前に、サービスプロバイダーが要求の受信を試行する時間の長さをミリ秒単位で設定します。デフォルトは `30000` です。 `0` はプロバイダーがタイムアウトしないことを指定します。
`SuppressClientSendErrors`	リクエストの受信時に例外が出力されるかどうかを指定します。デフォルトは `false` で、エラーが発生すると例外が出力されます。
`SuppressClientReceiveErrors`	コンシューマーへの応答の送信時にエラーが発生したときに例外を出力するかどうかを指定します。デフォルトは `false` で、エラーが発生すると例外が出力されます。
`HonorKeepAlive`	応答の送信後に、サービスプロバイダーが接続のリクエストを開いたままにするかどうかを指定します。デフォルトは `false` で、キープアライブ要求は無視されます。
`RedirectURL`	クライアント要求で指定された URL が要求されたリソースに対して適切でなくなった場合に、クライアント要求がリダイレクトされる URL を指定します。この場合、サーバー応答の最初の行にステータスコードが自動的に設定されていない場合、ステータスコードは 302 に設定され、ステータスの説明はオブジェクト移動に設定されます。値は 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 要素は、名前空間 http://cxf.apache.org/transports/http/configuration で定義されています。通常、接頭辞 http-conf を使用して参照されます。HTTP 設定要素を使用するには、例12.12「HTTP プロバイダーの WSDL 要素の名前空間」にある行をエンドポイントの WSDL ドキュメントの definitions 要素に追加する必要があります。

例12.12 HTTP プロバイダーの WSDL 要素の名前空間

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

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

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

サーバー要素

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	すべてのキャッシュは応答を保存できます。
プライベート	パブリック (共有) キャッシュは、応答が 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 ランタイムの設定に使用される要素は、名前空間 http://cxf.apache.org/transports/http-undertow/configuration で定義されています。Undertow 設定要素を使用するには、例12.14「Undertow ランタイム設定名前空間」にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。この例では、名前空間に接頭辞 httpu が割り当てられています。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.14 Undertow ランタイム設定名前空間

<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 の数を指定する、組み込み undertow とポートを持つグローバル IP アドレスを指定する host の 2 つの属性があります。

注記

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

各 httpu:engine 要素には、セキュリティープロパティーを設定する子と Undertow インスタンスのスレッドプールを設定する子の 2 つの子があります。設定の各タイプに対して、設定情報を直接提供するか、親 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 要素を使用して、スレッドプールのサイズを指定します。次に、tthreadingParametersRef 要素を使用して要素を参照します。
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 ハンドラーを設定するための属性
属性	説明
`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 ランタイムの設定に使用される要素は、名前空間 http://cxf.apache.org/transports/http-netty-server/configuration で定義されています。通常、接頭辞 httpn を使用して参照されます。Netty 設定要素を使用するには、例12.17「Netty ランタイム設定名前空間」にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.17 Netty ランタイム設定名前空間

<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 ランタイムを設定するために使用されるルート要素です。1 つの必須属性 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 要素を使用して、スレッドプールのサイズを指定します。次に、tthreadingParametersRef 要素を使用して要素を参照します。
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 応答をコンシューマーに送信します。その後、リクエストを処理し、新しい分離された server→client HTTP 接続を使用して応答をコンシューマーに送信します。コンシューマーランタイムは着信応答を受信し、アプリケーションコードに戻る前に、それを適切な要求と関連付けます。

分離された対話の設定

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

WS-Addressing を使用するようにコンシューマーを設定します。
「WS-Addressing を使用するためのエンドポイントの設定」を参照してください。
分離されたエンドポイントを使用するようにコンシューマーを設定します。
「コンシューマーの設定」を参照してください。
WS-Addressing を使用するためにコンシューマーが対話するサービスプロバイダーを設定します。
「WS-Addressing を使用するためのエンドポイントの設定」を参照してください。

WS-Addressing を使用するためのエンドポイントの設定

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

エンドポイントが WS-Addressing を使用するように指定するには、次の 2 つの方法のいずれかを使用します。

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

例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 トランスポートのメッセージフロー

切り離されたメッセージエクスチェンジには、fifteen のステップがあります。

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

コンシューマーの実装は操作を呼び出し、リクエストメッセージが生成されます。
WS-Addressing レイヤーは WS-A ヘッダーをメッセージに追加します。
分離されたエンドポイントがコンシューマーの設定に指定されると、切り離されたエンドポイントのアドレスは WS-A ReplyTo ヘッダーに配置されます。
メッセージはサービスプロバイダーに送信されます。
サービスプロバイダーはメッセージを受信します。
コンシューマーからの要求メッセージは、プロバイダーの WS-A レイヤーにディスパッチされます。
WS-A ReplyTo ヘッダーは anonymous に設定されていないため、プロバイダーは HTTP ステータスコードが 202 に設定されたメッセージを返信し、リクエストが受信されたことを承認します。
HTTP レイヤーは、元の接続のバックチャネルを使用して 202 Accepted メッセージをコンシューマーに送信します。
コンシューマーは、元のメッセージの送信に使用する HTTP 接続のバックチャネルで 202 Accepted 応答を受け取ります。
コンシューマーが 202 Accepted 応答を受け取ると、HTTP 接続を閉じます。
要求は、要求が処理されるサービスプロバイダーの実装に渡されます。
応答の準備ができると、WS-A 層にディスパッチされます。
WS-A レイヤーは、WS-Addressing ヘッダーを応答メッセージに追加します。
HTTP トランスポートは、コンシューマーの分離されたエンドポイントに応答を送信します。
コンシューマーの分離されたエンドポイントは、サービスプロバイダーからの応答を受信します。
レスポンスはコンシューマーの WS-A レイヤーにディスパッチされ、WS-A RelatesTo ヘッダーを使用して適切なリクエストに相関します。
相関応答がクライアント実装に返され、呼び出し呼び出しのブロックが解除されます。

第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 プロトコルは、World Wide Web Consortium (W3C) によって、ほとんどのサービスで使用される通常の SOAP/HTTP プロトコルにさらに信頼性の高いトランスポート層を提供する方法として定義されています。Apache CXF の実装は仕様に完全に準拠しており、準拠しているすべてのフレームワークと互換性がある必要があります。

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

SOAP/JMS トランスポートを使用するには:

トランスポートタイプが SOAP/JMS であることを指定します。
JMS URI を使用してターゲット宛先を指定します。
必要に応じて、JNDI 接続を設定します。
オプションで、JMS 設定を追加します。

JMS トランスポートタイプの指定

WSDL バインディングを指定するときに JMS トランスポートを使用するように SOAP バインディングを設定します。soap:binding 要素の トランスポート 属性を 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 エンドポイントは、URI Scheme for JMS 1.0 で定義されている 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 トランスポートを設定するためのいくつかの方法を提供します。

「JMS URI」
「WSDL 拡張機能」

13.2. JMS URI

概要

SOAP/JMS を使用する場合、JMS URI を使用してエンドポイントのターゲット宛先を指定します。URI に 1 つ以上のオプションを追加すると、JMS 接続の設定に JMS URI を使用することもできます。これらのオプションは、IETF 標準、URI Scheme for Java Message Service 1.0 で説明されています。これらを使用して、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`	[CXF3.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 の接頭辞として使用するかどうかを指定します。すべての Conduits に一意の UUID が割り当てられているため、このプロパティーを `true` に設定すると、複数のエンドポイントが JMS キューまたはトピックを共有できます。
`username`		[オプション] 接続の作成に使用するユーザー名を指定します。

JNDI プロパティー

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

表13.3 URI オプションとして設定可能な JNDI プロパティー
プロパティー	説明
`jndiConnectionFactoryName`	JMS 接続ファクトリーの JNDI 名を指定します。
`jndiInitialContextFactory`	JNDI プロバイダーの完全修飾クラス名を指定します (`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 プロバイダーがまだ設定されていない場合は、オプションを使用して URI で必要な JNDI 設定の詳細を提供できます (表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 extension 要素」は、JMS トランスポートの設定に使用できる WSDL 拡張要素すべてを示しています。

表13.4 SOAP/JMS WSDL extension 要素
要素	デフォルト	説明
`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 要素の親は、設定が配置されるスコープを次のスコープのどれに決定するかを決定します。

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

例

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

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

<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「SOAP/JMS 設定との WSDL コントラクト」の WSDL は以下を行います。

SOAP/JMS エクステンションの namespace を宣言します。

バインディングスコープで JNDI 接続を設定します。

JMS 配信スタイルを非永続に設定し、各メッセージを 1 分間存続させます。

ターゲットの宛先を指定します。

応答メッセージが greeterReply.queue キューで配信されるように JMS トランスポートを設定します。

第14章汎用 JMS の使用

概要

Apache CXF は、JMS トランスポートの汎用実装を提供します。一般的な JMS トランスポートは、SOAP メッセージの使用に制限されておらず、JMS を使用する任意のアプリケーションに接続できます。

14.1. JMS を設定するためのアプローチ

Apache CXF 汎用 JMS トランスポートは JMS プロバイダーに接続し、JMS メッセージを TextMessage または ByteMessage のいずれかのボディーで交換するアプリケーションと動作します。

JMS トランスポートを有効にして設定するには、次の 2 つの方法があります。

「JMS 設定 Bean の使用」
「WSDL を使用した JMS の設定」

14.2. JMS 設定 Bean の使用

概要

JMS 設定を簡素化し、より強力にするために、Apache CXF は単一の JMS 設定 Bean を使用して JMS エンドポイントを設定します。Bean は org.apache.cxf.transport.jms.JMSConfiguration クラスによって実装されます。エンドポイントを直接設定したり、JMS コンジットと宛先を設定するために使用できます。

設定名前空間

JMS 設定 Bean は、Spring p-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 に依存しなくなったため、SpringJMS 関連のオプションの一部が削除されました。

表14.1「一般的な JMS 設定プロパティー」プロバイダーとコンシューマーの両方に共通するプロパティーを一覧表示します。

表14.1 一般的な JMS 設定プロパティー
プロパティー	デフォルト	説明
`connectionFactory`		[必須] JMSConnectionFactory を定義する Bean への参照を指定します。
`wrapInSingleConnectionFactory`	`true` [pre v3.0]	CXF3.0 で削除 pre CXF 3.0 では、ConnectionFactory を Spring `SingleConnectionFactory` でラップするかどうかを指定します。 JMS トランスポートのパフォーマンスを向上するため、接続をプールしない ConnectionFactory を使用する場合は、このプロパティーを有効にします。これは、JMS トランスポートが各メッセージの新しい接続を作成し、`SingleConnectionFactory` が接続のキャッシュに必要なため、再利用できるためです。
`reconnectOnException`	`false`	CXF 3.0 で非推奨 CXF は、例外が発生したときに常に再接続します。以前の CXF3.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`	CXF3.0 で削除 CXF3.0 より前の SpringTaskExecutor への参照を指定します。これは、受信メッセージの処理方法を決定するためにリスナーで使用されます。
`useJms11`	`false`	CXF3.0 で削除 CXF3.0 は JMS1.1 機能のみをサポートします。 CXF 3.0 より前 JMS 1.1 機能が使用されるかどうかを指定します。有効な値は以下のとおりです。 `true` - JMS 1.1 機能 `false` - JMS 1.0.2 機能
`messageIdEnabled`	`true`	CXF3.0 で削除 CXF 3.0 より前は、JMS トランスポートが JMS ブローカーにメッセージ ID を提供するかどうかを指定します。有効な値は以下のとおりです。 `true` - ブローカーはメッセージ ID を提供する必要があります。 `false` - ブローカーはメッセージ ID を提供する必要がありません。この場合、エンドポイントはメッセージプロデューサーの `setDisableMessageID()` メソッドを `true` の値で呼び出します。その後、ブローカーはメッセージ ID を生成したりエンドポイントのメッセージに追加したりする必要がないヒントを提供します。ブローカーはヒントを受け入れるか、無視します。
`messageTimestampEnabled`	`true`	CXF3.0 で削除 CXF 3.0 JMS トランスポートが JMS ブローカーにメッセージタイムスタンプを提供するかどうかを指定します。有効な値は以下のとおりです。 `true` - ブローカーはメッセージのタイムスタンプを提供する必要があります。 `false` - ブローカーはメッセージのタイムスタンプを提供する必要はありません。この場合、エンドポイントはメッセージプロデューサーの `setDisableMessageTimestamp()` メソッドを `true` の値で呼び出します。その後、ブローカーはタイムスタンプを生成したり、エンドポイントのメッセージに追加したりする必要がないヒントを提供します。ブローカーはヒントを受け入れるか、無視します。
`cacheLevel`	`-1` (機能の無効化)	CXF3.0 で削除 CXF 3.0 より前 JMS リスナーコンテナーが適用されるキャッシングのレベルを指定します。有効な値は以下のとおりです。 `0` - CACHE_NONE `1` - CACHE_CONNECTION `2` - CACHE_SESSION `3` - CACHE_CONSUMER `4` — CACHE_AUTO 詳細は、ClassDefaultMessageListenerContainer を参照してください。
`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`	CXF3.0 で削除 CXF 3.0 より前リスナーの同時コンシューマーの最小数を指定します。
`maxConcurrentConsumers`	`1`	CXF3.0 で削除 CXF 3.0 より前リスナーの同時コンシューマーの最大数を指定します。
`messageSelector`		受信メッセージのフィルターに使用するセレクターの文字列値を指定します。このプロパティーにより、複数の接続でキューを共有できます。メッセージセレクターを指定するために使用される構文の詳細については、JMS1.1 仕様を参照してください。
`subscriptionDurable`	`false`	サーバーが永続サブスクリプションを使用するかどうかを指定します。
`durableSubscriptionName`		永続サブスクリプションの登録に使用される名前 (文字列) を指定します。
`messageType`	`text`	メッセージデータを JMS メッセージとしてパッケージ化する方法を指定します。有効な値は以下のとおりです。 `text` - データが `TextMessage` としてパッケージ化されることを指定します。 `byte` AsyncResult-AsyncResultspecifies は、データがバイトの配列 (`byte[]`) としてパッケージ化されるように指定します。 `binary` AsyncResult-AsyncResultspecifies は、データが `ByteMessage` としてパッケージ化されることを示します。
`pubSubDomain`	`false`	ターゲットの宛先がトピックであるかキューであるかを指定します。有効な値は以下のとおりです。 `true` - トピック `false` - キュー
`jmsProviderTibcoEms`	`false`	JMS プロバイダーが TibcoEMS であるかどうかを指定します。 `true` に設定すると、セキュリティーコンテキストのプリンシパルが `JMS_TIBCO_SENDER` ヘッダーから入力されます。
`useMessageIDAsCorrelationID`	`false`	CXF3.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 機能メカニズムを使用してサーバーとクライアントエンドポイントの両方に直接適用できます。これを行うには、以下を行います。

エンドポイントの address 属性を jms:// に設定します。
jaxws:feature 要素をエンドポイントの設定に追加します。
org.apache.cxf.transport.jms.JMSConfigFeature タイプの Bean を機能に追加します。
bean 要素の p:jmsConfig-ref 属性を JMSConfiguration Bean の ID に設定します。

例14.3「JAX-WS クライアントに JMS 設定を追加」は、例14.2「JMS 設定 Bean」からの JMS 設定を使用する JAX-WS クライアントを示しています。

例14.3 JAX-WS クライアントに JMS 設定を追加

<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 は、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 プロデューサーを作成します。これは、session および producer オブジェクトがスレッドセーフであるためです。プロデューサーの作成には、サーバーと通信する必要があるため、特に時間がかかります。

接続ファクトリーのプールは、接続、セッション、およびプロデューサーをキャッシュすることでパフォーマンスを向上します。

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 トランザクションガイドの付録 AJMS シングルおよびマルチリソーストランザクションのパフォーマンスの最適化を参照してください。

同期受信の回避

要求/応答交換の場合、JMS トランスポートは要求を送信してから応答を待ちます。可能な場合は、JMS MessageListener を使用してリクエスト/リプライメッセージングが非同期に実装されます。

ただし、エンドポイント間でキューを共有する必要がある場合は、CXF は同期 Consumer.receive() メソッドを使用する必要があります。このシナリオでは、MessageListener がメッセージセレクターを使用してメッセージをフィルターする必要があります。メッセージセレクターは事前に認識される必要があるため、MessageListener は一度だけ開かれます。

メッセージセレクターを事前に知ることができない 2 つのケースは避ける必要があります。

JMSMessageID が JMSCorrelationID として使用される場合
JMS プロパティーが useConduitIdSelector および conduitSelectorPrefix が JMS トランスポートに設定されていない場合、クライアントは JMSCorrelationId を設定しません。これにより、サーバーは JMSCorrelationId としてリクエストメッセージの JMSMessageId を使用します。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 トランザクションガイドを参照してください。

JTA トランザクション

JTA トランザクションを使用すると、任意の数の XA リソースを調整できます。CXF エンドポイントが JTA トランザクション用に設定されている場合、サービス実装を呼び出す前にトランザクションを開始します。例外が発生しなければ、トランザクションはコミットされます。それ以外の場合は、ロールバックされます。

JTA トランザクションでは、JMS メッセージが消費され、データがデータベースに書き込まれます。例外が発生すると、両方のリソースがロールバックされるため、メッセージが消費されてデータがデータベースに書き込まれるか、メッセージがロールバックされてデータがデータベースに書き込まれません。

JTA トランザクションの設定には、次の 2 つの手順が必要です。

トランザクションマネージャーの定義
- Bean メソッド
  - トランザクションマネージャーの定義
    <bean id="transactionManager" class="org.apache.geronimo.transaction.manager.GeronimoTransactionManager"/>
  - JMS URI でトランザクションマネージャーの名前を設定します
    jms:queue:myqueue?jndiTransactionManager=TransactionManager
    この例では、ID TransactionManager の Bean を検索します。
- OSGi 参照方法
  - ブループリントを使用して、トランザクションマネージャーを OSGi サービスとして検索します
    <reference id="TransactionManager" interface="javax.transaction.TransactionManager"/>
  - JMS URI でトランザクションマネージャーの名前を設定します
    jms:jndi:myqueue?jndiTransactionManager=java:comp/env/TransactionManager
    この例では、JNDI でトランザクションマネージャーを検索します。
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 Extension Namespance

JMS エンドポイントを定義するための WSDL 拡張機能は、名前空間 http://cxf.apache.org/transports/jms で定義されています。JMS 拡張機能を使用するには、例14.5「JMS WSDL 拡張名前空間」に示す行をコントラクトの定義要素に追加する必要があります。

例14.5 JMS WSDL 拡張名前空間

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 要素には、name と value の 2 つの属性があります。name は設定するプロパティーの名前を指定します。value 属性は、指定されたプロパティーの値を指定します。JMS:JMSNamingProperties 要素は、プロバイダー固有のプロパティーの仕様にも使用できます。

以下は、設定可能な一般的な JNDI プロパティーの一覧です。

java.naming.factory.initial
java.naming.provider.url
java.naming.factory.object
java.naming.factory.state
java.naming.factory.url.pkgs
java.naming.dns.url
java.naming.authoritative
java.naming.batchsize
java.naming.referral
java.naming.security.protocol
java.naming.security.authentication
java.naming.security.principal
java.naming.security.credentials
java.naming.language
java.naming.applet

これらの属性で使用する情報の詳細については、JNDI プロバイダーのドキュメントを確認し、JavaAPI リファレンス資料を参照してください。

例

例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`	使用するメッセージセレクターの文字列値を指定します。メッセージセレクターを指定するために使用される構文の詳細については、JMS1.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 設定の一部として返信を送信するために使用されるキューを設定できます。

応答先名の設定

エンドポイントの JMS 設定の jmsReplyDestinationName 属性または jndiReplyDestinationName 属性のいずれかを使用して、応答宛先を指定します。クライアントエンドポイントは、指定された宛先で応答をリッスンし、すべての送信要求の ReplyTo フィールドに属性の値を指定します。サービスエンドポイントは、リクエストの jndiReplyDestinationName フィールドに宛先が指定されていない場合に、応答の送信先として ReplyTo 属性の値を使用します。

例

例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 プロバイダーを設定する必要はありません。

The initial context factory

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 名 ConnectionFactory を ActiveMQConnectionFactory インスタンスにマッピングします。例15.2「Apache ActiveMQ 接続ファクトリーを指定する SOAP/JMS WSDL」 ApacheActiveMQ 接続ファクトリーを指定するための 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 name greeter.request.queue にバインドします。

第16章コンジット

概要

コンジットは、アウトバウンド接続を実装するために使用されるトランスポートアーキテクチャーの低レベルの部分です。それらの動作とライフサイクルは、システムのパフォーマンスと処理負荷に影響を与える可能性があります。

概要

コンジットは、Apache CXF ランタイムでクライアント側またはアウトバウンドのトランスポートの詳細を管理します。これらは、ポートのオープン、アウトバウンド接続の確立、メッセージの送信、およびアプリケーションと単一の外部エンドポイント間の応答のリッスンを担当します。アプリケーションが複数のエンドポイントに接続する場合、エンドポイントごとに 1 つのコンジットインスタンスがあります。

各トランスポートタイプは、コンジットインターフェイスを使用して独自のコンジットを実装します。これにより、アプリケーションレベルの機能とトランスポート間の標準化されたインターフェイスが可能になります。

一般に、クライアント側のトランスポートの詳細を設定するときに、アプリケーションで使用されているコンジットについてのみ心配する必要があります。ランタイムがコンジットを処理する方法の基本的なセマンティクスは、一般に、開発者が心配する必要のあるものではありません。

ただし、コンジットを理解することが役立つ場合があります。

カスタムトランスポートの実装
限られたリソースを管理するための高度なアプリケーションチューニング

コンジットのライフサイクル

コンジットは、クライアント実装オブジェクトによって管理されます。作成されると、コンジットはクライアント実装オブジェクトの期間中存続します。コンジットのライフサイクルは次のとおりです。

クライアント実装オブジェクトが作成されると、ConduitSelector オブジェクトへの参照が付与されます。
クライアントがメッセージを送信する必要がある場合は、コンジットセレクターからのコンジットへのリクエストの参照です。
メッセージが新しいエンドポイントに対するものである場合、コンジットセレクターは新しいコンジットを作成し、それをクライアント実装に渡します。それ以外の場合は、ターゲットエンドポイントのコンジットへの参照をクライアントに渡します。
コンジットは、必要に応じてメッセージを送信します。
クライアント実装オブジェクトが破棄されると、それに関連付けられているすべてのコンジットが破棄されます。

コンジットの重み

コンジットオブジェクトの重みは、トランスポートの実装によって異なります。HTTP コンジットは非常に軽量です。JMS コンジットは、JMS Session オブジェクトと 1 つ以上の JMSListenerContainer オブジェクトに関連付けられるため重くなります。

パート IV. Web サービスエンドポイントの設定

このガイドでは、Red Hat Fuse で Apache CXF エンドポイントを作成する方法について説明します。

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

概要

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

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

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

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

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

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

「jaxws:endpoint 要素の使用」
「jaxws:server 要素の使用」

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

17.1.2. jaxws:endpoint 要素の使用

概要

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

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

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

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

serviceName 属性と endpointName 属性との組み合わせ
serviceName 属性は、サービスのエンドポイントを定義する wsdl:service 要素を指定します。endpointName 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素を指定します。どちらの属性も、ns:name の形式で QNames として指定されます。ns は要素の namespace で、name は要素の name 属性の値です。
注記
wsdl:service 要素に wsdl:port 要素が 1 つしかない場合は、endpointName 属性を省略できます。
name 属性
name 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素の QName を指定します。QName は、{ns}localPart の形式で提供されます。ns は wsdl:port 要素の namespace で、localPart は wsdl:port 要素の name 属性の値です。

属性

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

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

表17.1 jaxws:endpoint 要素を使用して JAX-WS サービスプロバイダーを設定するための属性
属性	説明
`id`	他の設定要素がエンドポイントを参照するのに使用できる一意の識別子を指定します。
`implementor`	サービスを実装するクラスを指定します。実装クラスを設定する Spring Bean へのクラス名または ID 参照のいずれかを使用して、実装クラスを指定できます。このクラスはクラスパス上にある必要があります。
`implementorClass`	サービスを実装するクラスを指定します。この属性は、`implementor` 属性に指定された値が Spring AOP を使用してラップされる Bean への参照である場合に便利です。
`address`	HTTP エンドポイントのアドレスを指定します。この値は、サービスコントラクトで指定された値を上書きします。
`wsdlLocation`	エンドポイントの WSDL コントラクトの場所を指定します。WSDL コントラクトの場所は、サービスのデプロイ元のフォルダーを基準にしています。
`endpointName`	サービスの `wsdl:port` 要素の `name` 属性値を指定します。これは、`ns:name` 形式を使用して QName として指定されます。ここで、ns は `wsdl:port` 要素の namespace です。
`serviceName`	サービスの `wsdl:service` 要素の `name` 属性値を指定します。これは、`ns:name` 形式を使用して QName として指定されます。ここで、ns は `wsdl:service` 要素の namespace になります。
`publish`	サービスを自動的に公開するかどうかを指定します。これを `false` に設定すると、開発者は 31章サービスの公開に記載されているようにエンドポイントを明示的にパブリッシュする必要があります。
`bus`	サービスエンドポイントの管理に使用されるバスを設定する Spring Bean の ID を指定します。これは、共通の機能セットを使用するように複数のエンドポイントを設定する場合に役立ちます。
`bindingUri`	サービスが使用するメッセージバインディングの ID を指定します。有効なバインディング ID のリストは、23章Apache CXF バインディング ID に提供されています。
`name`	サービスの `wsdl:port` 要素の文字列化した QName を指定します。これは、`{ns}localPart` 形式を使用して QName として指定されます。ns は `wsdl:port` 要素の namespace で、localPart は `wsdl:port` 要素の `name` 属性の値です。
`abstract`	Bean が抽象 Bean であるかどうかを指定します。抽象 Bean は、具体的な Bean 定義の親として機能し、インスタンス化されません。デフォルトは `false` です。これを `true` に設定すると、Bean ファクトリーが Bean をインスタンス化しないように指示します。
`depends-on`	インスタンス化する前にエンドポイントがインスタンス化に依存する Bean のリストを指定します。
`createdFromAPI`	ユーザーが、`Endpoint.publish()` または `Service.getPort()` などの Apache CXF API を使用してその Bean を作成したことを指定します。デフォルトは `false` です。これを `true` に設定すると以下を行います。 `.jaxws-endpoint` を ID に追加して Bean の内部名を変更する Bean を抽象化します
`publishedEndpointUrl`	生成された WSDL の `address` 要素に配置される URL。この値が指定されない場合、`address` 属性の値が使用されます。この属性は、パブリック URL がサービスがデプロイされている URL と同じでない場合に役立ちます。

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

例

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

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

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

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

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

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

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

</beans>

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

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

Apache CXF 用の HTTP/2 の設定

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

注記

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

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

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

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

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

</beans>

注記

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

17.1.3. jaxws:server 要素の使用

概要

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

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

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

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

serviceName 属性と endpointName 属性との組み合わせ
serviceName 属性は、サービスのエンドポイントを定義する wsdl:service 要素を指定します。endpointName 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素を指定します。どちらの属性も、ns:name の形式で QNames として指定されます。ns は要素の namespace で、name は要素の name 属性の値です。
注記
wsdl:service 要素に wsdl:port 要素が 1 つしかない場合は、endpointName 属性を省略できます。
name 属性
name 属性は、サービスのエンドポイントを定義する特定の wsdl:port 要素の QName を指定します。QName は、{ns}localPart の形式で提供されます。ns は wsdl:port 要素の namespace で、localPart は wsdl:port 要素の name 属性の値です。

属性

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

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

表17.2 jaxws:server 要素を使用して JAX-WS サービスプロバイダーを設定するための属性
属性	説明
`id`	他の設定要素がエンドポイントを参照するのに使用できる一意の識別子を指定します。
`serviceBean`	サービスを実装するクラスを指定します。実装クラスを設定する Spring Bean へのクラス名または ID 参照のいずれかを使用して、実装クラスを指定できます。このクラスはクラスパス上にある必要があります。
`serviceClass`	サービスを実装するクラスを指定します。この属性は、`implementor` 属性に指定された値が Spring AOP を使用してラップされる Bean への参照である場合に便利です。
`address`	HTTP エンドポイントのアドレスを指定します。この値は、サービスコントラクトで指定された値を上書きします。
`wsdlLocation`	エンドポイントの WSDL コントラクトの場所を指定します。WSDL コントラクトの場所は、サービスのデプロイ元のフォルダーを基準にしています。
`endpointName`	サービスの `wsdl:port` 要素の `name` 属性値を指定します。これは、`ns:name` 形式を使用して QName として指定されます。ここで、ns は `wsdl:port` 要素の namespace になります。
`serviceName`	サービスの `wsdl:service` 要素の `name` 属性値を指定します。これは、`ns:name` 形式を使用して QName として指定されます。ここで、ns は `wsdl:service` 要素の namespace になります。
`publish`	サービスを自動的に公開するかどうかを指定します。これを `false` に設定すると、開発者は 31章サービスの公開に記載されているようにエンドポイントを明示的にパブリッシュする必要があります。
`bus`	サービスエンドポイントの管理に使用されるバスを設定する Spring Bean の ID を指定します。これは、共通の機能セットを使用するように複数のエンドポイントを設定する場合に役立ちます。
`bindingId`	サービスが使用するメッセージバインディングの ID を指定します。有効なバインディング ID のリストは、23章Apache CXF バインディング ID に提供されています。
`name`	サービスの `wsdl:port` 要素の文字列化した QName を指定します。これは、`{ns}localPart` 形式を使用して QName として指定されます。ここで、ns は `wsdl:port` 要素の namespace であり、localPart は `wsdl:port` 要素の `name` 属性の値になります。
`abstract`	Bean が抽象 Bean であるかどうかを指定します。抽象 Bean は、具体的な Bean 定義の親として機能し、インスタンス化されません。デフォルトは `false` です。これを `true` に設定すると、Bean ファクトリーが Bean をインスタンス化しないように指示します。
`depends-on`	エンドポイントをインスタンス化する前に、エンドポイントがインスタンス化に依存する Bean のリストを指定します。
`createdFromAPI`	ユーザーが、`Endpoint.publish()` または `Service.getPort()` などの Apache CXF API を使用してその Bean を作成したことを指定します。デフォルトは `false` です。これを `true` に設定すると以下を行います。 `.jaxws-endpoint` を ID に追加して Bean の内部名を変更する Bean を抽象化します

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

例

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

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

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

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

概要

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

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

19章Apache CXF ロギング
59章インターセプターを使用するためのエンドポイントの設定
20章WS-Addressing のデプロイ
21章信頼性の高いメッセージングの有効化
「JAX-WS エンドポイントでスキーマ検証を有効にする」

要素

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

表17.3 JAX-WS サービスプロバイダーの設定に使用される要素
要素	説明
`jaxws:handlers`	メッセージを処理するための JAX-WS ハンドラー実装のリストを指定します。JAX-WS ハンドラーの実装の詳細は、43章ハンドラーの作成を参照してください。
`jaxws:inInterceptors`	インバウンド要求を処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」を参照してください。
`jaxws:inFaultInterceptors`	インバウンド障害メッセージを処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」を参照してください。
`jaxws:outInterceptors`	アウトバウンド応答を処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」を参照してください。
`jaxws:outFaultInterceptors`	アウトバウンド障害メッセージを処理するインターセプターのリストを指定します。詳細は、パートVII「Apache CXF インターセプターの開発」を参照してください。
`jaxws:binding`	エンドポイントが使用するメッセージバインディングを設定する Bean を指定します。メッセージバインディングは、`org.apache.cxf.binding.BindingFactory` インターフェイスの実装を使用して設定されます。^[a]
`jaxws:dataBinding` ^[b]	エンドポイントで使用されるデータバインディングを実装するクラスを指定します。これは、埋め込み Bean 定義を使用して指定されます。
`jaxws:executor`	サービスに使用される Java エグゼキュータを指定します。これは、埋め込み Bean 定義を使用して指定されます。
`jaxws:features`	Apache CXF の高度な機能を設定する Bean のリストを指定します。Bean 参照のリストまたは埋め込み Bean のリストのいずれかを提供できます。
`jaxws:invoker`	サービスが使用する org.apache.cxf.service.Invoker インターフェイスの実装を指定します。^[c]
`jaxws:properties`	エンドポイントに渡されるプロパティーの Spring マップを指定します。これらのプロパティーを使用して、MTOM サポートの有効化などの機能を制御できます。
`jaxws:serviceFactory`	サービスのインスタンス化に使用される `JaxWsServiceFactoryBean` オブジェクトを設定する Bean を指定します。
^[a] SOAP バインディングは `soap:soapBinding` Bean を使用して設定されます。 ^[b] `jaxws:endpoint` 要素は `jaxws:dataBinding` 要素をサポートしません。 ^[c] Invoker 実装は、サービスの呼び出し方法を制御します。たとえば、各リクエストをサービス実装の新しいインスタンスで処理するかどうか、または呼び出し間で状態を保持するかどうかを制御します。

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

概要

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

例

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

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

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

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 として指定されます。ここで、ns は `wsdl:port` 要素の namespace になります。
`serviceName`	コンシューマーが要求するサービスの `wsdl:service` 要素の `name` 属性の値を指定します。これは、`ns:name` 形式を使用して QName として指定されます。ここで、ns は `wsdl:service` 要素の namespace になります。
`username`	単純なユーザー名/パスワード認証に使用されるユーザー名を指定します。
`password`	単純なユーザー名/パスワード認証に使用されるパスワードを指定します。
`serviceClass`	サービスエンドポイントインターフェイス (SEI) の名前を指定します。
`wsdlLocation`	エンドポイントの WSDL コントラクトの場所を指定します。WSDL コントラクトの場所は、クライアントのデプロイ元のフォルダーを基準にしています。
`name`	コンシューマーが要求するサービスの `wsdl:port` 要素の文字列化された QName を指定します。これは、`{ns}localPart` 形式を使用して QName として指定されます。ここで、ns は `wsdl:port` 要素の namespace であり、localPart は `wsdl:port` 要素の `name` 属性の値になります。
`abstract`	Bean が抽象 Bean であるかどうかを指定します。抽象 Bean は、具体的な Bean 定義の親として機能し、インスタンス化されません。デフォルトは `false` です。これを `true` に設定すると、Bean ファクトリーが Bean をインスタンス化しないように指示します。
`depends-on`	インスタンス化する前にエンドポイントがインスタンス化に依存する Bean のリストを指定します。
`createdFromAPI`	`Service.getPort()` などの Apache CXF API を使用して Bean を作成したユーザーを指定します。デフォルトは `false` です。これを `true` に設定すると以下を行います。 Bean の内部名を変更するには、`.jaxws-client` を id に追加します。 Bean を抽象化します

表17.4「JAX-WS コンシューマーの設定に使用する属性」に一覧表示される属性の他に、複数の xmlns:shortName 属性を使用して endpointName および serviceName 属性によって使用される namespace を宣言する必要がある場合があります。

機能の追加

コンシューマーに機能を追加したり、高度な設定を行うには、設定に子要素を追加する必要があります。

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

19章Apache CXF ロギング
59章インターセプターを使用するためのエンドポイントの設定
20章WS-Addressing のデプロイ
21章信頼性の高いメッセージングの有効化
「JAX-WS コンシューマーでのスキーマ検証の有効化」

表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 ハンドラー実装のリストを指定します。JAX-WS ハンドラーの実装に関する詳細は、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 サーバーエンドポイントを定義するには、少なくとも以下の項目を指定する必要があります。

XML でエンドポイントを定義するために使用される jaxrs:server 要素。jaxrs: namespace 接頭辞は、ブループリントと Spring の異なる名前空間にそれぞれマッピングされることに注意してください。
jaxrs:server 要素の address 属性を使用した JAX-RS サービスのベース URL。アドレス URL を指定する方法は 2 つあり、エンドポイントのデプロイ方法に影響を与えることに注意してください。
- 相対 URL(例: /customers)。この場合、エンドポイントはデフォルトの HTTP コンテナーにデプロイされ、エンドポイントのベース URL は、CXF サーブレットのベース URL と指定された相対 URL を組み合わせることによって暗黙的に取得されます。
  たとえば、JAX-RS エンドポイントを Fuse コンテナーにデプロイする場合、指定の /customers URL は URL http://Hostname:8181/cxf/customers に解決されます (コンテナーがデフォルトの 8181 ポートを使用していることを前提とします)。
- http://0.0.0.0:8200/cxf/customers のように、絶対 URL を指定 (例: ) として。この場合、JAX-RS エンドポイント用に新しい HTTP リスナーポートが開かれます (まだ開いていない場合)。たとえば、Fuse のコンテキストでは、JAX-RS エンドポイントをホストするために新しい Undertow コンテナーが暗黙的に作成されます。特別な IP アドレス 0.0.0.0 は、現在のホストに割り当てられたホスト名のいずれかに一致するワイルドカードとして機能します (マルチホームホストマシンで役に立ちます)。
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 名前空間

ブループリントで JAX-RS エンドポイントを定義するには、通常、少なくとも次の XML 名前空間が必要です。

接頭辞	Namespace
(デフォルト)	`http://www.osgi.org/xmlns/blueprint/v1.0.0`
`cxf`	`http://cxf.apache.org/blueprint/core`
`jaxrs`	`http://cxf.apache.org/blueprint/jaxrs`

Spring の例

以下の Spring XML の例は、相対アドレス /customers (デフォルトの HTTP コンテナーにデプロイされるように) を指定し、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 名前空間

Spring で JAX-RS エンドポイントを定義するには、通常、少なくとも次の XML 名前空間が必要です。

接頭辞	Namespace
(デフォルト)	`http://www.springframework.org/schema/beans`
`cxf`	`http://cxf.apache.org/core`
`jaxrs`	`http://cxf.apache.org/jaxrs`

Spring XML の自動検出

(Spring only) 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>

前述の例では、customerBean1 と customerBean2 の 2 つのリソース Bean を設定します。beanNames 属性は、リソース Bean ID のスペース区切りリストとして指定されます。

最終的な柔軟性を高めるために、jaxrs:serviceFactories 要素を使用して JAX-RS サーバーエンドポイントを設定する際に、サービスファクトリーオブジェクト を明示的に定義 することができます。このより冗長なアプローチには、デフォルトのサービスファクトリー実装をカスタム実装に置き換えることができるという利点があります。これにより、Bean のライフサイクルを最終的に制御できます。以下の例は、このアプローチを使用して、2 つのリソース Bean (customerBean1 と customerBean2) を設定する方法を示しています。

<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 によって一意に識別される必要があります。
Transport ID: JMS トランポートを選択するには、, the transportId 属性を http://cxf.apache.org/transports/jms に設定する必要があります。
JMS アドレス: jaxrs:server/@address 属性は標準化された構文を使用して、送信する JMS キューまたはトピックを指定します。この構文の詳細は、https://tools.ietf.org/id/draft-merrick-jms-uri-06.txt を参照してください。

拡張マッピングと言語マッピング

JAX-RS サーバーエンドポイントは、ファイル接尾辞 (URL に表示される) を MIME コンテンツタイプヘッダーに自動的にマップし、言語接尾辞を言語タイプヘッダーにマップするように設定できます。たとえば、次の形式の 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 のみ) JAX-RS ルートリソースクラスや JAX-RS プロバイダークラスを検出するために検索される Java パッケージのコンマ区切りリストを指定することにより、自動検出を有効にします。
`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 クライアントエンドポイントの定義

クライアントプロキシーの挿入

クライアントプロキシー Bean を XML 言語 (BlueprintXML または SpringXML) でインスタンス化する主なポイントは、別の Bean に挿入し、クライアントプロキシーを使用して REST サービスを呼び出すことができるようにすることです。XML でクライアントプロキシー Bean を作成するには、jaxrs:client 要素を使用します。

Namespaces

JAX-RS クライアントエンドポイントは、サーバーエンドポイントとは 異なる XML 名前空間を使用して定義されます。次の表は、どの XML 言語にどの名前空間を使用するかを示しています。

XML 言語	クライアントエンドポイントの namespace
ブループリント	`http://cxf.apache.org/blueprint/jaxrs-client`
Spring	`http://cxf.apache.org/jaxrs-client`

基本のクライアントエンドポイント定義

次の例は、BlueprintXML または SpringXML でクライアントプロキシー 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 サービスの説明を提供します。実際、これは server クラスですが、クライアントで直接使用されません。指定されたクラスは、クライアントプロキシーを動的に構築するのに使用されるメタデータ (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 Client Endpoint 属性」jaxrs:client 要素で利用可能な属性を説明します。

表18.3 JAX-RS Client Endpoint 属性
属性	説明
`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 Client Endpoint ポイントの子要素」に jaxrs:client 要素の子要素をまとめます。

表18.4 JAX-RS Client Endpoint ポイントの子要素
要素	説明
`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>

Namespaces

モデルスキーマの定義に使用する XML 名前空間は、対応する JAX-RS エンドポイントを Blueprint XML で定義するか Spring XML で定義するかによって異なります。次の表は、どの XML 言語にどの名前空間を使用するかを示しています。

XML 言語	Namespace
ブループリント	`http://cxf.apache.org/blueprint/jaxrs`
Spring	`http://cxf.apache.org/jaxrs`

モデルスキーマをエンドポイントにアタッチする方法

モデルスキーマを定義してエンドポイントにアタッチするには、次の手順を実行します。

選択したインジェクションプラットフォーム (Blueprint XML または Spring XML) に適切な XML 名前空間を使用して、モデルスキーマを定義します。
モデルスキーマファイルをプロジェクトのリソースに追加して、スキーマファイルが最終パッケージ (JAR、WAR、または OSGi バンドルファイル) のクラスパスで使用できるようにします。
注記
あるいは、エンドポイントの jaxrs:model 子要素を使用して、モデルスキーマを直接 JAX-RS エンドポイントに組み込むこともできます。
エンドポイントの modelRef 属性をクラスパス上のモデルスキーマの場所に設定し (クラスパス URL を使用)、モデルスキーマを使用するようにエンドポイントを設定します。
必要な場合は、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/xml` または `application/json`)。 +
`produces`	このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: `application/xml` または `application/json`)。 +

model/resource/operation

operation 要素は、メタデータを Java メソッドに関連付けるために使用されます。operation 要素に以下の属性を定義できます。

属性	説明 +
`name`	この要素が適用される Java メソッドの名前。 +
`path`	このメソッドにマップする REST URL パスのコンポーネント。この属性値には、パラメーターの参照を含めることができます (例: `path="/books/{id}/chapter"`)。ここで、`{id}` はパスから `id` パラメーターの値を抽出します。 +
`verb`	このメソッドにマップする HTTP 動詞を指定します。通常、`GET`、`POST`、`PUT`、または `DELETE` のいずれかです。HTTP の動詞が指定されていない場合、Java メソッドはサブリソースロケーターと考えられ、サブリソースオブジェクトへの参照を返します (サブリソースクラスにも `resource` 要素を使用してメタデータを指定する必要があります)。 +
`consumes`	この操作によって消費されるコンテンツタイプ (インターネットメディアタイプ) を指定します (例: `application/xml` や `application/json` )。 +
`produces`	この操作で生成されるコンテンツタイプ (インターネットメディアタイプ) を指定します (例:`application/xml` や `application/json`)。 +
`oneway`	`true` の場合、操作を一方向に設定します。つまり、リプライメッセージは不要になります。デフォルトは `false` です。 +

model/resource/operation/param

param 要素は、REST URL から値を抽出し、それをメソッドパラメーターのいずれかに注入するために使用されます。param 要素で以下の属性を定義できます。

属性	説明 +
`name`	この要素が適用される Java メソッドパラメーターの名前。 +
`type`	パラメーター値を REST URL またはメッセージから抽出する方法を指定します。`PATH`、`QUERY`、`MATRIX`、`HEADER`、`COOKIE`、`FORM`、`CONTEXT`、`REQUEST_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 サンプルアプリケーションでログレベルとログメッセージの出力先を変更するには、以下のステップを実行してください。

InstallDir/samples/wsdl_first ディレクトリーの README.txt ファイルの 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 &` +

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 ディレクトリーにあります。Apache CXF ロガーを設定し、WARNING レベルのログメッセージをコンソールに出力します。その結果、コンソールに印刷されるものはほとんどありません。

README.txt ファイルの説明に従ってサーバーを停止します。
デフォルトの logging.properties ファイルのコピーを作成します。名前が mylogging.properties ファイルになり、デフォルトの logging.properties ファイルと同じディレクトリーに保存します。
以下の設定行を編集して、mylogging.properties ファイルのグローバルロギングレベルおよびコンソールロギングレベルを INFO に変更します。
```
.level= INFO
java.util.logging.ConsoleHandler.level = INFO
```

次のコマンドを使用してサーバーを再起動します。

プラットフォームコマンド +

プラットフォーム	コマンド +
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 &` +

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 ディレクトリーにあります。Apache CXF ロガーを設定し、WARNING レベルのメッセージをコンソールに出力します。このレベルのログがアプリケーションに適している場合は、使用する前にファイルに変更を加える必要はありません。ただし、ログメッセージの詳細レベルを変更することはできます。たとえば、ログメッセージをコンソールに送信するか、ファイルに送信するか、またはその両方に送信するかを変更できます。さらに、個々のパッケージのレベルでロギングを指定できます。

注記

このセクションでは、デフォルトの logging.properties ファイルに表示される設定プロパティーを説明します。ただし、設定可能なその他の java.util.logging 設定プロパティーが多数あります。java.util.logging API の詳細は、http://download.oracle.com/javase/1.5/docs/api/java/util/logging/package-summary.html の java.util.logging を参照してください。

19.3.2. ロギング出力の設定

概要

Java ロギングユーティリティー java.util.logging は、ハンドラークラスを使用してログメッセージを出力します。表19.1「Java.util.logging Handler Classes」は、デフォルトの logging.properties ファイルで設定されるハンドラーを示しています。

表19.1 Java.util.logging Handler Classes
ハンドラークラス	への出力
`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
警告
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`	interceptors
`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 メッセージの内容をログに記録したい場合があります。

メッセージコンテンツロギングの設定

サービスとコンシューマーの間で送信されるメッセージをログに記録するには、またはその逆の場合は、次の手順を実行します。

エンドポイントの設定にログ機能を追加します。
ロギング機能をコンシューマーの設定に追加します。
ロギングシステムログ INFO レベルのメッセージを設定します。

エンドポイントへのロギング機能の追加

例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 サンプルアプリケーションを変更します。

例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>
```
この例では、InstallDir/etc ディレクトリーにあるデフォルトの logging.properties ファイルを使用します。このファイルのコピーを作成し、これに mylogging.properties という名前を付けます。
mylogging.properties ファイルで、以下のように java. level と java.util.logging.ConsoleHandler.level 設定プロパティーを編集して、ロギングレベルを INFO に変更します。
```
.level= INFO
java.util.logging.ConsoleHandler.level = INFO
```

以下のように 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 &

次のコマンドを使用して、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 の詳細は、http://www.w3.org/Submission/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`	メッセージアドレス指定プロパティー (MAPs) を SOAP ヘッダーとしてエンコードおよびデコードするプロトコル固有のインターセプター。

20.3. WS-Addressing の有効化

概要

WS-Addressing を有効にするには、WS-Addressing インターセプターをインバウンドおよびアウトバウンドインターセプターチェーンに追加する必要があります。これは、次のいずれかの方法で行われます。

Apache CXF の機能
RMAssertion と WS-Policy フレームワーク
WS-Addressing 機能でのポリシーアサーションの使用

機能としての 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 機能要素は、namespace http://cxf.apache.org/ws/addressing で定義されています。表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章信頼性の高いメッセージングの有効化

概要

Apache CXF は、WS-Reliable Messaging (WS-RM) をサポートしています。この章では、Apache CXF で WS-RM を有効にして設定する方法について説明します。

21.1. WS-RM の概要

概要

WS-ReliableMessaging (WS-RM) は、分散環境でのメッセージの信頼性の高い配信を保証するプロトコルです。これにより、ソフトウェア、システム、またはネットワークに障害が発生した場合でも、分散アプリケーション間でメッセージを確実に配信できます。

たとえば、WS-RM を使用すると、正しいメッセージがネットワークを介して 1 回だけ、正しい順序で配信されていることを確認できます。

WS-RM のしくみ

WS-RM は、送信元エンドポイントと宛先エンドポイント間のメッセージの信頼性の高い配信を保証します。図21.1「Web サービスの信頼できるメッセージング」に示すように、送信元はメッセージの最初の送信者であり、宛先は最終的な受信者です。

図21.1 Web サービスの信頼できるメッセージング

WS-RM メッセージのフローは、次のように説明できます。

RM ソースは CreateSequence プロトコルメッセージを RM 宛先に送信します。これには、確認応答を受け取るエンドポイント (wsrm:AcksTo エンドポイント) の参照が含まれます。
RM 宛先は CreateSequenceResponse プロトコルメッセージを RM ソースに戻します。このメッセージには、RM シーケンスセッションのシーケンス ID が含まれています。
RM ソースは、アプリケーションソースが送信する各メッセージに RM Sequence ヘッダーを追加します。このヘッダーには、シーケンス ID と一意のメッセージ ID が含まれています。
RM 送信元は、各メッセージを RM 宛先に送信します。
RM 宛先は、RM SequenceAcknowledgement ヘッダーが含まれるメッセージを送信し、RM ソースからメッセージの受信を認識します。
RM 宛先は、メッセージを 1 回限りの順序でアプリケーション宛先に配信します。
RM ソースは、確認応答をまだ受信していないというメッセージを再送信します。
最初の再送信の試行は、基本再送信間隔の後に行われます。連続した再送信の試行は、デフォルトで、指数バックオフ間隔で、または代わりに、固定間隔で行われます。詳細は、「WS-RM の設定」を参照してください。

このプロセス全体は、要求メッセージと応答メッセージの両方で対称的に発生します。つまり、応答メッセージの場合、サーバーは RM ソースとして機能し、クライアントは RM 宛先として機能します。

WS-RM 配信保証

WS-RM は、使用されるトランスポートプロトコルに関係なく、分散環境での信頼性の高いメッセージ配信を保証します。信頼できる配信が保証されない場合は、送信元エンドポイントまたは宛先エンドポイントのいずれかがエラーをログに記録します。

サポートされている仕様

Apache CXF は、次のバージョンの WS-RM 仕様をサポートしています。

WS-ReliableMessaging 1.0

(デフォルト) 2005 年 2 月の提出バージョンに対応しますが、現在は古くなっています。ただし、下位互換性のため、このバージョンがデフォルトとして使用されます。

WS-RM のバージョン 1.0 は、次の名前空間を使用します。

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 サービスの信頼できるメッセージング仕様に対応します。

WS-RM のバージョン 1.1 および 1.2 は、次の名前空間を使用します。

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-ReliableMessaging のバージョンに適応し、適切に応答します。
クライアント側の設定: クライアント側では、WS-RM バージョンは、クライアント設定で使用するネームスペースによって決定されます (「WS-RM の設定」を参照)。または、ランタイム制御オプションを使用して、実行時に WS-RM バージョンをオーバーライドする (「ランタイム制御」を参照)。

21.2. WS-RM インターセプター

概要

Apache CXF では、WS-RM 機能がインターセプターとして実装されます。Apache CXF ランタイムは、インターセプターを使用して、送受信されている生のメッセージを傍受して処理します。トランスポートはメッセージを受信すると、メッセージオブジェクトを作成し、そのメッセージをインターセプターチェーンを介して送信します。アプリケーションのインターセプターチェーンに WS-RM インターセプターが含まれている場合、アプリケーションは信頼性の高いメッセージングセッションに参加できます。WS-RM インターセプターは、メッセージチャンクの収集と集約を処理します。また、すべての確認応答および再送信ロジックを処理します。

Apache CXF -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`	アプリケーションメッセージに Piggy backed である RM プロトコルメッセージと `SequenceAcknowledgement` メッセージの傍受および処理を行います。
`org.apache.cxf.ws.rm.RMCaptureInInterceptor`	永続ストレージ用の着信メッセージのキャッシュ。
`org.apache.cxf.ws.rm.RMDeliveryInterceptor`	アプリケーションへのメッセージの InOrder 配信を保証します。
`org.apache.cxf.ws.rm.soap.RMSoapInterceptor`	信頼性プロパティーを SOAP ヘッダーとしてエンコードおよびデコードする責任があります。
`org.apache.cxf.ws.rm.RetransmissionInterceptor`	将来の再送信のためにアプリケーションメッセージのコピーを作成する責任があります。

WS-RM の有効化

インターセプターチェーンに WS-RM インターセプターが存在することで、必要に応じて WS-RM プロトコルメッセージが交換されます。たとえば、アウトバウンドインターセプターチェーンで最初のアプリケーションメッセージをインターセプトすると、 RMOutInterceptor は CreateSequence リクエストを送信し、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 インターセプターもインターセプターチェーンに存在する必要があります。

これらのインターセプターの存在を確認するには、次の 2 つの方法のいずれかを使用します。

明示的に、Spring beans を使用してディスパッチチェーンに追加します
暗黙的に、WS-Policy アサーションを使用します。これにより、Apache CXF ランタイムがユーザーに代わってインターセプターを透過的に追加します。

Spring beans: 明示的にインターセプターを追加する

WS-RM を有効にするには、WS-RM および WS-Addressing インターセプターを Apache CXF バス、または Spring bean 設定を使用するコンシューマーまたはサービスエンドポイントに追加します。これは、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 インターセプター - RMOutInterceptor、RMInInterceptor、および 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 サービスポリシー 1.5- フレームワークおよび Web サービスポリシー 1.5- 添付ファイルの仕様の 2006 年 11 月のドラフト公開に準拠しています。

Apache CXF WS-Policy フレームワークを使用して WS-RM を有効にするには、次の手順を実行します。

ポリシー機能をクライアントとサーバーのエンドポイントに追加します。例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>
```
例21.3「WSDL ファイルへの RM ポリシーの追加」に示すように、信頼できるメッセージングポリシーを wsdl:service 要素またはポリシー参照要素として使用できる他の WSDL 要素に追加します。
例21.3 WSDL ファイルへの RM ポリシーの追加

Apache CXF 開発ガイド

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

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

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

第1章 WSDL コントラクトの紹介

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

概要

論理部分

具体的な部分

1.2. WSDL 要素

1.3. コントラクトの設計

第2章 論理データ単位の定義

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

2.2. データを論理データ単位にマッピング

概要

サービスデータユニットを定義するのに利用可能な型システム

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

データユニットを作成する際の考慮事項

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

概要

手順

2.4. XML スキーマの単純型

概要

単純型の入力

サポートされている XSD 単純型

2.5. 複雑なデータ型の定義

2.5.1. データ構造の定義

概要

複合型の種類

構造の部分を定義

属性の定義

2.5.2. 配列の定義

概要

複合型配列

SOAP 配列

2.5.3. 拡張による型の定義

2.5.4. 制限によるタイプの定義

概要

基本型の指定

制限の定義

例

2.5.5. 列挙型の定義

概要

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

例

2.6. 要素の定義

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

概要

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

レガシーシステムと統合するためのメッセージデザイン

SOAP サービスのメッセージデザイン

メッセージの命名

メッセージ部分

例

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

概要

Process

ポートタイプ

操作

操作メッセージ

戻り値

例

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

第5章 WSDL のバインディングを理解

概要

ポートタイプとバインディング

WSDL 要素

コントラクトへの追加

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

第6章 SOAP1.1 メッセージの使用

6.1. SOAP1.1 バインディングの追加

wsdl2soap の使用

例

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

概要

構文

本文とヘッダーの間でメッセージを分割

例

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

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

第2章論理データ単位の定義

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

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

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