com.compoze.mail
Interface IMessage

All Known Implementing Classes:

AbstractMessage

public interface IMessage

This interface defines a mail message. A message can be obtained from a folder.

A new message for sending can be created by using ISession.createMessage(). Prepare the message and then call send().

To reply, reply to all recipients or forward a message, use reply(), replyAll() or forward().

Field Summary

static int	MESSAGE_RECIPIENT_BCC Recipient is a "Bcc" address.
static int	MESSAGE_RECIPIENT_CC Recipient is a "Cc" address.
static int	MESSAGE_RECIPIENT_TO Recipient is a "To" address.

Method Summary

void	addAttachment(FileAttachment file) Adds a file attachment to this message.
void	addAttachments(FileAttachment[] files) Adds the file attachments to this message.
void	addHeader(java.lang.String sName, java.lang.String sValue) Adds the value to the existing values for this header name.
void	addRecipients(int type, IMailAddress[] addresses) Adds these recipient addresses to the existing ones of the given type.
void	delete() Deletes the message from the underlying store.
void	delete(boolean bDeletedFolder) Deletes the message from the underlying store.
IMessage	forward() Forwards the message.
java.util.Map	getAllHeaders() Gets a map of all the header values.
IAttachment	getAttachment(java.lang.String sFilename) Gets a file attachment from the message by the specified name.
IAttachment[]	getAttachments() Gets all file attachments for this message.
IAttachment[]	getAttachments(boolean bLoadData) Gets all file attachments for this message.
IMailAddress[]	getBcc() Gets the "Bcc" addresses for the recipient of the message.
java.lang.String	getBccString() Gets the "Bcc" attribute in printable form.
Body	getBody() Gets the message body.
IMailAddress[]	getCc() Gets the "Cc" addresses for the recipient of the message.
java.lang.String	getCcString() Gets the "Cc" attribute in printable form.
java.lang.Object	getFolderID() Gets the folder id from which this message was obtained.
IMailAddress[]	getFrom() Gets the "From" addresses for the sender of the message.
java.lang.String	getFromString() Gets the "From" attribute in printable form.
java.lang.String	getHeaderValue(java.lang.String sName) Gets a single header value for the specified header name.
java.lang.String[]	getHeaderValues(java.lang.String sName) Gets all the header values for the specified header name.
java.lang.Object	getID() Gets the ID of this message.
java.util.Date	getReceivedDate() Gets the date this message was received.
java.lang.String	getReceivedDateString(java.text.DateFormat dateFormat) Gets the displayable received date using the specified date format.
java.util.List	getRecipients(int type) Gets the recipients of the specified type.
java.util.Date	getSentDate() Gets the date this message was sent.
java.lang.String	getSentDateString(java.text.DateFormat dateFormat) Gets the displayable sent date using the specified date format.
int	getSize() Gets the size of this message in bytes.
java.lang.String	getSizeKilos() Gets the size of this message in kilobytes.
java.lang.String	getSubject() Gets the subject of this message.
java.lang.String	getSubject(int iLength) Gets the subject of the message.
java.lang.String	getSubject(java.util.Locale locale) Gets the subject of this message.
java.lang.String	getSubject(java.util.Locale locale, int iLength) Gets the subject of the message.
IMailAddress[]	getTo() Gets the "To" addresses for the recipient of the message.
java.lang.String	getToString() Gets the "To" attribute in printable form.
boolean	hasAttachments() Checks if the messages has attachments.
boolean	isHighPriority() Checks whether the message is high priority.
boolean	isUnread() Checks whether the message is unread.
void	move(java.lang.Object folderID) Moves the message to the folder with the specified ID.
void	removeHeader(java.lang.String sName) Removes all headers with this name.
boolean	removeRecipient(int type, IMailAddress address) Removes this recipient address from the existing ones.
IMessage	reply() Replies to the message.
IMessage	replyAll() Replies to the message.
void	saveDraft() Saves the message in the Drafts folder.
void	send() Sends the message.
void	send(boolean bSaveSent) Sends the message.
void	send(boolean bSaveSent, IMailAddress from) Sends the message with the specified from address.
void	setBody(Body body) Sets the body of this message.
void	setHeader(java.lang.String sName, java.lang.String sValue) Sets the value for this header name.
void	setHighPriority(boolean bFlag) Sets the high priority flag for this message.
void	setSubject(java.lang.String sSubject) Sets the subject of this message.

