Class Message
- java.lang.Object
-
- jakarta.mail.Message
-
- All Implemented Interfaces:
Part
- Direct Known Subclasses:
MimeMessage
public abstract class Message extends Object implements Part
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.- Author:
- John Mani, Bill Shannon, Max Spivak
- See Also:
Part
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Message.RecipientType
This inner class defines the types of recipients allowed by the Message class.
-
Field Summary
Fields Modifier and Type Field Description protected boolean
expunged
True if this message has been expunged.protected Folder
folder
The containing folder, if this message is obtained from a folderprotected int
msgnum
The number of this message within its folder, or zero if the message was not retrieved from a folder.protected Session
session
The Session object for this Message-
Fields inherited from interface jakarta.mail.Part
ATTACHMENT, INLINE
-
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
addFrom(Address[] addresses)
Add these addresses to the existing "From" attributevoid
addRecipient(Message.RecipientType type, Address address)
Add this recipient address to the existing ones of the given type.abstract void
addRecipients(Message.RecipientType type, Address[] addresses)
Add these recipient addresses to the existing ones of the given type.Address[]
getAllRecipients()
Get all the recipient addresses for the message.abstract Flags
getFlags()
Returns aFlags
object containing the flags for this message.Folder
getFolder()
Get the folder from which this message was obtained.abstract Address[]
getFrom()
Returns the "From" attribute.int
getMessageNumber()
Get the Message number for this Message.abstract Date
getReceivedDate()
Get the date this message was received.abstract Address[]
getRecipients(Message.RecipientType type)
Get all the recipient addresses of the given type.Address[]
getReplyTo()
Get the addresses to which replies should be directed.abstract Date
getSentDate()
Get the date this message was sent.Session
getSession()
Return the Session used when this message was created.abstract String
getSubject()
Get the subject of this message.boolean
isExpunged()
Checks whether this message is expunged.boolean
isSet(Flags.Flag flag)
Check whether the flag specified in theflag
argument is set in this message.boolean
match(SearchTerm term)
Apply the specified Search criterion to this message.abstract Message
reply(boolean replyToAll)
Get a new Message suitable for a reply to this message.abstract void
saveChanges()
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.protected void
setExpunged(boolean expunged)
Sets the expunged flag for this Message.void
setFlag(Flags.Flag flag, boolean set)
Set the specified flag on this message to the specified value.abstract void
setFlags(Flags flag, boolean set)
Set the specified flags on this message to the specified value.abstract void
setFrom()
Set the "From" attribute in this Message.abstract void
setFrom(Address address)
Set the "From" attribute in this Message.protected void
setMessageNumber(int msgnum)
Set the Message number for this Message.void
setRecipient(Message.RecipientType type, Address address)
Set the recipient address.abstract void
setRecipients(Message.RecipientType type, Address[] addresses)
Set the recipient addresses.void
setReplyTo(Address[] addresses)
Set the addresses to which replies should be directed.abstract void
setSentDate(Date date)
Set the sent date of this message.abstract void
setSubject(String subject)
Set the subject of this message.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface jakarta.mail.Part
addHeader, getAllHeaders, getContent, getContentType, getDataHandler, getDescription, getDisposition, getFileName, getHeader, getInputStream, getLineCount, getMatchingHeaders, getNonMatchingHeaders, getSize, isMimeType, removeHeader, setContent, setContent, setDataHandler, setDescription, setDisposition, setFileName, setHeader, setText, writeTo
-
-
-
-
Field Detail
-
msgnum
protected int msgnum
The number of this message within its folder, or zero if the message was not retrieved from a folder.
-
expunged
protected boolean expunged
True if this message has been expunged.
-
folder
protected Folder folder
The containing folder, if this message is obtained from a folder
-
session
protected Session session
The Session object for this Message
-
-
Constructor Detail
-
Message
protected Message()
No-arg version of the constructor.
-
Message
protected Message(Folder folder, int msgnum)
Constructor that takes a Folder and a message number. Used by Folder implementations.- Parameters:
folder
- containing foldermsgnum
- this message's sequence number within this folder
-
Message
protected Message(Session session)
Constructor that takes a Session. Used for client created Message objects.- Parameters:
session
- A Session object
-
-
Method Detail
-
getSession
public Session getSession()
Return the Session used when this message was created.- Returns:
- the message's Session
- Since:
- JavaMail 1.5
-
getFrom
public abstract 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.- Returns:
- array of Address objects
- Throws:
MessagingException
- for failures
-
setFrom
public abstract 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.- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
setFrom
public abstract void setFrom(Address address) throws MessagingException
Set the "From" attribute in this Message.- Parameters:
address
- the sender- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
addFrom
public abstract void addFrom(Address[] addresses) throws MessagingException
Add these addresses to the existing "From" attribute- Parameters:
addresses
- the senders- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
getRecipients
public abstract Address[] getRecipients(Message.RecipientType type) throws MessagingException
Get all the recipient addresses of the given type.This method returns
null
if no recipients of the given type are present in this message. It may return an empty array if the header is present, but contains no addresses.- Parameters:
type
- the recipient type- Returns:
- array of Address objects
- Throws:
MessagingException
- for failures- See Also:
Message.RecipientType.TO
,Message.RecipientType.CC
,Message.RecipientType.BCC
-
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 thegetRecipients
method.This method returns
null
if none of the recipient headers are present in this message. It may Return an empty array if any recipient header is present, but contains no addresses.- Returns:
- array of Address objects
- Throws:
MessagingException
- for failures- See Also:
Message.RecipientType.TO
,Message.RecipientType.CC
,Message.RecipientType.BCC
,getRecipients(jakarta.mail.Message.RecipientType)
-
setRecipients
public abstract 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.- Parameters:
type
- the recipient typeaddresses
- the addresses- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
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.- Parameters:
type
- the recipient typeaddress
- the address- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesMessagingException
- for other failures
-
addRecipients
public abstract void addRecipients(Message.RecipientType type, Address[] addresses) throws MessagingException
Add these recipient addresses to the existing ones of the given type.- Parameters:
type
- the recipient typeaddresses
- the addresses- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
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.- Parameters:
type
- the recipient typeaddress
- the address- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesMessagingException
- for other failures
-
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.- Returns:
- addresses to which replies should be directed
- Throws:
MessagingException
- for failures- See Also:
getFrom()
-
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.
- Parameters:
addresses
- addresses to which replies should be directed- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MethodNotSupportedException
- if the underlying implementation does not support setting this attributeMessagingException
- for other failures
-
getSubject
public abstract String getSubject() throws MessagingException
Get the subject of this message.- Returns:
- the subject
- Throws:
MessagingException
- for failures
-
setSubject
public abstract void setSubject(String subject) throws MessagingException
Set the subject of this message.- Parameters:
subject
- the subject- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
getSentDate
public abstract Date getSentDate() throws MessagingException
Get the date this message was sent.- Returns:
- the date this message was sent
- Throws:
MessagingException
- for failures
-
setSentDate
public abstract void setSentDate(Date date) throws MessagingException
Set the sent date of this message.- Parameters:
date
- the sent date of this message- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures
-
getReceivedDate
public abstract Date getReceivedDate() throws MessagingException
Get the date this message was received.- Returns:
- the date this message was received
- Throws:
MessagingException
- for failures
-
getFlags
public abstract Flags getFlags() throws MessagingException
Returns aFlags
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.- Returns:
- Flags object containing the flags for this message
- Throws:
MessagingException
- for failures- See Also:
Flags
,setFlags(jakarta.mail.Flags, boolean)
-
isSet
public boolean isSet(Flags.Flag flag) throws MessagingException
Check whether the flag specified in theflag
argument is set in this message.The default implementation uses
getFlags
.- Parameters:
flag
- the flag- Returns:
- value of the specified flag for this message
- Throws:
MessagingException
- for failures- See Also:
Flags.Flag
,Flags.Flag.ANSWERED
,Flags.Flag.DELETED
,Flags.Flag.DRAFT
,Flags.Flag.FLAGGED
,Flags.Flag.RECENT
,Flags.Flag.SEEN
-
setFlags
public abstract 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 givenFlags
object are unaffected.This will result in a
MessageChangedEvent
being delivered to any MessageChangedListener registered on this Message's containing folder.- Parameters:
flag
- Flags object containing the flags to be setset
- the value to be set- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing values.IllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures- See Also:
MessageChangedEvent
-
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 aMessageChangedEvent
being delivered to any MessageChangedListener registered on this Message's containing folder.The default implementation uses the
setFlags
method.- Parameters:
flag
- Flags.Flag object containing the flag to be setset
- the value to be set- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing values.IllegalStateException
- if this message is obtained from a READ_ONLY folder.MessagingException
- for other failures- See Also:
MessageChangedEvent
-
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.
- Returns:
- the message number
-
setMessageNumber
protected void setMessageNumber(int msgnum)
Set the Message number for this Message. This method is invoked only by the implementation classes.- Parameters:
msgnum
- the message number
-
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.- Returns:
- the containing folder
-
isExpunged
public boolean isExpunged()
Checks whether this message is expunged. All other methods exceptgetMessageNumber()
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 explicitexpunge()
is done on the Folder.See the description of
expunge()
for more details on expunge handling.- Returns:
- true if the message is expunged
- See Also:
Folder.expunge()
-
setExpunged
protected void setExpunged(boolean expunged)
Sets the expunged flag for this Message. This method is to be used only by the implementation classes.- Parameters:
expunged
- the expunged flag
-
reply
public abstract 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 thegetReplyTo
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.
- Parameters:
replyToAll
- reply should be sent to all recipients of this message- Returns:
- the reply Message
- Throws:
MessagingException
- for failures
-
saveChanges
public abstract 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.
- Throws:
IllegalStateException
- if this message is obtained from a READ_ONLY folder.IllegalWriteException
- if the underlying implementation does not support modification of existing values.MessagingException
- for other failures
-
match
public boolean match(SearchTerm term) throws MessagingException
Apply the specified Search criterion to this message.- Parameters:
term
- the Search criterion- Returns:
- true if the Message matches this search criterion, false otherwise.
- Throws:
MessagingException
- for failures- See Also:
SearchTerm
-
-