パッケージ jakarta.xml.soap

クラス SOAPMessage

  • public abstract class SOAPMessage
extends ObjectSE
    すべての SOAP メッセージのルートクラス。「ワイヤー」で送信されるように、SOAP メッセージは XML ドキュメントまたは MIME メッセージであり、その最初の本文部分は XML/SOAP ドキュメントです。

    SOAPMessage オブジェクトは、SOAP パーツと、オプションで 1 つ以上のアタッチメントパーツで構成されます。SOAPMessage オブジェクトの SOAP 部分は SOAPPart オブジェクトであり、メッセージのルーティングと識別に使用される情報が含まれ、アプリケーション固有のコンテンツを含めることができます。メッセージの SOAP 部分のすべてのデータは、XML 形式である必要があります。

    新しい SOAPMessage オブジェクトには、デフォルトで次のものが含まれています。

    • SOAPPart オブジェクト
    • SOAPEnvelope オブジェクト
    • SOAPBody オブジェクト
    • SOAPHeader オブジェクト
    メッセージの SOAP 部分は、メソッド SOAPMessage.getSOAPPart() を呼び出すことで取得できます。SOAPEnvelope オブジェクトは SOAPPart オブジェクトから取得され、SOAPEnvelope オブジェクトは SOAPBody および SOAPHeader オブジェクトを取得するために使用されます。
    
     SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     SOAPBody sb = se.getBody();
     SOAPHeader sh = se.getHeader();

    必須の SOAPPart オブジェクトに加えて、SOAPMessage オブジェクトには 0 個以上の AttachmentPart オブジェクトが含まれる場合があり、各オブジェクトにはアプリケーション固有のデータが含まれます。SOAPMessage インターフェースは、AttachmentPart オブジェクトを作成し、SOAPMessage オブジェクトに追加するためのメソッドを提供します。SOAPMessage オブジェクトを受け取ったパーティは、個々のアタッチメントパーツを取得することでその内容を調べることができます。

    他の SOAP メッセージとは異なり、添付ファイルは XML 形式である必要はないため、単純なテキストからイメージファイルまで何でもかまいません。XML 形式でないメッセージコンテンツはすべて AttachmentPart オブジェクトに含まれている必要があります。

    MessageFactory オブジェクトは、SAAJ の特定の実装またはアプリケーションに特化した動作で SOAPMessage オブジェクトを作成する場合があります。たとえば、MessageFactory オブジェクトは、ebXML などの特定のプロファイルに準拠する SOAPMessage オブジェクトを生成する場合があります。この場合、MessageFactory オブジェクトは、ebXML ヘッダーで初期化される SOAPMessage オブジェクトを生成する可能性があります。

    ソースの後方互換性を確保するために、SAAJ 仕様のバージョン 1.1 の後にこのクラスに追加されるメソッドは、抽象ではなくすべて具象であり、すべてデフォルトの実装があります。これらのメソッドの JavaDocs で特に明記されていない限り、デフォルトの実装は単に UnsupportedOperationException をスローし、SAAJ 実装コードは指定された動作を提供するメソッドでオーバーライドする必要があります。ただし、レガシークライアントコードにはこの制限はありません。ただし、元の仕様よりも新しいバージョンの仕様に準拠しているという主張がない限りです。SOAPMessage クラスを継承するレガシークラスは、変更することなく、SAAJAPI の後続バージョンに対してコンパイルおよび / または実行できます。そのようなクラスが正しく実装されていれば、それが作成された仕様のバージョンに対して引き続き正しく動作します。

    導入:
    1.6
    関連事項:
    MessageFactory, AttachmentPart

    • フィールドのサマリー

      フィールド  
      修飾子と型 フィールド 説明
      static StringSECHARACTER_SET_ENCODING
      SOAP メッセージの文字型エンコーディングを指定します。
      static StringSEWRITE_XML_DECLARATION
      送信時に SOAP メッセージに XML 宣言を含めるかどうかを指定します。

    • コンストラクター概要

      コンストラクター  
      修飾子 コンストラクター 説明
      protected SOAPMessage()
      デフォルトコンストラクター。

    • フィールドの詳細

      • CHARACTER_SET_ENCODING

        public static final StringSE CHARACTER_SET_ENCODING
        SOAP メッセージの文字型エンコーディングを指定します。有効な値には、"utf-8" および "utf-16" が含まれます。サポートされている追加の値については、ベンダーのドキュメントを参照してください。デフォルトは "utf-8" です。
        導入:
        1.6、SAAJ 1.2
        関連事項:
        SOAPMessage.setProperty, 定数フィールド値

      • WRITE_XML_DECLARATION

        public static final StringSE WRITE_XML_DECLARATION
        送信時に SOAP メッセージに XML 宣言を含めるかどうかを指定します。有効な値は "true" と "false" のみです。デフォルトは "false" です。
        導入:
        1.6、SAAJ 1.2
        関連事項:
        SOAPMessage.setProperty, 定数フィールド値

    • コンストラクターの詳細

      • SOAPMessage

        protected SOAPMessage()
        デフォルトコンストラクター。

    • メソッドの詳細

      • setContentDescription

        public abstract void setContentDescription​(StringSE description)
        この SOAPMessage オブジェクトのコンテンツの説明を指定された説明で設定します。
        パラメーター:
        description - このメッセージの内容を説明する String 
        関連事項:
        getContentDescription()

      • getContentDescription

        public abstract StringSE getContentDescription()
        この SOAPMessage オブジェクトのコンテンツの説明を取得します。
        戻り値:
        このメッセージの内容を説明する String、または説明が設定されていない場合は null 
        関連事項:
        setContentDescription(java.lang.String)

      • getSOAPPart

        public abstract SOAPPart getSOAPPart()
        この SOAPMessage オブジェクトの SOAP 部分を取得します。

        SOAPMessage オブジェクトには 1 つ以上の添付ファイルが含まれているため、SOAP パーツはメッセージの最初の MIME 本文パーツである必要があります。

        戻り値:
        この SOAPMessage オブジェクトの SOAPPart オブジェクト

      • getSOAPBody

        public SOAPBody getSOAPBody()
                     throws SOAPException
        この SOAPMessage オブジェクトに含まれる SOAP 本体を取得します。
        戻り値:
        この SOAPMessage オブジェクトに含まれる SOAPBody オブジェクト
        例外:
        SOAPException - SOAP 本体が存在しないか、取得できない場合
        導入:
        1.6、SAAJ 1.2

      • getSOAPHeader

        public SOAPHeader getSOAPHeader()
                         throws SOAPException
        この SOAPMessage オブジェクトに含まれる SOAP ヘッダーを取得します。
        戻り値:
        この SOAPMessage オブジェクトに含まれる SOAPHeader オブジェクト
        例外:
        SOAPException - SOAP ヘッダーが存在しないか、取得できない場合
        導入:
        1.6、SAAJ 1.2

      • removeAllAttachments

        public abstract void removeAllAttachments()
        この SOAPMessage オブジェクトに追加されたすべての AttachmentPart オブジェクトを削除します。

        このメソッドは SOAP 部分には影響しません。

      • countAttachments

        public abstract int countAttachments()
        このメッセージの添付ファイルの数を取得します。このカウントには、SOAP 部分は含まれていません。
        戻り値:
        この SOAPMessage オブジェクトの一部である AttachmentPart オブジェクトの数

      • getAttachments

        public abstract IteratorSE<AttachmentPart> getAttachments()
        この SOAPMessage オブジェクトの一部であるすべての AttachmentPart オブジェクトを取得します。
        戻り値:
        このメッセージのすべての添付ファイルに対するイテレータ

      • getAttachments

        public abstract IteratorSE<AttachmentPart> getAttachments​(MimeHeaders headers)
        指定されたヘッダーと一致するヘッダーエントリを持つすべての AttachmentPart オブジェクトを取得します。返される添付ファイルには、指定されたものに加えてヘッダーが含まれる可能性があることに注意してください。
        パラメーター:
        headers - 検索対象の MIME ヘッダーを含む MimeHeaders オブジェクト
        戻り値:
        指定されたヘッダーの 1 つと一致するヘッダーを持つすべての添付ファイルに対するイテレーター

      • removeAttachments

        public abstract void removeAttachments​(MimeHeaders headers)
        指定されたヘッダーと一致するヘッダーエントリを持つすべての AttachmentPart オブジェクトを削除します。削除された添付ファイルには、指定されたものに加えてヘッダーが含まれる可能性があることに注意してください。
        パラメーター:
        headers - 検索対象の MIME ヘッダーを含む MimeHeaders オブジェクト
        導入:
        1.6、SAAJ 1.3

      • getAttachment

        public abstract AttachmentPart getAttachment​(SOAPElement element)
                                      throws SOAPException
        この SOAPElement または null によって参照される接続ファイルが存在しない場合は、その接続ファイルに関連付けられている AttachmentPart オブジェクトを返します。参照は、添付ファイル付きの SOAP メッセージで説明されている href 属性を介して、またはスキーマ型参照: swaRef の要素の WS-I 接続ファイルプロファイル 1.0 で説明されている URI を含む単一の Text 子ノードを介して作成できます。これら 2 つのメカニズムをサポートする必要があります。href 属性による参照のサポートは、このメソッドが xop:Include 要素 ( XOP ) である要素でもサポートされる必要があることも意味します。他の参照メカニズムは、この規格の個々の実装によってサポートされる場合があります。詳細については、ベンダーにお問い合わせください。
        パラメーター:
        element - 添付ファイルへの参照を含む SOAPElement 
        戻り値:
        参照された AttachmentPart、またはそのような AttachmentPart が存在しない場合、この SOAPElement に参照が見つからない場合は null。
        例外:
        SOAPException - 添付ファイルへのアクセスにエラーが発生した場合
        導入:
        1.6、SAAJ 1.3

      • addAttachmentPart

        public abstract void addAttachmentPart​(AttachmentPart attachmentPart)
        指定された AttachmentPart オブジェクトをこの SOAPMessage オブジェクトに追加します。AttachmentPart オブジェクトは、メッセージに追加する前に作成する必要があります。
        パラメーター:
        attachmentPart - この SOAPMessage オブジェクトの一部となる attachmentPart オブジェクト
        例外:
        IllegalArgumentExceptionSE - 指定された attachmentPart オブジェクトに問題があった場合

      • createAttachmentPart

        public abstract AttachmentPart createAttachmentPart()
        新しい空の AttachmentPart オブジェクトを作成します。メソッド addAttachmentPart は、この SOAPMessage オブジェクトへのアタッチメントになるために、この新しい AttachmentPart オブジェクトをパラメーターとして呼び出す必要があることに注意してください。
        戻り値:
        この SOAPMessage オブジェクトに入力して追加できる新しい AttachmentPart オブジェクト

      • createAttachmentPart

        public AttachmentPart createAttachmentPart​(DataHandler dataHandler)
        AttachmentPart オブジェクトを作成し、指定された DataHandler オブジェクトを使用してデータを設定します。
        パラメーター:
        dataHandler - この SOAPMessage オブジェクトのコンテンツを生成する jakarta.activation.DataHandler オブジェクト
        戻り値:
        指定された DataHandler オブジェクトによって生成されたデータを含む新しい AttachmentPart オブジェクト
        例外:
        IllegalArgumentExceptionSE - 指定された DataHandler オブジェクトに問題があった場合
        関連事項:
        DataHandler, DataContentHandler

      • getMimeHeaders

        public abstract MimeHeaders getMimeHeaders()
        この SOAPMessage オブジェクトのすべてのトランスポート固有の MIME ヘッダーをトランスポートに依存しない方法で返します。
        戻り値:
        MimeHeader オブジェクトを含む MimeHeaders オブジェクト

      • createAttachmentPart

        public AttachmentPart createAttachmentPart​(ObjectSE content,
                                           StringSE contentType)
        AttachmentPart オブジェクトを作成し、指定されたコンテンツ型の指定されたデータをそのオブジェクトに入力します。Object の型は、Content-Type に指定された値に対応している必要があります。
        パラメーター:
        content - 作成する AttachmentPart オブジェクトのコンテンツを含む Object 
        contentType - コンテンツの型を提供する String オブジェクト。例としては、"text/xml","text/plain"、および "image/jpeg" があります。
        戻り値:
        指定されたデータを含む新しい AttachmentPart オブジェクト
        例外:
        IllegalArgumentExceptionSE - contentType がコンテンツオブジェクトの型と一致しない場合、または指定されたコンテンツオブジェクトに DataContentHandler オブジェクトがなかった場合にスローされる可能性があります。
        関連事項:
        DataHandler, DataContentHandler

      • saveChanges

        public abstract void saveChanges()
                          throws SOAPException
        この SOAPMessage オブジェクトを、それに加えられたすべての変更で更新します。このメソッドは、writeTo(OutputStream) が呼び出されると自動的に呼び出されます。ただし、受信したメッセージまたはすでに送信されたメッセージに変更が加えられた場合、変更を保存するには、メソッド saveChanges を明示的に呼び出す必要があります。メソッド saveChanges は、読み戻すことができる変更も生成します（たとえば、メッセージ ID をサポートするプロファイルの MessageId）。送信目的で作成されたメッセージ内のすべての MIME ヘッダーは、saveChanges が呼び出された後にのみ有効な値を持つことが保証されます。

        さらに、このメソッドは、すべての構成 AttachmentPart オブジェクトからのデータがメッセージにプルされるポイントをマークします。

        例外:
        SOAPException - このメッセージへの変更を保存する際に問題が発生した場合。

      • saveRequired

        public abstract boolean saveRequired()
        この SOAPMessage オブジェクトでメソッド saveChanges を呼び出す必要があるかどうかを示します。
        戻り値:
         saveChanges を呼び出す必要がある場合は true。それ以外の場合は false。

      • writeTo

        public abstract void writeTo​(OutputStreamSE out)
                      throws SOAPException,
                             IOExceptionSE
        この SOAPMessage オブジェクトを指定された出力ストリームに書き込みます。外部化形式は、添付ファイル付きの SOAP 1.1 仕様で定義されているとおりです。

        添付ファイルがない場合は、XML ストリームのみが書き出されます。添付ファイルのあるメッセージの場合、writeTo は MIME エンコードされたバイトストリームを書き込みます。

        このメソッドは、メッセージのトランスポート固有の MIME ヘッダーを書き込まないことに注意してください

        パラメーター:
        out - この SOAPMessage オブジェクトが書き込まれる OutputStream オブジェクト
        例外:
        IOExceptionSE - I/O エラーが発生した場合
        SOAPException - この SOAP メッセージの外部化に問題があった場合

      • setProperty

        public void setProperty​(StringSE property,
                        ObjectSE value)
                 throws SOAPException
        指定された値を指定されたプロパティに関連付けます。このプロパティに関連付けられた値がすでに存在する場合は、古い値が置き換えられます。

        有効なプロパティ名には WRITE_XML_DECLARATION と CHARACTER_SET_ENCODING が含まれます。これらの標準の SAAJ プロパティはすべて、"jakarta.xml.soap" というプレフィックスが付いています。ベンダーは、実装固有のプロパティを追加することもできます。これらのプロパティには、ベンダーに固有のパッケージ名のプレフィックスを付ける必要があります。

        プロパティ WRITE_XML_DECLARATION を "true" に設定すると、SOAP メッセージの開始時に XML 宣言が書き出されます。デフォルト値の "false" は、この宣言を抑制します。

        プロパティ CHARACTER_SET_ENCODING のデフォルト値は "utf-8" であり、これにより、SOAP メッセージは UTF-8 を使用してエンコードされます。CHARACTER_SET_ENCODING を "utf-16" に設定すると、SOAP メッセージは UTF-16 を使用してエンコードされます。

        一部の実装では、UTF-8 および UTF-16 に加えてエンコーディングが許可される場合があります。詳細については、ベンダーのドキュメントを参照してください。

        パラメーター:
        property - 指定された値が関連付けられるプロパティ。
        value - 指定されたプロパティに関連付けられる値
        例外:
        SOAPException - プロパティ名が認識されない場合。
        導入:
        1.6、SAAJ 1.2

      • getProperty

        public ObjectSE getProperty​(StringSE property)
                   throws SOAPException
        指定されたプロパティの値を取得します。
        パラメーター:
        property - 取得するプロパティの名前
        戻り値:
        指定されたプロパティに関連付けられた値、またはそのようなプロパティが存在しない場合は null。
        例外:
        SOAPException - プロパティ名が認識されない場合。
        導入:
        1.6、SAAJ 1.2