概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法

javax.xml.soap
類別 SOAPMessage

java.lang.Object
  繼承者 javax.xml.soap.SOAPMessage

public abstract class SOAPMessage
extends Object

所有 SOAP 訊息的根類別。因為 SOAP 訊息是通過“導線”傳輸的，所以它是 XML 文檔或第一個正文部分為 XML/SOAP 文檔的 MIME 訊息。

SOAPMessage 物件由一個 SOAP 部分和一個或多個附件部分（可選）組成。SOAPMessage 物件的 SOAP 部分是一個 SOAPPart 物件，包含了用於訊息路由和標識的資訊，並可以包含特定於應用程序的內容。訊息 SOAP 部分中的所有資料都必須是 XML 格式。

預設情況下，新的 SOAPMessage 物件包含以下物件：

可以通過調用方法 SOAPMessage.getSOAPPart() 檢索訊息的 SOAP 部分。SOAPEnvelope 物件是從 SOAPPart 物件檢索的，SOAPEnvelope 物件用於檢索 SOAPBody 和 SOAPHeader 物件。 
SOAPPart sp = message.getSOAPPart();
SOAPEnvelope se = sp.getEnvelope();
SOAPBody sb = se.getBody();
SOAPHeader sh = se.getHeader();

除強制性 SOAPPart 物件之外，SOAPMessage 物件還可以包含零個或多個 AttachmentPart 物件，每個 AttachmentPart 物件都包含特定於應用程序的資料。SOAPMessage 介面提供了一些用於創建 AttachmentPart 物件的方法，以及一些將它們添加到 SOAPMessage 物件的方法。收到 SOAPMessage 物件的一方可以通過檢索各個附件部分來檢查訊息內容。

與 SOAP 訊息的其餘部分不同，附件不需要是 XML 格式，因此可以是簡單文本或圖像檔案等任何形式。因此，任何非 XML 格式的訊息內容必須在 AttachmentPart 物件中。

MessageFactory 物件可以創建行為特定於具體 SAAJ 實作或應用程序的 SOAPMessage 物件。例如，MessageFactory 物件可以產生符合特定配置檔案（如 ebXML）的 SOAPMessage 物件。在這種情況下，MessageFactory 物件可以產生使用 ebXML 頭初始化的 SOAPMessage 物件。

為了確保與後向源的相容性，在 SAAJ 規範的 1.1 版本之後添加到此類別的方法都是具體而非抽象的，它們都具有預設實作。除在 JavaDocs 中有對這些方法的另行說明外，預設實作只是拋出 UnsupportedOperationException，並且 SAAJ 實作程式碼必須使用提供指定行為的方法覆寫它們。但是，只要沒有宣告符合初始版本之後的某些更高版本規範，遺留客戶端程式碼就沒有這種限制。可以根據 SAAJ API 的未修改後續版本來編譯和/或運行擴展 SOAPMessage 類別的遺留類別。如果正確實作了這樣的類別，則對於規範的更高版本（相對於初始版本）來說，該類別將繼續有效。

另請參見：
MessageFactory, AttachmentPart

欄位摘要
static String CHARACTER_SET_ENCODING
          指定 SOAP Message 的字元型別編碼。
static String WRITE_XML_DECLARATION
          指定 SOAP Message 在發送時是否包含 XML 宣告。
 
建構子摘要
SOAPMessage()
           
 
方法摘要
abstract  void addAttachmentPart(AttachmentPart AttachmentPart)
          將給定的 AttachmentPart 物件添加到此 SOAPMessage 物件。
abstract  int countAttachments()
          獲取此訊息中附件數量的計數。
abstract  AttachmentPart createAttachmentPart()
          創建一個新的空 AttachmentPart 物件。
 AttachmentPart createAttachmentPart(DataHandler dataHandler)
          創建 AttachmentPart 物件並使用給定的 DataHandler 物件填充。
 AttachmentPart createAttachmentPart(Object content, String contentType)
          創建 AttachmentPart 物件並使用指定內容型別的指定資料填充。
