javax.xml.soap
類別 AttachmentPart

java.lang.Object
  javax.xml.soap.AttachmentPart

public abstract class AttachmentPart
extends Object

SOAPMessage 物件的一個附件。SOAPMessage 物件可以包含 0 個、1 個或多個 AttachmentPart 物件。每個 AttachmentPart 物件由兩部分組成：特定於應用程序的內容和關聯的 MIME 頭。MIME 頭由可用於標識和描述內容的名稱/值對組成。

AttachmentPart 物件必須符合某些標準。

1. 它必須符合 MIME [RFC2045] 標準
2. 它必須包含內容
3. 頭部分必須包含以下頭內容：
   • Content-Type
     此頭標識 AttachmentPart 物件內容中的資料型別，必須符合 [RFC2045]。以下是一個 Content-Type 頭的範例：

     Content-Type:application/xml
            

     以下程式碼行（其中 ap 是一個 AttachmentPart 物件）設置前一範例中顯示的頭。

     ap.setMimeHeader("Content-Type", "application/xml");
            

AttachmentPart 物件的內容部分沒有任何限制。內容可以是簡單的純文本物件、複雜的 XML 文檔或圖像檔案。

AttachmentPart 物件是使用方法 SOAPMessage.createAttachmentPart 創建的。設置 MIME 頭之後，使用方法 SOAPMessage.addAttachmentPart 將 AttachmentPart 物件添加到創建它的訊息中。

以下程式碼片段（其中 m 是一個 SOAPMessage 物件，contentStringl 是一個 String）創建 AttachmentPart 的實例，使用一些內容和頭資訊設置 AttachmentPart 物件，並將 AttachmentPart 物件添加到 SOAPMessage 物件。

AttachmentPart ap1 = m.createAttachmentPart();
ap1.setContent(contentString1, "text/plain");
m.addAttachmentPart(ap1);
 

以下程式碼片段創建第二個 AttachmentPart 實例並將其添加到同一訊息中。jpegData 是表示 jpeg 檔案的一個二進制位元組緩衝區。

AttachmentPart ap2 = m.createAttachmentPart();
byte[] jpegData =  ...;
ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
m.addAttachmentPart(ap2);
 

getContent 方法檢索 AttachmentPart 物件的內容和頭。根據存在 DataContentHandler 物件的不同，返回的 Object 可能是與 MIME 型別相對應的型別化的 Java 物件，也可能是以位元組形式包含內容的 InputStream 物件。

String content1 = ap1.getContent();
java.io.InputStream content2 = ap2.getContent();
 

方法 clearContent 從 AttachmentPart 物件中移除所有內容，但不影響其頭資訊。

ap1.clearContent();
 

建構子摘要

AttachmentPart()

方法摘要

