AttachmentPart (Java EE 5)

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

A single attachment to a SOAPMessage object. A SOAPMessage object may contain zero, one, or many AttachmentPart objects. Each AttachmentPart object consists of two parts, application-specific content and associated MIME headers. The MIME headers consists of name/value pairs that can be used to identify and describe the content.

An AttachmentPart object must conform to certain standards.

1. It must conform to MIME [RFC2045] standards
2. It MUST contain content
3. The header portion MUST include the following header:
   • Content-Type
     This header identifies the type of data in the content of an AttachmentPart object and MUST conform to [RFC2045]. The following is an example of a Content-Type header:

            Content-Type:  application/xml
            

     The following line of code, in which ap is an AttachmentPart object, sets the header shown in the previous example.

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

There are no restrictions on the content portion of an AttachmentPart object. The content may be anything from a simple plain text object to a complex XML document or image file.

An AttachmentPart object is created with the method SOAPMessage.createAttachmentPart. After setting its MIME headers, the AttachmentPart object is added to the message that created it with the method SOAPMessage.addAttachmentPart.

The following code fragment, in which m is a SOAPMessage object and contentStringl is a String, creates an instance of AttachmentPart, sets the AttachmentPart object with some content and header information, and adds the AttachmentPart object to the SOAPMessage object.

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

The following code fragment creates and adds a second AttachmentPart instance to the same message. jpegData is a binary byte buffer representing the jpeg file.

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

The getContent method retrieves the contents and header from an AttachmentPart object. Depending on the DataContentHandler objects present, the returned Object can either be a typed Java object corresponding to the MIME type or an InputStream object that contains the content as bytes.

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

     ap1.clearContent();
 

public AttachmentPart()

英文文档：

AttachmentPart

public AttachmentPart()

abstract public int getSize() throws SOAPException
返回此 AttachmentPart 对象中的字节数。

return	此 AttachmentPart 对象的大小，以字节为单位；如果无法确定其大小，则返回 -1
Throws	SOAPException: 如果此附件的内容已损坏，或者尝试确定其大小时引发异常。

英文文档：

getSize

public abstract int getSize()
                     throws SOAPException

Returns the number of bytes in this AttachmentPart object.

Returns:

the size of this AttachmentPart object in bytes or -1 if the size cannot be determined

Throws:

SOAPException - if the content of this attachment is corrupted of if there was an exception while trying to determine the size.

abstract public void clearContent()
清除此 AttachmentPart 对象的内容。MIME 头部分保持不变。

英文文档：

clearContent

public abstract void clearContent()

Clears out the content of this AttachmentPart object. The MIME header portion is left untouched.

abstract public 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 对象。

return	带有此 AttachmentPart 对象内容的 Java 对象
Throws	SOAPException: 如果此 AttachmentPart 对象中没有设置任何内容，或者出现数据转换错误

英文文档：

getContent

public abstract Object getContent()
                           throws SOAPException

Gets the content of this AttachmentPart object as a Java object. The type of the returned Java object depends on (1) the DataContentHandler object that is used to interpret the bytes and (2) the Content-Type given in the header.

For the MIME content types "text/plain", "text/html" and "text/xml", the DataContentHandler object does the conversions to and from the Java types corresponding to the MIME types. For other MIME types,the DataContentHandler object can return an InputStream object that contains the content data as raw bytes.

A SAAJ-compliant implementation must, as a minimum, return a java.lang.String object corresponding to any content stream with a Content-Type value of text/plain, a javax.xml.transform.stream.StreamSource object corresponding to a content stream with a Content-Type value of text/xml, a java.awt.Image object corresponding to a content stream with a Content-Type value of image/gif or image/jpeg. For those content types that an installed DataContentHandler object does not understand, the DataContentHandler object is required to return a java.io.InputStream object with the raw bytes.

Returns:

a Java object with the content of this AttachmentPart object

Throws:

SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error

