MimeMultipart (Java EE 5)

MimeMultipart 从基本类型为 "multipart" 的 MimePart 中获取（通过调用该部分的 getContent() 方法），也可以通过客户端作为新建 MimeMessage 的一部分创建。

默认的 multipart 子类型为 "mixed"。其他 multipart 子类型（如 "alternative"、"related"，等等）可以作为 MimeMultipart 的子类实现，需要一些额外的方法来实现该类型 multipart 内容的其他语义。服务提供者、邮件 JavaBean 编写者和邮件客户端将编写许多这种子类型及其命令 Bean，并将它们安装在 JavaBeans Activation Framework 中，以便任何 JavaMail 实现及其客户端能透明地找到并使用这些类。因此，MIME multipart 处理程序的处理方式与任何其他类型的处理程序一样，要将提供multipart 处理程序的过程从 JavaMail API 中分离出来。如果缺少这些附加的 MimeMultipart 子类，所有子类型的 MIME multipart 数据都将显示为 MimeMultipart 对象。

通过使用 MimeMultipart(String subtype) 构造方法，应用程序可以直接构造任意子类型的 MIME multipart 对象。例如，要创建 "multipart/alternative" 对象，则使用 new MimeMultipart("alternative")。

mail.mime.multipart.ignoremissingendboundary 属性可以设置为 false，在这种情况下，如果 multipart 数据不能以所需的结束边界行结尾，则抛出 MessagingException。如果此属性设置为 true 或没有设置，则缺少结束边界不会被视为错误，最终的正文部分将在数据末尾结束。

mail.mime.multipart.ignoremissingboundaryparameter 系统属性可以设置为 false，在这种情况下，如果 Content-Type 的 MimeMultipart 不包括 boundary 参数，则抛出 MessagingException。如果此属性设置为 true 或没有设置，则 multipart 解析代码将查找一个类似边界行的行，并将此行用作分隔各部分的边界。

The MimeMultipart class is an implementation of the abstract Multipart class that uses MIME conventions for the multipart data.

