SOAP データ・ハンドラーの処理

SOAP データ・ハンドラーは、SOAP メッセージとビジネス・オブジェクトの間の変換を次の方法で実行します。

SOAP 本文メッセージからビジネス・オブジェクトへの処理

このセクションでは、SOAP 本文メッセージからビジネス・オブジェクトへの変換 について、段階を追って説明します。

  1. SOAP データ・ハンドラーが SOAP メッセージを受け取ります。
  2. データ・ハンドラーは、Apache SOAP API を使用して、SOAP メッセージを解析します。
  3. データ・ハンドラーは、SOAP メッセージのコンポーネントであるエンベロープ、ヘッダー、および本文を抽出します。
  4. ヘッダーの処理 詳しくは、SOAP ヘッダー・メッセージからビジネス・オブジェクトへの処理を参照してください。
  5. 本文の処理 データ・ハンドラーは、SOAP 本文が障害に関するものか、データの通知かを確認するため、SOAP 本文の最初の要素を読み取ります。本文の内容が障害でない場合には、データ・ハンドラーは次の処理を実行します。
    1. どのビジネス・オブジェクトが変換に使用されるのかを判別するために、ビジネス・オブジェクト解決を実行します。カスタム名前ハンドラーが構成されている場合には、下記のデフォルトのビジネス・オブジェクト解決は適用されません。プラグ可能な名前ハンドラーの指定については、プラグ可能な名前ハンドラーの指定を参照してください。
    2. データ・ハンドラーは、変換に使用される SOAP 構成 MO (データ・ハンドラーが 作成している SOAP ビジネス・オブジェクトの子) も解決します。SOAP 構成 MO のインスタンスが存在しない場合、データ・ハンドラーはインスタンスを作成し、そのデフォルト値を読み取ります。データ・ハンドラーは、ConfigMO の属性値からビジネス・オブジェクトの動詞を 読み取ります。データ・ハンドラーは SOAP ビジネス・オブジェクトのインスタンスを生成し、該当の動詞を設定します。このビジネス・オブジェクトは、データ・ハンドラーが SOAP メッセージの書き込みを試みる対象となります。
    3. データ・ハンドラーは、一度に 1 要素ずつ SOAP メッセージの構文解析を続行します。rpc の場合、データ・ハンドラーは、先頭の要素を親と判断します。
    4. データ・ハンドラーは、ビジネス・オブジェクト (またはそのアプリケーション固有情報、詳しくは ビジネス・オブジェクトから SOAP メッセージへの変換における ASIを参照) の属性の名前が、子要素と同じであるものと想定します。その属性がビジネス・オブジェクトから見つからない場合、データ・ハンドラーは例外をスローします。子要素は、単純タイプの場合と複合タイプの場合があります。複合要素とは、子要素を持つ要素のことです。
    5. 単純要素 子要素が単純要素の場合、デフォルトでは、データ・ハンドラーは、ビジネス・オブジェクト属性が 単純要素のビジネス・オブジェクト属性と同じ名前 (または ASI) であることを想定します。データ・ハンドラーは単純要素の値を読み取り、ビジネス・オブジェクトにその値を 設定します。
    6. 複合要素 子要素が複合タイプの要素である場合、データ・ハンドラーは、ビジネス・オブジェクトの属性の名前 (または ASI) および型が子ビジネス・オブジェクトのもの と同じであるものと想定します。この属性は、複合 SOAP 要素が存在するか、それとも SOAP 配列が存在するかによって、単一カーディナリティーの場合と複数カーディナリティーの場合があります。次に、データ・ハンドラーは子ビジネス・オブジェクトのインスタンスを作成し (デフォルト では、属性の型に応じて子ビジネス・オブジェクトの名前が決まります)、この複合要素のすべての子要素を読み取って、子ビジネス・オブジェクトの それらの値を設定します。データ・ハンドラーは、親ビジネス・オブジェクト属性のカーディナリティー を検査した後で、この子ビジネス・オブジェクトを親ビジネス・オブジェクト属性に 組み込みます。属性がカーディナリティー n の場合、データ・ハンドラーは、このビジネス・オブジェクトをコンテナーに追加します。複合要素の子要素は、単純要素の場合と複合要素の場合とがあります。これらも、同じように扱われます。単純要素である場合には、データ・ハンドラーは値を子ビジネス・オブジェクトで設定し、複合要素である場合には、データ・ハンドラーは子ビジネス・オブジェクトのインスタンス を作成します。
  6. 障害の処理 データ・ハンドラーは、SOAP 本文の 最初の要素の名前を読み取り、SOAP 本文が障害に関するものかどうかを判別します。最初の要素の名前が Fault の場合、データ・ハンドラーはこれが障害メッセージであると認識します。 この障害メッセージをどのビジネス・オブジェクトに変換するのかを決定するために、障害ビジネス・オブジェクトの解決が行われます。その後データ・ハンドラーは、本文の処理の場合と同じ処理を行います。データ・ハンドラーは、子ビジネス・オブジェクトで指定された ビジネス・オブジェクトが以下の属性を備えているものと想定します。
    1. faultcode: 必須。String 属性
    2. faultstring: 必須。String 属性
    3. faultactor: 任意。String 属性
    4. detail: 任意。子ビジネス・オブジェクト
  7. なんらかの理由で障害処理が失敗した場合、スローされる例外には、SOAP 障害メッセージの faultcode、faultstring、および faultactor 要素から得られたテキストが含まれます。