abstract public java.io.InputStream getRawContent() throws SOAPException
以 InputStream 的形式获取此 AttachmentPart 对象的内容，等效于调用了 getContent 但没有为此 AttachmentPart 的 content-type 注册 DataContentHandler。

注意，读取返回的 InputStream 可能导致消耗流中的数据。调用者负责在调用 Subsequent API 之前适当地重置 InputStream。如果需要附件原始内容的一个副本，则应改用 #getRawContentBytes API。

return	一个 InputStream 对象，从中可以访问 AttachmentPart 包含的原始数据。
Throws	SOAPException: 如果此 AttachmentPart 对象中没有设置任何内容，或者出现数据转换错误。
since	SAAJ 1.3
See also	getRawContentBytes

英文文档：

getRawContent

public abstract InputStream getRawContent()
                                   throws SOAPException

Gets the content of this AttachmentPart object as an InputStream as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.

Note that reading from the returned InputStream would result in consuming the data in the stream. It is the responsibility of the caller to reset the InputStream appropriately before calling a Subsequent API. If a copy of the raw attachment content is required then the getRawContentBytes() API should be used instead.

Returns:

an InputStream from which the raw data contained by the AttachmentPart can be accessed.

Throws:

SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.

Since:

SAAJ 1.3

See Also:

getRawContentBytes()

abstract public byte[] getRawContentBytes() throws SOAPException
以 byte[] 数组形式获取此 AttachmentPart 对象的内容，等效于调用了 getContent 但没有为此 AttachmentPart 的 content-type 注册 DataContentHandler。

return	包含 AttachmentPart 原始数据的 byte[] 数组。
Throws	SOAPException: 如果此 AttachmentPart 对象中没有设置任何内容，或者出现数据转换错误。
since	SAAJ 1.3

英文文档：

getRawContentBytes

public abstract byte[] getRawContentBytes()
                                   throws SOAPException

Gets the content of this AttachmentPart object as a byte[] array as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.

Returns:

a byte[] array containing the raw data of the AttachmentPart.

Throws:

SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.

Since:

SAAJ 1.3

abstract public java.io.InputStream getBase64Content() throws SOAPException
以 Base64 编码字符数据的形式返回可用于获取 AttachmentPart 内容的 InputStream，此方法将对附件的原始字节进行 Base64 编码，然后返回该内容。

return	一个 InputStream 对象，从中可以读取 Base64 编码的 AttachmentPart。
Throws	SOAPException: 如果此 AttachmentPart 对象中没有设置任何内容，或者出现数据转换错误。
since	SAAJ 1.3

英文文档：

getBase64Content

public abstract InputStream getBase64Content()
                                      throws SOAPException

Returns an InputStream which can be used to obtain the content of AttachmentPart as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.

Returns:

an InputStream from which the Base64 encoded AttachmentPart can be read.

Throws:

SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.

Since:

SAAJ 1.3

abstract public void setContent(Object object, String contentType)
将此附件部分的内容设置为给定 Object 的内容，并将 Content-Type 头的值设置为给定类型。Object 的类型应该对应于指定给 Content-Type 的值。这取决于所使用的特定 DataContentHandler 对象集合。

object	组成此附件部分内容的 Java 对象
contentType	指定内容类型的 MIME 字符串
Throws	IllegalArgumentException: 如果 contentType 不匹配内容对象的类型，或者没有针对此内容对象的 DataContentHandler 对象
See also	getContent

英文文档：

setContent

public abstract void setContent(Object object,
                                String contentType)

Sets the content of this attachment part to that of the given Object and sets the value of the Content-Type header to the given type. The type of the Object should correspond to the value given for the Content-Type. This depends on the particular set of DataContentHandler objects in use.

Parameters:

object - the Java object that makes up the content for this attachment part

contentType - the MIME string that specifies the type of the content

Throws:

IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for this content object

See Also:

getContent()