Field Detail

MESSAGE_RECIPIENT_TO

public static final int MESSAGE_RECIPIENT_TO

Recipient is a "To" address.

MESSAGE_RECIPIENT_CC

public static final int MESSAGE_RECIPIENT_CC

Recipient is a "Cc" address.

MESSAGE_RECIPIENT_BCC

public static final int MESSAGE_RECIPIENT_BCC

Recipient is a "Bcc" address.

Method Detail

setSubject

public void setSubject(java.lang.String sSubject)
                throws MailException

Sets the subject of this message. MailException is thrown if this is not a new message.

Parameters:

sSubject - the subject of this message (must be UTF-8 encoding)

getSubject

public java.lang.String getSubject()
                            throws MailException

Gets the subject of this message. Returns the message.no_subject property from mail_resources.properties if the subject is null or zero length.

Returns:

the subject of this message

getSubject

public java.lang.String getSubject(java.util.Locale locale)
                            throws MailException

Gets the subject of this message. Returns the message.no_subject property from mail_resources.properties if the subject is null or zero length.

The locale is used to determine the (no subject) message if the actual message subject is null or empty. The (no subject) string is configurable in mail_resources.properties.

Parameters:

locale - the locale to use (may not be null)

Returns:

the subject of this message

getSubject

public java.lang.String getSubject(int iLength)
                            throws MailException

Gets the subject of the message. The subject is truncated after the specified number of characters and "..." is appended to it.

Parameters:

iLength - the maximum length of the result (string plus "...")

Returns:

the truncated subject of the message

getSubject

public java.lang.String getSubject(java.util.Locale locale,
                                   int iLength)
                            throws MailException

Gets the subject of the message. The subject is truncated after the specified number of characters and "..." is appended to it.

The locale is used to determine the (no subject) message if the actual message subject is null or empty. The (no subject) string is configurable in mail_resources.properties.

Parameters:

locale - the locale to use (may not be null)

iLength - the maximum length of the result (string plus "...")

Returns:

the truncated subject of the message

getSentDateString

public java.lang.String getSentDateString(java.text.DateFormat dateFormat)
                                   throws MailException

Gets the displayable sent date using the specified date format.

Parameters:

dateFormat - the date format to use when formating the sent date (may not be null)

Returns:

the sent date in displayable string form

getSentDate

public java.util.Date getSentDate()
                           throws MailException

Gets the date this message was sent.

Returns:

the sent date or null if not available

getReceivedDateString

public java.lang.String getReceivedDateString(java.text.DateFormat dateFormat)
                                       throws MailException

Gets the displayable received date using the specified date format.

Parameters:

dateFormat - the date format to use when formating the received date (may not be null)

Returns:

the received date in displayable string form

getReceivedDate

public java.util.Date getReceivedDate()
                               throws MailException

Gets the date this message was received.

Returns:

the received date or null if not available

getBody

public Body getBody()
             throws MailException

Gets the message body.

Returns:

the message body

setBody

public void setBody(Body body)
             throws MailException

Sets the body of this message. MailException is thrown if this is not a new message.

Parameters:

body - the body of this message (may not be null)

getFromString

public java.lang.String getFromString()
                               throws MailException

Gets the "From" attribute in printable form.

Returns:

the "From" attribute

Throws:

MailException - an error occurs retrieving From recipients from the message

getFrom

public IMailAddress[] getFrom()
                       throws MailException

Gets the "From" addresses for the sender of the message.

Returns:

an array of "From" addresses

Throws:

MailException - an error occurs retrieving From recipients from the message

getTo

public IMailAddress[] getTo()
                     throws MailException

Gets the "To" addresses for the recipient of the message.