注:
障害メッセージに関する SOAP 仕様によると、faultcode、faultstring、および faultactor は単純要素であり、detail は複合要素 (子要素を含む要素) です。また、faultcode、faultstring、faultactor、および detail は SOAP エンベロープ・ネーム・スペース に属しますが、detail 子要素はユーザー定義のネーム・スペースに属することもあります。

SOAP ヘッダー・メッセージからビジネス・オブジェクトへの処理

ここでは、データ・ハンドラーによる SOAP メッセージのヘッダーからビジネス・オブジェクトへの変換の方法について説明します。

  1. SOAP データ・ハンドラーは SOAP メッセージの本文を処理します。本文の処理により SOAP ビジネス・オブジェクトが作成されます。
  2. SOAP メッセージに SOAP ヘッダー要素があると、SOAP データ・ハンドラーは、本文の処理の結果生成されたビジネス・オブジェクト内に SOAP ヘッダー属性が存在すると想定します。SOAPHeader 属性は、ビジネス・オブジェクトの子属性であり、soap_location=SOAPHeader をそのアプリケーション固有の情報として持っています。このような属性が存在しない場合、SOAP データ・ハンドラーはエラーをスローします。SOAPHeader 属性は、SOAP ヘッダー・コンテナー・ビジネス・オブジェクトの型であることが必要です。SOAP データ・ハンドラーは、ステップ 1 で取得した SOAP ビジネス・オブジェクト内に、この属性のインスタンスを作成します。
  3. SOAP-Env:Header 要素の直接の子それぞれに対して、次の処理が実行されます。
    1. データ・ハンドラーは、SOAP ヘッダー・コンテナー・ビジネス・オブジェクト内に子属性が存在すると想定します。この属性の名前は、ヘッダー要素の名前と同じであること、および SOAP ヘッダー子ビジネス・オブジェクトに準拠していることが必要です。このような属性を見つけることができない場合、データ・ハンドラーはエラーをスローします。 さらに、ネーム・スペースこの要素のネーム・スペースは、この属性の elem_ns アプリケーション固有情報に指定されたネーム・スペースと同じです。同じでない場合、データ・ハンドラーはエラーをスローします。
    2. データ・ハンドラーは SOAP ヘッダー子ビジネス・オブジェクトのインスタンスを作成し、ステップ 2 で 作成された SOAP ヘッダー・コンテナー・ビジネス・オブジェクトのインスタンスにこれを格納します。
    3. このヘッダー要素に actor 属性がある場合、データ・ハンドラーは、actor 属性が上記で作成された子ビジネス・オブジェクト内に存在すると想定します。actor 属性が見つからない場合、データ・ハンドラーはエラーをスローします。
      注:
      actor 属性を追加する必要がある場合は、SOAP 属性の指定を参照してください。
    4. このヘッダー要素に mustUnderstand 属性がある場合、データ・ハンドラーは、上記で作成された子ビジネス・オブジェクト内に mustUnderstand 属性が存在すると想定します。mustUnderstand 属性が見つからないと、データ・ハンドラーはエラーをスローします。
      注:
      mustUnderstand 属性を追加する必要がある場合は、SOAP 属性の指定を参照してください。
    5. このヘッダー要素の各子要素について、データ・ハンドラーは、子ビジネス・オブジェクト内に同じ名前の属性が存在すると想定します。これらの要素は、SOAP-Env:Body 要素の子要素と同じ方法で処理されます。