abstract  AttachmentPart getAttachment(SOAPElement element)
          返回與此 SOAPElement 參考的附件關聯的 AttachmentPart 物件，如果不存在此類別附件，則返回 null。
abstract  Iterator getAttachments()
          檢索所有作為此 SOAPMessage 物件一部分的 AttachmentPart 物件。
abstract  Iterator getAttachments(MimeHeaders headers)
          檢索所有頭條目比對指定頭的 AttachmentPart 物件。
abstract  String getContentDescription()
          檢索此 SOAPMessage 物件內容的描述。
abstract  MimeHeaders getMimeHeaders()
          以與傳輸無關的方式返回此 SOAPMessage 物件所有特定於傳輸的 MIME 頭。
 Object getProperty(String property)
          檢索指定屬性的值。
 SOAPBody getSOAPBody()
          獲取此 SOAPMessage 物件中包含的 SOAP Body。
 SOAPHeader getSOAPHeader()
          獲取此 SOAPMessage 物件中包含的 SOAP Header。
abstract  SOAPPart getSOAPPart()
          獲取此 SOAPMessage 物件的 SOAP 部分。
abstract  void removeAllAttachments()
          移除所有已經添加到此 SOAPMessage 物件的 AttachmentPart 物件。
abstract  void removeAttachments(MimeHeaders headers)
          移除所有頭條目比對指定頭的 AttachmentPart 物件。
abstract  void saveChanges()
          使用對其所作的所有更改更新此 SOAPMessage 物件。
abstract  boolean saveRequired()
          指示是否此 SOAPMessage 物件需要調用方法 saveChanges。
abstract  void setContentDescription(String description)
          使用給定描述設置此 SOAPMessage 物件內容的描述。
 void setProperty(String property, Object value)
          將指定值與指定屬性關聯。
abstract  void writeTo(OutputStream out)
          將此 SOAPMessage 物件寫入給定輸出串流。
 
從類別 java.lang.Object 繼承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

欄位詳細資訊

CHARACTER_SET_ENCODING

public static final String CHARACTER_SET_ENCODING
指定 SOAP Message 的字元型別編碼。有效值包括 "utf-8" 和 "utf-16"。有關其他受支持的值，請參閱供應商文檔。預設值是 "utf-8"。

從以下版本開始：
SAAJ 1.2
另請參見：
SOAPMessage.setProperty, 常數欄位值

WRITE_XML_DECLARATION

public static final String WRITE_XML_DECLARATION
指定 SOAP Message 在發送時是否包含 XML 宣告。僅有的有效值為 "true" 和 "false"。預設值為 "false"。

從以下版本開始：
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 物件包含一個或多個附件，SOAP 部分必須是訊息中的第一個 MIME 正文部分。

返回：
此 SOAPMessage 物件的 SOAPPart 物件

getSOAPBody

public SOAPBody getSOAPBody()
                     throws SOAPException
獲取此 SOAPMessage 物件中包含的 SOAP Body。

返回：
此 SOAPMessage 物件包含的 SOAPBody 物件
拋出：
SOAPException - 如果 SOAP Body 不存在或無法被檢索
從以下版本開始：
SAAJ 1.2

getSOAPHeader

public SOAPHeader getSOAPHeader()
                         throws SOAPException
獲取此 SOAPMessage 物件中包含的 SOAP Header。

返回：
此 SOAPMessage 物件包含的 SOAPHeader 物件
拋出：
SOAPException - 如果 SOAP Header 不存在或無法被檢索
從以下版本開始：
SAAJ 1.2

removeAllAttachments

public abstract void removeAllAttachments()
移除所有已經添加到此 SOAPMessage 物件的 AttachmentPart 物件。

此方法不接觸 SOAP 部分。

countAttachments

public abstract int countAttachments()
獲取此訊息中附件數量的計數。此計數不包括 SOAP 部分。

返回：
作為此 SOAPMessage 物件一部分的 AttachmentPart 物件的數量

getAttachments

public abstract Iterator getAttachments()
檢索所有作為此 SOAPMessage 物件一部分的 AttachmentPart 物件。

