public class MimeMultipart extends Multipart
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 Jakarta Mail 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 Jakarta Mail 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.
The mail.mime.multipart.ignoreexistingboundaryparameter
System property may be set to true
to cause any boundary
to be ignored and instead search for a boundary line in the message
as with mail.mime.multipart.ignoremissingboundaryparameter
.
Normally, when writing out a MimeMultipart that contains no body
parts, or when trying to parse a multipart message with no body parts,
a MessagingException
is thrown. The MIME spec does not allow
multipart content with no body parts. The
mail.mime.multipart.allowempty
System property may be set to
true
to override this behavior.
When writing out such a MimeMultipart, a single empty part will be
included. When reading such a multipart, a MimeMultipart will be created
with no body parts.
Modifier and Type | Field and Description |
---|---|
protected boolean |
allowEmpty
Flag corresponding to the "mail.mime.multipart.allowempty"
property, set in the
initializeProperties() method called from
constructors and the parse method. |
protected boolean |
complete
Have we seen the final bounary line?
|
protected DataSource |
ds
The DataSource supplying our InputStream.
|
protected boolean |
ignoreExistingBoundaryParameter
Flag corresponding to the
"mail.mime.multipart.ignoreexistingboundaryparameter"
property, set in the
initializeProperties() method called from
constructors and the parse method. |
protected boolean |
ignoreMissingBoundaryParameter
Flag corresponding to the
"mail.mime.multipart.ignoremissingboundaryparameter"
property, set in the
initializeProperties() method called from
constructors and the parse method. |
protected boolean |
ignoreMissingEndBoundary
Flag corresponding to the "mail.mime.multipart.ignoremissingendboundary"
property, set in the
initializeProperties() method called from
constructors and the parse method. |
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.
|
protected String |
preamble
The MIME multipart preamble text, the text that
occurs before the first boundary line.
|
contentType, parent, parts
Constructor and Description |
---|
MimeMultipart()
Default constructor.
|
MimeMultipart(BodyPart... parts)
Construct a MimeMultipart object of the default "mixed" subtype,
and with the given body parts.
|
MimeMultipart(DataSource ds)
Constructs a MimeMultipart object and its bodyparts from the
given DataSource.
|
MimeMultipart(String subtype)
Construct a MimeMultipart object of the given subtype.
|
MimeMultipart(String subtype,
BodyPart... parts)
Construct a MimeMultipart object of the given subtype
and with the given body parts.
|
Modifier and Type | Method and Description |
---|---|
void |
addBodyPart(BodyPart part)
Adds a Part to the multipart.
|
void |
addBodyPart(BodyPart part,
int index)
Adds a BodyPart at position
index . |
protected InternetHeaders |
createInternetHeaders(InputStream is)
Create and return an InternetHeaders object that loads the
headers from the given InputStream.
|
protected MimeBodyPart |
createMimeBodyPart(InputStream is)
Create and return a MimeBodyPart object to represent a
body part parsed from the InputStream.
|
protected MimeBodyPart |
createMimeBodyPart(InternetHeaders headers,
byte[] content)
Create and return a MimeBodyPart object to represent a
body part parsed from the InputStream.
|
BodyPart |
getBodyPart(int index)
Get the specified BodyPart.
|
BodyPart |
getBodyPart(String CID)
Get the MimeBodyPart referred to by the given ContentID (CID).
|
int |
getCount()
Return the number of enclosed BodyPart objects.
|
String |
getPreamble()
Get the preamble text, if any, that appears before the
first body part of this multipart.
|
protected void |
initializeProperties()
Initialize flags that control parsing behavior,
based on System properties described above in
the class documentation.
|
boolean |
isComplete()
Return true if the final boundary line for this
multipart was seen.
|
protected void |
parse()
Parse the InputStream from our DataSource, constructing the
appropriate MimeBodyParts.
|
boolean |
removeBodyPart(BodyPart part)
Remove the specified part from the multipart message.
|
void |
removeBodyPart(int index)
Remove the part at specified location (starting from 0).
|
void |
setPreamble(String preamble)
Set the preamble text to be included before the first
body part.
|
void |
setSubType(String subtype)
Set the subtype.
|
protected void |
updateHeaders()
Update headers.
|
void |
writeTo(OutputStream os)
Iterates through all the parts and outputs each MIME part
separated by a boundary.
|
getContentType, getParent, setMultipartDataSource, setParent
protected DataSource ds
protected boolean parsed
protected boolean complete
protected String preamble
protected boolean ignoreMissingEndBoundary
initializeProperties()
method called from
constructors and the parse method.protected boolean ignoreMissingBoundaryParameter
initializeProperties()
method called from
constructors and the parse method.protected boolean ignoreExistingBoundaryParameter
initializeProperties()
method called from
constructors and the parse method.protected boolean allowEmpty
initializeProperties()
method called from
constructors and the parse method.public MimeMultipart()
contentType
field. MimeBodyParts may be added later.
public MimeMultipart(String subtype)
contentType
field.
Calls the initializeProperties()
method.MimeBodyParts may be added later.
subtype
- the MIME content subtypepublic MimeMultipart(BodyPart... parts) throws MessagingException
parts
- the body partsMessagingException
- for failurespublic MimeMultipart(String subtype, BodyPart... parts) throws MessagingException
subtype
- the MIME content subtypeparts
- the body partsMessagingException
- for failurespublic MimeMultipart(DataSource ds) throws MessagingException
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.
ds
- DataSource, can be a MultipartDataSourceParseException
- for failures parsing the messageMessagingException
- for other failuresprotected void initializeProperties()
public void setSubType(String subtype) throws MessagingException
subtype
- SubtypeMessagingException
- for failurespublic int getCount() throws MessagingException
getCount
in class Multipart
MessagingException
- for failuresMultipart.parts
public BodyPart getBodyPart(int index) throws MessagingException
getBodyPart
in class Multipart
index
- the index of the desired BodyPartMessagingException
- if no such BodyPart existspublic BodyPart getBodyPart(String CID) throws MessagingException
CID
- the ContentID of the desired partMessagingException
- for failurespublic boolean removeBodyPart(BodyPart part) throws MessagingException
removeBodyPart
in class Multipart
part
- The part to removeMessagingException
- if no such Part existsIllegalWriteException
- if the underlying
implementation does not support modification
of existing valuespublic void removeBodyPart(int index) throws MessagingException
removeBodyPart
in class Multipart
index
- Index of the part to removeIndexOutOfBoundsException
- if the given index
is out of range.IllegalWriteException
- if the underlying
implementation does not support modification
of existing valuesMessagingException
- for other failurespublic void addBodyPart(BodyPart part) throws MessagingException
addBodyPart
in class Multipart
part
- The Part to be appendedIllegalWriteException
- if the underlying
implementation does not support modification
of existing valuesMessagingException
- for other failurespublic void addBodyPart(BodyPart part, int index) throws MessagingException
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.addBodyPart
in class Multipart
part
- The BodyPart to be insertedindex
- Location where to insert the partIllegalWriteException
- if the underlying
implementation does not support modification
of existing valuesMessagingException
- for other failurespublic boolean isComplete() throws MessagingException
MessagingException
- for failurespublic String getPreamble() throws MessagingException
MessagingException
- for failurespublic void setPreamble(String preamble) throws MessagingException
preamble
- the preamble textMessagingException
- for failuresprotected void updateHeaders() throws MessagingException
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.
MessagingException
- for failurespublic void writeTo(OutputStream os) throws IOException, MessagingException
writeTo
in class Multipart
os
- the stream to write toIOException
- if an IO related exception occursMessagingException
- for other failuresprotected void parse() throws MessagingException
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.
The initializeProperties()
method is called before
parsing the data.ParseException
- for failures parsing the messageMessagingException
- for other failuresprotected InternetHeaders createInternetHeaders(InputStream is) throws MessagingException
is
- the InputStream to read the headers fromMessagingException
- for failuresprotected MimeBodyPart createMimeBodyPart(InternetHeaders headers, byte[] content) throws MessagingException
headers
- the headers for the body partcontent
- the content of the body partMessagingException
- for failuresprotected MimeBodyPart createMimeBodyPart(InputStream is) throws MessagingException
is
- InputStream containing the body partMessagingException
- for failuresCopyright © 2019 Eclipse Foundation. Use is subject to license terms.