abstract void	addMimeHeader(String name, String value) 將帶有指定名稱和值的 MIME 頭添加到此 AttachmentPart 物件。
abstract void	clearContent() 清除此 AttachmentPart 物件的內容。
abstract Iterator	getAllMimeHeaders() 以 MimeHeader 物件上的迭代器形式，檢索此 AttachmentPart 物件的所有頭。
abstract InputStream	getBase64Content() 以 Base64 編碼字元資料的形式返回可用於獲取 AttachmentPart 內容的 InputStream，此方法將對附件的原始位元組進行 Base64 編碼，然後返回該內容。
abstract Object	getContent() 以 Java 物件的形式獲取此 AttachmentPart 物件的內容。
String	getContentId() 獲取名為 "Content-ID" 的 MIME 頭的值。
String	getContentLocation() 獲取名為 "Content-Location" 的 MIME 頭的值。
String	getContentType() 獲取名為 "Content-Type" 的 MIME 頭的值。
abstract DataHandler	getDataHandler() 獲取針對此 AttachmentPart 物件的 DataHandler 物件。
abstract Iterator	getMatchingMimeHeaders(String[] names) 檢索比對給定陣列中名稱的所有 MimeHeader 物件。
abstract String[]	getMimeHeader(String name) 獲取給定 String 所標識的頭的所有值。
abstract Iterator	getNonMatchingMimeHeaders(String[] names) 檢索所有名稱不比對給定陣列中任一名稱的 MimeHeader 物件。
abstract InputStream	getRawContent() 以 InputStream 的形式獲取此 AttachmentPart 物件的內容，等效於調用了 getContent 但沒有為此 AttachmentPart 的 content-type 註冊 DataContentHandler。
abstract byte[]	getRawContentBytes() 以 byte[] 陣列形式獲取此 AttachmentPart 物件的內容，等效於調用了 getContent 但沒有為此 AttachmentPart 的 content-type 註冊 DataContentHandler。
abstract int	getSize() 返回此 AttachmentPart 物件中的位元組數。
abstract void	removeAllMimeHeaders() 移除所有 MIME 頭條目。
abstract void	removeMimeHeader(String header) 移除比對給定名稱的所有 MIME 頭。
abstract void	setBase64Content(InputStream content, String contentType) 根據 Base64 源 InputStream 設置此附件部分的內容，並將 Content-Type 頭的值設置為 contentType 中包含的值，此方法將首先對 base64 輸入串流進行解碼，然後將得到的原始位元組寫入附件。
abstract void	setContent(Object object, String contentType) 將此附件部分的內容設置為給定 Object 的內容，並將 Content-Type 頭的值設置為給定型別。
void	setContentId(String contentId) 使用給定值設置名為 "Content-ID" 的 MIME 頭。
void	setContentLocation(String contentLocation) 使用給定值設置名為 "Content-Location" 的 MIME 頭。
void	setContentType(String contentType) 使用給定值設置名為 "Content-Type" 的 MIME 頭。
abstract void	setDataHandler(DataHandler dataHandler) 將給定的 DataHandler 物件設置為此 AttachmentPart 物件的資料處理程序。
abstract void	setMimeHeader(String name, String value) 將比對給定名稱的第一個頭條目的值更改為給定值，如果現有的頭都不比對，則添加一個新的頭。
abstract void	setRawContent(InputStream content, String contentType) 將此附件部分的內容設置為 InputStream content 所包含的內容，並將 Content-Type 頭的值設置為 contentType 中包含的值。
abstract void	setRawContentBytes(byte[] content, int offset, int len, String contentType) 將此附件部分的內容設置為 byte[] 陣列 content 所包含的內容，並將 Content-Type 頭的值設置為 contentType 中包含的值。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

建構子詳細資訊

AttachmentPart

public AttachmentPart()

方法詳細資訊

getSize

public abstract int getSize()
                     throws SOAPException

返回此 AttachmentPart 物件中的位元組數。

返回：

此 AttachmentPart 物件的大小，以位元組為單位；如果無法確定其大小，則返回 -1

拋出：

SOAPException - 如果此附件的內容已損壞，或者嘗試確定其大小時引發異常。

clearContent

public abstract void clearContent()

清除此 AttachmentPart 物件的內容。MIME 頭部分保持不變。

getContent

public abstract Object getContent()
                           throws SOAPException

以 Java 物件的形式獲取此 AttachmentPart 物件的內容。返回的 Java 物件的型別取決於：(1) 用來解釋位元組的 DataContentHandler 物件；(2) 頭中給定的 Content-Type。

對於 MIME 內容型別 "text/plain"、"text/html" 和 "text/xml"，DataContentHandler 物件執行與對應於 MIME 型別的 Java 型別之間的轉換。對於其他 MIME 型別，DataContentHandler 物件可以返回以原始位元組形式包含內容的 InputStream 物件。

符合 SAAJ 的實作至少必須返回一個 java.lang.String 物件（與 Content-Type 值為 text/plain 的任何內容串流相對應）、一個 javax.xml.transform.stream.StreamSource 物件（與 Content-Type 值為 text/xml 的內容串流相對應）、以及一個 java.awt.Image 物件（與 Content-Type 值為 image/gif 或 image/jpeg 的內容串流相對應）。對於已安裝的 DataContentHandler 物件不理解的內容型別，DataContentHandler 物件要返回帶有原始位元組的 java.io.InputStream 物件。

返回：

帶有此 AttachmentPart 物件內容的 Java 物件

拋出：

SOAPException - 如果此 AttachmentPart 物件中沒有設置任何內容，或者出現資料轉換錯誤

getRawContent

public abstract InputStream getRawContent()
                                   throws SOAPException

以 InputStream 的形式獲取此 AttachmentPart 物件的內容，等效於調用了 getContent 但沒有為此 AttachmentPart 的 content-type 註冊 DataContentHandler。

注意，讀取返回的 InputStream 可能導致消耗串流中的資料。調用者負責在調用 Subsequent API 之前適當地重置 InputStream。如果需要附件原始內容的一個副本，則應改用 getRawContentBytes() API。

返回：

一個 InputStream 物件，從中可以存取 AttachmentPart 套件含的原始資料。

