Message (Java 2 Platform Ent. Ed. v1.4) - Java Platform, Enterprise Edition v1.4 API Specifications

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

static class Message.RecipientType
          This inner class defines the types of recipients allowed by the Message class.

Field Summary

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 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 javax.mail.Part

ATTACHMENT, INLINE

Constructor Summary

protected Message()
          No-arg version of the constructor.

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

protected Message(Session session)
          Constructor that takes a Session.

Method Summary

abstract void addFrom(Address[] addresses)
          Add these addresses to the existing "From" attribute

void 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 a Flags 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.

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 the flag 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 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 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 folder; msgnum - 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

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

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:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.

setFrom

public abstract void setFrom(Address address)
                      throws MessagingException

Set the "From" attribute in this Message.

Parameters:: address - the sender
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.

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 values; IllegalStateException - if this message is obtained from a READ_ONLY folder.; MessagingException

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

Returns:: array of Address objects
Throws:: MessagingException
See Also:: Message.RecipientType.TO, Message.RecipientType.CC, Message.RecipientType.BCC, getRecipients(javax.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 type; addresses - the addresses
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.

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 type; address - the address
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values

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 type; addresses - the addresses
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.

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 type; address - the address
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values

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
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:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.; MethodNotSupportedException - if the underlying implementation does not support setting this attribute

getSubject

public abstract String getSubject()
                           throws MessagingException

Get the subject of this message.

Returns:: the subject
Throws:: MessagingException

setSubject

public abstract void setSubject(String subject)
                         throws MessagingException

Set the subject of this message.

Parameters:: subject - the subject
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.

getSentDate

public abstract Date getSentDate()
                          throws MessagingException

Get the date this message was sent.

Returns:: the date this message was sent
Throws:: MessagingException

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:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values; IllegalStateException - if this message is obtained from a READ_ONLY folder.

getReceivedDate

public abstract Date getReceivedDate()
                              throws MessagingException

Get the date this message was received.

Returns:: the date this message was received
Throws:: MessagingException

getFlags

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

Returns:: Flags object containing the flags for this message
Throws:: MessagingException
See Also:: Flags, setFlags(javax.mail.Flags, boolean)

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.

Parameters:: flag - the flag
Returns:: value of the specified flag for this message
Throws:: MessagingException
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 given Flags 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 set; set - the value to be set
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values.; IllegalStateException - if this message is obtained from a READ_ONLY folder.
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 a MessageChangedEvent 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 set; set - the value to be set
Throws:: MessagingException; IllegalWriteException - if the underlying implementation does not support modification of existing values.; IllegalStateException - if this message is obtained from a READ_ONLY folder.
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.

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

Parameters:: replyToAll - reply should be sent to all recipients of this message
Returns:: the reply Message
Throws:: MessagingException

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:: MessagingException; IllegalStateException - if this message is obtained from a READ_ONLY folder.; IllegalWriteException - if the underlying implementation does not support modification of existing values.

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
See Also:: SearchTerm

Overview

Package

Class

Tree

Deprecated

Index

Help

Java^TM 2 Platform
Ent. Ed. v1.4

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature

Nested Class Summary
`static class`	`Message.RecipientType` This inner class defines the types of recipients allowed by the Message class.

Field Summary
`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 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

Constructor Summary
`protected`	`Message()` No-arg version of the constructor.
`protected`	`Message(Folder folder, int msgnum)` Constructor that takes a Folder and a message number.
`protected`	`Message(Session session)` Constructor that takes a Session.

Method Summary
`abstract void`	`addFrom(Address[] addresses)` Add these addresses to the existing "From" attribute
`void`	`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 a `Flags` 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.
`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 the `flag` 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.

Message (Java 2 Platform Ent. Ed. v1.4) - Java Platform, Enterprise Edition v1.4 API Specifications

javax.mail Class Message

msgnum

expunged

folder

session

Message

Message

Message

getFrom

setFrom

setFrom

addFrom

getRecipients

getAllRecipients

setRecipients

setRecipient

addRecipients

addRecipient

getReplyTo

setReplyTo

getSubject

setSubject

getSentDate

setSentDate

getReceivedDate

getFlags

isSet

setFlags

setFlag

getMessageNumber

setMessageNumber

getFolder

isExpunged

setExpunged

reply

saveChanges

match

javax.mail
Class Message