パッケージ jakarta.xml.soap

SOAP メッセージを作成および構築するための API を提供します。このパッケージは、Jakarta SOAP withAttachments 仕様で定義されています。

jakarta.xml.soap パッケージの API を使用すると、次のことができます。

  • 指定されたエンドポイントへのポイントツーポイント接続を作成します
  • SOAP メッセージを作成する
  • XML フラグメントを作成する
  • SOAP メッセージのヘッダーにコンテンツを追加する
  • SOAP メッセージの本文にコンテンツを追加する
  • アタッチメントパーツを作成し、それらにコンテンツを追加します
  • SOAP メッセージの一部にアクセス / 追加 / 変更する
  • SOAP 障害情報の作成 / 追加 / 変更
  • SOAP メッセージからコンテンツを抽出する
  • SOAP リクエスト / レスポンスメッセージを送信します

このドキュメントでの SAAJ への参照は、特に明記されていない限り、添付ファイル API を備えた Jakarta SOAP を指します。
このドキュメントでの JAXB への参照は、特に明記されていない限り、Jakarta XML Binding を指します。

さらに、jakarta.xml.soap パッケージの API は、org.w3c.dom パッケージの対応する API を継承します。これは、SOAPMessage の SOAPPart も DOM レベル 2 Document であり、DOM を使用するアプリケーション、ツール、ライブラリによってそのように操作できることを意味します（詳細については、http://www.w3.org/DOM/ を参照してください）。DOM API を使用して通常の DOM ノードを SAAJ ツリーに追加することは可能ですが、ツリーを調べたり操作したりする場合は、SAAJAPI が SAAJ 型を返す必要があることに注意してください。これを実現するために、SAAJ API（具体的には SOAPElement.getChildElements()）は、SAAJ 要件に関連して誤って型付けされたオブジェクトを、必要な型の同等のオブジェクトにサイレントに置き換えることができます。これらの置換によってツリーの論理構造が変更されることは決してないため、DOM API の観点からは、ツリーは変更されません。ただし、ツリーの物理的構成が変更され、置き換えられたノードへの参照は、ツリーの一部ではなくなったノードを参照するようになります。SAAJ API は、必要がない場合はこれらの置換を行うことを許可されていないため、置換オブジェクトがその後 SAAJAPI への呼び出しによってサイレントに置換されることはありません。

これが実際に意味することは、DOMAPI を使用してツリーを操作した後にツリーで SAAJAPI の使用を開始するアプリケーションは、ツリーがすべての SAAJ ツリーに変換され、ツリー内のオブジェクトへの参照が取得されたと想定する必要があるということです。DOMAPI の使用は無効になりました。SAAJAPI から DOMAPI に切り替えると、無効な参照が発生することは許可されておらず、SAAJAPI を排他的に使用することもできません。無効な参照のリスクを引き起こすのは、特定の SAAJ ツリーでの DOMAPI の使用から SAAJAPI の使用への切り替えのみです。

SAAJ 実装の発見

特定の実装を検出してロードするために、SAAJAPI で定義されているいくつかのファクトリがあります。

最初の 3 つは、一般的なルックアップ手順を使用して実装クラスを決定する newInstance() メソッドを定義します。
  • ファクトリクラスと同じ名前のシステムプロパティが設定されているかどうかを確認します（例: jakarta.xml.soap.SOAPFactory）。そのようなプロパティが存在する場合、その値は実装クラスの完全修飾名であると見なされます。ルックアップのこのフェーズでは、SAAJ 実装の JVM ごとのオーバーライドが有効になります。
  • ServiceLoaderSE クラスで定義されているサービスプロバイダーのロード機能を使用して、デフォルトのロードメカニズムSEを使用してサービスの実装を見つけてロードしようとします。
  • 最後に、上記のすべての手順が失敗した場合、SAAJMetaFactory インスタンスを使用して特定の実装を見つけるか（MessageFactory および SOAPFactory の場合）、プラットフォームのデフォルトの実装を使用します（SOAPConnectionFactory）。SAAJMetaFactory が使用されるときはいつでも、実際のインスタンスを取得するためのルックアップ手順が実行されます。