Apache CXF 開発ガイド

Red Hat Fuse 7.6

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

概要

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

パート 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 ドキュメントの論理部分には、typesmessage、および 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 コントラクトを設計するには、次の手順を実行する必要があります。

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

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

概要

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

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

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

  1. データを論理ユニットに分割し、サービスの物理的な実装で使用されるデータ型にマッピングできるようにする
  2. 操作を実行するためにエンドポイント間で渡されるメッセージに論理ユニットを結合する

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

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

概要

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

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

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

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

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

WSDL XML スキーマで使用される場合は、サービスとの対話に使用されるデータを保持する 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 コントラクトで使用されるデータの定義には、次の手順が含まれます。

  1. コントラクトで記述されているインターフェイスで使用されているすべてのデータ単位を判別します。
  2. コントラクトに types 要素を作成します。
  3. 例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/">
  4. 要素のコレクションである複合型ごとに、complexType 要素を使用してデータ型を定義します。「データ構造の定義」を参照してください。
  5. 各配列について、complexType 要素を使用してデータタイプを定義します。「配列の定義」 を参照してください。
  6. 単純型から派生する複合型ごとに、simpleType 要素を使用してデータ型を定義します。「制限によるタイプの定義」 を参照してください。
  7. 各列挙型について、simpleType 要素を使用してデータタイプを定義します。「列挙型の定義」を参照してください。
  8. 要素ごとに、element 要素を使用して定義します。「要素の定義」を参照してください。

2.4. XML スキーマの単純型

概要

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

単純型の入力

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

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

例2.2 単純型で要素の定義

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

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

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

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

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

概要

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

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

2.5.1. データ構造の定義

概要

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

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

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

例2.3 簡易構造

struct personalInfo
{
  string name;
  int age;
};

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

nametype 以外に、element 要素には、minOcurrsmaxOccurs の 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 要素は、allsequence、または choice 要素の後にのみ表示できます。複合型の属性ごとに attribute 要素を 1 つ指定します。attribute 要素は、complexType 要素の直接の子でなければなりません。

例2.8 属性を持つ複合型

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

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

  • name - 属性を識別する文字列を指定する必須属性。
  • type - フィールドに保存されたデータの型を指定します。タイプは、XML スキーマの単純型の 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 つの部分があります。

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

    注記

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

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

たとえば、alienInfo は、例2.13「拡張子で定義されたタイプ」 のように定義されます。

例2.13 拡張子で定義されたタイプ

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

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

概要

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

制限による型の定義には、次の 3 つのことが必要です。

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

基本型の指定

基本型は、新しいタイプを定義するために制限されているタイプです。これは restriction 要素を使用して指定されます。restriction 要素は simpleType 要素の唯一の子で、ベース型を指定する 1 つの属性 base を持ちます。基本型は、任意の XML スキーマの単純型にすることができます。

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

例2.14 基本型として int の使用

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

制限の定義

基本型に課せられた制限を定義するルールは、ファセット と呼ばれます。ファセットとは、ファセットの適用方法を定義する 1 つの属性 value を持つ要素です。利用可能なファセットとその有効な value 設定は、ベース型によって異なります。たとえば、xsd:string は、以下を含む 6 つのファセットをサポートします。

  • 長さ
  • 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 - ドキュメントから要素を完全に省略できるかどうかを指定します。nillabletrue に設定されている場合、要素はスキーマを使用して生成したドキュメントから省略できます。

要素は、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 コントラクトで論理インターフェイスを定義するには、以下を実行する必要があります。

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

ポートタイプ

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

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

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

操作

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

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

操作メッセージ

論理操作は、操作を実行するためにエンドポイント間で通信される論理メッセージを表す要素のセットで設定されます。操作を説明できる要素は、表4.1「操作メッセージ要素」 のとおりです。

表4.1 操作メッセージ要素

要素説明

input

要求が行われたときにクライアントエンドポイントがサービスプロバイダーに送信するメッセージを指定します。このメッセージの一部は、操作の入力パラメーターに対応しています。

output

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

fault

エンドポイント間でエラー状態を伝達するために使用されるメッセージを指定します。

操作は、少なくとも 1 つの input 要素または 1 つの output 要素を持つ必要があります。操作は 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

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

-i port-type-name および wsdlurl 引数が必要です。-style rpc 引数を指定すると、-n soap-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 要素は、バインディングの inputoutput、および fault 要素の任意の子です。SOAP ヘッダーは親メッセージの一部になります。SOAP ヘッダーは、メッセージとメッセージ部分を指定することによって定義されます。各 SOAP ヘッダーにはメッセージ部分を 1 つだけ含めることができますが、必要な数の SOAP ヘッダーを挿入できます。

構文

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

例6.3 SOAP ヘッダー構文

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

必須の messagepart 属性と同様に、soap:header は、namespaceuse、および encodingStyle 属性もサポートします。これらの属性は soap:body の場合と同様に soap:header でも機能します。

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

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

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

注記

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

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

例6.4 SOAP 1.1 SOAP ヘッダーを使用したバインド

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

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

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

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

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

例6.4「SOAP 1.1 SOAP ヘッダーを使用したバインド」 を変更して、ヘッダー値が入力メッセージと出力メッセージの一部になるようにします。

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

概要

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

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

wsdl2soap の使用

注記

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

wsdl2soap を使用して SOAP 1.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 要素は、バインディングの inputoutput、および fault 要素の任意の子です。SOAP ヘッダーは親メッセージの一部になります。SOAP ヘッダーは、メッセージとメッセージ部分を指定することによって定義されます。各 SOAP ヘッダーには 1 つのメッセージ部分しか含めることができませんが、必要な数のヘッダーを挿入できます。

構文

SOAP ヘッダーを定義するための構文を 例7.3「SOAP ヘッダー構文」 に示します。

例7.3 SOAP ヘッダー構文

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

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

表7.1 soap12:header 属性

属性説明

message

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

part

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

use

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

encodingStyle

メッセージの作成に使用されるエンコード規則を指定します。

namespace

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

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

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

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

注記

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

例7.4「SOAP ヘッダーを使用した 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 バインディングでは、inputoutput、および fault 要素の最初の子要素は、データを表す SOAP メッセージのボディーを記述する soap:body 要素です。添付ファイル付き SOAP を使用する場合、soap:body 要素は mime:multipartRelated 要素に置き換えられます。

注記

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

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

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

MIME マルチパートメッセージの説明

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

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

    注記

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

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

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

    表8.1 mime:content 属性

    属性説明

    part

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

    +

    type

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

    +

    image/jpeg および text/plain といった事前定義された MIME タイプは複数あります。MIME タイプは、Internet Assigned Numbers Authority (IANA) によって維持され、Multipurpose Internet Mail Extensions (MIME) パート 1: インターネットメッセージ本文Multipurpose Internet Mail Extensions (MIME) パート 2: メディアタイプ で詳細に説明されています。

    +

  6. 追加の 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 マルチパート/関連メッセージを完全に定義する必要はありません。ただし、次のことを行う必要があります。

  1. 添付ファイルとして送信するデータに 注釈 を付けます。

    データを実装する WSDL または Java クラスのいずれかに注釈を付けることができます。

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

    これは、プログラムで、または設定を通して行うことができます。

  3. 添付ファイルとして渡されるデータの 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 を準備できます。

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

例9.3「MTOM の JAXB クラス」 は、MTOM を使用するために注釈が付けられた JAXB クラスを示しています。

例9.3 MTOM の JAXB クラス

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

9.3. MTOM の有効化

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

9.3.1. JAX-WS API の使用

概要

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

Service provider

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

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

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

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

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

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

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

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

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

    binding.setMTOMEnabled(true);

コンシューマー

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

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

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

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

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

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

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

    binding.setMTOMEnabled(true);

9.3.2. 設定の使用

概要

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

手順

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

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

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

例9.8 MTOM の有効化設定

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

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

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

概要

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 ペイロードフォーマットにマッピングするには、以下を行います。

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

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

  7. オプションで、有効な rootNode 属性を持つ xformat:body 要素を、追加された inputoutput、および fault 要素に追加して、バインディングレベルで設定された rootNode の値をオーバーライドします。
注記

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

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

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

両問題を解決する簡単な方法は、グローバル xformat:binding 要素または個別のメッセージの xformat:body 要素のいずれかで、オプションの rootNode 属性を使用することです。rootNode 属性は、Apache CXF が生成した XML ドキュメントの 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 ランタイム実装をサポートします。

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

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 が、クレデンシャルを先制的に提供するように設定されている。
  • AutoRedirecttrue に設定されている。

いずれの場合も、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 つのメカニズムを使用して設定できます。

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 があります。

注記

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 スレッドプールを設定するための属性

属性説明

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>

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.16「Netty ランタイム設定名前空間」 にある行をエンドポイント設定ファイルの beans 要素に追加する必要があります。また、設定要素の namespace を xsi:schemaLocation 属性に追加する必要があります。

例12.16 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.10「Netty ランタイムファクトリーを設定するための要素」 で説明されています。

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

要素説明

httpn:engine

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

httpn:identifiedTLSServerParameters

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

httpn:identifiedThreadingParameters

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

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

engine 要素

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

表12.11 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.12「Netty ランタイムインスタンスを設定するための要素」 に表示されます。

表12.12 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.13「Netty スレッドプールを設定するための属性」 で説明されているようにスレッドプールのサイズを指定する 1 つの属性があります。

注記

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

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

属性説明

threadPoolSize

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

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

例12.17 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 トランスポートを使用するには、次のことを行う必要があります。

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

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

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

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

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

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

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

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

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

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

    例12.18 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.19「ポリシーを使用した WS-Addressing のアクティブ化」 に示されるように、WS-Addressing ポリシーをエンドポイントの WSDL port 要素に追加します。

    例12.19 ポリシーを使用した 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.20「結合された HTTP エンドポイントを使用するためのコンシューマーの設定」 は、例12.18「WSDL を使用した WS-Addressing のアクティブ化」 で定義されたエンドポイントを設定し、分離したエンドポイントを使用する設定を示しています。コンシューマーは http://widgetvendor.net/widgetSellerInbox ですべての応答を受け取るようになりました。

例12.20 結合された 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 のステップがあります。

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

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

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

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

    コンシューマーが 202 Accepted 応答を受け取ると、HTTP 接続を閉じます。

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

第13章 SOAP Over JMS の使用

概要

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

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

13.1. 基本設定

概要

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

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

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

  1. トランスポートタイプが SOAP/JMS であることを指定します。
  2. JMS URI を使用してターゲット宛先を指定します。
  3. 必要に応じて、JNDI 接続を設定します。
  4. オプションで、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 トランスポートを設定するためのいくつかの方法を提供します。

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 を使用する任意のアプリケーションに接続できます。

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

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

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

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