A MimeMultipart is obtained from a MimePart whose primary type is "multipart" (by invoking the part's getContent() method) or it can be created by a client as part of creating a new MimeMessage.

The default multipart subtype is "mixed". The other multipart subtypes, such as "alternative", "related", and so on, can be implemented as subclasses of MimeMultipart with additional methods to implement the additional semantics of that type of multipart content. The intent is that service providers, mail JavaBean writers and mail clients will write many such subclasses and their Command Beans, and will install them into the JavaBeans Activation Framework, so that any JavaMail implementation and its clients can transparently find and use these classes. Thus, a MIME multipart handler is treated just like any other type handler, thereby decoupling the process of providing multipart handlers from the JavaMail API. Lacking these additional MimeMultipart subclasses, all subtypes of MIME multipart data appear as MimeMultipart objects.

An application can directly construct a MIME multipart object of any subtype by using the MimeMultipart(String subtype) constructor. For example, to create a "multipart/alternative" object, use new MimeMultipart("alternative").

The mail.mime.multipart.ignoremissingendboundary property may be set to false to cause a MessagingException to be thrown if the multipart data does not end with the required end boundary line. If this property is set to true or not set, missing end boundaries are not considered an error and the final body part ends at the end of the data.

The mail.mime.multipart.ignoremissingboundaryparameter System property may be set to false to cause a MessagingException to be thrown if the Content-Type of the MimeMultipart does not include a boundary parameter. If this property is set to true or not set, the multipart parsing code will look for a line that looks like a bounary line and use that as the boundary separating the parts.

Version:

1.48, 07/05/15

Author:

John Mani, Bill Shannon, Max Spivak

英文文档：

ds

protected DataSource ds

The DataSource supplying our InputStream.

英文文档：

parsed

protected boolean parsed

Have we parsed the data from our InputStream yet? Defaults to true; set to false when our constructor is given a DataSource with an InputStream that we need to parse.

public MimeMultipart()
默认构造方法。创建一个空 MimeMultipart 对象。其内容类型设置为 "multipart/mixed"。将生成唯一的边界字符串，并且此字符串将设置为 contentType 字段的 "boundary" 参数。

可以随后添加 MimeBodyParts。

英文文档：

MimeMultipart

public MimeMultipart()

Default constructor. An empty MimeMultipart object is created. Its content type is set to "multipart/mixed". A unique boundary string is generated and this string is setup as the "boundary" parameter for the contentType field.

MimeBodyParts may be added later.

public MimeMultipart(String subtype)
构造给定子类型的 MimeMultipart 对象。将生成唯一的边界字符串，并且此字符串将设置为 contentType 字段的 "boundary" 参数。

可以随后添加 MimeBodyPart。

英文文档：

MimeMultipart

public MimeMultipart(String subtype)

Construct a MimeMultipart object of the given subtype. A unique boundary string is generated and this string is setup as the "boundary" parameter for the contentType field.

MimeBodyParts may be added later.

public MimeMultipart(DataSource ds) throws MessagingException
根据给定 DataSource 构造 MimeMultipart 对象及其 bodypart。

此构造方法处理的是一种特殊情况，即给定的 DataSource 是一个 MultipartDataSource 对象。在这种情况下，此方法仅调用带有 MultipartDataSource 对象的超类（即 Multipart）构造方法。

在其他情况下，DataSource 被假定为提供一个 MIME multipart 字节流。parsed 标志设置为 false。当需要正文部分的数据时，解析器从此 DataSource 的内容类型中提取 "boundary" 参数，跳过 'preamble' 并读取终止边界之前的字节，然后为此流的每个部分创建 MimeBodyPart。

ds	DataSource，可以是 MultipartDataSource

英文文档：

MimeMultipart

public MimeMultipart(DataSource ds)
              throws MessagingException

Constructs a MimeMultipart object and its bodyparts from the given DataSource.

This constructor handles as a special case the situation where the given DataSource is a MultipartDataSource object. In this case, this method just invokes the superclass (i.e., Multipart) constructor that takes a MultipartDataSource object.

Otherwise, the DataSource is assumed to provide a MIME multipart byte stream. The parsed flag is set to false. When the data for the body parts are needed, the parser extracts the "boundary" parameter from the content type of this DataSource, skips the 'preamble' and reads bytes till the terminating boundary and creates MimeBodyParts for each part of the stream.

Parameters:

ds - DataSource, can be a MultipartDataSource

Throws:

MessagingException

public void setSubType(String subtype) throws MessagingException
设置子类型。只应该对客户端创建的新 MimeMultipart 对象调用此方法。这种 multipart 对象的默认子类型为 "mixed"。

subtype

子类型

英文文档：

setSubType

public void setSubType(String subtype)
                throws MessagingException

Set the subtype. This method should be invoked only on a new MimeMultipart object created by the client. The default subtype of such a multipart object is "mixed".

Parameters:

subtype - Subtype

Throws:

MessagingException

public int getCount() throws MessagingException
返回封闭 BodyPart 对象的数量。

return

部分数

英文文档：

getCount

public int getCount()
             throws MessagingException

Return the number of enclosed BodyPart objects.

Overrides:

getCount in class Multipart

Returns:

number of parts

Throws:

MessagingException

See Also:

Multipart.parts

public BodyPart getBodyPart(int index) throws MessagingException
获取指定的 BodyPart。BodyPart 从 0 开始编号。

index	所需 BodyPart 的索引
return	Part
Throws	MessagingException: 如果不存在这种 BodyPart

英文文档：

getBodyPart

public BodyPart getBodyPart(int index)
                     throws MessagingException

Get the specified BodyPart. BodyParts are numbered starting at 0.

Overrides:

getBodyPart in class Multipart

Parameters:

index - the index of the desired BodyPart

Returns:

the Part

Throws:

MessagingException - if no such BodyPart exists

public BodyPart getBodyPart(String CID) throws MessagingException
获取给定 ContentID (CID) 所引用的 MimeBodyPart。如果未找到该部分，则返回 null。

CID	所需部分的 ContentID
return	Part

英文文档：

getBodyPart

public BodyPart getBodyPart(String CID)
                     throws MessagingException

Get the MimeBodyPart referred to by the given ContentID (CID). Returns null if the part is not found.

Parameters:

CID - the ContentID of the desired part

Returns:

the Part

Throws:

MessagingException

public boolean removeBodyPart(BodyPart part) throws MessagingException
从 multipart 消息中移除指定的部分。将所有部分向移除部分移动一位。

part	要移除的部分
return	如果移除了 part，则返回 true；否则返回 false
Throws	MessagingException: 如果不存在此类 Part
Throws	IllegalWriteException: 如果底层实现不支持修改现有值

英文文档：

removeBodyPart

public boolean removeBodyPart(BodyPart part)
                       throws MessagingException

Remove the specified part from the multipart message. Shifts all the parts after the removed part down one.

Overrides:

removeBodyPart in class Multipart

Parameters:

part - The part to remove

Returns:

true if part removed, false otherwise

Throws:

MessagingException - if no such Part exists

IllegalWriteException - if the underlying implementation does not support modification of existing values

public void removeBodyPart(int index) throws MessagingException
移除指定位置（从 0 开始）的部分。将所有部分向移除部分移动一位。

index	要移除部分的索引
Throws	MessagingException:
Throws	IndexOutOfBoundsException: 如果给定索引超出范围。
Throws	IllegalWriteException: 如果底层实现不支持修改现有值

英文文档：

removeBodyPart

public void removeBodyPart(int index)
                    throws MessagingException

Remove the part at specified location (starting from 0). Shifts all the parts after the removed part down one.

Overrides:

removeBodyPart in class Multipart

Parameters:

index - Index of the part to remove

Throws:

MessagingException

IndexOutOfBoundsException - if the given index is out of range.

IllegalWriteException - if the underlying implementation does not support modification of existing values

public void addBodyPart(BodyPart part) throws MessagingException
将 Part 添加到 multipart。BodyPart 将被添加到现有的 Part 列表。

part	要添加的 Part
Throws	MessagingException:
Throws	IllegalWriteException: 如果底层实现不支持修改现有值

英文文档：

addBodyPart

public void addBodyPart(BodyPart part)
                 throws MessagingException

Adds a Part to the multipart. The BodyPart is appended to the list of existing Parts.

Overrides:

addBodyPart in class Multipart

Parameters:

part - The Part to be appended

Throws:

MessagingException

IllegalWriteException - if the underlying implementation does not support modification of existing values

public void addBodyPart(BodyPart part, int index) throws MessagingException
在 index 处添加 BodyPart。如果 index 不是列表中的最后一个，则后续部分将向上移。如果 index 大于现有的部分数，则将在末尾添加 BodyPart。

part	要插入的 BodyPart
index	插入部分的位置
Throws	MessagingException:
Throws	IllegalWriteException: 如果底层实现不支持修改现有值

英文文档：

addBodyPart

public void addBodyPart(BodyPart part,
                        int index)
                 throws MessagingException

Adds a BodyPart at position index. If index is not the last one in the list, the subsequent parts are shifted up. If index is larger than the number of parts present, the BodyPart is appended to the end.

Overrides:

addBodyPart in class Multipart

Parameters:

part - The BodyPart to be inserted

index - Location where to insert the part

Throws:

MessagingException

IllegalWriteException - if the underlying implementation does not support modification of existing values

public boolean isComplete() throws MessagingException
如果遇到此 multipart 的最终边界线，则返回 true。解析 multipart 内容时，如果在遇到最终 multipart 边界行之前已到达输入末尾，则子类将（在默认情况下）终止解析，而且没有任何错误。在这种情况下，此方法将返回 false。（如果系统属性 "mail.mime.multipart.ignoremissingendboundary" 设置为 false，则解析此类消息将改为抛出 MessagingException。）

return	如果遇到最终边界行，则返回 true
since	en JavaMail 1.4

英文文档：

isComplete

public boolean isComplete()
                   throws MessagingException

Return true if the final boundary line for this multipart was seen. When parsing multipart content, this class will (by default) terminate parsing with no error if the end of input is reached before seeing the final multipart boundary line. In such a case, this method will return false. (If the System property "mail.mime.multipart.ignoremissingendboundary" is set to false, parsing such a message will instead throw a MessagingException.)

Returns:

true if the final boundary line was seen

Throws:

MessagingException

Since:

JavaMail 1.4

public String getPreamble() throws MessagingException
获取导言文本（如果有），它位于此 multipart 的第一个正文部分的前面。有些协议（如 IMAP）将不允许访问导言文本。

return	导言文本；如果没有导言，则返回 null
since	en JavaMail 1.4

英文文档：

getPreamble

public String getPreamble()
                   throws MessagingException

Get the preamble text, if any, that appears before the first body part of this multipart. Some protocols, such as IMAP, will not allow access to the preamble text.

Returns:

the preamble text, or null if no preamble

Throws:

MessagingException

Since:

JavaMail 1.4

public void setPreamble(String preamble) throws MessagingException
将导言文本设置为包含在第一个正文部分前面。应用程序通常不应该包含任何导言文本。在某些情况下，包含带有针对准 MIME 软件用户的说明的导言文本会很有用。导言文本应该是完整的行，包括新行。

preamble	导言文本
since	en JavaMail 1.4

英文文档：

setPreamble

public void setPreamble(String preamble)
                 throws MessagingException

Set the preamble text to be included before the first body part. Applications should generally not include any preamble text. In some cases it may be helpful to include preamble text with instructions for users of pre-MIME software. The preamble text should be complete lines, including newlines.

Parameters:

preamble - the preamble text

Throws:

MessagingException

Since:

JavaMail 1.4

protected void updateHeaders() throws MessagingException
更新头。这里的默认实现仅对头的每个子 BodyPart 调用 updateHeaders 方法。

注意，在创建新的空 MimeMultipart 对象时，boundary 参数已经设置。

对包含此 Multipart 的 Message 对象调用 saveChanges 方法时，调用此方法。这通常作为 Message 发送过程的一部分完成，但是要注意，客户端可以随意调用此方法任意次数。因此，如果对于特定 MimeMultipart 子类，头更新过程开销很大，则它会自己跟踪其内部状态是否真正发生了更改，并只在必要时更新头。

英文文档：

updateHeaders

protected void updateHeaders()
                      throws MessagingException

Update headers. The default implementation here just calls the updateHeaders method on each of its children BodyParts.

Note that the boundary parameter is already set up when a new and empty MimeMultipart object is created.

This method is called when the saveChanges method is invoked on the Message object containing this Multipart. This is typically done as part of the Message send process, however note that a client is free to call it any number of times. So if the header updating process is expensive for a specific MimeMultipart subclass, then it might itself want to track whether its internal state actually did change, and do the header updating only if necessary.

Throws:

MessagingException

public void writeTo(java.io.OutputStream os) throws java.io.IOException, MessagingException
迭代所有部分并输出边界分隔的每个 MIME 部分。

英文文档：

writeTo

public void writeTo(OutputStream os)
             throws IOException,
                    MessagingException

Iterates through all the parts and outputs each MIME part separated by a boundary.

Specified by:

writeTo in class Multipart

Throws:

IOException - if an IO related exception occurs

MessagingException

protected void parse() throws MessagingException
解析 DataSource 的 InputStream，构造相应的 MimeBodyPart。parsed 标志设置为 true，为 true 时不进行任何输入。此方法供所有其他需要正文部分数据的方法调用，以确保数据已经被解析。

since

en JavaMail 1.2

英文文档：

parse

protected void parse()
              throws MessagingException

Parse the InputStream from our DataSource, constructing the appropriate MimeBodyParts. The parsed flag is set to true, and if true on entry nothing is done. This method is called by all other methods that need data for the body parts, to make sure the data has been parsed.

Throws:

MessagingException

Since:

JavaMail 1.2

protected InternetHeaders createInternetHeaders(java.io.InputStream is) throws MessagingException
创建并返回从给定 InputStream 加载头的 InternetHeaders 对象。子类可重写此方法，以返回 InternetHeaders 的子类（如有必要）。此实现只是构造和返回 InternetHeaders 对象。

is	要从中读取头的 InputStream
Throws	MessagingException:
since	en JavaMail 1.2

英文文档：

createInternetHeaders

protected InternetHeaders createInternetHeaders(InputStream is)
                                         throws MessagingException

Create and return an InternetHeaders object that loads the headers from the given InputStream. Subclasses can override this method to return a subclass of InternetHeaders, if necessary. This implementation simply constructs and returns an InternetHeaders object.

Parameters:

is - the InputStream to read the headers from

Throws:

MessagingException

Since:

JavaMail 1.2

protected MimeBodyPart createMimeBodyPart(InternetHeaders headers, byte[] content) throws MessagingException
创建并返回一个 MimeBodyPart 对象，表示解析 InputStream 的正文部分。子类可重写此方法，以返回 MimeBodyPart 的子类（如果需要）。此实现只是构造和返回 MimeBodyPart 对象。

headers	正文部分的头
content	正文部分的内容
Throws	MessagingException:
since	en JavaMail 1.2

英文文档：

createMimeBodyPart

protected MimeBodyPart createMimeBodyPart(InternetHeaders headers,
                                          byte[] content)
                                   throws MessagingException

Create and return a MimeBodyPart object to represent a body part parsed from the InputStream. Subclasses can override this method to return a subclass of MimeBodyPart, if necessary. This implementation simply constructs and returns a MimeBodyPart object.

Parameters:

headers - the headers for the body part

content - the content of the body part

Throws:

MessagingException

Since:

JavaMail 1.2

protected MimeBodyPart createMimeBodyPart(java.io.InputStream is) throws MessagingException
创建并返回一个 MimeBodyPart 对象，表示解析 InputStream 的正文部分。子类可重写此方法，以返回 MimeBodyPart 的子类（如果需要）。此实现只是构造和返回 MimeBodyPart 对象。

is	包含正文部分的 InputStream
Throws	MessagingException:
since	en JavaMail 1.2

英文文档：

createMimeBodyPart

protected MimeBodyPart createMimeBodyPart(InputStream is)
                                   throws MessagingException

Create and return a MimeBodyPart object to represent a body part parsed from the InputStream. Subclasses can override this method to return a subclass of MimeBodyPart, if necessary. This implementation simply constructs and returns a MimeBodyPart object.

Parameters:

is - InputStream containing the body part

Throws:

MessagingException

Since:

JavaMail 1.2

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