This class models an email message. This is an abstract class. Subclasses
provide actual implementations.
Message implements the Part interface. Message contains a set of attributes
and a "content". Messages within a folder also have a set of flags that
describe its state within the folder.
Message defines some new attributes in addition to those defined in the
Part interface. These attributes specify meta-data for the message - i.e.,
addressing and descriptive information about the message.
Message objects are obtained either from a Folder or by constructing a new
Message object of the appropriate subclass. Messages that have been received
are normally retrieved from a folder named "INBOX".
A Message object obtained from a folder is just a lightweight reference to
the actual message. The Message is 'lazily' filled up(on demand) when
each item is requested from the message. Note that certain folder
implementations may return Message objects that are pre-filled with certain
user-specified items. To send a message, an appropriate subclass of
Message(e.g., MimeMessage) is instantiated, the attributes and content
are filled in, and the message is sent using the
Transport.send
method.
addFrom
public void addFrom(Address[] addresses)
throws MessagingException Add these addresses to the existing "From" attribute
addresses - - the senders
addRecipient
public void addRecipient(Message.RecipientType type,
Address address)
throws MessagingException Add this recipient address to the existing ones of the given type.
The default implementation uses the addRecipients method.
addRecipients
public void addRecipients(Message.RecipientType type,
Address[] addresses)
throws MessagingException Add these recipient addresses to the existing ones of the given type.
type - the recipient typeaddresses - the addresses
getAllRecipients
public Address[] getAllRecipients()
throws MessagingException Get all the recipient addresses for the message.
The default implementation extracts the TO, CC, and BCC recipients
using the getRecipients method.
This method returns null if none of the recipient headers are present in
this message. Returns an empty array if any recipient header is present,
but contains no addresses.
getFlags
public Flags getFlags()
throws MessagingException Returns a Flags object containing the flags for this message.
Modifying any of the flags in this returned Flags object will not affect
the flags of this message. Use
setFlags() to do that.
getFolder
public Folder getFolder()
Get the folder from which this message was obtained.
If this is a new message or nested message, this method returns null.
getFrom
public Address[] getFrom()
throws MessagingException Returns the "From" attribute.
The "From" attribute contains the identity of the person(s) who
wished this message to be sent.
In certain implementations, this may be different from the entity that
actually sent the message.
This method returns null if this attribute is not present in this message.
Returns an empty array if this attribute is present, but contains no
addresses.
getMessageNumber
public int getMessageNumber()
Get the Message number for this Message.
A Message object's message number is the relative position of this
Message in its Folder. Note that the message number for a particular
Message can change during a session if other messages in the Folder
are deleted and expunged.
Valid message numbers start at 1. Messages that do not belong to any
folder(like newly composed or derived messages) have 0 as their
message number.
getReceivedDate
public Date getReceivedDate()
throws MessagingException Get the date this message was received.
getRecipients
public Address[] getRecipients(Message.RecipientType type)
throws MessagingException Get all the recipient addresses of the given type.
This method returns null if the header for the given type is not present
in this message. Returns an empty array if the header is present, but
contains no addresses.
type - the recipient type
getReplyTo
public Address[] getReplyTo()
throws MessagingException Get the addresses to which replies should be directed.
This will usually be the sender of the message, but some messages
may direct replies to a different address.
The default implementation simply calls the getFrom method.
This method returns null if the corresponding header is not present.
Returns an empty array if the header is present, but contains no
addresses.
getSentDate
public Date getSentDate()
throws MessagingException Get the date this message was sent.
getSubject
public String getSubject()
throws MessagingException Get the subject of this message.
isExpunged
public boolean isExpunged()
Checks whether this message is expunged.
All other methods except
getMessageNumber() are invalid
on an expunged Message object.
Messages that are expunged due to an explict expunge() request on the
containing Folder are removed from the Folder immediately. Messages that
are externally expunged by another source are marked "expunged" and return
true for the
isExpunged() method, but they are not removed
from the Folder until an explicit
expunge() is done on the
Folder.
See the description of
expunge() for more details on
expunge handling.
Folder.expunge()
isSet
public boolean isSet(Flags.Flag flag)
throws MessagingException Check whether the flag specified in the flag argument is set in this
message.
The default implementation uses getFlags.
flag - the flag
- value of the specified flag for this message
match
public boolean match(SearchTerm term)
throws MessagingException Apply the specified Search criterion to this message.
term - the Search criterion
reply
public Message reply(boolean replyToAll)
throws MessagingException Get a new Message suitable for a reply to this message.
The new Message will have its attributes and headers set up
appropriately. Note that this new message object will be empty,
that is, it will not have a "content".
These will have to be suitably filled in by the client.
If
replyToAll is set, the new Message will be addressed
to all recipients of this message. Otherwise, the reply will be
addressed to only the sender of this message(using the value of the
getReplyTo method).
The "Subject" field is filled in with the original subject prefixed with
"Re:"(unless it already starts with "Re:").
The reply message will use the same session as this message.
replyToAll - reply should be sent to all recipients of this message
saveChanges
public void saveChanges()
throws MessagingException Save any changes made to this message into the message-store when the
containing folder is closed, if the message is contained in a folder.
(Some implementations may save the changes immediately.)
Update any header fields to be consistent with the changed message
contents. If any part of a message's headers or contents are changed,
saveChanges must be called to ensure that those changes
are permanent. If
saveChanges is not called, any such
modifications may or may not be saved, depending on the message store
and folder implementation.
Messages obtained from folders opened READ_ONLY should not be modified
and
saveChanges should not be called on such messages.
setExpunged
protected void setExpunged(boolean expunged)
Sets the expunged flag for this Message.
This method is to be used only by the implementation classes.
setFlag
public void setFlag(Flags.Flag flag,
boolean set)
throws MessagingException Set the specified flag on this message to the specified value.
This will result in a MessageChangedEvent being delivered to any
MessageChangedListener registered on this Message's containing folder.
The default implementation uses the
setFlags method.
setFlags
public void setFlags(Flags flag,
boolean set)
throws MessagingException Set the specified flags on this message to the specified value.
Note that any flags in this message that are not specified in the
given Flags object are unaffected.
This will result in a MessageChangedEvent being delivered to any
MessageChangedListener registered on this Message's containing folder.
flag - Flags object containing the flags to be setset - the value to be set
setFrom
public void setFrom()
throws MessagingException Set the "From" attribute in this Message.
The value of this attribute is obtained from the property "mail.user".
If this property is absent, the system property "user.name" is used.
setFrom
public void setFrom(Address address)
throws MessagingException Set the "From" attribute in this Message.
address - the sender
setMessageNumber
protected void setMessageNumber(int msgnum)
Set the Message number for this Message.
This method is invoked only by the implementation classes.
setRecipient
public void setRecipient(Message.RecipientType type,
Address address)
throws MessagingException Set the recipient address.
All addresses of the specified type are replaced by the address parameter.
The default implementation uses the setRecipients method.
setRecipients
public void setRecipients(Message.RecipientType type,
Address[] addresses)
throws MessagingException Set the recipient addresses.
All addresses of the specified type are replaced by the addresses
parameter.
type - the recipient typeaddresses - the addresses
setReplyTo
public void setReplyTo(Address[] addresses)
throws MessagingException Set the addresses to which replies should be directed.
(Normally only a single address will be specified.)
Not all message types allow this to be specified separately from
the sender of the message.
The default implementation provided here just throws the
MethodNotSupportedException.
setSentDate
public void setSentDate(Date date)
throws MessagingException Set the sent date of this message.
date - the sent date of this message
setSubject
public void setSubject(String subject)
throws MessagingException Set the subject of this message.
subject - the subject