The Part interface is the common base interface for Messages and BodyParts.
Part consists of a set of attributes and a "Content".
Attributes:
The JavaMail API defines a set of standard Part attributes that are
considered to be common to most existing Mail systems. These attributes
have their own settor and gettor methods. Mail systems may support other
Part attributes as well, these are represented as name-value pairs where
both the name and value are Strings.
Content:
The data type of the "content" is returned by the
getContentType() method. The MIME typing system is used to
name data types.
The "content" of a Part is available in various formats:
- As a DataHandler - using the
getDataHandler() method.
The "content" of a Part is also available through a
javax.activation.DataHandler object. The DataHandler object allows clients
to discover the operations available on the content, and to instantiate
the appropriate component to perform those operations.
- As an input stream - using the
getInputStream() method.
Any mail-specific encodings are decoded before this stream is returned.
- As a Java object - using the
getContent() method.
This method returns the "content" as a Java object.
The returned object is of course dependent on the content itself.
In particular, a "multipart" Part's content is always a Multipart or
subclass thereof. That is, getContent() on a "multipart" type
Part will always return a Multipart(or subclass) object.
Part provides the
writeTo() method that streams out its
bytestream in mail-safe form suitable for transmission.
This bytestream is typically an aggregation of the Part attributes
and its content's bytestream.
Message and BodyPart implement the Part interface.
Note that in MIME parlance, Part models an Entity(RFC 2045, Section 2.4).
addHeader
public void addHeader(String name,
String value)
throws MessagingException Add this value to the existing values for this header name.
name - the name of this headervalue - the value for this header
getAllHeaders
public Enumeration getAllHeaders()
throws MessagingException Return all the headers from this part as an Enumeration of Header
objects.
getContent
public Object getContent()
throws IOException,
MessagingException Return the content as a Java object.
The type of the returned object is of course dependent on the content
itself. For example, the object returned for "text/plain" content
is usually a String object. The object returned for a "multipart"
content is always a Multipart subclass. For content-types that are
unknown to the DataHandler system, an input stream is returned as
the content
This is a convenience method that just invokes the DataHandler's
getContent() method
getContentType
public String getContentType()
throws MessagingException Returns the Content-Type of the content of this part.
Returns null if the Content-Type could not be determined.
The MIME typing system is used to name Content-types.
getDataHandler
public DataHandler getDataHandler()
throws MessagingException Return a DataHandler for the content within this part.
The DataHandler allows clients to operate on as well as retrieve
the content.
getDescription
public String getDescription()
throws MessagingException Return a description String for this part.
This typically associates some descriptive information with this part.
Returns null if none is available.
getDisposition
public String getDisposition()
throws MessagingException Return the disposition of this part.
The disposition describes how the part should be presented to the user.
(See RFC 2183.) The return value should be considered without
regard to case. For example:
String disp = part.getDisposition();
if (disp == null || disp.equalsIgnoreCase(Part.ATTACHMENT))
// treat as attachment if not first part
getFileName
public String getFileName()
throws MessagingException Get the filename associated with this part, if possible.
Useful if this part represents an "attachment" that was loaded
from a file. The filename will usually be a simple name, not
including directory components.
getHeader
public String[] getHeader(String name)
throws MessagingException Get all the headers for this header name.
Returns null if no headers for this header name are available.
name - the name of this header
getInputStream
public InputStream getInputStream()
throws IOException,
MessagingException Return an input stream for this part's "content".
Any mail-specific transfer encodings will be decoded before the
input stream is provided.
This is typically a convenience method that just invokes the
DataHandler's
getInputStream() method.
getLineCount
public int getLineCount()
throws MessagingException Return the number of lines in the content of this part.
Return -1 if the number cannot be determined.
Note that this number may not be an exact measure of the content
length and may or may not account for any transfer encoding
of the content.
getMatchingHeaders
public Enumeration getMatchingHeaders(String[] names)
throws MessagingException Return matching headers from this part as an Enumeration of Header
objects.
getNonMatchingHeaders
public Enumeration getNonMatchingHeaders(String[] names)
throws MessagingException Return non-matching headers from this envelope as an Enumeration of
Header objects.
getSize
public int getSize()
throws MessagingException Return the size of the content of this part in bytes.
Return -1 if the size cannot be determined.
Note that the size may not be an exact measure of the content size
and may or may not account for any transfer encoding of the content.
The size is appropriate for display in a user interface to give the
user a rough idea of the size of this part.
isMimeType
public boolean isMimeType(String mimeType)
throws MessagingException Is this Part of the specified MIME type?
This method compares only the primaryType and subType.
The parameters of the content types are ignored.
For example, this method will return true when comparing a Part
of content type "text/plain" with "text/plain; charset=foobar".
If the subType of mimeType is the special character '*',
then the subtype is ignored during the comparison.
removeHeader
public void removeHeader(String name)
throws MessagingException Remove all headers with this name.
name - the name of this header
setContent
public void setContent(Object obj,
String type)
throws MessagingException A convenience method for setting this part's content.
The part internally wraps the content in a DataHandler.
Note that a DataContentHandler class for the specified type should be
available to the JavaMail implementation for this to work right. i.e., to
do
setContent(foobar, "application/x-foobar"),
a DataContentHandler for "application/x-foobar" should be installed.
Refer to the Java Activation Framework for more information.
obj - A java object.type - MIME type of this object.
setContent
public void setContent(Multipart mp)
throws MessagingException This method sets the given Multipart object as this message's content.
mp - The multipart object that is the Message's content
setDataHandler
public void setDataHandler(DataHandler dh)
throws MessagingException This method provides the mechanism to set this part's content.
The DataHandler wraps around the actual content.
dh - The DataHandler for the content.
setDescription
public void setDescription(String description)
throws MessagingException Set a description String for this part.
This typically associates some descriptive information with this part.
description - description of this part
setDisposition
public void setDisposition(String disposition)
throws MessagingException Set the disposition of this part.
disposition - disposition of this part
setFileName
public void setFileName(String filename)
throws MessagingException Set the filename associated with this part, if possible.
Useful if this part represents an "attachment" that was loaded
from a file. The filename will usually be a simple name, not
including directory components.
filename - Filename to associate with this part
setHeader
public void setHeader(String name,
String value)
throws MessagingException Set the value for this header name.
Replaces all existing header values with this new value.
name - the name of this headervalue - the value for this header
setText
public void setText(String text)
throws MessagingException A convenience method that sets the given String as this part's content
with a MIME type of "text/plain".
text - The text that is the Message's content.
writeTo
public void writeTo(OutputStream os)
throws IOException,
MessagingException Output a bytestream for this Part.
This bytestream is typically an aggregration of the Part attributes
and an appropriately encoded bytestream from its 'content'.
Classes that implement the Part interface decide on the appropriate
encoding algorithm to be used.
The bytestream is typically used for sending.
MessagingException - if an error occurs fetching the data
to be written