javax.mail.internet
Class MimeMessage

java.lang.Object
  javax.mail.Message
      javax.mail.internet.MimeMessage

All Implemented Interfaces:

MimePart, Part

public class MimeMessage
extends Message
implements MimePart

Version:

$Rev: 398618 $ $Date: 2006-05-01 08:18:57 -0700 (Mon, 01 May 2006) $

Nested Class Summary

static class

MimeMessage.RecipientType Extends Message.RecipientType to support addition recipient types.

Field Summary

protected byte[]	content This message's content (unless sourced from a SharedInputStream).
protected InputStream	contentStream If the data for this message was supplied by a SharedInputStream then this is another such stream representing the content of this message; if this field is non-null, then content will be null.
protected DataHandler	dh The DataHandler for this Message's content.
protected Flags	flags This message's flags.
protected InternetHeaders	headers This message's headers.
protected boolean	modified Flag indicating that the message has been modified; set to true when an empty message is created or when saveChanges() is called.
protected boolean	saved Flag indicating that the message has been saved.

Fields inherited from class javax.mail.Message

expunged, folder, msgnum, session

Fields inherited from interface javax.mail.Part

ATTACHMENT, INLINE

Constructor Summary

protected	MimeMessage(Folder folder, InputStream in, int number) Create a MimeMessage by reading an parsing the data from the supplied stream.
protected	MimeMessage(Folder folder, int number) Create an new MimeMessage in the supplied Folder and message number.
protected	MimeMessage(Folder folder, InternetHeaders headers, byte[] content, int number) Create a MimeMessage with the supplied headers and content.
	MimeMessage(MimeMessage message) Copy a MimeMessage.
	MimeMessage(Session session) Create a new MimeMessage.
	MimeMessage(Session session, InputStream in) Create a MimeMessage by reading an parsing the data from the supplied stream.

Method Summary