拋出：

SOAPException - 如果此 AttachmentPart 物件中沒有設置任何內容，或者出現資料轉換錯誤。

從以下版本開始：

SAAJ 1.3

另請參見：

getRawContentBytes()

getRawContentBytes

public abstract byte[] getRawContentBytes()
                                   throws SOAPException

以 byte[] 陣列形式獲取此 AttachmentPart 物件的內容，等效於調用了 getContent 但沒有為此 AttachmentPart 的 content-type 註冊 DataContentHandler。

返回：

包含 AttachmentPart 原始資料的 byte[] 陣列。

拋出：

SOAPException - 如果此 AttachmentPart 物件中沒有設置任何內容，或者出現資料轉換錯誤。

從以下版本開始：

SAAJ 1.3

getBase64Content

public abstract InputStream getBase64Content()
                                      throws SOAPException

以 Base64 編碼字元資料的形式返回可用於獲取 AttachmentPart 內容的 InputStream，此方法將對附件的原始位元組進行 Base64 編碼，然後返回該內容。

返回：

一個 InputStream 物件，從中可以讀取 Base64 編碼的 AttachmentPart。

拋出：

SOAPException - 如果此 AttachmentPart 物件中沒有設置任何內容，或者出現資料轉換錯誤。

從以下版本開始：

SAAJ 1.3

setContent

public abstract void setContent(Object object,
                                String contentType)

將此附件部分的內容設置為給定 Object 的內容，並將 Content-Type 頭的值設置為給定型別。Object 的型別應該對應於指定給 Content-Type 的值。這取決於所使用的特定 DataContentHandler 物件集合。

參數：

object - 組成此附件部分內容的 Java 物件

contentType - 指定內容型別的 MIME 字元串

拋出：

IllegalArgumentException - 如果 contentType 不比對內容物件的型別，或者沒有針對此內容物件的 DataContentHandler 物件

另請參見：

getContent()

setRawContent

public abstract void setRawContent(InputStream content,
                                   String contentType)
                            throws SOAPException

將此附件部分的內容設置為 InputStream content 所包含的內容，並將 Content-Type 頭的值設置為 contentType 中包含的值。

後續調用 getSize() 可能無法準確度量內容的大小。

參數：

content - 要添加到附件部分的原始資料

contentType - 將在 Content-Type 頭中設置的值

拋出：

SOAPException - 如果設置內容時發生錯誤

NullPointerException - 如果 content 為 null

從以下版本開始：

SAAJ 1.3

setRawContentBytes

public abstract void setRawContentBytes(byte[] content,
                                        int offset,
                                        int len,
                                        String contentType)
                                 throws SOAPException

將此附件部分的內容設置為 byte[] 陣列 content 所包含的內容，並將 Content-Type 頭的值設置為 contentType 中包含的值。

參數：

content - 要添加到附件部分的原始資料

contentType - 要在 Content-Type 頭中設置的值

offset - 內容位元組陣列中的偏移量

len - 組成內容的位元組數

拋出：

SOAPException - 如果設置內容時發生錯誤，或者內容為 null

從以下版本開始：

SAAJ 1.3

setBase64Content

public abstract void setBase64Content(InputStream content,
                                      String contentType)
                               throws SOAPException

根據 Base64 源 InputStream 設置此附件部分的內容，並將 Content-Type 頭的值設置為 contentType 中包含的值，此方法將首先對 base64 輸入串流進行解碼，然後將得到的原始位元組寫入附件。

後續調用 getSize() 可能無法準確度量內容的大小。

參數：

content - 要添加到附件部分的 Base64 解碼資料

contentType - 要在 Content-Type 頭中設置的值

拋出：

SOAPException - 如果設置內容時發生錯誤

NullPointerException - 如果 content 為 null

從以下版本開始：

SAAJ 1.3

getDataHandler

public abstract DataHandler getDataHandler()
                                    throws SOAPException

獲取針對此 AttachmentPart 物件的 DataHandler 物件。

返回：

與此 AttachmentPart 物件關聯的 DataHandler 物件

拋出：

SOAPException - 如果此 AttachmentPart 物件中沒有資料

setDataHandler

public abstract void setDataHandler(DataHandler dataHandler)

將給定的 DataHandler 物件設置為此 AttachmentPart 物件的資料處理程序。通常，對於傳入的訊息，資料處理程序是自動設置的。創建訊息並填充內容之後，可以使用 setDataHandler 方法從各種資料源獲取資料並轉入該訊息中。

