javax.mail
Class Message

java.lang.Object
  javax.mail.Message

All Implemented Interfaces:

Part

Direct Known Subclasses:

MimeMessage

public abstract class Message
extends Object
implements Part

Version:

$Rev: 421852 $ $Date: 2006-07-14 03:02:19 -0700 (Fri, 14 Jul 2006) $

Nested Class Summary

static class

Message.RecipientType Enumeration of types of recipients allowed by the Message class.

Field Summary

protected boolean	expunged True if this message has been expunged from the Store.
protected Folder	folder The Folder that contains this message, or null if it was not obtained from a folder.
protected int	msgnum The index of a message withing its folder, or zero if the message was not retrieved from a folder.
protected Session	session The Session associated with this message.

Fields inherited from interface javax.mail.Part

ATTACHMENT, INLINE

Constructor Summary

protected	Message() Default constructor.
protected	Message(Folder folder, int msgnum) Constructor initializing folder and message msgnum; intended to be used by implementations of Folder.
protected	Message(Session session) Constructor initializing the session; intended to by used by client created instances.

Method Summary

abstract void	addFrom(Address[] addresses) Add multiple addresses to the "From" header.
void	addRecipient(Message.RecipientType type, Address address) Add a recipent of a specified type.
abstract void	addRecipients(Message.RecipientType type, Address[] addresses) Add recipents of a specified type.
Address[]	getAllRecipients() Get all recipients of this message.
abstract Flags	getFlags() Return a copy the flags associated with this message.
Folder	getFolder() Return the folder containing this message.
abstract Address[]	getFrom() Return the "From" header indicating the identity of the person who the message is from; in some circumstances this may be different to the actual sender.
int	getMessageNumber() Return the message number for this Message.
abstract Date	getReceivedDate() Return the date this message was received.
abstract Address[]	getRecipients(Message.RecipientType type) Get all recipients of the given type.
Address[]	getReplyTo() Get the addresses to which replies should be directed.
abstract Date	getSentDate() Return the date that this message was sent.
abstract String	getSubject() Get the subject for this message.
boolean	isExpunged() Checks to see if this message has been expunged.
boolean	isSet(Flags.Flag flag) Check whether the supplied flag is set.
boolean	match(SearchTerm term) Apply the specified search criteria to this message
abstract Message	reply(boolean replyToAll) Create a new message suitable as a reply to this message with all headers set up appropriately.
abstract void	saveChanges() To ensure changes are saved to the store, this message should be invoked before its containing folder is closed.
protected void	setExpunged(boolean expunged) Set the expunged flag for this message.
void	setFlag(Flags.Flag flag, boolean set) Set a flag to the supplied value.
abstract void	setFlags(Flags flags, boolean set) Set the flags specified to the supplied value; flags not included in the supplied Flags parameter are not affected.
abstract void	setFrom() Set the "From" header for this message to the value of the "mail.user" property, of if that property is not set, to the value of the system property "user.name"
abstract void	setFrom(Address address) Set the "From" header to the supplied address.
protected void	setMessageNumber(int number) Set the message number for this Message.
void	setRecipient(Message.RecipientType type, Address address) Set the list of recipients for the specified type to a single address.
abstract void	setRecipients(Message.RecipientType type, Address[] addresses) Set the list of recipients for the specified type.
void	setReplyTo(Address[] addresses) Set the addresses to which replies should be directed.
abstract void	setSentDate(Date sent) Set the date this message was sent.
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 javax.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 index of a message withing its folder, or zero if the message was not retrieved from a folder.

expunged

protected boolean expunged

True if this message has been expunged from the Store.

folder

protected Folder folder

The Folder that contains this message, or null if it was not obtained from a folder.

session

protected Session session

The Session associated with this message.

Constructor Detail

Message

protected Message()

Default constructor.

Message

protected Message(Folder folder,
                  int msgnum)

Constructor initializing folder and message msgnum; intended to be used by implementations of Folder.

Parameters:

folder - the folder that contains the message

msgnum - the message index within the folder

Message

protected Message(Session session)

Constructor initializing the session; intended to by used by client created instances.

Parameters:

session - the session associated with this message

Method Detail

getFrom

public abstract Address[] getFrom()
                           throws MessagingException

Return the "From" header indicating the identity of the person who the message is from; in some circumstances this may be different to the actual sender.

Returns:

a list of addresses this message is from; may be empty if the header is present but empty, or null if the header is not present

Throws:

MessagingException - if there was a problem accessing the store

setFrom

public abstract void setFrom()
                      throws MessagingException

Set the "From" header for this message to the value of the "mail.user" property, of if that property is not set, to the value of the system property "user.name"

Throws:

MessagingException - if there was a problem accessing the store

setFrom

public abstract void setFrom(Address address)
                      throws MessagingException

Set the "From" header to the supplied address.

Parameters:

address - the address of the person who the message is from

Throws:

MessagingException - if there was a problem accessing the store

addFrom

public abstract void addFrom(Address[] addresses)
                      throws MessagingException

Add multiple addresses to the "From" header.

Parameters:

addresses - the addresses to add

Throws:

MessagingException - if there was a problem accessing the store

getRecipients

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

Get all recipients of the given type.

Parameters:

type - the type of recipient to get

Returns:

a list of addresses; may be empty if the header is present but empty, or null if the header is not present

Throws:

MessagingException - if there was a problem accessing the store

See Also:

Message.RecipientType

getAllRecipients

public Address[] getAllRecipients()
                           throws MessagingException

Get all recipients of this message. The default implementation extracts the To, Cc, and Bcc recipients using getRecipients(javax.mail.Message.RecipientType) and then concatentates the results into a single array; it returns null if no headers are defined.

Returns:

an array containing all recipients

Throws:

MessagingException - if there was a problem accessing the store

setRecipients

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

Set the list of recipients for the specified type.

Parameters:

type - the type of recipient

addresses - the new addresses

Throws:

MessagingException - if there was a problem accessing the store

setRecipient

public void setRecipient(Message.RecipientType type,
                         Address address)
                  throws MessagingException

Set the list of recipients for the specified type to a single address.

Parameters:

type - the type of recipient

address - the new address

Throws:

MessagingException - if there was a problem accessing the store

addRecipients

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

Add recipents of a specified type.

Parameters:

type - the type of recipient

addresses - the addresses to add

Throws:

MessagingException - if there was a problem accessing the store

addRecipient

public void addRecipient(Message.RecipientType type,
                         Address address)
                  throws MessagingException

Add a recipent of a specified type.

Parameters:

type - the type of recipient

address - the address to add

Throws:

MessagingException - if there was a problem accessing the store

getReplyTo

public Address[] getReplyTo()
                     throws MessagingException

Get the addresses to which replies should be directed.

As the most common behavior is to return to sender, the default implementation simply calls getFrom().

Returns:

a list of addresses to which replies should be directed

Throws:

MessagingException - if there was a problem accessing the store

setReplyTo

public void setReplyTo(Address[] addresses)
                throws MessagingException

Set the addresses to which replies should be directed.

The default implementation throws a MethodNotSupportedException.

Parameters:

addresses - to which replies should be directed

Throws:

MessagingException - if there was a problem accessing the store

getSubject

public abstract String getSubject()
                           throws MessagingException

Get the subject for this message.

Returns:

the subject

Throws:

MessagingException - if there was a problem accessing the store

setSubject

public abstract void setSubject(String subject)
                         throws MessagingException

Set the subject of this message

Parameters:

subject - the subject

Throws:

MessagingException - if there was a problem accessing the store

getSentDate

public abstract Date getSentDate()
                          throws MessagingException

Return the date that this message was sent.

Returns:

the date this message was sent

Throws:

MessagingException - if there was a problem accessing the store

setSentDate

public abstract void setSentDate(Date sent)
                          throws MessagingException

Set the date this message was sent.

Parameters:

sent - the date when this message was sent

Throws:

MessagingException - if there was a problem accessing the store

getReceivedDate

public abstract Date getReceivedDate()
                              throws MessagingException

Return the date this message was received.

Returns:

the date this message was received

Throws:

MessagingException - if there was a problem accessing the store

getFlags

public abstract Flags getFlags()
                        throws MessagingException

Return a copy the flags associated with this 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

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

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 abstract void setFlags(Flags flags,
                              boolean set)
                       throws MessagingException

Set the flags specified to the supplied value; flags not included in the supplied Flags parameter are not affected.

Parameters:

flags - the flags to modify

set - the new value of those flags

Throws:

MessagingException - if there was a problem accessing the store

setFlag

public void setFlag(Flags.Flag flag,
                    boolean set)
             throws MessagingException

Set a flag to the supplied value. The default implmentation uses setFlags(Flags, boolean).

Parameters:

flag - the flag to set

set - the value for that flag

Throws:

MessagingException - if there was a problem accessing the store

getMessageNumber

public int getMessageNumber()

Return the message number for this Message. This number refers to the relative position of this message in a Folder; the message number for any given message can change during a seesion if the Folder is expunged. Message numbers for messages in a folder start at one; the value zero indicates that this message does not belong to a folder.

Returns:

the message number

setMessageNumber

protected void setMessageNumber(int number)

Set the message number for this Message. This must be invoked by implementation classes when the message number changes.

Parameters:

number - the new message number

getFolder

public Folder getFolder()

Return the folder containing this message. If this is a new or nested message then this method returns null.

Returns:

the folder containing this message

isExpunged

public boolean isExpunged()

Checks to see if this message has been expunged. If true, all methods other than getMessageNumber() are invalid.

Returns:

true if this method has been expunged

setExpunged

protected void setExpunged(boolean expunged)

Set the expunged flag for this message.

Parameters:

expunged - true if this message has been expunged

reply

public abstract Message reply(boolean replyToAll)
                       throws MessagingException

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 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.

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

saveChanges

public abstract void saveChanges()
                          throws MessagingException

To ensure changes are saved to the store, this message should be invoked before its containing folder is closed. Implementations may save modifications immediately but are free to defer such updates to they may be sent to the server in one batch; if saveChanges is not called then such changes may not be made permanent.

Throws:

MessagingException - if there was a problem accessing the store

match

public boolean match(SearchTerm term)
              throws MessagingException

Apply the specified search criteria to this message

Parameters:

term - the search criteria

Returns:

true if this message matches the search criteria.

Throws:

MessagingException - if there was a problem accessing the store