abstract public void setRawContent(java.io.InputStream content, String contentType) throws SOAPException
将此附件部分的内容设置为 InputStream content 所包含的内容，并将 Content-Type 头的值设置为 contentType 中包含的值。

后续调用 getSize() 可能无法准确度量内容的大小。

content	要添加到附件部分的原始数据
contentType	要在 Content-Type 头中设置的值
Throws	SOAPException: 如果设置内容时发生错误
Throws	NullPointerException: 如果 content 为 null
since	SAAJ 1.3

英文文档：

setRawContent

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

Sets the content of this attachment part to that contained by the InputStream content and sets the value of the Content-Type header to the value contained in contentType.

A subsequent call to getSize() may not be an exact measure of the content size.

Parameters:

content - the raw data to add to the attachment part

contentType - the value to set into the Content-Type header

Throws:

SOAPException - if an there is an error in setting the content

NullPointerException - if content is null

Since:

SAAJ 1.3

abstract public void setRawContentBytes(byte[] content, int offset, int len, String contentType) throws SOAPException
将此附件部分的内容设置为 byte[] 数组 content 所包含的内容，并将 Content-Type 头的值设置为 contentType 中包含的值。

content	要添加到附件部分的原始数据
contentType	要在 Content-Type 头中设置的值
offset	内容字节数组中的偏移量
len	组成内容的字节数
Throws	SOAPException: 如果设置内容时发生错误，或者内容为 null
since	SAAJ 1.3

英文文档：

setRawContentBytes

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

Sets the content of this attachment part to that contained by the byte[] array content and sets the value of the Content-Type header to the value contained in contentType.

Parameters:

content - the raw data to add to the attachment part

contentType - the value to set into the Content-Type header

offset - the offset in the byte array of the content

len - the number of bytes that form the content

Throws:

SOAPException - if an there is an error in setting the content or content is null

Since:

SAAJ 1.3

abstract public void setBase64Content(java.io.InputStream content, String contentType) throws SOAPException
根据 Base64 源 InputStream 设置此附件部分的内容，并将 Content-Type 头的值设置为 contentType 中包含的值，此方法将首先对 base64 输入流进行解码，然后将得到的原始字节写入附件。

后续调用 getSize() 可能无法准确度量内容的大小。

content	要添加到附件部分的 Base64 解码数据
contentType	要在 Content-Type 头中设置的值
Throws	SOAPException: 如果设置内容时发生错误
Throws	NullPointerException: 如果 content 为 null
since	SAAJ 1.3

英文文档：

setBase64Content

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

Sets the content of this attachment part from the Base64 source InputStream and sets the value of the Content-Type header to the value contained in contentType, This method would first decode the base64 input and write the resulting raw bytes to the attachment.

A subsequent call to getSize() may not be an exact measure of the content size.

Parameters:

content - the base64 encoded data to add to the attachment part

contentType - the value to set into the Content-Type header

Throws:

SOAPException - if an there is an error in setting the content

NullPointerException - if content is null

Since:

SAAJ 1.3

abstract public DataHandler getDataHandler() throws SOAPException
获取针对此 AttachmentPart 对象的 DataHandler 对象。

return	与此 AttachmentPart 对象关联的 DataHandler 对象
Throws	SOAPException: 如果此 AttachmentPart 对象中没有数据

英文文档：

getDataHandler

public abstract DataHandler getDataHandler()
                                    throws SOAPException

Gets the DataHandler object for this AttachmentPart object.

Returns:

the DataHandler object associated with this AttachmentPart object

Throws:

SOAPException - if there is no data in this AttachmentPart object

abstract public void setDataHandler(DataHandler dataHandler)
将给定的 DataHandler 对象设置为此 AttachmentPart 对象的数据处理程序。通常，对于传入的消息，数据处理程序是自动设置的。创建消息并填充内容之后，可以使用 setDataHandler 方法从各种数据源获取数据并转入该消息中。

dataHandler	要设置的 DataHandler 对象
Throws	IllegalArgumentException: 如果指定的 DataHandler 对象存在问题