參數：

dataHandler - 要設置的 DataHandler 物件

拋出：

IllegalArgumentException - 如果指定的 DataHandler 物件存在問題

getContentId

public String getContentId()

獲取名為 "Content-ID" 的 MIME 頭的值。

返回：

給出 "Content-ID" 頭值的 String；如果不存在此類別字元串，則返回 null

另請參見：

setContentId(java.lang.String)

getContentLocation

public String getContentLocation()

獲取名為 "Content-Location" 的 MIME 頭的值。

返回：

給出 "Content-Location" 頭值的 String；如果不存在此類別字元串，則返回 null

getContentType

public String getContentType()

獲取名為 "Content-Type" 的 MIME 頭的值。

返回：

給出 "Content-Type" 頭值的 String；如果不存在此類別字元串，則返回 null

setContentId

public void setContentId(String contentId)

使用給定值設置名為 "Content-ID" 的 MIME 頭。

參數：

contentId - 給出 "Content-ID" 頭值的 String

拋出：

IllegalArgumentException - 如果指定的 contentId 值存在問題

另請參見：

getContentId()

setContentLocation

public void setContentLocation(String contentLocation)

使用給定值設置名為 "Content-Location" 的 MIME 頭。

參數：

contentLocation - 給出 "Content-Location" 頭值的 String

拋出：

IllegalArgumentException - 如果指定的內容位置存在問題

setContentType

public void setContentType(String contentType)

使用給定值設置名為 "Content-Type" 的 MIME 頭。

參數：

contentType - 給出 "Content-Type" 頭值的 String

拋出：

IllegalArgumentException - 如果指定的內容型別存在問題

removeMimeHeader

public abstract void removeMimeHeader(String header)

移除比對給定名稱的所有 MIME 頭。

參數：

header - 要移除的 MIME 頭的字元串名

removeAllMimeHeaders

public abstract void removeAllMimeHeaders()

移除所有 MIME 頭條目。

getMimeHeader

public abstract String[] getMimeHeader(String name)

獲取給定 String 所標識的頭的所有值。

參數：

name - 頭的名稱；範例："Content-Type"

返回：

給出指定頭值的 String 陣列

另請參見：

setMimeHeader(java.lang.String, java.lang.String)

setMimeHeader

public abstract void setMimeHeader(String name,
                                   String value)

將比對給定名稱的第一個頭條目的值更改為給定值，如果現有的頭都不比對，則添加一個新的頭。此方法還將移除第一個比對頭以外的所有比對的頭。

注意，RFC822 頭只能包含 US-ASCII 字元。

參數：

name - 一個 String，用於提供要搜尋的頭的名稱

value - 一個 String，用於提供將用來設置名稱比對給定名稱的頭的值

拋出：

IllegalArgumentException - 如果指定的 MIME 頭名稱或值存在問題

addMimeHeader

public abstract void addMimeHeader(String name,
                                   String value)

將帶有指定名稱和值的 MIME 頭添加到此 AttachmentPart 物件。

注意，RFC822 頭只能包含 US-ASCII 字元。

參數：

name - 一個 String，用於提供要添加的頭的名稱

value - 一個 String，用於提供要添加的頭的值

拋出：

IllegalArgumentException - 如果指定的 MIME 頭名稱或值存在問題

getAllMimeHeaders

public abstract Iterator getAllMimeHeaders()

以 MimeHeader 物件上的迭代器形式，檢索此 AttachmentPart 物件的所有頭。

返回：

帶有此 AttachmentPart 物件所有 MIME 頭的 Iterator 物件

getMatchingMimeHeaders

public abstract Iterator getMatchingMimeHeaders(String[] names)

檢索比對給定陣列中名稱的所有 MimeHeader 物件。

參數：

names - 一個 String 陣列，帶有要返回的 MIME 頭的名稱

返回：

所有比對給定陣列中任一名稱的 MIME 頭（Iterator 物件的形式）

getNonMatchingMimeHeaders

public abstract Iterator getNonMatchingMimeHeaders(String[] names)

檢索所有名稱不比對給定陣列中任一名稱的 MimeHeader 物件。

參數：

names - 一個 String 陣列，帶有無需返回的 MIME 頭的名稱

返回：

此 AttachmentPart 物件中的所有 MIME 頭，但比對給定陣列中任一名稱的 MIME 頭除外。以 Iterator 物件的形式返回不比對的 MIME 頭。