FileDocCategorySizeDatePackage
Message.javaAPI DocJavaMail 1.4.325235Tue Nov 17 10:38:12 GMT 2009javax.mail

Message

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
author
Bill Shannon
author
Max Spivak
see
javax.mail.Part

Fields Summary
protected int
msgnum
The number of this message within its folder, or zero if the message was not retrieved from a folder.
protected boolean
expunged
True if this message has been expunged.
protected Folder
folder
The containing folder, if this message is obtained from a folder
protected Session
session
The Session object for this Message
Constructors Summary
protected Message()
No-arg version of the constructor.


              
       
protected Message(Folder folder, int msgnum)
Constructor that takes a Folder and a message number. Used by Folder implementations.

param
folder containing folder
param
msgnum this message's sequence number within this folder

	this.folder = folder;
	this.msgnum = msgnum;
	session = folder.store.session;
    
protected Message(Session session)
Constructor that takes a Session. Used for client created Message objects.

param
session A Session object

	this.session = session;
    
Methods Summary
public abstract voidaddFrom(javax.mail.Address[] addresses)
Add these addresses to the existing "From" attribute

param
addresses the senders
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.
exception
MessagingException

public voidaddRecipient(javax.mail.Message$RecipientType type, javax.mail.Address address)
Add this recipient address to the existing ones of the given type.

The default implementation uses the addRecipients method.

param
type the recipient type
param
address the address
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values

	Address[] a = new Address[1];
	a[0] = address;
	addRecipients(type, a);
    
public abstract voidaddRecipients(javax.mail.Message$RecipientType type, javax.mail.Address[] addresses)
Add these recipient addresses to the existing ones of the given type.

param
type the recipient type
param
addresses the addresses
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.

public javax.mail.Address[]getAllRecipients()
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. It may Return an empty array if any recipient header is present, but contains no addresses.

return
array of Address objects
exception
MessagingException
see
Message.RecipientType#TO
see
Message.RecipientType#CC
see
Message.RecipientType#BCC
see
#getRecipients

	Address[] to = getRecipients(RecipientType.TO);
	Address[] cc = getRecipients(RecipientType.CC);
	Address[] bcc = getRecipients(RecipientType.BCC);

	if (cc == null && bcc == null)
	    return to;		// a common case

	int numRecip =
	    (to != null ? to.length : 0) +
	    (cc != null ? cc.length : 0) +
	    (bcc != null ? bcc.length : 0);
	Address[] addresses = new Address[numRecip];
	int pos = 0;
	if (to != null) {
	    System.arraycopy(to, 0, addresses, pos, to.length);
	    pos += to.length;
	}
	if (cc != null) {
	    System.arraycopy(cc, 0, addresses, pos, cc.length);
	    pos += cc.length;
	}
	if (bcc != null) {
	    System.arraycopy(bcc, 0, addresses, pos, bcc.length);
	    pos += bcc.length;
	}
	return addresses;
    
public abstract javax.mail.FlagsgetFlags()
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.

return
Flags object containing the flags for this message
see
javax.mail.Flags
see
#setFlags
exception
MessagingException

public javax.mail.FoldergetFolder()
Get the folder from which this message was obtained. If this is a new message or nested message, this method returns null.

return
the containing folder

	return folder;
    
public abstract javax.mail.Address[]getFrom()
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.

return
array of Address objects
exception
MessagingException

public intgetMessageNumber()
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.

return
the message number

	return msgnum;
    
public abstract java.util.DategetReceivedDate()
Get the date this message was received.

return
the date this message was received
exception
MessagingException

public abstract javax.mail.Address[]getRecipients(javax.mail.Message$RecipientType type)
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.

param
type the recipient type
return
array of Address objects
exception
MessagingException
see
Message.RecipientType#TO
see
Message.RecipientType#CC
see
Message.RecipientType#BCC

public javax.mail.Address[]getReplyTo()
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.

