モジュール java.xml.ws
パッケージ javax.xml.soap

クラスSOAPMessage

  • public abstract class SOAPMessage
extends Object
    すべてのSOAPメッセージのルート・クラスです。 ワイヤー上を転送されるため、SOAPメッセージはXMLドキュメントまたは最初の本体がXML/SOAPドキュメントであるMIMEメッセージです。

    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オブジェクトにはゼロ個以上のAttachmentPartオブジェクトが含まれる場合があり、それぞれにはアプリケーション固有のデータが含まれています。 SOAPMessageインタフェースはAttachmentPartオブジェクトを作成するメソッドを提供し、SOAPMessageオブジェクトに追加するメソッドも提供します。 SOAPMessageオブジェクトを受け取った側は、個々の添付部を取得してコンテンツを調べることができます。

    SOAPメッセージの残りの部分とは異なり、添付部はXML形式である必要はなく、単純なテキストからイメージ・ファイルまであらゆる形式が可能です。 したがって、XML形式でないメッセージのコンテンツは、AttachmentPartオブジェクトの中に入れる必要があります。

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

    下位ソース互換を確保するため、SAAJのバージョン1.1のあとにこのクラスに追加されるメソッドは、すべて抽象ではなく具象であり、すべてデフォルトの実装を持ちます。 これらのメソッドのJavaDocで特に明記されていないかぎり、デフォルトの実装は単にUnsupportedOperationExceptionをスローし、特定の動作を提供するメソッドによってSAAJ実装コードがオーバーライドする必要があります。 ただし、本来書かれた仕様よりもあとのバージョンの仕様に準拠しているという主張がなされない限り、従来のクライアント・コードにはこの制約はありません。 SOAPMessageクラスを拡張する従来のクラスは、変更することなく後続のバージョンに対してコンパイルまたは実行、あるいはその両方を行うことができます。 そのようなクラスが正常に実装された場合、書かれた仕様のバージョンに対して正常に動作し続けます。

    導入されたバージョン:
    1.6
    関連項目:
    MessageFactory, AttachmentPart

    • フィールドのサマリー

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

    • コンストラクタのサマリー

      コンストラクタ 
      コンストラクタ 説明
      SOAPMessage()  

    • フィールドの詳細

      • CHARACTER_SET_ENCODING

        public static final String CHARACTER_SET_ENCODING
        SOAPメッセージの文字タイプ・エンコーディングを指定します。 有効な値には、"utf-8"および"utf-16"が含まれます。 さらにサポートされる値については、ベンダーからのマニュアルを参照してください。 デフォルトは"utf-8"です。
        導入されたバージョン:
        1.6, SAAJ 1.2
        関連項目:
        SOAPMessage.setProperty、定数フィールド値

      • WRITE_XML_DECLARATION

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

    • コンストラクタの詳細

      • SOAPMessage

        public SOAPMessage()

    • メソッドの詳細

      • setContentDescription

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

      • getContentDescription

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

      • getSOAPPart

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

        SOAPMessageオブジェクトは1つ以上の添付を含んでおり、SOAP Partはメッセージで最初のMIME本体である必要があります。

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

      • getSOAPBody

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

      • getSOAPHeader

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

      • removeAllAttachments

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

        このメソッドは、SOAP部には影響を与えません。

      • countAttachments

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

      • getAttachments

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

      • getAttachments

        public abstract Iterator<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が参照する添付と関連付けられたAttachmentPartオブジェクト、またはそのような添付が存在しない場合はnullを返します。 参照は、「SOAP Messages with Attachments」で説明されているhref属性、またはスキーマ型ref:swaRefの要素用に「WS-I Attachments Profile 1.0」で説明されているとおり、URIを含む単一のText子ノードを介して行えます。 これら2つのメカニズムはサポートされている必要があります。 href属性を使用した参照のサポートとは、xop:Include要素(XOP)である要素に対してもこのメソッドがサポートされる必要があるという意味でもあります。その他の参照メカニズムは、この標準の個々の実装によってサポートされることがあります。 詳細は、ベンダーにご連絡ください。
        パラメータ:
        element - Attachmentへの参照を含むSOAPElement
        戻り値:
        参照されたAttachmentPart。そのようなAttachmentPartが存在しないか、このSOAPElement内に参照が見つからない場合はnull。
        例外:
        SOAPException - 添付にアクセスしようとしたときにエラーが発生した場合
        導入されたバージョン:
        1.6, SAAJ 1.3

      • addAttachmentPart

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

      • createAttachmentPart

        public abstract AttachmentPart createAttachmentPart()
        空の新しいAttachmentPartオブジェクトを作成します。 addAttachmentPartメソッドは、この新しいAttachmentPartオブジェクトをこのSOAPMessageオブジェクトの添付にするために、新しいAttachmentPartオブジェクトとともにパラメータとして呼び出される必要があります。
        戻り値:
        データが取り込まれ、このSOAPMessageオブジェクトに追加される新しいAttachmentPartオブジェクト

      • createAttachmentPart

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

      • getMimeHeaders

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

      • createAttachmentPart

        public AttachmentPart createAttachmentPart​(Object content,
                                           String contentType)
        AttachmentPartオブジェクトを作成し、指定したコンテンツ・タイプの指定したデータを使用して生成します。 Objectの型は、Content-Typeで指定した値に対応する必要があります。
        パラメータ:
        content - 作成されるAttachmentPartオブジェクトのコンテンツを含むObject
        contentType - コンテンツのタイプを示すStringオブジェクト。たとえば、"text/xml"、"text/plain"、"image/jpeg"
        戻り値:
        指定したデータを含む新しいAttachmentPartオブジェクト
        例外:
        IllegalArgumentException - 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​(OutputStream out)
                      throws SOAPException,
                             IOException
        このSOAPMessageオブジェクトを指定した出力ストリームに書き込みます。 外部化形式は、SOAP 1.1 with Attachments仕様で定義されているものと同じです。

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

        このメソッドは、メッセージのトランスポート固有のMIMEヘッダーは書き込みません。

        パラメータ:
        out - このSOAPMessageオブジェクトを書き込むOutputStreamオブジェクト
        例外:
        IOException - 入出力エラーが発生した場合
        SOAPException - このSOAPメッセージの外部化で問題があった場合

      • setProperty

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

        有効なプロパティ名には、WRITE_XML_DECLARATIONおよびCHARACTER_SET_ENCODINGが含まれます。 標準SAAJプロパティにはすべて、先頭に「javax.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 Object getProperty​(String property)
                   throws SOAPException
        指定されたプロパティの値を取得します。
        パラメータ:
        property - 取得するプロパティの名前
        戻り値:
        指定されたプロパティに関連付けられた値。該当するプロパティが存在しない場合はnull。
        例外:
        SOAPException - プロパティ名が認識されない場合。
        導入されたバージョン:
        1.6, SAAJ 1.2