ビジネス・オブジェクトから SOAP メッセージ本文への処理

ビジネス・オブジェクトから SOAP メッセージ本文への変換は、次のような手順を経て実行されます。アプリケーション固有情報が使用される特殊なケース については、ビジネス・オブジェクトから SOAP メッセージへの変換における ASIを参照してください。

  1. SOAP データ・ハンドラーは、変換対象の SOAP ビジネス・オブジェクト に対応する SOAP 構成 MO を探します。
  2. データ・ハンドラーは、SOAP メッセージのエンベロープとヘッダーを作成します。
  3. データ・ハンドラーは SOAP 構成 MO を解決します。SOAP 構成 MO のインスタンスが存在しない場合、データ・ハンドラーはインスタンスを作成し、デフォルト値を読み取ります。デフォルトでは、データ・ハンドラーは、SOAP 構成 MO の BodyName 属性の値を読み取って、処理しているビジネス・オブジェクトが障害ビジネス・オブジェクトであるかどうかを判別します。この値が soap:fault に設定されている場合には、そのビジネス・オブジェクトは SOAP 障害ビジネス・オブジェクトであるとみなされます。それが障害ビジネス・オブジェクトでない場合、データ・ハンドラーは、下記の『本文の作成』で述べられた処理を行い、それ以外の場合には『障害メッセージの作成』で 述べられた処理を行います。
  4. 本文の作成 データ・ハンドラーがビジネス・オブジェクト から SOAP メッセージの本文を作成するために行う処理について、以下のステップで詳しく説明します。
  5. 障害メッセージの作成 以下のセクションでは、データ・ハンドラーが障害メッセージを作成するプロセスについて、順に説明します。
  6. CxIgnore の処理 データ・ハンドラーは、属性の値が CxIgnore に設定されていることを検出した場合には、この属性に対応する要素を作成しません。
  7. CxBlank の処理 データ・ハンドラーは、属性の値が CxBlank に設定されていることを判別した場合には、この属性に対応する要素を作成しますが、その値を設定しません。

ビジネス・オブジェクトから SOAP メッセージ・ヘッダーへの処理