英文文档：

setDataHandler

public abstract void setDataHandler(DataHandler dataHandler)

Sets the given DataHandler object as the data handler for this AttachmentPart object. Typically, on an incoming message, the data handler is automatically set. When a message is being created and populated with content, the setDataHandler method can be used to get data from various data sources into the message.

Parameters:

dataHandler - the DataHandler object to be set

Throws:

IllegalArgumentException - if there was a problem with the specified DataHandler object

public String getContentId()
获取名为 "Content-ID" 的 MIME 头的值。

return	给出 "Content-ID" 头值的 String；如果不存在此类字符串，则返回 null
See also	setContentId

英文文档：

getContentId

public String getContentId()

Gets the value of the MIME header whose name is "Content-ID".

Returns:

a String giving the value of the "Content-ID" header or null if there is none

See Also:

setContentId(java.lang.String)

public String getContentLocation()
获取名为 "Content-Location" 的 MIME 头的值。

return

给出 "Content-Location" 头值的 String；如果不存在此类字符串，则返回 null

英文文档：

getContentLocation

public String getContentLocation()

Gets the value of the MIME header whose name is "Content-Location".

Returns:

a String giving the value of the "Content-Location" header or null if there is none

public String getContentType()
获取名为 "Content-Type" 的 MIME 头的值。

return

给出 "Content-Type" 头值的 String；如果不存在此类字符串，则返回 null

英文文档：

getContentType

public String getContentType()

Gets the value of the MIME header whose name is "Content-Type".

Returns:

a String giving the value of the "Content-Type" header or null if there is none

public void setContentId(String contentId)
使用给定值设置名为 "Content-ID" 的 MIME 头。

contentId	给出 "Content-ID" 头值的 String
Throws	IllegalArgumentException: 如果指定的 contentId 值存在问题
See also	getContentId

英文文档：

setContentId

public void setContentId(String contentId)

Sets the MIME header whose name is "Content-ID" with the given value.

Parameters:

contentId - a String giving the value of the "Content-ID" header

Throws:

IllegalArgumentException - if there was a problem with the specified contentId value

See Also:

getContentId()

public void setContentLocation(String contentLocation)
使用给定值设置名为 "Content-Location" 的 MIME 头。

contentLocation	给出 "Content-Location" 头值的 String
Throws	IllegalArgumentException: 如果指定的内容位置存在问题

英文文档：

setContentLocation

public void setContentLocation(String contentLocation)

Sets the MIME header whose name is "Content-Location" with the given value.

Parameters:

contentLocation - a String giving the value of the "Content-Location" header

Throws:

IllegalArgumentException - if there was a problem with the specified content location

public void setContentType(String contentType)
使用给定值设置名为 "Content-Type" 的 MIME 头。

contentType	给出 "Content-Type" 头值的 String
Throws	IllegalArgumentException: 如果指定的内容类型存在问题

英文文档：

setContentType

public void setContentType(String contentType)

Sets the MIME header whose name is "Content-Type" with the given value.

Parameters:

contentType - a String giving the value of the "Content-Type" header

Throws:

IllegalArgumentException - if there was a problem with the specified content type

abstract public void removeMimeHeader(String header)
移除所有与给定名称匹配的 MIME 头。

header

要移除的 MIME 头的字符串名

英文文档：

removeMimeHeader

public abstract void removeMimeHeader(String header)

Removes all MIME headers that match the given name.

Parameters:

header - the string name of the MIME header/s to be removed

abstract public void removeAllMimeHeaders()
移除所有 MIME 头条目。

英文文档：

removeAllMimeHeaders

public abstract void removeAllMimeHeaders()

Removes all the MIME header entries.

abstract public String[] getMimeHeader(String name)
获取给定 String 所标识的头的所有值。

name	头的名称；示例："Content-Type"
return	给出指定头值的 String 数组
See also	setMimeHeader

英文文档：