14.2. JMS 設定 Bean の使用

概要

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

設定名前空間

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 機能メカニズムを使用してサーバーとクライアントエンドポイントの両方に直接適用できます。これを行うには、以下を行います。

  1. エンドポイントの address 属性を jms:// に設定します。
  2. jaxws:feature 要素をエンドポイントの設定に追加します。
  3. org.apache.cxf.transport.jms.JMSConfigFeature タイプの Bean を機能に追加します。
  4. 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 つのケースは避ける必要があります。

  • JMSMessageIDJMSCorrelationID として使用される場合

    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 つの手順が必要です。

  1. トランザクションマネージャーの定義

    • 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 でトランザクションマネージャーを検索します。

  2. JCA プール接続ファクトリーの設定

    Spring を使用して JCA プールされた接続ファクトリーを定義します。

    <bean id="xacf" class="org.apache.activemq.ActiveMQXAConnectionFactory">
      <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>
    
    <bean id="ConnectionFactory" class="org.apache.activemq.jms.pool.JcaPooledConnectionFactory">
      <property name="transactionManager" ref="transactionManager" />
      <property name="connectionFactory" ref="xacf" />
    </bean>

    この例では、最初の Bean は JcaPooledConnectionFactory に指定される ActiveMQ XA 接続ファクトリーを定義します。JcaPooledConnectionFactory は id ConnectionFactory のデフォルトの Bean として提供されます。

    JcaPooledConnectionFactory は通常の ConnectionFactory のようになることに注意してください。ただし、新しい接続とセッションが開かれると、XA トランザクションがチェックされ、見つかった場合は、JMS セッションが XA リソースとして自動的に登録されます。これにより、JMS セッションが JMS トランザクションに参加できるようになります。

    重要

    JMS トランスポートに XA ConnectionFactory を直接設定することはできません。

14.5. WSDL を使用した JMS の設定

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

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

  1. java.naming.factory.initial
  2. java.naming.provider.url
  3. java.naming.factory.object
  4. java.naming.factory.state
  5. java.naming.factory.url.pkgs
  6. java.naming.dns.url
  7. java.naming.authoritative
  8. java.naming.batchsize
  9. java.naming.referral
  10. java.naming.security.protocol
  11. java.naming.security.authentication
  12. java.naming.security.principal
  13. java.naming.security.credentials
  14. java.naming.language
  15. java.naming.applet

これらの属性で使用する情報の詳細については、JNDI プロバイダーのドキュメントを確認し、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 名 ConnectionFactoryActiveMQConnectionFactory インスタンスにマッピングします。例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 つのコンジットインスタンスがあります。

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

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

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

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

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

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

  1. クライアント実装オブジェクトが作成されると、ConduitSelector オブジェクトへの参照が付与されます。
  2. クライアントがメッセージを送信する必要がある場合は、コンジットセレクターからのコンジットへのリクエストの参照です。

    メッセージが新しいエンドポイントに対するものである場合、コンジットセレクターは新しいコンジットを作成し、それをクライアント実装に渡します。それ以外の場合は、ターゲットエンドポイントのコンジットへの参照をクライアントに渡します。

  3. コンジットは、必要に応じてメッセージを送信します。
  4. クライアント実装オブジェクトが破棄されると、それに関連付けられているすべてのコンジットが破棄されます。

コンジットの重み

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

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

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

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

概要

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

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

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

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

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

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

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

17.1.2. jaxws:endpoint 要素の使用

概要

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

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

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

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

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

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

    注記

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

  • name 属性

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

属性

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

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

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

属性説明

id

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

implementor

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

implementorClass

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

address

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

wsdlLocation

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

endpointName

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

serviceName

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

publish

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

bus

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

bindingUri

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

name

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

abstract

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

depends-on

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

createdFromAPI

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

デフォルトは false です。

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

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

publishedEndpointUrl

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

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

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

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

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

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

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

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

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

</beans>

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

17.1.3. jaxws:server 要素の使用

概要

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

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

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

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

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

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

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

    注記

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

  • name 属性

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

属性

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

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

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

属性説明

id

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

serviceBean

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

serviceClass

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

address

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

wsdlLocation

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

endpointName

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

serviceName

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

publish

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

bus

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

bindingId

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

name

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

abstract

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

depends-on

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

createdFromAPI

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

デフォルトは false です。

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

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

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

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

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

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

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

概要

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

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

要素

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

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

要素説明

jaxws:handlers

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

jaxws:inInterceptors

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

jaxws:inFaultInterceptors

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

jaxws:outInterceptors

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

jaxws:outFaultInterceptors

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

jaxws:binding

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

jaxws:dataBinding [b]

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

jaxws:executor

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

jaxws:features

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

jaxws:invoker

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

jaxws:properties

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

jaxws:serviceFactory

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

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

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

概要

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

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

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

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

17.2. コンシューマーエンドポイントの設定

概要

JAX-WS コンシューマーエンドポイントは、jaxws:client 要素を使用して設定されます。要素の属性は、コンシューマーを作成するために必要な基本情報を提供します。

WS-RM などのその他の機能をコンシューマーに追加するには、子を jaxws:client 要素に追加します。子要素は、エンドポイントのログ動作を設定したり、エンドポイントの実装に他のプロパティーを挿入したりするためにも使用されます。

基本的な設定プロパティー

表17.4「JAX-WS コンシューマーの設定に使用する属性」 で説明されている属性は、JAX-WS コンシューマーの設定に必要な基本情報を提供します。設定する特定のプロパティーの値のみを指定する必要があります。ほとんどのプロパティーには適切なデフォルトがあるか、エンドポイントのコントラクトによって提供される情報に依存しています。

表17.4 JAX-WS コンシューマーの設定に使用する属性

属性説明

address

コンシューマーが要求を行うエンドポイントの HTTP アドレスを指定します。この値は、コントラクトで設定された値を上書きします。

bindingId

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

bus

エンドポイントを管理するバスを設定する Spring Bean の ID を指定します。

endpointName

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

serviceName

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

username

単純なユーザー名/パスワード認証に使用されるユーザー名を指定します。

password

単純なユーザー名/パスワード認証に使用されるパスワードを指定します。

serviceClass

サービスエンドポイントインターフェイス (SEI) の名前を指定します。

wsdlLocation

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

name

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

abstract

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

depends-on

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

createdFromAPI

Service.getPort() などの Apache CXF API を使用して Bean を作成したユーザーを指定します。

デフォルトは false です。

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

  • Bean の内部名を変更するには、.jaxws-client を id に追加します。
  • Bean を抽象化します

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

機能の追加

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

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

表17.5「コンシューマーエンドポイント設定の要素」 JAX-WS コンシューマーの設定に使用できる子要素の説明を示します。

表17.5 コンシューマーエンドポイント設定の要素

要素説明

jaxws:binding

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

jaxws:dataBinding

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

jaxws:features

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

jaxws:handlers

メッセージを処理するための JAX-WS ハンドラー実装のリストを指定します。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.4「簡単なコンシューマー設定」 は、簡単なコンシューマー設定を示しています。

例17.4 簡単なコンシューマー設定

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:client id="bookClient"
                serviceClass="org.apache.cxf.demo.BookClientImpl"
                address="http://localhost:8080/books"/>
  ...
</beans>

JAX-WS コンシューマーでのスキーマ検証の有効化

JAX-WS コンシューマーでスキーマ検証を有効にするには、jaxws:client 要素の jaxws:properties 子要素の schema-validation-enabled プロパティーを以下のように設定します。

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

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

第18章 JAX-RS エンドポイントの設定

概要

この章では、Blueprint XML および Spring XML で JAX-RS サーバーエンドポイントをインスタンス化および設定する方法と、XML で JAX-RS クライアントエンドポイント (クライアントプロキシー Bean) をインスタンス化および設定する方法について説明します。

18.1. JAX-RS サーバーエンドポイントの設定

18.1.1. JAX-RS サーバーエンドポイントの定義

基本のサーバーエンドポイント定義

XML で JAX-RS サーバーエンドポイントを定義するには、少なくとも以下の項目を指定する必要があります。

  1. XML でエンドポイントを定義するために使用される jaxrs:server 要素。jaxrs: namespace 接頭辞は、ブループリントと Spring の異なる名前空間にそれぞれマッピングされることに注意してください。
  2. 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 は、現在のホストに割り当てられたホスト名のいずれかに一致するワイルドカードとして機能します (マルチホームホストマシンで役に立ちます)。
  3. JAX-RS サービスの実装を提供する 1 つ以上の JAX-RS ルートリソースクラス。リソースクラスを指定する最も簡単な方法は、jaxrs:serviceBeans 要素内にリソースクラスを一覧表示することです。

Blueprint の例

以下の Blueprint XML の例は、(デフォルトの HTTP コンテナーにデプロイするように) 相対アドレス /customers を指定し、service.CustomerService リソースクラスによって実装される、JAX-RS エンドポイントを定義する方法を示しています。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
    xmlns:cxf="http://cxf.apache.org/blueprint/core"
    xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd
http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
">

    <cxf:bus>
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref component-id="serviceBean" />
        </jaxrs:serviceBeans>
     </jaxrs:server>

     <bean id="serviceBean" class="service.CustomerService"/>
</blueprint>

Blueprint XML 名前空間

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

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 名前空間が必要です。

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>

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

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

<beans ... >
  <jaxrs:server id="customerService" address="/service1">
    <jaxrs:serviceFactories>
      <ref bean="sfactory1" />
      <ref bean="sfactory2" />
    </jaxrs:serviceFactories>
  </jaxrs:server>

  <bean id="sfactory1" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean1"/>
  </bean>
  <bean id="sfactory2" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean2"/>
  </bean>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>
注記

シングルトン以外のライフサイクルを指定する場合は、org.apache.cxf.service.Invoker Bean を実装および登録することが推奨されます (インスタンスは jaxrs:server/jaxrs:invoker 要素から参照して登録できます)。

WADL ドキュメントの添付

任意で、jaxrs:server 要素の docLocation 属性を使用して、WADL ドキュメントを JAX-RS サーバーエンドポイントに関連付けることができます。以下に例を示します。

<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
      <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
</jaxrs:server>

スキーマ検証

外部 XML スキーマがある場合、JAX-B 形式のメッセージコンテンツを記述するため、これらの外部スキーマを jaxrs:schemaLocations 要素を介して JAX-RS サーバーエンドポイントに関連付けることができます。