このセクションでは SOAP ヘッダー属性の処理についてのみ説明します。他のすべての属性は、ビジネス・オブジェクトから SOAP メッセージ本文への処理で説明されているとおりに処理されます。

  1. SOAP データ・ハンドラーは、ビジネス・オブジェクトから SOAPHeader 属性を取得します。この属性には、そのアプリケーション固有情報として、soap_location=SOAPHeader があります。SOAP データ・ハンドラーは、この属性の値がヌル以外のときに限って、SOAP-Env:Header 要素を作成します。ビジネス・オブジェクトに複数の SOAPHeader 属性が格納されている場合、最初の属性のみが処理され、残りは本文の一部として扱われます。
  2. SOAP データ・ハンドラーは、SOAPHeader 属性が、SOAP Header Container ビジネス・オブジェクトを表す単一カーディナリティーの子であると想定します。データ・ハンドラーは、SOAP Header Container ビジネス・オブジェクトの属性の中で、SOAP Header Child ビジネス・オブジェクトの型の属性を処理します。
  3. SOAP Header Container ビジネス・オブジェクトの各属性に対して、データ・ハンドラーは次の処理を実行します。
    1. カーディナリティーをチェックし、この属性がカーディナリティー 1 の子オブジェクトでもカーディナリティー n の子オブジェクトでもなければ、その属性を無視します。
    2. 値をチェックし、この属性の値が NULL であれば、その属性を無視します。
    3. 属性がカーディナリティー 1 または n の子オブジェクトの場合、SOAP データ・ハンドラーは、ステップ 1 で作成された SOAP-Env:Header 要素の直接の子であるヘッダー要素を作成します。このヘッダー要素の名前は属性の名前と同じです。この要素のネーム・スペースは、この属性の elem_ns アプリケーション固有情報により指定されます。
    4. 属性が SOAP Header Child ビジネス・オブジェクトであれば、このビジネス・オブジェクトのすべての属性が処理されます。この属性は actor および mustUnderstand 属性を持つ場合があります。
      注:
      mustUnderstand 属性または actor 属性を追加する必要がある場合は、SOAP 属性の指定を参照してください。
    5. SOAP Header Child ビジネス・オブジェクトにヌル以外の actor 属性が存在する場合、データ・ハンドラーは、ステップ c で作成されたヘッダー要素内に actor 属性を作成します。
    6. SOAP Header Child ビジネス・オブジェクトにヌル以外の mustUnderstand 属性が存在する場合、データ・ハンドラーは、ステップ c で作成されたヘッダー要素内に mustUnderstand 属性を作成します。
    7. SOAP Header Child ビジネス・オブジェクトのヌル以外のその他すべての属性は、このヘッダー要素の子要素となります。これらの要素は、SOAP-Env:Body 要素の子要素と同じ方法で構成されます。

ヘッダー障害の処理

SOAP の仕様では、ヘッダーに関するエラーはヘッダーで戻さなければならないと規定されています。このようなヘッダーは、SOAP 障害メッセージで戻します。メッセージ・ヘッダーが要求および応答のビジネス・オブジェクトの SOAPHeader 属性で指定されるように、障害ヘッダーは、障害ビジネス・オブジェクトの SOAPHeader 属性で指定されます。

要求ビジネス・オブジェクトまたは応答ビジネス・オブジェクトに付くどのヘッダーも、エラーの発生を招くことがあります。このようなエラーは、障害メッセージのヘッダーに報告されます。

WSDL 文書には SOAP バインディング・ヘッダー障害要素があり、これを使用することにより、障害ヘッダーを指定することができます。詳しくは、第 1 章に表で示した SOAP 仕様および WSDL 仕様を参照してください。

headerfault のアプリケーション固有情報により、各ヘッダーの障害を指定することができます。SOAP Header Container ビジネス・オブジェクトの各属性について、headerfault アプリケーション固有情報を指定できます。障害ビジネス・オブジェクトに対する SOAP Header Container ビジネス・オブジェクト内の属性リストは次のとおりです。

headerfault=attr1, attr2, attr3...

WSDL 構成ウィザードにより、要求または応答オブジェクトの SOAP Header Child ビジネス・オブジェクト内に headerfault アプリケーション固有情報が検出されると、このユーティリティーは、これらのヘッダーのために生成された WSDL の中に headerfault 要素を作成します。WSDL では、要求 (入力) ヘッダーおよび応答 (出力) ヘッダーのそれぞれに対して、複数のヘッダー障害を指定することができます。したがって、アプリケーション固有情報の値は、コンマ区切りの属性リストです。

Copyright IBM Corp. 2004, 2005