返回：
可在此訊息中所有附件上進行迭代的迭代器。

getAttachments

public abstract Iterator getAttachments(MimeHeaders headers)
檢索所有頭條目比對指定頭的 AttachmentPart 物件。注意，返回的附件除指定的頭之外，還可以有其他頭。

參數：
headers - 套件含要搜尋的 MIME 頭的 MimeHeaders 物件
返回：
一個迭代器，可在所有頭比對任一給定頭的附件上進行迭代

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)
移除所有頭條目比對指定頭的 AttachmentPart 物件。注意，移除的附件除指定的頭之外，還可以有其他頭。

參數：
headers - 套件含要搜尋的 MIME 頭的 MimeHeaders 物件
從以下版本開始：
SAAJ 1.3

getAttachment

public abstract AttachmentPart getAttachment(SOAPElement element)
                                      throws SOAPException
返回與此 SOAPElement 參考的附件關聯的 AttachmentPart 物件，如果不存在此類別附件，則返回 null。可以通過 SOAP Messages with Attachments 中描述的 href 屬性，或者包含 WS-I Attachments Profile 1.0（用於網要型別 ref:swaRef(ref:swaRef) 的元素）中所描述的 URI 的一個 Text 子節點來進行參考。必須支持這兩種機制。支持通過 href 屬性獲取參考同時意味著，對於作為 xop:Include 元素 (XOP) 的元素也應該支持此方法。其他參考機制可以由此標準的各個實作支持。有關詳細資訊，請與您的供應商聯繫。

參數：
element - 套件含對附件參考的 SOAPElement
返回：
參考的 AttachmentPart；如果不存在此類別 AttachmentPart 或在此 SOAPElement 中找不到參考，則返回 null。
拋出：
SOAPException - 如果嘗試存取附件時出現錯誤
從以下版本開始：
SAAJ 1.3

addAttachmentPart

public abstract void addAttachmentPart(AttachmentPart AttachmentPart)
將給定的 AttachmentPart 物件添加到此 SOAPMessage 物件。必須先創建 AttachmentPart 物件，然後才能將其添加到訊息。

參數：
AttachmentPart - 將作為此 SOAPMessage 物件一部分的 AttachmentPart 物件
拋出：
IllegalArgumentException

createAttachmentPart

public abstract AttachmentPart createAttachmentPart()
創建一個新的空 AttachmentPart 物件。注意，調用方法 addAttachmentPart 時必須將此新 AttachmentPart 物件作為參數，以便該物件成為此 SOAPMessage 物件的附件。

返回：
可以填充並添加到此 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）。只有在調用 saveChanges 之後，才能保證為發送而創建的訊息中的所有 MIME 頭具有有效值。

此外，此方法標記了位置點，取自所有 AttachmentPart 物件元件的資料在該點處被拉入訊息。

拋出：
SOAPException - 如果在保存此訊息的更改時出現問題。
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 Header

參數：
out - SOAPMessage 物件將寫入的 OutputStream 物件
拋出：
IOException - 如果發生 I/O 錯誤
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 Declaration。預設值 "false" 表示取消此宣告。

屬性 CHARACTER_SET_ENCODING 預設為值 "utf-8"，該值將導致使用 UTF-8 編碼 SOAP 訊息。將 CHARACTER_SET_ENCODING 設置為 "utf-16" 將導致使用 UTF-16 編碼 SOAP 訊息。

某些實作可能允許除 UTF-8 和 UTF-16 之外的編碼。有關詳細資訊，請參閱供應商文檔。

參數：
property - 要關聯指定值的屬性。
value - 要與指定屬性關聯的值
拋出：
SOAPException - 如果無法識別屬性名。
從以下版本開始：
SAAJ 1.2

getProperty

public Object getProperty(String property)
                   throws SOAPException
檢索指定屬性的值。

參數：
property - 要檢索的屬性名稱
返回：
與指定屬性關聯的值；如果不存在此類別屬性，則返回 null。
拋出：
SOAPException - 如果無法識別屬性名。
從以下版本開始：
SAAJ 1.2
概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法
提交錯誤或意見

版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。