たとえば、サーバーエンドポイントを WADL ドキュメントに関連付けており、着信メッセージのスキーマ検証も有効にする場合は、次のように関連付けられた XML スキーマファイルを指定できます。

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/a.xsd</jaxrs:schemaLocation>
     <jaxrs:schemaLocation>classpath:/schemas/b.xsd</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

あるいは、特定のディレクトリーのスキーマファイル *.xsd をすべて含める場合は、以下のようにディレクトリー名を指定するだけです。

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

この方法でスキーマを指定すると、一般に、JAX-B スキーマへのアクセスを必要とするあらゆる種類の機能に役立ちます。

データバインディングの指定

jaxrs:dataBinding 要素を使用して、リクエストおよびリプライメッセージのメッセージボディーをエンコードするデータバインディングを指定できます。たとえば、JAX-B データバインディングを指定するには、次のように JAX-RS エンドポイントを設定できます。

<jaxrs:server id="jaxbbook" address="/jaxb">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.jaxb.JAXBDataBinding"/>
  </jaxrs:dataBinding>
</jaxrs:server>>

または、Aegis データバインディングを指定するには、JAX-RS エンドポイントを次のように設定できます。

<jaxrs:server id="aegisbook" address="/aegis">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.aegis.databinding.AegisDatabinding">
      <property name="aegisContext">
        <bean class="org.apache.cxf.aegis.AegisContext">
          <property name="writeXsiTypes" value="true"/>
        </bean>
      </property>
    </bean>
  </jaxrs:dataBinding>
</jaxrs:server>

JMS トランスポートの使用

HTTP の代わりに JMS メッセージングライブラリーをトランスポートプロトコルとして使用するように JAX-RS を設定することができます。JMS 自体はトランスポートプロトコルでは ない ため、実際のメッセージングプロトコルは設定する特定の JMS 実装によって異なります。

たとえば、次の Spring XML の例は、JMS トランスポートプロトコルを使用するように JAX-RS サーバーエンドポイントを設定する方法を示しています。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jms="http://cxf.apache.org/transports/jms"
       xmlns:jaxrs="http://cxf.apache.org/jaxrs"
       xsi:schemaLocation="
http://cxf.apache.org/transports/jms http://cxf.apache.org/schemas/configuration/jms.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    <bean id="ConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:${testutil.ports.EmbeddedJMSBrokerLauncher}" />
    </bean>

    <jaxrs:server xmlns:s="http://books.com"
    	serviceName="s:BookService"
    	transportId= "http://cxf.apache.org/transports/jms"
    	address="jms:queue:test.jmstransport.text?replyToName=test.jmstransport.response">
        <jaxrs:serviceBeans>
            <bean class="org.apache.cxf.systest.jaxrs.JMSBookStore"/>
        </jaxrs:serviceBeans>
    </jaxrs:server>

</beans>

前の例について、次の点に注意してください。

  • JMS 実装: JMS 実装は ConnectionFactory Bean によって提供され、Apache ActiveMQ 接続ファクトリーオブジェクトをインスタンス化します。接続ファクトリーをインスタンス化すると、デフォルトの JMS 実装レイヤーとして自動的にインストールされます。
  • JMS コンジットまたはデスティネーションオブジェクト:Apache CXF は、JMS コンジットオブジェクト (JMS コンシューマーを表すため) または JMS デスティネーションオブジェクト (JMS プロバイダーを表すため) を暗黙的にインスタンス化します。このオブジェクトは、属性設定 xmlns:s="http://books.com" (namespace の接頭辞を定義) と serviceName="s:BookService" (QName を定義) で定義される QName によって一意に識別される必要があります。
  • 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

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

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

  1. 選択したインジェクションプラットフォーム (Blueprint XML または Spring XML) に適切な XML 名前空間を使用して、モデルスキーマを定義します。
  2. モデルスキーマファイルをプロジェクトのリソースに追加して、スキーマファイルが最終パッケージ (JAR、WAR、または OSGi バンドルファイル) のクラスパスで使用できるようにします。

    注記

    あるいは、エンドポイントの jaxrs:model 子要素を使用して、モデルスキーマを直接 JAX-RS エンドポイントに組み込むこともできます。

  3. エンドポイントの modelRef 属性をクラスパス上のモデルスキーマの場所に設定し (クラスパス URL を使用)、モデルスキーマを使用するようにエンドポイントを設定します。
  4. 必要な場合は、jaxrs:serviceBeans 要素を使用して、ルートリソースを明示的にインスタンス化します。モデルスキーマが (ベースインターフェイスを参照する代わりに) ルートリソースクラスを直接参照する場合は、この手順をスキップできます。

クラスを参照するモデルスキーマの設定

モデルスキーマがルートリソースクラスに直接適用される場合、モデルスキーマは自動的にルートリソース Bean をインスタンス化するため、jaxrs:serviceBeans 要素を使用してルートリソース Bean を定義する必要はありません。

たとえば、customer-resources.xml がメタデータをカスタマーリソースクラスに関連付けるモデルスキーマの場合、以下のように customerService サービスエンドポイントをインスタンス化できます。

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-resources.xml" />

インターフェイスを参照するモデルスキーマの設定

モデルスキーマが Java インターフェイス (ルートリソースのベースインターフェイス) に適用される場合、エンドポイントの jaxrs:serviceBeans 要素を使用してルートリソースクラスをインスタンス化する必要があります。

たとえば、customer-interfaces.xml がメタデータをカスタマーリソースクラスに関連付けるモデルスキーマの場合、以下のように customerService サービスエンドポイントをインスタンス化できます。

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-interfaces.xml">
    <jaxrs:serviceBeans>
       <ref component-id="serviceBean" />
    </jaxrs:serviceBeans>
</jaxrs:server>

<bean id="serviceBean" class="service.CustomerService"/>

モデルスキーマリファレンス

モデルスキーマは、次の XML 要素を使用して定義されます。

model
モデルスキーマのルート要素。モデルスキーマを参照する必要がある場合は (たとえば、modelRef 属性を使用して JAX-RS エンドポイントから)、この要素の id 属性を設定する必要があります。
model/resource

resource 要素は、メタデータを特定のルートリソースクラス (または対応するインターフェイス) に関連付けるために使用されます。resource 要素に以下の属性を定義できます。

属性説明 +

name

このリソースモデルが適用されるリソースクラス (または対応するインターフェイス) の名前。

+

path

このリソースにマップする REST URL パスのコンポーネント。

+

consumes