void	addFrom(Address[] addresses) Add a set of addresses to the existing From header.
void	addHeader(String name, String value) Add a new value to an existing header.
void	addHeaderLine(String line)
void	addRecipients(Message.RecipientType type, Address[] address) Add a list of addresses to a target recipient list.
void	addRecipients(Message.RecipientType type, String address) Add an address to a target recipient list by string name.
protected InternetHeaders	createInternetHeaders(InputStream in)
Enumeration	getAllHeaderLines()
Enumeration	getAllHeaders() Retrieve the complete list of message headers, as an enumeration.
Address[]	getAllRecipients() Retrieve all of the recipients defined for this message.
Object	getContent()
String	getContentID() Retrieve the value of the "Content-ID" header.
String[]	getContentLanguage()
String	getContentMD5()
protected InputStream	getContentStream()
String	getContentType() Returns the current content type (defined in the "Content-Type" header.
DataHandler	getDataHandler()
String	getDescription()
String	getDisposition() Retrieve the message "Content-Disposition" header field.
String	getEncoding() Decode the Content-Transfer-Encoding header to determine the transfer encoding type.
String	getFileName()
Flags	getFlags() Return a copy the flags associated with this message.
Address[]	getFrom() Get the message "From" addresses.
String[]	getHeader(String name) Retrieve all headers that match a given name.
String	getHeader(String name, String delimiter) Get all headers that match a particular name, as a single string.
InputStream	getInputStream()
int	getLineCount() Retrieve the line count for the current message.
Enumeration	getMatchingHeaderLines(String[] names)
Enumeration	getMatchingHeaders(String[] names)
String	getMessageID()
Enumeration	getNonMatchingHeaderLines(String[] names)
Enumeration	getNonMatchingHeaders(String[] names)
InputStream	getRawInputStream()
Date	getReceivedDate() Get the message received date.
Address[]	getRecipients(Message.RecipientType type) Gets the recipients by type.
Address[]	getReplyTo() Get the ReplyTo address information.
Address	getSender() Return the "Sender" header as an address.
Date	getSentDate() Get the value of the "Date" header field.
int	getSize() Return the content size of this message.
String	getSubject() Returns the value of the "Subject" header.
boolean	isMimeType(String type) Tests to see if this message has a mime-type match with the given type name.
boolean	isSet(Flags.Flag flag) Check whether the supplied flag is set.
protected void	parse(InputStream in) Parse the supplied stream and initialize headers and content appropriately.
void	removeHeader(String name) Remove a header with the given name.
Message	reply(boolean replyToAll) Create a new message suitable as a reply to this message with all headers set up appropriately.
void	saveChanges() Saves any changes on this message.
void	setContent(Multipart part)
void	setContent(Object content, String type)
void	setContentID(String cid)
void	setContentLanguage(String[] languages)
void	setContentMD5(String md5)
void	setDataHandler(DataHandler handler)
void	setDescription(String description)
void	setDescription(String description, String charset)
void	setDisposition(String disposition) Set a new dispostion value for the "Content-Disposition" field.
void	setFileName(String name)
void	setFlags(Flags flag, boolean set) Set or clear a flag value.
void	setFrom() Set the "From" header using the value returned by InternetAddress.getLocalAddress(javax.mail.Session).
void	setFrom(Address address) Set the current message "From" recipient.
void	setHeader(String name, String value) Set a new value for a named header.
void	setRecipients(Message.RecipientType type, Address[] addresses) Set a recipients list for a particular recipient type.
void	setRecipients(Message.RecipientType type, String address) Set a recipient field to a string address (which may be a list or group type).
void	setReplyTo(Address[] address) Set the Reply-To field to the provided list of addresses.
void	setSender(Address address) Set the "Sender" header.
void	setSentDate(Date sent) Set the message sent date.
void	setSubject(String subject) Set the value for the "Subject" header.
void	setSubject(String subject, String charset)
void	setText(String text)
void	setText(String text, String charset)
protected void	updateHeaders() Update the internet headers so that they make sense.
void	writeTo(OutputStream out) Write the message out to a stream in RFC 822 format.
void	writeTo(OutputStream out, String[] ignoreHeaders) Write the message out to a target output stream, excluding the specified message headers.

Methods inherited from class javax.mail.Message

addRecipient, getFolder, getMessageNumber, isExpunged, match, setExpunged, setFlag, setMessageNumber, setRecipient

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dh

protected DataHandler dh

The DataHandler for this Message's content.

content

protected byte[] content

This message's content (unless sourced from a SharedInputStream).

contentStream

protected InputStream contentStream

If the data for this message was supplied by a SharedInputStream then this is another such stream representing the content of this message; if this field is non-null, then content will be null.

headers

protected InternetHeaders headers

This message's headers.

flags

protected Flags flags

This message's flags.

modified

protected boolean modified

Flag indicating that the message has been modified; set to true when an empty message is created or when saveChanges() is called.

saved

protected boolean saved

Flag indicating that the message has been saved.

Constructor Detail

MimeMessage

public MimeMessage(Session session)

Create a new MimeMessage. An empty message is created, with empty headers and empty flags. The modified flag is set.

Parameters:

session - the session for this message

MimeMessage

public MimeMessage(Session session,
                   InputStream in)
            throws MessagingException

Create a MimeMessage by reading an parsing the data from the supplied stream.

Parameters:

session - the session for this message

in - the stream to load from

Throws:

MessagingException - if there is a problem reading or parsing the stream

MimeMessage

public MimeMessage(MimeMessage message)
            throws MessagingException

Copy a MimeMessage.

Parameters:

message - the message to copy

Throws:

MessagingException - is there was a problem copying the message

MimeMessage

protected MimeMessage(Folder folder,
                      int number)

Create an new MimeMessage in the supplied Folder and message number.

Parameters:

folder - the Folder that contains the new message

number - the message number of the new message

MimeMessage

protected MimeMessage(Folder folder,
                      InputStream in,
                      int number)
               throws MessagingException

Create a MimeMessage by reading an parsing the data from the supplied stream.

Parameters:

folder - the folder for this message

in - the stream to load from

number - the message number of the new message

Throws:

MessagingException - if there is a problem reading or parsing the stream

MimeMessage

protected MimeMessage(Folder folder,
                      InternetHeaders headers,
                      byte[] content,
                      int number)
               throws MessagingException

Create a MimeMessage with the supplied headers and content.

Parameters:

folder - the folder for this message

headers - the headers for the new message

content - the content of the new message

number - the message number of the new message

Throws:

MessagingException - if there is a problem reading or parsing the stream

Method Detail

parse

protected void parse(InputStream in)
              throws MessagingException

Parse the supplied stream and initialize headers and content appropriately.

Parameters:

in - the stream to read

Throws:

MessagingException - if there was a problem parsing the stream

getFrom

public Address[] getFrom()
                  throws MessagingException

Get the message "From" addresses. This looks first at the "From" headers, and no "From" header is found, the "Sender" header is checked. Returns null if not found.

Specified by:

getFrom in class Message

Returns:

An array of addresses identifying the message from target. Returns null if this is not resolveable from the headers.

Throws:

MessagingException

setFrom

public void setFrom(Address address)
             throws MessagingException

Set the current message "From" recipient. This replaces any existing "From" header. If the address is null, the header is removed.

Specified by:

setFrom in class Message

Parameters:

address - The new "From" target.

Throws:

MessagingException

setFrom

public void setFrom()
             throws MessagingException

Set the "From" header using the value returned by InternetAddress.getLocalAddress(javax.mail.Session).

Specified by:

setFrom in class Message

Throws:

MessagingException - if there was a problem setting the header

addFrom

public void addFrom(Address[] addresses)
             throws MessagingException

Add a set of addresses to the existing From header.

Specified by:

addFrom in class Message

Parameters:

addresses - The list to add.

Throws:

MessagingException

getSender

public Address getSender()
                  throws MessagingException

Return the "Sender" header as an address.

Returns:

the "Sender" header as an address, or null if not present

Throws:

MessagingException - if there was a problem parsing the header

setSender

public void setSender(Address address)
               throws MessagingException

Set the "Sender" header. If the address is null, this will remove the current sender header.

Parameters:

address - the new Sender address

Throws:

MessagingException - if there was a problem setting the header

getRecipients

public Address[] getRecipients(Message.RecipientType type)
                        throws MessagingException

Gets the recipients by type. Returns null if there are no headers of the specified type. Acceptable RecipientTypes are: javax.mail.Message.RecipientType.TO javax.mail.Message.RecipientType.CC javax.mail.Message.RecipientType.BCC javax.mail.internet.MimeMessage.RecipientType.NEWSGROUPS

Specified by:

getRecipients in class Message

Parameters:

type - The message RecipientType identifier.

Returns:

The array of addresses for the specified recipient types.

Throws:

MessagingException

See Also:

Message.RecipientType

getAllRecipients

public Address[] getAllRecipients()
                           throws MessagingException

Retrieve all of the recipients defined for this message. This returns a merged array of all possible message recipients extracted from the headers. The relevant header types are: javax.mail.Message.RecipientType.TO javax.mail.Message.RecipientType.CC javax.mail.Message.RecipientType.BCC javax.mail.internet.MimeMessage.RecipientType.NEWSGROUPS

Overrides:

getAllRecipients in class Message

Returns:

An array of all target message recipients.

Throws:

MessagingException

setRecipients

public void setRecipients(Message.RecipientType type,
                          Address[] addresses)
                   throws MessagingException

Set a recipients list for a particular recipient type. If the list is null, the corresponding header is removed.

Specified by:

setRecipients in class Message

Parameters:

type - The type of recipient to set.

addresses - The list of addresses.

Throws:

MessagingException

setRecipients

public void setRecipients(Message.RecipientType type,
                          String address)
                   throws MessagingException

Set a recipient field to a string address (which may be a list or group type). If the address is null, the field is removed.

Parameters:

type - The type of recipient to set.

address - The address string.

Throws:

MessagingException

addRecipients

public void addRecipients(Message.RecipientType type,
                          Address[] address)
                   throws MessagingException

Add a list of addresses to a target recipient list.

Specified by:

addRecipients in class Message

Parameters:

type - The target recipient type.

address - An array of addresses to add.

Throws:

MessagingException

addRecipients

public void addRecipients(Message.RecipientType type,
                          String address)
                   throws MessagingException

Add an address to a target recipient list by string name.

Parameters:

type - The target header type.

address - The address to add.

Throws:

MessagingException

getReplyTo

public Address[] getReplyTo()
                     throws MessagingException

Get the ReplyTo address information. The headers are parsed using the "mail.mime.address.strict" setting. If the "Reply-To" header does not have any addresses, then the value of the "From" field is used.

Overrides:

getReplyTo in class Message

Returns:

An array of addresses obtained from parsing the header.

Throws:

MessagingException

setReplyTo

public void setReplyTo(Address[] address)
                throws MessagingException

Set the Reply-To field to the provided list of addresses. If the address list is null, the header is removed.

Overrides:

setReplyTo in class Message

Parameters:

address - The new field value.

Throws:

MessagingException

getSubject

public String getSubject()
                  throws MessagingException

Returns the value of the "Subject" header. If the subject is encoded as an RFC 2047 value, the value is decoded before return. If decoding fails, the raw string value is returned.

Specified by:

getSubject in class Message

Returns:

The String value of the subject field.

Throws:

MessagingException

setSubject

public void setSubject(String subject)
                throws MessagingException

Set the value for the "Subject" header. If the subject contains non US-ASCII characters, it is encoded in RFC 2047 fashion. If the subject value is null, the Subject field is removed.

Specified by:

setSubject in class Message

Parameters:

subject - The new subject value.

Throws:

MessagingException

setSubject

public void setSubject(String subject,
                       String charset)
                throws MessagingException

Throws:

MessagingException

getSentDate

public Date getSentDate()
                 throws MessagingException

Get the value of the "Date" header field. Returns null if if the field is absent or the date is not in a parseable format.

Specified by:

getSentDate in class Message

Returns:

A Date object parsed according to RFC 822.

Throws:

MessagingException

setSentDate

public void setSentDate(Date sent)
                 throws MessagingException

Set the message sent date. This updates the "Date" header. If the provided date is null, the header is removed.

Specified by:

setSentDate in class Message

Parameters:

sent - The new sent date value.

Throws:

MessagingException

getReceivedDate

public Date getReceivedDate()
                     throws MessagingException

Get the message received date. The Sun implementation is documented as always returning null, so this one does too.

Specified by:

getReceivedDate in class Message

Returns:

Always returns null.

Throws:

MessagingException

getSize

public int getSize()
            throws MessagingException

Return the content size of this message. This is obtained either from the size of the content field (if available) or from the contentStream, IFF the contentStream returns a positive size. Returns -1 if the size is not available.

Specified by:

getSize in interface Part

Returns:

Size of the content in bytes.

Throws:

MessagingException

getLineCount

public int getLineCount()
                 throws MessagingException

Retrieve the line count for the current message. Returns -1 if the count cannot be determined. The Sun implementation always returns -1, so this version does too.

Specified by:

getLineCount in interface Part

Returns:

The content line count (always -1 in this implementation).

Throws:

MessagingException

getContentType

public String getContentType()
                      throws MessagingException

Returns the current content type (defined in the "Content-Type" header. If not available, "text/plain" is the default.

Specified by:

getContentType in interface Part

Returns:

The String name of the message content type.

Throws:

MessagingException

isMimeType

public boolean isMimeType(String type)
                   throws MessagingException

Tests to see if this message has a mime-type match with the given type name.

Specified by:

isMimeType in interface Part

Parameters:

type - The tested type name.

Returns:

If this is a type match on the primary and secondare portion of the types.

Throws:

MessagingException

getDisposition

public String getDisposition()
                      throws MessagingException

Retrieve the message "Content-Disposition" header field. This value represents how the part should be represented to the user.

Specified by:

getDisposition in interface Part

Returns:

The string value of the Content-Disposition field.

Throws:

MessagingException

setDisposition

public void setDisposition(String disposition)
                    throws MessagingException

Set a new dispostion value for the "Content-Disposition" field. If the new value is null, the header is removed.

Specified by:

setDisposition in interface Part

Parameters:

disposition - The new disposition value.

Throws:

MessagingException

getEncoding

public String getEncoding()
                   throws MessagingException

Decode the Content-Transfer-Encoding header to determine the transfer encoding type.

Specified by:

getEncoding in interface MimePart

Returns:

The string name of the required encoding.

Throws:

MessagingException

getContentID

public String getContentID()
                    throws MessagingException

Retrieve the value of the "Content-ID" header. Returns null if the header does not exist.

Specified by:

getContentID in interface MimePart

Returns:

The current header value or null.

Throws:

MessagingException

setContentID

public void setContentID(String cid)
                  throws MessagingException

Throws:

MessagingException

getContentMD5

public String getContentMD5()
                     throws MessagingException

Specified by:

getContentMD5 in interface MimePart

Throws:

MessagingException

setContentMD5

public void setContentMD5(String md5)
                   throws MessagingException

Specified by:

setContentMD5 in interface MimePart

Throws:

MessagingException

getDescription

public String getDescription()
                      throws MessagingException

Specified by:

getDescription in interface Part

Throws:

MessagingException

setDescription

public void setDescription(String description)
                    throws MessagingException

Specified by:

setDescription in interface Part

Throws:

MessagingException

setDescription

public void setDescription(String description,
                           String charset)
                    throws MessagingException

Throws:

MessagingException

getContentLanguage

public String[] getContentLanguage()
                            throws MessagingException

Specified by:

getContentLanguage in interface MimePart

Throws:

MessagingException

setContentLanguage

public void setContentLanguage(String[] languages)
                        throws MessagingException

Specified by:

setContentLanguage in interface MimePart

Throws:

MessagingException

getMessageID

public String getMessageID()
                    throws MessagingException

Throws:

MessagingException

getFileName

public String getFileName()
                   throws MessagingException

Specified by:

getFileName in interface Part

Throws:

MessagingException

setFileName

public void setFileName(String name)
                 throws MessagingException

Specified by:

setFileName in interface Part

Throws:

MessagingException

getInputStream

public InputStream getInputStream()
                           throws MessagingException,
                                  IOException

Specified by:

getInputStream in interface Part

Throws:

MessagingException

IOException

getContentStream

protected InputStream getContentStream()
                                throws MessagingException

Throws:

MessagingException

getRawInputStream

public InputStream getRawInputStream()
                              throws MessagingException

Throws:

MessagingException

getDataHandler

public DataHandler getDataHandler()
                           throws MessagingException

Specified by:

getDataHandler in interface Part

Throws:

MessagingException

getContent

public Object getContent()
                  throws MessagingException,
                         IOException

Specified by:

getContent in interface Part

Throws:

MessagingException

IOException

setDataHandler

public void setDataHandler(DataHandler handler)
                    throws MessagingException

Specified by:

setDataHandler in interface Part

Throws:

MessagingException

setContent

public void setContent(Object content,
                       String type)
                throws MessagingException

Specified by:

setContent in interface Part

Throws:

MessagingException

setText

public void setText(String text)
             throws MessagingException

Specified by:

setText in interface MimePart

Specified by:

setText in interface Part

Throws:

MessagingException

setText

public void setText(String text,
                    String charset)
             throws MessagingException

Specified by:

setText in interface MimePart

Throws:

MessagingException

setContent

public void setContent(Multipart part)
                throws MessagingException

Specified by:

setContent in interface Part

Throws:

MessagingException

reply

public Message reply(boolean replyToAll)
              throws MessagingException

Description copied from class: Message

Create a new message suitable as a reply to this message with all headers set up appropriately. The message body will be empty.

if replyToAll is set then the new message will be addressed to all recipients of this message; otherwise the reply will be addressed only to the sender as returned by Message.getReplyTo().

The subject field will be initialized with the subject field from the orginal message; the text "Re:" will be prepended unless it is already present.

Specified by:

reply in class Message

Parameters:

replyToAll - if true, indciates the message should be addressed to all recipients not just the sender

Returns:

a new message suitable as a reply to this message

Throws:

MessagingException - if there was a problem accessing the store

writeTo

public void writeTo(OutputStream out)
             throws MessagingException,
                    IOException

Write the message out to a stream in RFC 822 format.

Specified by:

writeTo in interface Part

Parameters:

out - The target output stream.

Throws:

MessagingException

IOException

writeTo

public void writeTo(OutputStream out,
                    String[] ignoreHeaders)
             throws MessagingException,
                    IOException

Write the message out to a target output stream, excluding the specified message headers.

Parameters:

out - The target output stream.

ignoreHeaders - An array of header types to ignore. This can be null, which means write out all headers.

Throws:

MessagingException

IOException

getHeader

public String[] getHeader(String name)
                   throws MessagingException

Retrieve all headers that match a given name.

Specified by:

getHeader in interface Part

Parameters:

name - The target name.

Returns:

The set of headers that match the given name. These headers will be the decoded() header values if these are RFC 2047 encoded.

Throws:

MessagingException

getHeader

public String getHeader(String name,
                        String delimiter)
                 throws MessagingException

Get all headers that match a particular name, as a single string. Individual headers are separated by the provided delimiter. If the delimiter is null, only the first header is returned.

Specified by:

getHeader in interface MimePart

Parameters:

name - The source header name.

delimiter - The delimiter string to be used between headers. If null, only the first is returned.

Returns:

The headers concatenated as a single string.

Throws:

MessagingException

setHeader

public void setHeader(String name,
                      String value)
               throws MessagingException

Set a new value for a named header.

Specified by:

setHeader in interface Part

Parameters:

name - The name of the target header.

value - The new value for the header.

Throws:

MessagingException

addHeader

public void addHeader(String name,
                      String value)
               throws MessagingException

Add a new value to an existing header. The added value is created as an additional header of the same type and value.

Specified by:

addHeader in interface Part

Parameters:

name - The name of the target header.

value - The removed header.

Throws:

MessagingException

removeHeader

public void removeHeader(String name)
                  throws MessagingException

Remove a header with the given name.

Specified by:

removeHeader in interface Part

Parameters:

name - The name of the removed header.

Throws:

MessagingException

getAllHeaders

public Enumeration getAllHeaders()
                          throws MessagingException

Retrieve the complete list of message headers, as an enumeration.

Specified by:

getAllHeaders in interface Part

Returns:

An Enumeration of the message headers.

Throws:

MessagingException

getMatchingHeaders

public Enumeration getMatchingHeaders(String[] names)
                               throws MessagingException

Specified by:

getMatchingHeaders in interface Part

Throws:

MessagingException

getNonMatchingHeaders

public Enumeration getNonMatchingHeaders(String[] names)
                                  throws MessagingException

Specified by:

getNonMatchingHeaders in interface Part

Throws:

MessagingException

addHeaderLine

public void addHeaderLine(String line)
                   throws MessagingException

Specified by:

addHeaderLine in interface MimePart

Throws:

MessagingException

getAllHeaderLines

public Enumeration getAllHeaderLines()
                              throws MessagingException

Specified by:

getAllHeaderLines in interface MimePart

Throws:

MessagingException

getMatchingHeaderLines

public Enumeration getMatchingHeaderLines(String[] names)
                                   throws MessagingException

Specified by:

getMatchingHeaderLines in interface MimePart

Throws:

MessagingException

getNonMatchingHeaderLines

public Enumeration getNonMatchingHeaderLines(String[] names)
                                      throws MessagingException

Specified by:

getNonMatchingHeaderLines in interface MimePart

Throws:

MessagingException

getFlags

public Flags getFlags()
               throws MessagingException

Description copied from class: Message

Return a copy the flags associated with this message.

Specified by:

getFlags in class Message

Returns:

a copy of the flags for this message

Throws:

MessagingException - if there was a problem accessing the store

isSet

public boolean isSet(Flags.Flag flag)
              throws MessagingException

Description copied from class: Message

Check whether the supplied flag is set. The default implementation checks the flags returned by Message.getFlags().

Overrides:

isSet in class Message

Parameters:

flag - the flags to check for

Returns:

true if the flags is set

Throws:

MessagingException - if there was a problem accessing the store

setFlags

public void setFlags(Flags flag,
                     boolean set)
              throws MessagingException

Set or clear a flag value.

Specified by:

setFlags in class Message

Parameters:

flags - The set of flags to effect.

set - The value to set the flag to (true or false).

Throws:

MessagingException

saveChanges

public void saveChanges()
                 throws MessagingException

Saves any changes on this message. When called, the modified and saved flags are set to true and updateHeaders() is called to force updates.

Specified by:

saveChanges in class Message

Throws:

MessagingException

updateHeaders

protected void updateHeaders()
                      throws MessagingException

Update the internet headers so that they make sense. This will attempt to make sense of the message content type given the state of the content.

Throws:

MessagingException

createInternetHeaders

protected InternetHeaders createInternetHeaders(InputStream in)
                                         throws MessagingException

Throws:

MessagingException