Returns:

an array of "To" addresses

Throws:

MailException - an error occurs retrieving To recipients from the message

getToString

public java.lang.String getToString()
                             throws MailException

Gets the "To" attribute in printable form.

Returns:

the "To" attribute

Throws:

MailException - an error occurs retrieving To recipients from the message

getCc

public IMailAddress[] getCc()
                     throws MailException

Gets the "Cc" addresses for the recipient of the message.

Returns:

an array of "Cc" addresses

Throws:

MailException - an error occurs retrieving Cc recipients from the message

addRecipients

public void addRecipients(int type,
                          IMailAddress[] addresses)
                   throws MailException

Adds these recipient addresses to the existing ones of the given type.

Parameters:

type - the recipient type (see MESSAGE_RECIPIENT_ constants);

addresses - the addresses

Throws:

MailException - an error occurs retrieving Cc recipients from the message

getRecipients

public java.util.List getRecipients(int type)
                             throws MailException

Gets the recipients of the specified type.

Parameters:

type - the recipient type (see MESSAGE_RECIPIENT_ constants);

Returns:

a list of IMailAddress objects or an empty list if no recipients of that type exist

Throws:

MailException - an error occurs retrieving Cc recipients from the message

removeRecipient

public boolean removeRecipient(int type,
                               IMailAddress address)
                        throws MailException

Removes this recipient address from the existing ones.

Parameters:

type - the recipient type (see MESSAGE_RECIPIENT_ constants);

address - the address to remove

Returns:

true if the recipient existed and was removed; false otherwise

Throws:

MailException - an error occurs retrieving Cc recipients from the message

getCcString

public java.lang.String getCcString()
                             throws MailException

Gets the "Cc" attribute in printable form.

Returns:

the "Cc" attribute

Throws:

MailException - an error occurs retrieving Cc recipients from the message

getBcc

public IMailAddress[] getBcc()
                      throws MailException

Gets the "Bcc" addresses for the recipient of the message.

Returns:

an array of "Bcc" addresses

Throws:

MailException - an error occurs retrieving Bcc recipients from the message

getSize

public int getSize()
            throws MailException

Gets the size of this message in bytes.

Returns:

the size of this message in bytes or -1 if the size cannot be determined

getSizeKilos

public java.lang.String getSizeKilos()
                              throws MailException

Gets the size of this message in kilobytes.

Returns:

the size of this message in kilobytes or -1 if the size cannot be determined

getBccString

public java.lang.String getBccString()
                              throws MailException

Gets the "Bcc" attribute in printable form.

Returns:

the "Bcc" attribute

Throws:

MailException - an error occurs retrieving Bcc recipients from the message

delete

public void delete()
            throws MailException

Deletes the message from the underlying store. The message is moved to the deleted folder.

delete

public void delete(boolean bDeletedFolder)
            throws MailException

Deletes the message from the underlying store.

Parameters:

bDeletedFolder - true to move the message to the deleted folder; false otherwise

isHighPriority

public boolean isHighPriority()
                       throws MailException

Checks whether the message is high priority.

Returns:

true if this message is high priority; false otherwise

setHighPriority

public void setHighPriority(boolean bFlag)
                     throws MailException

Sets the high priority flag for this message. MailException is thrown if this is not a new message.

Parameters:

bFlag - true if this message is to be sent with high priority; false otherwise

isUnread

public boolean isUnread()
                 throws MailException

Checks whether the message is unread.

Returns:

true if this message is unread; false otherwise

getID

public java.lang.Object getID()
                       throws MailException

Gets the ID of this message.

Returns:

the ID of this message

reply

public IMessage reply()
               throws MailException

Replies to the message.

Returns:

a new message suitable for replying to the sender

replyAll

public IMessage replyAll()
                  throws MailException

Replies to the message.

Returns:

a new message suitable for replying to the sender and all recipients

forward

public IMessage forward()
                 throws MailException

Forwards the message.

Returns:

a new message suitable for forwarding

saveDraft

public void saveDraft()
               throws MailException