このリソースによって使用されるコンテンツの型 (インターネットメディアの型) を指定します (例: application/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 動詞を指定します。通常、GETPOSTPUT、または DELETE のいずれかです。HTTP の動詞が指定されて いない 場合、Java メソッドは サブリソースロケーター と考えられ、サブリソースオブジェクトへの参照を返します (サブリソースクラスにも resource 要素を使用してメタデータを指定する必要があります)。

+

consumes

この操作によって消費されるコンテンツタイプ (インターネットメディアタイプ) を指定します (例: application/xmlapplication/json )。

+

produces

この操作で生成されるコンテンツタイプ (インターネットメディアタイプ) を指定します (例:application/xmlapplication/json)。

+

oneway

true の場合、操作を 一方向に設定します。つまり、リプライメッセージは不要になります。デフォルトは false です。

+

model/resource/operation/param

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

属性説明 +

name

この要素が適用される Java メソッドパラメーターの名前。

+

type

パラメーター値を REST URL またはメッセージから抽出する方法を指定します。PATHQUERYMATRIXHEADERCOOKIEFORMCONTEXTREQUEST_BODY のいずれかの値に設定できます。

+

defaultValue

REST URL またはメッセージから値を抽出できなかった場合に、パラメーターに挿入するデフォルト値。

+

encoded

true の場合、パラメーター値は URI でエンコードされた形式で挿入されます (つまり %nn エンコーディングを使用します)。デフォルトは false です。たとえば、URL パス (/name/Joe%20Bloggs) からパラメーターを抽出する際に、エンコードが true に設定されると、パラメーターは Joe%20Bloggs として注入されます。そうでない場合は、パラメーターは Joe Bloggs として注入されます。

+

第19章 Apache CXF ロギング

概要

この章では、Apache CXF ランタイムでロギングを設定する方法について説明します。

19.1. Apache CXF ロギングの概要

概要

Apache CXF は Java ロギングユーティリティー java.util.logging を使用します。ロギングは、標準の java.util.Properties 形式を使用して書き込まれるロギング設定ファイルで設定されます。アプリケーションでログを実行するには、プログラムでログを指定するか、アプリケーションの起動時にログ設定ファイルを指すコマンドでプロパティーを定義します。

デフォルトのプロパティーファイル

Apache CXF には、InstallDir/etc ディレクトリーにデフォルトの logging.properties ファイルが含まれています。このファイルは、ログメッセージの出力先と公開されるメッセージレベルの両方を設定します。デフォルト設定は、WARNING レベルでフラグが付けられたメッセージをコンソールへ出力するようにロガーを設定します。設定オプションを変更せずにデフォルトのファイルを使用することも、特定のアプリケーションに合わせて設定オプションを変更することもできます。

ロギング機能

Apache CXF には、ロギングを有効にするためにクライアントまたはサービスにプラグインできるロギング機能が含まれています。例19.1「ロギングの有効化設定」 は、ログ機能を有効にするための設定を示しています。

例19.1 ロギングの有効化設定

<jaxws:endpoint...>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>

詳細は、「メッセージコンテンツのログ」 を参照してください。

どこから始めますか ?

ロギングの簡単な例を実行するには、「ロギングを使用する簡単な例」

Apache CXF でのロギングの動作の詳細については、この章全体をお読みください。

java.util.logging に関する詳細情報

java.util.logging ユーティリティーは、最も広く使用されている Java ロギングフレームワークの 1 つです。このフレームワークの使用方法と拡張方法を説明するオンラインで入手可能な情報はたくさんあります。ただし、開始点として、以下のドキュメントでは java.util.logging の詳細な概要を説明します。

19.2. ロギングを使用する簡単な例

ログレベルと出力先の変更

wsdl_first サンプルアプリケーションでログレベルとログメッセージの出力先を変更するには、以下のステップを実行してください。

  1. InstallDir/samples/wsdl_first ディレクトリーの README.txt ファイルの java を使用したデモの実行 に記載されているサンプルサーバーを実行します。server start コマンドは、 以下のようにデフォルトの logging.properties ファイルを指定することに注意してください。

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

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties demo.hw.server.Server &

    +

    デフォルトの logging.properties ファイルは InstallDir/etc ディレクトリーにあります。Apache CXF ロガーを設定し、WARNING レベルのログメッセージをコンソールに出力します。その結果、コンソールに印刷されるものはほとんどありません。

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

    .level= INFO
    java.util.logging.ConsoleHandler.level = INFO
  5. 次のコマンドを使用してサーバーを再起動します。

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

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &

    +

    レベル INFO のメッセージをログに記録するようにグローバルロギングとコンソールロガーを設定しているため、コンソールに多くのログメッセージが表示されます。

19.3. デフォルトのログ設定ファイル

19.3.1. ロギング設定の概要

デフォルトのロギング設定ファイル logging.propertiesInstallDir/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.htmljava.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 メッセージの内容をログに記録したい場合があります。

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

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

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

例19.10「エンドポイント設定へのロギングの追加」 に示すように、ログ機能をエンドポイントの設定に追加します。

例19.10 エンドポイント設定へのロギングの追加

<jaxws:endpoint ...>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>

例19.10「エンドポイント設定へのロギングの追加」 に示す XML の例 SOAP メッセージのロギングを有効にします。

ロギング機能をコンシューマーに追加する

例19.11「クライアント設定へのログの追加」 に示すように、クライアントの設定でログ機能を追加します。

例19.11 クライアント設定へのログの追加

<jaxws:client ...>
   <jaxws:features>
      <bean class="org.apache.cxf.feature.LoggingFeature"/>
    </jaxws:features>
</jaxws:client>

例19.11「クライアント設定へのログの追加」 に示す XML の例 SOAP メッセージのロギングを有効にします。

INFO レベルのメッセージをログに記録するようにログを設定する

例19.12「ロギングレベルを INFO に設定する」 に示されるように、サービスに関連する logging.properties ファイルが INFO レベルのメッセージをログに記録するように設定されていることを確認します。

例19.12 ロギングレベルを INFO に設定する

.level= INFO
java.util.logging.ConsoleHandler.level = INFO

SOAP メッセージのロギング

SOAP メッセージのロギングを確認するには、以下のように InstallDir/samples/wsdl_first ディレクトリーにある wsdl_first サンプルアプリケーションを変更します。

  1. 例19.13「SOAP メッセージをログに記録するためのエンドポイント設定」 に記載されている jaxws:features 要素を、wsdl_first サンプルディレクトリーにある cxf.xml 設定ファイルに追加します。

    例19.13 SOAP メッセージをログに記録するためのエンドポイント設定

    <jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort"
                    createdFromAPI="true">
      <jaxws:properties>
        <entry key="schema-validation-enabled" value="true" />
      </jaxws:properties>
      <jaxws:features>
        <bean class="org.apache.cxf.feature.LoggingFeature"/>
      </jaxws:features>
    </jaxws:endpoint>
  2. この例では、InstallDir/etc ディレクトリーにあるデフォルトの logging.properties ファイルを使用します。このファイルのコピーを作成し、これに mylogging.properties という名前を付けます。
  3. mylogging.properties ファイルで、以下のように java. leveljava.util.logging.ConsoleHandler.level 設定プロパティーを編集して、ロギングレベルを INFO に変更します。

    .level= INFO
    java.util.logging.ConsoleHandler.level = INFO
  4. 以下のように cxf.xml ファイルと mylogging.properties ファイルの両方で、新しい設定設定を使用してサーバーを起動します。

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

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &

    +

  5. 次のコマンドを使用して、hello world クライアントを起動します。

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

    Windows

    java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.client.Client .\wsdl\hello_world.wsdl

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.client.Client ./wsdl/hello_world.wsdl

    +

SOAP メッセージはコンソールに記録されます。

第20章 WS-Addressing のデプロイ

概要

Apache CXF は、JAX-WS アプリケーションの WS-Addressing をサポートしています。この章では、Apache CXF ランタイム環境に WS-Addressing をデプロイする方法について説明します。

20.1. WS-Addressing の概要

概要

WS-Addressing は、サービスがトランスポートニュートラルな方法でアドレス情報を通信できるようにする仕様です。これは 2 つの部分で設定されています。

  • Web サービスエンドポイントへの参照を通信するための構造
  • アドレス情報を特定のメッセージに関連付けるメッセージアドレス指定プロパティー (MAP) のセット

サポートされている仕様

Apache CXF は、WS-Addressing 2004/08 仕様と WS-Addressing 2005/03 仕様の両方をサポートしています。

その他の情報

WS-Addressing の詳細は、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 メッセージのフローは、次のように説明できます。

  1. RM ソースは CreateSequence プロトコルメッセージを RM 宛先に送信します。これには、確認応答を受け取るエンドポイント (wsrm:AcksTo エンドポイント) の参照が含まれます。
  2. RM 宛先は CreateSequenceResponse プロトコルメッセージを RM ソースに戻します。このメッセージには、RM シーケンスセッションのシーケンス ID が含まれています。
  3. RM ソースは、アプリケーションソースが送信する各メッセージに RM Sequence ヘッダーを追加します。このヘッダーには、シーケンス ID と一意のメッセージ ID が含まれています。
  4. RM 送信元は、各メッセージを RM 宛先に送信します。
  5. RM 宛先は、RM SequenceAcknowledgement ヘッダーが含まれるメッセージを送信し、RM ソースからメッセージの受信を認識します。
  6. RM 宛先は、メッセージを 1 回限りの順序でアプリケーション宛先に配信します。
  7. RM ソースは、確認応答をまだ受信していないというメッセージを再送信します。

    最初の再送信の試行は、基本再送信間隔の後に行われます。連続した再送信の試行は、デフォルトで、指数バックオフ間隔で、または代わりに、固定間隔で行われます。詳細は、「WS-RM の設定」 を参照してください。

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

WS-RM 配信保証

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

サポートされている仕様

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

WS-ReliableMessaging 1.0

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

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

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 プロトコルメッセージが交換されます。たとえば、アウトバウンドインターセプターチェーンで最初のアプリケーションメッセージをインターセプトすると、 RMOutInterceptorCreateSequence リクエストを送信し、CreateSequenceResponse 応答を受信するまで元のアプリケーションメッセージを処理するのを待ちます。さらに、WS-RM インターセプターは、シーケンスヘッダーをアプリケーションメッセージに追加し、宛先側でメッセージから抽出します。メッセージの交換を信頼できるものにするために、アプリケーションコードに変更を加える必要はありません。

WS-RM を有効にする方法の詳細については、「WS-RM の有効化」 を参照してください。

WS-RM 属性の設定

設定を通じて、シーケンスの境界設定や信頼性の高い交換の他の側面を制御します。たとえば、デフォルトでは、Apache CXF はシーケンスの存続期間を最大化しようとするため、帯域外 WS-RM プロトコルメッセージによって発生するオーバーヘッドが削減されます。アプリケーションメッセージごとに別のシーケンスを使用するようにするには、WS-RM ソースシーケンス終了ポリシーを設定します (最大シーケンスの長さを 1 に設定)。

WS-RM 動作の設定の詳細については、「WS-RM の設定」 を参照してください。

21.3. WS-RM の有効化

概要

信頼性の高いメッセージングを有効にするには、インバウンドとアウトバウンドの両方のメッセージと障害のインターセプターチェーンに WS-RM インターセプターを追加する必要があります。WS-RM インターセプターは WS-Addressing を使用するため、WS-Addressing インターセプターもインターセプターチェーンに存在する必要があります。

これらのインターセプターの存在を確認するには、次の 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 インターセプター - RMOutInterceptorRMInInterceptor、および RMSoapInterceptor を設定します。

インバウンドメッセージのインターセプターチェーンに WS-Addressing および WS-RM インターセプターを追加します。

インバウンド障害のインターセプターチェーンに WS-Addressing および WS-RM インターセプターを追加します。

WS-Addressing および WS-RM インターセプターをアウトバウンドメッセージのインターセプターチェーンに追加します。

WS-Addressing および WS-RM インターセプターをアウトバウンド障害のインターセプターチェーンに追加します。

WS-Policy フレームワーク。暗黙的にインターセプターを追加する

WS-Policy フレームワークは、WS-Policy を使用できるようにするインフラストラクチャーと API を提供します。これは、Web サービスポリシー 1.5- フレームワーク および Web サービスポリシー 1.5- 添付ファイル の仕様の 2006 年 11 月のドラフト公開に準拠しています。

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

  1. ポリシー機能をクライアントとサーバーのエンドポイントに追加します。例21.2「WS-Policy を使用した WS-RM の設定」 は、jaxws:feature 要素内にネストされた参照 Bean を表示します。参照 Bean は AddressingPolicy を指定します。これは、同じ設定ファイル内で別の要素として定義されます。

    例21.2 WS-Policy を使用した WS-RM の設定

    <jaxws:client>
        <jaxws:features>
          <ref bean="AddressingPolicy"/>
        </jaxws:features>
    </jaxws:client>
    <wsp:Policy wsu:Id="AddressingPolicy" xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
        <wsam:Addressing>
          <wsp:Policy>
            <wsam:NonAnonymousResponses/>
          </wsp:Policy>
        </wsam:Addressing>
    </wsp:Policy>
  2. 例21.3「WSDL ファイルへの RM ポリシーの追加」 に示すように、信頼できるメッセージングポリシーを wsdl:service 要素またはポリシー参照要素として使用できる他の WSDL 要素に追加します。

    例21.3 WSDL ファイルへの RM ポリシーの追加

    <wsp:Policy wsu:Id="RM"
       xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
       xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
            <wsp:Policy/>
        </wsam:Addressing>
        <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
            <wsrmp:BaseRetransmissionInterval Milliseconds="10000"/>
        </wsrmp:RMAssertion>
    </wsp:Policy>
    ...
    <wsdl:service name="ReliableGreeterService">
        <wsdl:port binding="tns:GreeterSOAPBinding" name="GreeterPort">
            <soap:address location="http://localhost:9020/SoapContext/GreeterPort"/>
            <wsp:PolicyReference URI="#RM" xmlns:wsp="http://www.w3.org/2006/07/ws-policy"/>
        </wsdl:port>
    </wsdl:service>

21.4. ランタイム制御

概要

org.apache.cxf.ws.rm.RMManager クラスのパブリック定数で定義されたキー値を使用して、クライアントコードで複数のメッセージコンテキストプロパティー値を設定して WS-RM を制御できます。

ランタイム制御オプション

以下の表は、org.apache.cxf.ws.rm.RMManager クラスによって定義されるキーの一覧です。

キー説明

WSRM_VERSION_PROPERTY

文字列の WS-RM バージョン名前空間 (http://schemas.xmlsoap.org/ws/2005/02/rm/ または http://docs.oasis-open.org/ws-rx/wsrm/200702)。

WSRM_WSA_VERSION_PROPERTY

String WS-Addressing バージョンネームスペース (http://schemas.xmlsoap.org/ws/2004/08/addressing または http://www.w3.org/2005/08/addressing) - このプロパティーは、http://schemas.xmlsoap.org/ws/2005/02/rm/ RM ネームスペースを使用していない限りは無視されます)。

WSRM_LAST_MESSAGE_PROPERTY

ブール値 true で、最後のメッセージが送信されたことを WS-RM コードに指示し、コードが WS-RM シーケンスおよびリリースリソースを表示できるようにします (C 3.0.0 バージョンの CXF より、クライアントを閉じると WS-RM はデフォルトで RM シーケンスを閉じます)。

WSRM_INACTIVITY_TIMEOUT_PROPERTY

ミリ秒単位の長い非アクティブタイムアウト。

WSRM_RETRANSMISSION_INTERVAL_PROPERTY

ミリ秒単位の長いベース再送信間隔。

WSRM_EXPONENTIAL_BACKOFF_PROPERTY

ブール値バックオフフラグ。

WSRM_ACKNOWLEDGEMENT_INTERVAL_PROPERTY

ミリ秒単位の長い確認応答間隔。

JMX を介した WS-RM の制御

Apache CXF の JMX 管理機能を使用して、WS-RM の多くの側面を監視および制御することもできます。JMX 操作の完全な一覧は org.apache.cxf.ws.rm.ManagedRMManager および org.apache.cxf.ws.rm.ManagedRMEndpoint で定義されますが、これらの操作には現在の RM 状態を表示することが含まれます。JXM を使用して、WS-RM シーケンスを閉じたり終了したり、以前に送信されたメッセージがリモート RM エンドポイントによって確認されたときに通知を受信したりすることもできます。

JMX 制御の例

たとえば、クライアント設定で JMX サーバーを有効にしている場合は、次のコードを使用して、最後に受信した確認応答番号を追跡できます。

// Java
private static class AcknowledgementListener implements NotificationListener {
    private volatile long lastAcknowledgement;

    @Override
    public void handleNotification(Notification notification, Object handback) {
        if (notification instanceof AcknowledgementNotification) {
            AcknowledgementNotification ack = (AcknowledgementNotification)notification;
            lastAcknowledgement = ack.getMessageNumber();
        }
    }

    // initialize client
...
    // attach to JMX bean for notifications
    //  NOTE: you must have sent at least one message to initialize RM before executing this code
    Endpoint ep = ClientProxy.getClient(client).getEndpoint();
    InstrumentationManager im = bus.getExtension(InstrumentationManager.class);
    MBeanServer mbs = im.getMBeanServer();
    RMManager clientManager = bus.getExtension(RMManager.class);
    ObjectName name = RMUtils.getManagedObjectName(clientManager, ep);
    System.out.println("Looking for endpoint name " + name);
    AcknowledgementListener listener = new AcknowledgementListener();
    mbs.addNotificationListener(name, listener, null, null);

    // send messages using RM with acknowledgement status reported to listener
...

21.5. WS-RM の設定

21.5.1. Apache CXF 固有の WS-RM 属性の設定

概要

Apache CXF 固有の属性を設定するには、rmManager Spring Bean を使用します。以下を設定ファイルに追加します。

例21.4「Apache CXF 固有の WS-RM 属性の設定」 簡単な例を示します。

例21.4 Apache CXF 固有の WS-RM 属性の設定

&lt;beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
      xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
 http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd"&gt;
...
&lt;wsrm-mgr:rmManager&gt;
&lt;!--
  ...Your configuration goes here
--&gt;
&lt;/wsrm-mgr:rmManager&gt;

rmManager Spring bean の子

表21.2「rmManager Spring Bean の子」 は、http://cxf.apache.org/ws/rm/manager namespace で定義される rmManager Spring Bean の子要素を表示します。

表21.2 rmManager Spring Bean の子

要素説明

RMAssertion

RMAssertion 型の要素

deliveryAssurance

適用すべき配信保証を記述する DeliveryAssuranceType の要素

sourcePolicy

RM ソースの詳細を設定できるようにするタイプ SourcePolicyType の要素

destinationPolicy

RM 宛先の詳細を設定できるようにするタイプ DestinationPolicyType の要素

例は、「未確認メッセージの最大しきい値」 を参照してください。

21.5.2. 標準の WS-RM ポリシー属性の設定

概要

次のいずれかの方法で、標準の WS-RM ポリシー属性を設定できます。

WS-Policy RMAssertion の子

表21.3「WS-Policy RMAssertion 要素の子」、http://schemas.xmlsoap.org/ws/2005/02/rm/policy 名前空間で定義される要素を表示します。

表21.3 WS-Policy RMAssertion 要素の子

Name説明

InactivityTimeout

エンドポイントが非アクティブのために RM シーケンスが終了したと見なす前に、メッセージを受信せずに経過する必要がある時間を指定します。

BaseRetransmissionInterval

特定のメッセージについて RM ソースが確認応答を受信する必要がある間隔を設定します。BaseRetransmissionInterval によって設定された時間内に確認応答が受信されなかった場合、RM ソースはメッセージを再送信します。

ExponentialBackoff

一般的に知られている指数バックオフアルゴリズム (Tanenbaum) を使用して再送信間隔が調整されることを示します。

詳細については、Computer Networks、Andrew S. Tanenbaum、Prentice Hall PTR、2003 を参照してください。

AcknowledgementInterval

WS-RM では、確認応答は返信メッセージで送信されるか、スタンドアロンで送信されます。確認応答を送信するための返信メッセージが利用できない場合、RM 宛先は、スタンドアロン確認応答を送信する前に、確認応答間隔まで待機できます。確認応答されていないメッセージがない場合、RM 宛先は確認応答を送信しないことを選択できます。

より詳細な参照情報

各要素のサブ要素と属性の説明を含む、より詳細な参照情報については、http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd を参照してください。

rmManager Spring bean の RMAssertion

標準の WS-RM ポリシー属性を設定するには、Apache CXF rmManager Spring Bean 内に RMAssertion を追加します。これは、すべての WS-RM 設定を同じ設定ファイルに保持する場合に最適なアプローチです。つまり、Apache CXF 固有の属性と標準の WS-RM ポリシー属性を同じファイルで設定する場合です。

たとえば、例21.5「rmManager Spring Bean で RMAssertion を使用して WS-RM 属性を設定する」 の設定では次を示します。

  • rmManager Spring Bean 内で RMAssertion を使用して設定された標準の WS-RM ポリシー属性である BaseRetransmissionInterval
  • 同じ設定ファイルで設定された Apache CXF 固有の RM 属性 intraMessageThreshold

例21.5 rmManager Spring Bean で RMAssertion を使用して WS-RM 属性を設定する

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
       xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/>
    </wsrm-policy:RMAssertion>
    <wsrm-mgr:destinationPolicy>
        <wsrm-mgr:acksPolicy intraMessageThreshold="0" />
    </wsrm-mgr:destinationPolicy>
</wsrm-mgr:rmManager>
</beans>

機能内のポリシー

例21.6「機能内のポリシーとしての WS-RM 属性の設定」 に示すように、機能内で標準の WS-RM ポリシー属性を設定できます。

例21.6 機能内のポリシーとしての WS-RM 属性の設定

<xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:wsa="http://cxf.apache.org/ws/addressing"
        xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:jaxws="http://cxf.apache.org/jaxws"
        xsi:schemaLocation="
http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd
http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
    <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort" createdFromAPI="true">
        <jaxws:features>
               <wsp:Policy>
                   <wsrm:RMAssertion xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
                     <wsrm:AcknowledgementInterval Milliseconds="200" />
                   </wsrm:RMAssertion>
                   <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
                       <wsp:Policy>
                            <wsam:NonAnonymousResponses/>
                       </wsp:Policy>
                   </wsam:Addressing>
              </wsp:Policy>
        </jaxws:features>
    </jaxws:endpoint>
</beans>

WSDL ファイル

WS-Policy フレームワークを使用して WS-RM を有効にする場合は、WSDL ファイルで標準の WS-RM ポリシー属性を設定できます。これは、サービスを相互運用して、他のポリシー対応 Web サービススタックにデプロイされたコンシューマーとシームレスに WS-RM を使用する場合に適したアプローチです。

例については、「WS-Policy フレームワーク。暗黙的にインターセプターを追加する」を参照してください。ここで、基本再送信間隔は WSDL ファイルで設定されます。

外部アタッチメント

標準の WS-RM ポリシー属性を外部の添付ファイルで設定できます。これは、WSDL ファイルを変更できない、または変更したくない場合に適したアプローチです。

例21.7「外部アタッチメントでの WS-RM の設定」 は、特定の EPR に対して WS-A と WS-RM の両方 (基本再送信間隔 30 秒) を有効にする外部接続を示しています。

例21.7 外部アタッチメントでの WS-RM の設定

<attachments xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsp:PolicyAttachment>
        <wsp:AppliesTo>
           <wsa:EndpointReference>
                <wsa:Address>http://localhost:9020/SoapContext/GreeterPort</wsa:Address>
            </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wsp:Policy>
            <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata">
                <wsp:Policy/>
            </wsam:Addressing>
            <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
                <wsrmp:BaseRetransmissionInterval Milliseconds="30000"/>
            </wsrmp:RMAssertion>
        </wsp:Policy>
    </wsp:PolicyAttachment>
</attachments>/

21.5.3. WS-RM 設定のユースケース

概要

このサブセクションでは、ユースケースの観点から WS-RM 属性を設定することに焦点を当てます。属性が http://schemas.xmlsoap.org/ws/2005/02/rm/policy/ namespace で定義された標準の WS-RM ポリシー属性である場合、rmManager Spring Bean 内の RMAssertion で設定する例のみが表示されます。機能内のポリシーなどの属性を設定する方法の詳細については、WSDL ファイルまたは外部添付ファイルで、「標準の WS-RM ポリシー属性の設定」 を参照してください。

次のユースケースについて説明します。

基本再送間隔

BaseRetransmissionInterval 要素は、まだ確認されていないメッセージを RM ソースが再送信する間隔を指定します。これは、http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd スキーマファイルで定義されています。デフォルト値は 3000 ミリ秒です。

例21.8「WS-RM ベースの再送間隔の設定」 WS-RM ベースの再送間隔を設定する方法を示します。

例21.8 WS-RM ベースの再送間隔の設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/>
    </wsrm-policy:RMAssertion>
</wsrm-mgr:rmManager>
</beans>

再送信の指数バックオフ

ExponentialBackoff 要素は、承認されていないメッセージの連続する再送信試行が指数関数間隔で実行されるかどうかを判断します。

ExponentialBackoff 要素が存在すると、この機能が有効になります。デフォルトで 2 の指数バックオフ比率が使用されます。ExponentialBackoff はフラグです。要素が存在する場合、指数バックオフが有効になります。要素が存在しない場合、指数バックオフは無効になります。値は必要ありません。

例21.9「WS-RM 指数バックオフプロパティーの設定」 は、再送信のために WS-RM 指数バックオフを設定する方法を示しています。

例21.9 WS-RM 指数バックオフプロパティーの設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:ExponentialBackoff/>
    </wsrm-policy:RMAssertion>
</wsrm-mgr:rmManager>
</beans>

確認間隔

AcknowledgementInterval 要素は、WS-RM 宛先が非同期確認応答を送信する間隔を指定します。これらは、着信メッセージの受信時に送信する同期確認応答に追加されます。デフォルトの非同期確認間隔は 0 ミリ秒です。つまり、AcknowledgementInterval が特定の値に設定されていない場合、確認応答は即座に送信されます (つまり、利用可能な最初の機会)。

非同期確認応答は、次の両方の条件が満たされた場合にのみ RM 宛先によって送信されます。

  • RM 宛先は匿名以外の wsrm:acksTo エンドポイントを使用しています。
  • 応答メッセージに確認応答をピギーバックする機会は、確認応答間隔が満了する前には発生しません。

例21.10「WS-RM 確認応答間隔の設定」 WS-RM 確認応答間隔を設定する方法を示します。

例21.10 WS-RM 確認応答間隔の設定

<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy
...>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <wsrm-policy:RMAssertion>
        <wsrm-policy:AcknowledgementInterval Milliseconds="2000"/>
    </wsrm-policy:RMAssertion>
</wsrm-mgr:rmManager>
</beans>

未確認メッセージの最大しきい値

maxUnacknowledged 属性は、シーケンスが終了する前に、シーケンスごとにアクセッジできる承認されていないメッセージの最大数を設定します。

例21.11「WS-RM の未確認メッセージの最大しきい値の設定」 は、WS-RM の未確認メッセージの最大しきい値を設定する方法を示しています。

例21.11 WS-RM の未確認メッセージの最大しきい値の設定

<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager
...>
<wsrm-mgr:reliableMessaging>
    <wsrm-mgr:sourcePolicy>
        <wsrm-mgr:sequenceTerminationPolicy maxUnacknowledged="20" />
    </wsrm-mgr:sourcePolicy>
</wsrm-mgr:reliableMessaging>
</beans>

RM シーケンスの最大長

maxLength 属性は、WS-RM シーケンスの最大長を設定します。デフォルト値は 0 で、WS-RM シーケンスの長さがバインドされないことを意味します。

この属性が設定されている場合、RM エンドポイントは、制限に達したとき、および以前に送信されたメッセージのすべての確認応答を受信した後に、新しい RM シーケンスを作成します。新しいメッセージは、newsequence を使用して送信されます。

例21.12「WS-RM メッセージシーケンスの最大長の設定」 RM シーケンスの最大長を設定する方法を示します。

例21.12 WS-RM メッセージシーケンスの最大長の設定

<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager
...>
<wsrm-mgr:reliableMessaging>
    <wsrm-mgr:sourcePolicy>
        <wsrm-mgr:sequenceTerminationPolicy maxLength="100" />
    </wsrm-mgr:sourcePolicy>
</wsrm-mgr:reliableMessaging>
</beans>

メッセージ配信保証ポリシー

次の配信保証ポリシーを使用するように RM 宛先を設定できます。

  • AtMostOnce: RM 宛先はメッセージを 1 度のみアプリケーションの宛先に配信します。メッセージが複数回配信されると、エラーが発生します。シーケンス内の一部のメッセージが配信されない可能性があります。
  • AtLeastOnce: RM 宛先は少なくとも 1 回アプリケーションの宛先にメッセージを配信します。送信されたすべてのメッセージが配信されるか、エラーが発生します。一部のメッセージは複数回配信される場合があります。
  • InOrder: RM 宛先は、送信順にアプリケーションの宛先にメッセージを配信します。この配信保証は、AtMostOnce または AtLeastOnce 保証と組み合わせることができます。

例21.13「WS-RM メッセージ配信保証ポリシーの設定」 WS-RM メッセージ配信保証を設定する方法を示します。

例21.13 WS-RM メッセージ配信保証ポリシーの設定

<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager
...>
<wsrm-mgr:reliableMessaging>
    <wsrm-mgr:deliveryAssurance>
        <wsrm-mgr:AtLeastOnce />
    </wsrm-mgr:deliveryAssurance>
</wsrm-mgr:reliableMessaging>
</beans>

21.6. WS-RM 永続性の設定

概要

この章ですでに説明した Apache CXF -RM 機能は、ネットワーク障害などの場合に信頼性を提供します。WS-RM の永続性は、RM ソースや RM 宛先のクラッシュなどの他のタイプの障害全体で信頼性を提供します。

WS-RM の永続性には、さまざまな RM エンドポイントの状態を永続ストレージに保存することが含まれます。これにより、エンドポイントは、メッセージが生まれ変わったときにメッセージの送受信を継続できます。

Apache CXF は、設定ファイルで WS-RM の永続性を有効にします。デフォルトの WS-RM 永続ストアは JDBC ベースです。便宜上、Apache CXF には、すぐに使用できる展開用の Derby が含まれています。さらに、永続ストアも Java API を使用して公開されます。独自の永続化メカニズムを実装するには、この API と優先 DB を使用して永続化メカニズムを実装できます。

重要

WS-RM の永続性は一方向の通話でのみサポートされており、デフォルトでは無効になっています。

仕組み

Apache CXF WS-RM の永続性は次のように機能します。

  • RM 送信元エンドポイントでは、送信メッセージは送信前に保持されます。確認応答を受信した後、永続ストアから削除されます。
  • クラッシュからの回復後、永続化されたメッセージを回復し、すべてのメッセージが確認されるまで再送信します。その時点で、RM シーケンスは閉じられます。
  • RM 宛先エンドポイントでは、着信メッセージが永続化され、ストアが成功すると、確認応答が送信されます。メッセージが正常にディスパッチされると、永続ストアから削除されます。
  • クラッシュからの回復後、永続化されたメッセージを回復し、それらをディスパッチします。また、RM シーケンスを、新しいメッセージが受け入れられ、確認され、配信される状態にします。

WS- 永続性の有効化

WS-RM の永続性を有効にするには、WS-RM の永続ストアを実装するオブジェクトを指定する必要があります。独自に開発することも、Apache CXF に付属の JDBC ベースのストアを使用することもできます。

例21.14「デフォルトの WS-RM 永続ストアの設定」 に示す設定 Apache CXF に付属する JDBC ベースのストアを有効にします。

例21.14 デフォルトの WS-RM 永続ストアの設定

<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore"/>
<wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager">
    <property name="store" ref="RMTxStore"/>
</wsrm-mgr:rmManager>

WS- 永続性の設定

Apache CXF に付属する JDBC ベースのストアは、表21.4「JDBC ストアのプロパティー」 に示すプロパティーをサポートします。

表21.4 JDBC ストアのプロパティー

属性名デフォルト設定

driverClassName

文字列

org.apache.derby.jdbc.EmbeddedDriver

userName

文字列

null

passWord

文字列

null

url

文字列

jdbc:derby:rmdb;create=true

例21.15「WS-RM 永続性のための JDBC ストアの設定」 に示されている設定は、Apache CXF に同梱される JDBC ベースのストアを有効にし、driverClassName および url をデフォルト以外の値に設定します。

例21.15 WS-RM 永続性のための JDBC ストアの設定

<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore">
    <property name="driverClassName" value="com.acme.jdbc.Driver"/>
    <property name="url" value="jdbc:acme:rmdb;create=true"/>
</bean>

第22章 高可用性の有効化

概要

この章では、Apache CXF ランタイムでハイアベイラビリティを有効にして設定する方法について説明します。

22.1. 高可用性

概要

スケーラブルで信頼性の高いアプリケーションには、分散システムの単一障害点を回避するための高可用性が必要です。システムの単一障害点から、 複製されたサービス

レプリケートされたサービスは、同じサービスの複数のインスタンスまたは レプリカ で設定されます。これらが一緒になって、単一の論理サービスとして機能します。クライアントはレプリケートされたサービスでリクエストを呼び出し、Apache CXF はリクエストをメンバーレプリカの 1 つに配信します。レプリカへのルーティングは、クライアントに対して透過的です。

静的フェイルオーバーを備えた HA

Apache CXF は、レプリカの詳細がサービスの WSDL ファイルにエンコードされる静的フェールオーバーを備えた高可用性 (HA) をサポートします。WSDL ファイルには複数のポートが含まれており、同じサービスに対して複数のホストを含めることができます。クラスター内のレプリカの数は、WSDL ファイルが変更されていない限り静的なままです。クラスターサイズを変更するには、WSDL ファイルを編集する必要があります。

22.2. 静的フェイルオーバーによる HA の有効化

概要

静的フェールオーバーで HA を有効にするには、次の手順を実行する必要があります。

レプリカの詳細をサービス WSDL ファイルにエンコードします

クラスター内のレプリカの詳細をサービス WSDL ファイルにエンコードする必要があります。例22.1「静的フェイルオーバーによる HA の有効化。WSDL ファイル」 は、3 つのレプリカのサービスクラスターを定義する WSDL ファイル抽出を示しています。

例22.1 静的フェイルオーバーによる HA の有効化。WSDL ファイル

<wsdl:service name="ClusteredService">
    <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica1">
        <soap:address location="http://localhost:9001/SoapContext/Replica1"/>
    </wsdl:port>

    <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica2">
        <soap:address location="http://localhost:9002/SoapContext/Replica2"/>
    </wsdl:port>

    <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica3">
        <soap:address location="http://localhost:9003/SoapContext/Replica3"/>
    </wsdl:port>

</wsdl:service>

例22.1「静的フェイルオーバーによる HA の有効化。WSDL ファイル」 に示す WSDL 抽出は次のように説明することができます。

3 つのポートで公開されるサービス ClusterService を定義します。

  1. Replica1
  2. Replica2
  3. Replica3

Replica1 を定義して、ClusterService をポート 9001 で SOAP over HTTP エンドポイントとして公開します。

Replica2 を定義して、ClusterService をポート 9002 で SOAP over HTTP エンドポイントとして公開します。

Replica3 を定義して、ClusterService をポート 9003 で SOAP over HTTP エンドポイントとして公開します。

クラスターリング機能をクライアント設定に追加します

クライアント設定ファイルに、例22.2「静的フェイルオーバーによる HA の有効化。クライアント設定」 に示すようにクラスターリング機能を追加します。

例22.2 静的フェイルオーバーによる HA の有効化。クライアント設定

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xmlns:clustering="http://cxf.apache.org/clustering"
         xsi:schemaLocation="http://cxf.apache.org/jaxws
         http://cxf.apache.org/schemas/jaxws.xsd
         http://www.springframework.org/schema/beans
         http://www.springframework.org/schema/beans/spring-beans.xsd">

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica1"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover/>
        </jaxws:features>
    </jaxws:client>

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica2"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover/>
        </jaxws:features>
    </jaxws:client>

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica3"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover/>
        </jaxws:features>
    </jaxws:client>

</beans>

22.3. 静的フェイルオーバーを使用した HA の設定

概要

デフォルトでは、静的フェールオーバーを使用する HA は、クライアントが通信している元のサービスが使用できなくなった場合、または失敗した場合に、レプリカサービスを選択するときにシーケンシャル戦略を使用します。シーケンシャルストラテジーは、使用されるたびに同じシーケンシャル順序でレプリカサービスを選択します。選択は Apache CXF の内部サービスモデルによって決定され、決定論的なフェールオーバーパターンになります。

ランダム戦略の設定

レプリカを選択するときにシーケンシャル戦略の代わりにランダム戦略を使用するように静的フェイルオーバーを使用して HA を設定できます。ランダム戦略では、サービスが使用できなくなるか失敗するたびに、ランダムレプリカサービスが選択されます。クラスター内の存続メンバーからのフェイルオーバーターゲットの選択は完全にランダムです。

ランダム戦略を設定するには、クライアント設定ファイルに 例22.3「静的フェイルオーバーのランダム戦略の設定」 に示す設定を追加します。

例22.3 静的フェイルオーバーのランダム戦略の設定

<beans ...>
    <bean id="Random" class="org.apache.cxf.clustering.RandomStrategy"/>

    <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica3"
                  createdFromAPI="true">
        <jaxws:features>
            <clustering:failover>
                <clustering:strategy>
                    <ref bean="Random"/>
                </clustering:strategy>
            </clustering:failover>
        </jaxws:features>
    </jaxws:client>
</beans>

例22.3「静的フェイルオーバーのランダム戦略の設定」 に示す設定は次のように説明することができます。

ランダムストラテジーを実装する Random bean および実装クラスを定義します。

レプリカを選択するときにランダム戦略が使用されることを指定します。

第23章 Apache CXF バインディング ID

バインディング ID の表

付録A Maven OSGi ツールの使用

概要

大規模なプロジェクトのバンドルまたはバンドルのコレクションを手動で作成するのは面倒な場合があります。Maven バンドルプラグインは、プロセスを自動化し、バンドルマニフェストのコンテンツを指定するためのいくつかのショートカットを提供することにより、作業を容易にします。

A.1. Maven バンドルプラグイン

Red Hat Fuse OSGi ツールは、Apache Felix の Maven バンドルプラグイン を使用します。バンドルプラグインは、Peter Kriens の bnd ツールに基づいています。バンドルにパッケージ化されているクラスの内容をイントロスペクトすることにより、OSGi バンドルマニフェストの構築を自動化します。バンドルに含まれるクラスの知識を使用すると、プラグインは適切な値を計算して、バンドルマニフェストの Import-Packages および Export-Package プロパティーにデータを投入することができます。プラグインには、バンドルマニフェストの他の必須プロパティーに使用されるデフォルト値もあります。

バンドルプラグインを使用するには、次の手順を実行します。

  1. 「Red Hat FuseOSGi プロジェクトのセットアップ」 プロジェクトの POM ファイルへのバンドルプラグイン。
  2. 「バンドルプラグインの設定」 バンドルのマニフェストを正しく設定するためのプラグイン。

A.2. Red Hat FuseOSGi プロジェクトのセットアップ

概要

OSGi バンドルを構築するための Maven プロジェクトは、単純な単一レベルのプロジェクトにすることができます。サブプロジェクトは必要ありません。ただし、次のことを行う必要があります。

  1. バンドルプラグインの POM への 追加
  2. 結果を OSGi バンドルとしてパッケージ化するように Maven に 指示 します。
注記

適切な設定でプロジェクトをセットアップするために使用できる Maven アーキタイプがいくつかあります。

ディレクトリー構造

OSGi バンドルを構築するプロジェクトは、単一レベルのプロジェクトにすることができます。トップレベル POM ファイルと src フォルダーのみが必要になります。すべての Maven プロジェクトと同様に、すべての Java ソースコードを src/java フォルダーに配置し、Java 以外のリソースを src/resources フォルダーに配置します。

Java 以外のリソースには、Spring 設定ファイル、JBI エンドポイント設定ファイル、および WSDL コントラクトが含まれます。

注記

Apache CXF、Apache Camel、または別の Spring が設定されている Bean を使用する Red Hat Fuse OSGi プロジェクトには、src/resources/META-INF/spring フォルダーに beans.xml ファイルも含まれます。

バンドルプラグインの追加

バンドルプラグインを使用する前に、ApacheFelix への依存関係を追加する必要があります。依存関係を追加した後、バンドルプラグインを POM のプラグイン部分に追加できます。

例A.1「OSGi バンドルプラグインを POM に追加する」 は、バンドルプラグインをプロジェクトに追加するために必要な POM エントリーを示しています。

例A.1 OSGi バンドルプラグインを POM に追加する

...
<dependencies>
  <dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.osgi.core</artifactId>
    <version>1.0.0</version>
  </dependency>
...
</dependencies>
...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.felix</groupId>
      <artifactId>maven-bundle-plugin</artifactId>
      <configuration>
        <instructions>
          <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
          <Import-Package>*,org.apache.camel.osgi</Import-Package>
          <Private-Package>org.apache.servicemix.examples.camel</Private-Package>
        </instructions>
      </configuration>
    </plugin>
  </plugins>
</build>
...

例A.1「OSGi バンドルプラグインを POM に追加する」 内のエントリーは次を行います。

Apache Felix への依存関係を追加します

バンドルプラグインをプロジェクトに追加します

プロジェクトのアーティファクト ID をバンドルのシンボリック名として使用するようにプラグインを設定します

バンドルされたクラスによってインポートされたすべての Java パッケージを含めるようにプラグインを設定する。また、org.apache.camel.osgi パッケージをインポートする

リストされたクラスをバンドルするようにプラグインを設定しますが、エクスポートされたパッケージのリストにはそれらを含めません

注記

プロジェクトの要件を満たすように設定を編集します。

バンドルプラグインの設定の詳細には、「バンドルプラグインの設定」 を参照してください。

バンドルプラグインのアクティブ化

Maven にバンドルプラグインを使用させるには、プロジェクトの結果をバンドルとしてパッケージ化するように Maven に指示します。そのためには、POM ファイルの packaging 要素を bundle に設定します。

便利な Maven アーキタイプ

バンドルプラグインを使用するように事前設定されたプロジェクトを生成するために使用できる Maven アーキタイプがいくつかあります。

Spring OSGi アーキタイプ

Spring OSGi アーキタイプは、次のように、Spring DM を使用して OSGi プロジェクトを構築するための汎用プロジェクトを作成します。

org.springframework.osgi/spring-bundle-osgi-archetype/1.1.2

次のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.springframework.osgi -DarchetypeArtifactId=spring-osgi-bundle-archetype -DarchetypeVersion=1.1.2 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

Apache CXF コードファーストの原型

次に示すように、Apache CXF コードファーストアーキタイプは、Java からサービスを構築するためのプロジェクトを作成します。

org.apache.servicemix.tooling/servicemix-osgi-cxf-code-first-archetype/2010.02.0-fuse-02-00

次のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-code-first-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

Apache CXF wsdl - 原型アーキタイプ

次に示すように、Apache CXF wsdl-first アーキタイプは、WSDL からサービスを作成するためのプロジェクトを作成します。

org.apache.servicemix.tooling/servicemix-osgi-cxf-wsdl-first-archetype/2010.02.0-fuse-02-00

次のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-wsdl-first-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

Apache Camel アーキタイプ

次に示すように、Apache Camel アーキタイプは、Red Hat Fuse にデプロイされるルートを構築するためのプロジェクトを作成します。

org.apache.servicemix.tooling/servicemix-osgi-camel-archetype/2010.02.0-fuse-02-00

次のコマンドを使用してアーキタイプを呼び出します。

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-camel-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version

A.3. バンドルプラグインの設定

概要

バンドルプラグインを機能させるために必要な情報はほぼありません。必要なすべてのプロパティーは、デフォルト設定を使用して有効な OSGi バンドルを生成します。

デフォルト値のみを使用して有効なバンドルを作成できますが、値の一部を変更することをお勧めします。プラグインの instructions 要素内のほとんどのプロパティーを指定できます。

設定プロパティー

一般的に使用される設定プロパティーのいくつかは次のとおりです。

バンドルのシンボリック名の設定

デフォルトでは、バンドルプラグインは Bundle-SymbolicName プロパティーの値を groupId + "." + artifactId に設定します。ただし、以下の例外があります。

  • groupId にセクションが 1 つしかない (ドットがない) 場合には、クラスを含む最初のパッケージ名が返されます。

    たとえば、グループ ID が commons-logging:commons-logging の場合、バンドルのシンボリック名は org.apache.commons.logging です。

  • ArtifactIdgroupId の最後のセクションと同じ場合には、groupId が使用されます。

    たとえば、POM がグループ ID およびアーティファクト ID を org.apache.maven:maven として指定すると、バンドルのシンボリック名は org.apache.maven になります。

  • ArtifactIdgroupId の最後のセクションで始まる場合には、その部分は削除されます。

    たとえば、POM がグループ ID およびアーティファクト ID を org.apache.maven:maven-core として指定すると、バンドルのシンボリック名は org.apache.maven.core になります。

バンドルのシンボリック名に独自の値を指定するには、例A.2「バンドルのシンボリック名の設定」に示すように、プラグインの instructions 要素に Bundle-SymbolicName の子を追加します。

例A.2 バンドルのシンボリック名の設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
     ...
    </instructions>
  </configuration>
</plugin>

バンドル名の設定

デフォルトでは、バンドルの名前は ${project.name} に設定されます。

バンドルの名前に独自の値を指定するには、例A.3「バンドル名の設定」に示すように、プラグインの instructions 要素に Bundle-Name の子を追加します。

例A.3 バンドル名の設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Name>JoeFred</Bundle-Name>
     ...
    </instructions>
  </configuration>
</plugin>

バンドルのバージョンの設定

デフォルトでは、バンドルのバージョンは ${project.version} に設定されます。ダッシュ (-) はピリオド (.) に置き換えられ、数字は 4 桁に変換されます。たとえば、4.2-SNAPSHOT4.2.0.SNAPSHOT になります。

バンドルのバージョンに独自の値を指定するには、例A.4「バンドルのバージョンの設定」に示すように、プラグインの instructions 要素に Bundle-Version の子を追加します。

例A.4 バンドルのバージョンの設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Version>1.0.3.1</Bundle-Version>
     ...
    </instructions>
  </configuration>
</plugin>

エクスポートされたパッケージの指定

デフォルトでは、OSGi マニフェストの Export-Package リストには、ローカルの Java ソースコード (src/main/java 下) のすべてのパッケージが反映されます。ただし、デフォルトのパッケージ、.、および .impl または .internal が含まれるすべてのパッケージを 除きます

重要

プラグイン設定で Private-Package 要素を使用し、エクスポートするパッケージの一覧を指定しない場合、デフォルトの動作ではバンドルの Private-Package 要素にリストされているパッケージのみが含まれます。パッケージはエクスポートされません。

デフォルトの動作では、パッケージが非常に大きくなり、非公開にしておく必要のあるパッケージがエクスポートされる可能性があります。エクスポートされるパッケージの一覧を変更するには、Export-Package の子をプラグインの instructions 要素に追加します。

Export-Package 要素は、バンドルに含まれるパッケージとエクスポートされるパッケージの一覧を指定します。パッケージ名は、* ワイルドカードシンボルを使用して指定できます。たとえば、エントリー com.fuse.demo.* は、プロジェクトのクラスパスにある com.fuse.demo で始まるすべてのパッケージが含まれます。

除外するパッケージを指定するには、エントリーに ! の接頭辞を追加します。たとえば、エントリー !com.fuse.demo.private は、パッケージ com.fuse.demo.private を除外します。

パッケージを除外する場合に、リスト内のエントリーの順序が重要です。リストは最初から順番に処理され、それ以降の矛盾するエントリーは無視されます。

たとえば、パッケージ com.fuse.demo.private を除く com.fuse.demo で始まるすべてのパッケージを含めるには、以下のようにパッケージのリストを指定します。

!com.fuse.demo.private,com.fuse.demo.*

ただし、com.fuse.demo.*,!com.fuse.demo.private を使用してパッケージを一覧表示すると、com.fuse.demo.private は最初のパターンと一致するため、バンドルに含まれます。

プライベートパッケージの指定

バンドルに追加するパッケージの一覧を指定してそれらをエクスポート しない 場合、バンドルプラグイン設定に Private-Package 命令を追加できます。デフォルトでは、Private-Package 命令を指定しないと、ローカルの Java ソースのすべてのパッケージがバンドルに含まれます。

重要

パッケージが Private-Package 要素と Export-Package 要素の両方のエントリーと一致する場合は、Export-Package 要素が優先されます。パッケージがバンドルに追加され、エクスポートされます。

Private-Package 要素は、バンドルに含まれるパッケージの一覧を指定する点で Export-Package 要素と同様に機能します。バンドルプラグインは、リストを使用して、バンドルに含まれるプロジェクトのクラスパスにあるすべてのクラスを検索します。これらのパッケージはバンドルにパッケージ化されますが、(Export-Package 命令で選択されない限り) エクスポートされません。

例A.5「プライベートパッケージのバンドルへの追加」 はバンドルにプライベートパッケージを含めるための設定です。

例A.5 プライベートパッケージのバンドルへの追加

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Private-Package>org.apache.cxf.wsdlFirst.impl</Private-Package>
     ...
    </instructions>
  </configuration>
</plugin>

インポートされたパッケージの指定

デフォルトでは、バンドルプラグインは OSGi マニフェストの Import-Package プロパティーに、バンドルのコンテンツによって参照されるすべてのパッケージのリストを反映させます。

ほとんどのプロジェクトでは通常、デフォルトの動作で十分ですが、リストに自動的に追加されないパッケージをインポートする場合があります。デフォルトの動作では、不要なパッケージがインポートされる可能性もあります。

バンドルによってインポートされるパッケージの一覧を指定するには、Import-Package の子をプラグインの instructions 要素に追加します。パッケージ一覧の構文は、Export-Package 要素および Private-Package 要素の場合と同じです。

重要

Import-Package 要素を使用する場合、必要なインポートの有無を判断するのにプラグインはバンドルの内容を自動的にスキャンしません。バンドルの内容がスキャンされるようにするには、パッケージリストの最後のエントリーとして * を配置する必要があります。

例A.6「バンドルでインポートされたパッケージの指定」 は、バンドルでインポートされたパッケージを指定する設定です。

例A.6 バンドルでインポートされたパッケージの指定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Import-Package>javax.jws, javax.wsdl, org.apache.cxf.bus, org.apache.cxf.bus.spring, org.apache.cxf.bus.resource, org.apache.cxf.configuration.spring, org.apache.cxf.resource, org.springframework.beans.factory.config, * </Import-Package>
     ...
   </instructions>
  </configuration>
</plugin>

補足情報

バンドルプラグインの設定の詳細には、以下を参照してください。

パート V. JAX-WS を使用したアプリケーションの開発

このガイドでは、標準の JAX-WS API を使用して Web サービスを開発する方法について説明します。

第24章 ボトムアップサービス開発

概要

サービス指向アプリケーションの一部として公開したい一連の機能をすでに実装している Java コードがある場合が多くあります。また、WSDL を使用してインターフェイスを定義することは避けたい場合もあります。JAX-WS アノテーションを使用して、Java クラスのサービスを有効にするために必要な情報を追加できます。WSDL コントラクトの代わりに使用できる サービスエンドポイントインターフェイス (SEI) を作成することもできます。WSDL コントラクトが必要な場合、Apache CXF には、注釈付きの Java コードからコントラクトを生成するためのツールが用意されています。

24.1. JAX-WS サービス開発の概要

Java から開始してサービスを作成するには、次のことを行う必要があります。

  1. 「SEI の作成」 サービスとして公開するメソッドを定義するサービスエンドポイントインターフェイス (SEI)。

    注記

    Java クラスから直接作業することもできますが、インターフェイスから作業することをお勧めします。インターフェイスは、サービスを使用するアプリケーションの開発を担当する開発者と共有するのに適しています。インターフェイスは小さく、サービスの実装の詳細は提供されません。

  2. 「コードに注釈を付ける」 コードに必要な注釈。
  3. 「WSDL の生成」 サービスの WSDL コントラクト。

    注記

    SEI をサービスのコントラクトとして使用する場合は、WSDL コントラクトを生成する必要はありません。

  4. 31章サービスの公開 サービスプロバイダーとしてのサービス。

24.2. SEI の作成

概要

サービスエンドポイントインターフェイス (SEI) は、サービス実装とそのサービスで要求を行うコンシューマーの間で共有される Java コードの一部です。SEI は、サービスによって実装されるメソッドを定義し、サービスがエンドポイントとして公開される方法に関する詳細を提供します。WSDL コントラクトを開始する場合、SEI はコードジェネレーターによって生成されます。ただし、Java から開始する場合は、SEI を作成するのは開発者の責任です。 SEI を作成するには、次の 2 つの基本的なパターンがあります。

  • グリーンフィールド開発 — このパターンでは、既存の Java コードまたは WSDL を使用せずに新しいサービスを開発しています。SEI を作成することから始めるのが最善です。次に、SEI を使用するサービスプロバイダーとコンシューマーの実装を担当する開発者に SEI を配布できます。

    注記

    グリーンフィールドサービス開発を行うための推奨される方法は、サービスとそのインターフェイスを定義する WSDL コントラクトを作成することから始めることです。26章開始点の WSDL コントラクトを参照してください。

  • サービスの有効化—このパターンでは、通常、Java クラスとして実装されている既存の機能セットがあり、サービスを有効にします。これは、次の 2 つのことを行う必要があることを意味します。

    1. サービスの一部として公開される予定の操作 のみ を含む SEI を作成します。
    2. SEI を実装するように、既存の Java クラスを変更します。

      注記

      JAX-WS アノテーションを Java クラスに追加することはできますが、お勧めしません。

インターフェイスの作成

SEI は標準の Java インターフェイスです。クラスが実装する一連のメソッドを定義します。また、実装クラスがアクセスできるいくつかのメンバーフィールドと定数を定義することもできます。

SEI の場合、定義されたメソッドは、サービスによって公開される操作にマップされることを目的としています。SEI は wsdl:portType 要素に対応します。SEI で定義されたメソッドは、wsdl:portType 要素の wsdl:operation 要素に対応します。

注記

JAX-WS は、サービスの一部として公開されていないメソッドを指定できるようにするアノテーションを定義します。ただし、ベストプラクティスは、これらのメソッドを SEI から除外することです。

例24.1「シンプルな SEI」 は、株式更新サービスの簡単な SEI を示しています。

例24.1 シンプルな SEI

package com.fusesource.demo;

public interface quoteReporter
{
  public Quote getQuote(String ticker);
}

インターフェイスの実装

SEI は標準の Java インターフェイスであるため、SEI を実装するクラスは標準の Java クラスです。Java クラスから始める場合は、インターフェイスを実装するために Java クラスを変更する必要があります。SEI から始める場合、実装クラスは SEI を実装します。

例24.2「単純な実装クラス」 にインターフェイスを実装するためのクラスを示します例24.1「シンプルな SEI」

例24.2 単純な実装クラス

package com.fusesource.demo;

import java.util.*;

public class stockQuoteReporter implements quoteReporter
{
  ...
public Quote getQuote(String ticker)
  {
    Quote retVal = new Quote();
    retVal.setID(ticker);
    retVal.setVal(Board.check(ticker));[1]
    Date retDate = new Date();
    retVal.setTime(retDate.toString());
    return(retVal);
  }
}


[1] Board is an assumed class whose implementation is left to the reader.

24.3. コードに注釈を付ける

24.3.1. JAX-WS アノテーションの概要

JAX-WS アノテーションは、SEI を完全に指定されたサービス定義にマップするために使用されるメタデータを指定します。注釈で提供される情報には、次のものがあります。

  • サービスのターゲット名前空間。
  • リクエストメッセージを保持するために使用されるクラスの名前
  • 応答メッセージを保持するために使用されるクラスの名前
  • 操作が一方向操作の場合
  • サービスが使用するバインディングスタイル
  • カスタム例外に使用されるクラスの名前
  • サービスによって使用されるタイプが定義される名前空間
注記

ほとんどの注釈には適切なデフォルトがあり、それらに値を指定する必要はありません。ただし、アノテーションで提供する情報が多いほど、サービス定義がより適切に指定されます。明確に指定されたサービス定義は、分散