SOAP データ・ハンドラーは、SOAP メッセージとビジネス・オブジェクトの間の変換を次の方法で実行します。
このセクションでは、SOAP 本文メッセージからビジネス・オブジェクトへの変換について、段階を追って説明します。
- SOAP データ・ハンドラーが SOAP メッセージを受け取ります。
- データ・ハンドラーは、Apache SOAP API を使用して、SOAP メッセージを解析します。
- データ・ハンドラーは、SOAP メッセージのコンポーネントであるエンベロープ、ヘッダー、および本文を抽出します。
- ヘッダーの処理 詳しくは、SOAP ヘッダー・メッセージからビジネス・オブジェクトへの処理を参照してください。
- 本文の処理 データ・ハンドラーは、SOAP 本文が障害に関するものか、データの通知かを確認するため、SOAP 本文の最初の要素を読み取ります。本文の内容が障害でない場合には、データ・ハンドラーは次の処理を実行します。
- どのビジネス・オブジェクトが変換に使用されるのかを判別するために、ビジネス・オブジェクト解決を実行します。カスタム名前ハンドラーが構成されている場合には、下記のデフォルトのビジネス・オブジェクト解決は適用されません。プラグ可能な名前ハンドラーの指定については、プラグ可能な名前ハンドラーの指定を参照してください。
- データ・ハンドラーは、変換に使用される SOAP 構成 MO (データ・ハンドラーが作成している SOAP ビジネス・オブジェクトの子) も解決します。SOAP 構成 MO のインスタンスが存在しない場合、データ・ハンドラーはインスタンスを作成し、そのデフォルト値を読み取ります。データ・ハンドラーは、ConfigMO の属性値からビジネス・オブジェクトの動詞を読み取ります。データ・ハンドラーは SOAP ビジネス・オブジェクトのインスタンスを生成し、該当の動詞を設定します。このビジネス・オブジェクトは、データ・ハンドラーが SOAP メッセージの書き込みを試みる対象となります。
- データ・ハンドラーは、一度に 1 要素ずつ SOAP メッセージの構文解析を続行します。rpc の場合、データ・ハンドラーは、先頭の要素を親と判断します。
- データ・ハンドラーは、ビジネス・オブジェクト (またはそのアプリケーション固有情報、詳しくは ビジネス・オブジェクトから SOAP メッセージへの変換における ASIを参照) の属性の名前が、子要素と同じであるものと想定します。その属性がビジネス・オブジェクトから見つからない場合、データ・ハンドラーは例外をスローします。子要素は、単純タイプの場合と複合タイプの場合があります。複合要素とは、子要素を持つ要素のことです。
- 単純要素 子要素が単純要素の場合、デフォルトでは、データ・ハンドラーは、ビジネス・オブジェクト属性が単純要素のビジネス・オブジェクト属性と同じ名前 (または ASI) であることを想定します。データ・ハンドラーは単純要素の値を読み取り、ビジネス・オブジェクトにその値を設定します。
- 複合要素 子要素が複合タイプの要素である場合、データ・ハンドラーは、ビジネス・オブジェクトの属性の名前 (または ASI) および型が子ビジネス・オブジェクトのものと同じであるものと想定します。この属性は、複合 SOAP 要素が存在するか、それとも SOAP 配列が存在するかによって、単一カーディナリティーの場合と複数カーディナリティーの場合があります。次に、データ・ハンドラーは子ビジネス・オブジェクトのインスタンスを作成し (デフォルトでは、属性の型に応じて子ビジネス・オブジェクトの名前が決まります)、この複合要素のすべての子要素を読み取って、子ビジネス・オブジェクトのそれらの値を設定します。データ・ハンドラーは、親ビジネス・オブジェクト属性のカーディナリティーを検査した後で、この子ビジネス・オブジェクトを親ビジネス・オブジェクト属性に組み込みます。属性がカーディナリティー n の場合、データ・ハンドラーは、このビジネス・オブジェクトをコンテナーに追加します。複合要素の子要素は、単純要素の場合と複合要素の場合とがあります。これらも、同じように扱われます。単純要素である場合には、データ・ハンドラーは値を子ビジネス・オブジェクトで設定し、複合要素である場合には、データ・ハンドラーは子ビジネス・オブジェクトのインスタンスを作成します。
- 障害の処理 データ・ハンドラーは、SOAP 本文の最初の要素の名前を読み取り、SOAP 本文が障害に関するものかどうかを判別します。最初の要素の名前が Fault の場合、データ・ハンドラーはこれが障害メッセージであると認識します。この障害メッセージをどのビジネス・オブジェクトに変換するのかを決定するために、障害ビジネス・オブジェクトの解決が行われます。その後データ・ハンドラーは、本文の処理の場合と同じ処理を行います。データ・ハンドラーは、子ビジネス・オブジェクトで指定されたビジネス・オブジェクトが以下の属性を備えているものと想定します。
- faultcode: 必須。String 属性
- faultstring: 必須。String 属性
- faultactor: 任意。String 属性
- detail: 任意。子ビジネス・オブジェクト
- なんらかの理由で障害処理が失敗した場合、スローされる例外には、SOAP 障害メッセージの faultcode、faultstring、および faultactor 要素から得られたテキストが含まれます。
- 注:
- 障害メッセージに関する SOAP 仕様によると、faultcode、faultstring、および faultactor は単純要素であり、detail は複合要素 (子要素を含む要素) です。また、faultcode、faultstring、faultactor、および detail は SOAP エンベロープ・ネーム・スペースに属しますが、detail 子要素はユーザー定義のネーム・スペースに属することもあります。
ここでは、データ・ハンドラーによる SOAP メッセージのヘッダーからビジネス・オブジェクトへの変換の方法について説明します。
- SOAP データ・ハンドラーは SOAP メッセージの本文を処理します。本文の処理により SOAP ビジネス・オブジェクトが作成されます。
- SOAP メッセージに SOAP ヘッダー要素があると、SOAP データ・ハンドラーは、本文の処理の結果生成されたビジネス・オブジェクト内に SOAP ヘッダー属性が存在すると想定します。SOAPHeader 属性は、ビジネス・オブジェクトの子属性であり、soap_location=SOAPHeader をそのアプリケーション固有の情報として持っています。このような属性が存在しない場合、SOAP データ・ハンドラーはエラーをスローします。SOAPHeader 属性は、SOAP ヘッダー・コンテナー・ビジネス・オブジェクトの型であることが必要です。SOAP データ・ハンドラーは、ステップ 1 で取得した SOAP ビジネス・オブジェクト内に、この属性のインスタンスを作成します。
- SOAP-Env:Header 要素の直接の子それぞれに対して、次の処理が実行されます。
- データ・ハンドラーは、SOAP ヘッダー・コンテナー・ビジネス・オブジェクト内に子属性が存在すると想定します。この属性の名前は、ヘッダー要素の名前と同じであること、および SOAP ヘッダー子ビジネス・オブジェクトに準拠していることが必要です。このような属性を見つけることができない場合、データ・ハンドラーはエラーをスローします。さらに、ネーム・スペースこの要素のネーム・スペースは、この属性の elem_ns アプリケーション固有情報に指定されたネーム・スペースと同じです。同じでない場合、データ・ハンドラーはエラーをスローします。
- データ・ハンドラーは SOAP ヘッダー子ビジネス・オブジェクトのインスタンスを作成し、ステップ 2 で作成された SOAP ヘッダー・コンテナー・ビジネス・オブジェクトのインスタンスにこれを格納します。
- このヘッダー要素に actor 属性がある場合、データ・ハンドラーは、actor 属性が上記で作成された子ビジネス・オブジェクト内に存在すると想定します。actor 属性が見つからない場合、データ・ハンドラーはエラーをスローします。
- 注:
- actor 属性を追加する必要がある場合は、SOAP 属性の指定を参照してください。
- このヘッダー要素に mustUnderstand 属性がある場合、データ・ハンドラーは、上記で作成された子ビジネス・オブジェクト内に mustUnderstand 属性が存在すると想定します。mustUnderstand 属性が見つからないと、データ・ハンドラーはエラーをスローします。
- 注:
- mustUnderstand 属性を追加する必要がある場合は、SOAP 属性の指定を参照してください。
- このヘッダー要素の各子要素について、データ・ハンドラーは、子ビジネス・オブジェクト内に同じ名前の属性が存在すると想定します。これらの要素は、SOAP-Env:Body 要素の子要素と同じ方法で処理されます。
ビジネス・オブジェクトから SOAP メッセージ本文への変換は、次のような手順を経て実行されます。アプリケーション固有情報が使用される特殊なケースについては、ビジネス・オブジェクトから SOAP メッセージへの変換における ASIを参照してください。
- SOAP データ・ハンドラーは、変換対象の SOAP ビジネス・オブジェクトに対応する SOAP 構成 MO を探します。
- データ・ハンドラーは、SOAP メッセージのエンベロープとヘッダーを作成します。
- データ・ハンドラーは SOAP 構成 MO を解決します。SOAP 構成 MO のインスタンスが存在しない場合、データ・ハンドラーはインスタンスを作成し、デフォルト値を読み取ります。デフォルトでは、データ・ハンドラーは、SOAP 構成 MO の BodyName 属性の値を読み取って、処理しているビジネス・オブジェクトが障害ビジネス・オブジェクトであるかどうかを判別します。この値が soap:fault に設定されている場合には、そのビジネス・オブジェクトは SOAP 障害ビジネス・オブジェクトであるとみなされます。それが障害ビジネス・オブジェクトでない場合、データ・ハンドラーは、下記の『本文の作成』で述べられた処理を行い、それ以外の場合には『障害メッセージの作成』で述べられた処理を行います。
- 本文の作成 データ・ハンドラーがビジネス・オブジェクトから SOAP メッセージの本文を作成するために行う処理について、以下のステップで詳しく説明します。
- データ・ハンドラーは、SOAP 構成 MO 属性から BodyName および BodyNS を入手してから、SOAP メッセージ本文の最初の (親) 要素を作成します。デフォルトでは、最初の要素の名前は BodyName の値になります。本書では、これを本文要素とも呼びます。本文要素のネーム・スペースは、デフォルトでは BodyNS について決められた値となります。SOAP 構成 MO の Style 属性が document に設定されている場合、このステップ (最初の本文要素の作成) はスキップされます。
- データ・ハンドラーはビジネス・オブジェクトの属性を読み取り、それら属性を型ごとに処理します。各型の属性の処理について以下で説明します。
- 障害メッセージの作成 以下のセクションでは、データ・ハンドラーが障害メッセージを作成するプロセスについて、順に説明します。
- CxIgnore の処理 データ・ハンドラーは、属性の値が CxIgnore に設定されていることを検出した場合には、この属性に対応する要素を作成しません。
- CxBlank の処理 データ・ハンドラーは、属性の値が CxBlank に設定されていることを判別した場合には、この属性に対応する要素を作成しますが、その値を設定しません。
このセクションでは SOAP ヘッダー属性の処理についてのみ説明します。他のすべての属性は、"ビジネス・オブジェクトから SOAP メッセージ本文への処理"で説明されているとおりに処理されます。
- SOAP データ・ハンドラーは、ビジネス・オブジェクトから SOAPHeader 属性を取得します。この属性には、そのアプリケーション固有情報として、soap_location=SOAPHeader があります。SOAP データ・ハンドラーは、この属性の値がヌル以外のときに限って、SOAP-Env:Header 要素を作成します。ビジネス・オブジェクトに複数の SOAPHeader 属性が格納されている場合、最初の属性のみが処理され、残りは本文の一部として扱われます。
- SOAP データ・ハンドラーは、SOAPHeader 属性が、SOAP Header Container ビジネス・オブジェクトを表す単一カーディナリティーの子であると想定します。データ・ハンドラーは、SOAP Header
Container ビジネス・オブジェクトの属性の中で、SOAP Header
Child ビジネス・オブジェクトの型の属性を処理します。
- SOAP Header Container ビジネス・オブジェクトの各属性に対して、データ・ハンドラーは次の処理を実行します。
- カーディナリティーをチェックし、この属性がカーディナリティー 1 の子オブジェクトでもカーディナリティー n の子オブジェクトでもなければ、その属性を無視します。
- 値をチェックし、この属性の値が NULL であれば、その属性を無視します。
- 属性がカーディナリティー 1 または n の子オブジェクトの場合、SOAP データ・ハンドラーは、ステップ 1 で作成された SOAP-Env:Header 要素の直接の子であるヘッダー要素を作成します。このヘッダー要素の名前は属性の名前と同じです。この要素のネーム・スペースは、この属性の elem_ns アプリケーション固有情報により指定されます。
- 属性が SOAP Header Child ビジネス・オブジェクトであれば、このビジネス・オブジェクトのすべての属性が処理されます。この属性は actor および mustUnderstand 属性を持つ場合があります。
- 注:
- mustUnderstand 属性または actor 属性を追加する必要がある場合は、SOAP 属性の指定を参照してください。
- SOAP Header Child ビジネス・オブジェクトにヌル以外の actor 属性が存在する場合、データ・ハンドラーは、ステップ c で作成されたヘッダー要素内に actor 属性を作成します。
- SOAP Header Child ビジネス・オブジェクトにヌル以外の mustUnderstand 属性が存在する場合、データ・ハンドラーは、ステップ c で作成されたヘッダー要素内に mustUnderstand 属性を作成します。
- 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 では、要求 (入力) ヘッダーおよび応答 (出力) ヘッダーのそれぞれに対して、複数のヘッダー障害を指定することができます。したがって、アプリケーション固有情報の値は、コンマ区切りの属性リストです。
