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 头。