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();
 

ap1.clearContent();
 

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

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。