Saves the message in the Drafts folder.

send

public void send()
          throws MailException

Sends the message. Saves a copy of the message in Sent folder.

send

public void send(boolean bSaveSent)
          throws MailException

Sends the message.

Parameters:

bSaveSent - true to save a copy of the message in Sent folder; false otherwise

send

public void send(boolean bSaveSent,
                 IMailAddress from)
          throws MailException

Sends the message with the specified from address.

Parameters:

bSaveSent - true to save a copy of the message in Sent folder; false otherwise

address - the from address. If null, the connection ISession.CONNPROP_FROM is used

getHeaderValue

public java.lang.String getHeaderValue(java.lang.String sName)
                                throws MailException

Gets a single header value for the specified header name. If the header has more than one single value, the first value is returned. If the header has no values, null is returned.

Parameters:

sName - the name of this header

Returns:

the single value for all headers with this name or null if the header does not exist

See Also:

getHeaderValues(String)

getHeaderValues

public java.lang.String[] getHeaderValues(java.lang.String sName)
                                   throws MailException

Gets all the header values for the specified header name.

Parameters:

sName - the name of this header

Returns:

the values for all headers with this name or an empty array (zero length) if the header has not values

getAllHeaders

public java.util.Map getAllHeaders()
                            throws MailException

Gets a map of all the header values. The map key is the header name and the map value is an array of string values.

Returns:

a map of header names/values (unmodifiable)

addHeader

public void addHeader(java.lang.String sName,
                      java.lang.String sValue)
               throws MailException

Adds the value to the existing values for this header name.

Parameters:

sName - the name of the header to add to

sValue - the value of the header

setHeader

public void setHeader(java.lang.String sName,
                      java.lang.String sValue)
               throws MailException

Sets the value for this header name. Replaces all existing header values with this new value.

Parameters:

sName - the name of the header to set

sValue - the value of the header

removeHeader

public void removeHeader(java.lang.String sName)
                  throws MailException

Removes all headers with this name.

Parameters:

sName - the name of the header to remove

hasAttachments

public boolean hasAttachments()
                       throws MailException

Checks if the messages has attachments. Returns true if this message has attachments. The test for attachments is by checking the MIME type of the message. A message is considered to have attachments if the MIME type is multipart/*.

Returns:

true if this message has attachments; false otherwise

getAttachments

public IAttachment[] getAttachments()
                             throws MailException

Gets all file attachments for this message. This method loads the file attachment data, which could be costly if you are only interested in attachment summary data (filename, content-type). Use getAttachments(boolean) to optionally retrieve only the attachment shells.

Returns:

an array of file attachments or an empty array if no attachments exist

getAttachments

public IAttachment[] getAttachments(boolean bLoadData)
                             throws MailException

Gets all file attachments for this message.

Parameters:

bLoadData - true to load the attachment data; false to only load summary data

Returns:

an array of file attachments or an empty array if no attachments exist

getAttachment

public IAttachment getAttachment(java.lang.String sFilename)
                          throws MailException

Gets a file attachment from the message by the specified name.

Parameters:

sFilename - the name of the file attachment

Returns:

the file attachment or null if the file attachment does not exist

addAttachment

public void addAttachment(FileAttachment file)
                   throws MailException

Adds a file attachment to this message.

Parameters:

file - the file to attach (may not be null)

Throws:

MailException - an error occurs adding the file attachment

addAttachments

public void addAttachments(FileAttachment[] files)
                    throws MailException

Adds the file attachments to this message.

Parameters:

files - an array of files to attach (may not be null)

Throws:

MailException - an error occurs adding the file attachment

getFolderID

public java.lang.Object getFolderID()
                             throws MailException

Gets the folder id from which this message was obtained. If this is a new message, this method returns null. This only returns the ID of the message, instead of the folder itself. This helps to reduce overhead by not carrying around the reference if it is not needed.

Returns:

the folder id or null if this is a new message

move

public void move(java.lang.Object folderID)
          throws MailException

Moves the message to the folder with the specified ID.

Parameters:

folderID - the folder ID