return
addresses to which replies should be directed
exception
MessagingException
see
#getFrom

        return getFrom();
    
public abstract java.util.DategetSentDate()
Get the date this message was sent.

return
the date this message was sent
exception
MessagingException

public abstract java.lang.StringgetSubject()
Get the subject of this message.

return
the subject
exception
MessagingException

public booleanisExpunged()
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.

see
Folder#expunge

	return expunged;
    
public booleanisSet(javax.mail.Flags$Flag flag)
Check whether the flag specified in the flag argument is set in this message.

The default implementation uses getFlags.

param
flag the flag
return
value of the specified flag for this message
see
javax.mail.Flags.Flag
see
javax.mail.Flags.Flag#ANSWERED
see
javax.mail.Flags.Flag#DELETED
see
javax.mail.Flags.Flag#DRAFT
see
javax.mail.Flags.Flag#FLAGGED
see
javax.mail.Flags.Flag#RECENT
see
javax.mail.Flags.Flag#SEEN
exception
MessagingException

	return getFlags().contains(flag);
    
public booleanmatch(javax.mail.search.SearchTerm term)
Apply the specified Search criterion to this message.

param
term the Search criterion
return
true if the Message matches this search criterion, false otherwise.
exception
MessagingException
see
javax.mail.search.SearchTerm

	return term.match(this);
    
public abstract Messagereply(boolean replyToAll)
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.

param
replyToAll reply should be sent to all recipients of this message
return
the reply Message
exception
MessagingException

public abstract voidsaveChanges()
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.

exception
MessagingException
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.
exception
IllegalWriteException if the underlying implementation does not support modification of existing values.

protected voidsetExpunged(boolean expunged)
Sets the expunged flag for this Message. This method is to be used only by the implementation classes.

param
expunged the expunged flag

	this.expunged = expunged;
    
public voidsetFlag(javax.mail.Flags$Flag flag, boolean set)
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.

param
flag Flags.Flag object containing the flag to be set
param
set the value to be set
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values.
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.
see
javax.mail.event.MessageChangedEvent

	Flags f = new Flags(flag);
	setFlags(f, set);
    
public abstract voidsetFlags(javax.mail.Flags flag, boolean set)
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.

param
flag Flags object containing the flags to be set
param
set the value to be set
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values.
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.
see
javax.mail.event.MessageChangedEvent

public abstract voidsetFrom()
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.

exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.

public abstract voidsetFrom(javax.mail.Address address)
Set the "From" attribute in this Message.

param
address the sender
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.

protected voidsetMessageNumber(int msgnum)
Set the Message number for this Message. This method is invoked only by the implementation classes.

	this.msgnum = msgnum;
    
public voidsetRecipient(javax.mail.Message$RecipientType type, javax.mail.Address address)
Set the recipient address. All addresses of the specified type are replaced by the address parameter.

The default implementation uses the setRecipients method.

param
type the recipient type
param
address the address
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values

	Address[] a = new Address[1];
	a[0] = address;
	setRecipients(type, a);
    
public abstract voidsetRecipients(javax.mail.Message$RecipientType type, javax.mail.Address[] addresses)
Set the recipient addresses. All addresses of the specified type are replaced by the addresses parameter.

param
type the recipient type
param
addresses the addresses
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.

public voidsetReplyTo(javax.mail.Address[] addresses)
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.

param
addresses addresses to which replies should be directed
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.
exception
MethodNotSupportedException if the underlying implementation does not support setting this attribute

	throw new MethodNotSupportedException("setReplyTo not supported");
    
public abstract voidsetSentDate(java.util.Date date)
Set the sent date of this message.

param
date the sent date of this message
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.

public abstract voidsetSubject(java.lang.String subject)
Set the subject of this message.

param
subject the subject
exception
MessagingException
exception
IllegalWriteException if the underlying implementation does not support modification of existing values
exception
IllegalStateException if this message is obtained from a READ_ONLY folder.