getMimeHeader

public abstract String[] getMimeHeader(String name)

Gets all the values of the header identified by the given String.

Parameters:

name - the name of the header; example: "Content-Type"

Returns:

a String array giving the value for the specified header

See Also:

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

abstract public void setMimeHeader(String name, String value)
将匹配给定名称的第一个头条目的值更改为给定值，如果现有的头都不匹配，则添加一个新的头。此方法还将移除第一个匹配头以外的所有匹配的头。

注意，RFC822 头只能包含 US-ASCII 字符。

name	一个 String，用于提供要搜索的头的名称
value	一个 String，用于提供将用来设置名称匹配给定名称的头的值
Throws	IllegalArgumentException: 如果指定的 MIME 头名称或值存在问题

英文文档：

setMimeHeader

public abstract void setMimeHeader(String name,
                                   String value)

Changes the first header entry that matches the given name to the given value, adding a new header if no existing header matches. This method also removes all matching headers but the first.

Note that RFC822 headers can only contain US-ASCII characters.

Parameters:

name - a String giving the name of the header for which to search

value - a String giving the value to be set for the header whose name matches the given name

Throws:

IllegalArgumentException - if there was a problem with the specified mime header name or value

abstract public void addMimeHeader(String name, String value)
将带有指定名称和值的 MIME 头添加到此 AttachmentPart 对象。

注意，RFC822 头只能包含 US-ASCII 字符。

name	一个 String，用于提供要添加的头的名称
value	一个 String，用于提供要添加的头的值
Throws	IllegalArgumentException: 如果指定的 MIME 头名称或值存在问题

英文文档：

addMimeHeader

public abstract void addMimeHeader(String name,
                                   String value)

Adds a MIME header with the specified name and value to this AttachmentPart object.

Note that RFC822 headers can contain only US-ASCII characters.

Parameters:

name - a String giving the name of the header to be added

value - a String giving the value of the header to be added

Throws:

IllegalArgumentException - if there was a problem with the specified mime header name or value

abstract public java.util.Iterator<E> getAllMimeHeaders()
以 MimeHeader 对象上的迭代器形式，检索此 AttachmentPart 对象的所有头。

return

带有此 AttachmentPart 对象所有 MIME 头的 Iterator 对象

英文文档：

getAllMimeHeaders

public abstract Iterator getAllMimeHeaders()

Retrieves all the headers for this AttachmentPart object as an iterator over the MimeHeader objects.

Returns:

an Iterator object with all of the Mime headers for this AttachmentPart object

abstract public java.util.Iterator<E> getMatchingMimeHeaders(String[] names)
检索匹配给定数组中名称的所有 MimeHeader 对象。

names	一个 String 数组，带有要返回的 Mime 头的名称
return	所有匹配给定数组中任一名称的 MIME 头（Iterator 对象的形式）

英文文档：

getMatchingMimeHeaders

public abstract Iterator getMatchingMimeHeaders(String[] names)

Retrieves all MimeHeader objects that match a name in the given array.

Parameters:

names - a String array with the name(s) of the MIME headers to be returned

Returns:

all of the MIME headers that match one of the names in the given array as an Iterator object

abstract public java.util.Iterator<E> getNonMatchingMimeHeaders(String[] names)
检索所有名称不匹配给定数组中任一名称的 MimeHeader 对象。

names	一个 String 数组，带有不要返回的 Mime 头的名称
return	此 AttachmentPart 对象中的所有 MIME 头，但匹配给定数组中任一名称的 MIME 头除外。以 Iterator 对象的形式返回不匹配的 MIME 头。

英文文档：

getNonMatchingMimeHeaders

public abstract Iterator getNonMatchingMimeHeaders(String[] names)

Retrieves all MimeHeader objects whose name does not match a name in the given array.

Parameters:

names - a String array with the name(s) of the MIME headers not to be returned

Returns:

all of the MIME headers in this AttachmentPart object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an Iterator object.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.