com.funambol.mail
Class Message

java.lang.Object
  extended by com.funambol.mail.Part
      extended by com.funambol.mail.Message
Direct Known Subclasses:
LightMessage

public class Message
extends Part

This class models a MIME-style email message.

Message extends the Part abstract class, and 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. This state is in turn described by the calss MessageFlags.

Message defines some new attributes in addition to those defined in Part. These attributes specify meta-data for the message -i.e., addressing and descriptive information about the message.

Clients create new MIME-style messages building an empty Message object and then filling it with appropriate attributes and content. Message objects can be obtained from a Folder too.

A Message can be kept completely in memory or loaded from its store when needed. This allows clients to trade memory for performance. Headers and content can be lazy. When they are they get flushed every time the message is stored in a store. When they are needed they are loaded/used and discarded. If they are not lazy then they are always kept in memory. Besides this mechanism for lazy loading, there's also a mechanism for caching which is used to alleviate the slowness of lazy loading. If headers are lazy, then part of them (FROM, TO, SUBJECT and so on) can be cached. Every time they are read from the store they go in cache and kept for further uses. We do not cache the entire headers, but rather only a subset.


Field Summary
static java.lang.String BCC
          BCC header name
static int CACHE_BCC
          Cached "bcc" addresses.
static int CACHE_CC
          Cached "cc" addresses.
static int CACHE_FROM
          Cached "from" addresses.
static int CACHE_REPLYTO
          Cached "reply to" addresses.
static int CACHE_SUBJECT
          Cached "subject".
static int CACHE_TO
          Cached "to" addresses.
static java.lang.String CC
          CC header name
 int composedMessageLength
           
protected  java.lang.Object content
          The content of this Message as an Object (it can be a Multipart or a String) When it is a String, it is stored in the native encoding of the application, regardless of how it has been transferred.
protected  MessageFlags flags
          A combination of status flags for this Message within a folder, e.g.
static java.lang.String FROM
          FROM header name
protected  java.lang.String key
          Message key.
static int LAZY_CONTENT
          Lazy content.
static int LAZY_HEADERS
          Lazy headers.
static char MESSAGE_ITEM_PREFIX
           
protected  java.lang.String msgid
          The unique ID of this message.
static int NO_LAZY
          Do not be lazy
protected  Folder parent
          A Folder can contain many Messages, and each Message has a reference to its Folder
protected  long received
          The received date of this message
static java.lang.String REPLYTO
          REPLY-TO header name
protected  long sent
          The sent date of this message
static java.lang.String SUBJECT
          SUBJECT header name
static java.lang.String TO
          TO header name
 
Fields inherited from class com.funambol.mail.Part
CONTENT_TRANSFER_ENCODING, CONTENT_TYPE, contentType, ENC_7BIT, ENC_8BIT, ENC_B64, ENC_QP, headers, MULTIPART, MULTIPART_ALTERNATIVE, MULTIPART_MIXED, size, TEXT_PLAIN
 
Constructor Summary
Message()
          The default constructor
 
Method Summary
 void addRecipient(Address address)
          Add the specified recipient to the correct header, based on the Address type (see com.funambol.mail.Address for the defined types).
 void addRecipients(Address[] list)
          Add the specified recipients to the correct header, based on the Address type.
 int attachmentsNumber()
           
 java.lang.String createUniqueMessageIDValue()
          Creates a unique value for use in the Message ID
 void deserialize(java.io.DataInputStream din)
           
 Address[] getBcc()
          Get the BCC addresses.
 Address[] getCc()
          Get the CC addresses.
 int getComposedMessageLength()
           
 java.lang.Object getContent()
          Get the content of this message: can be a String or a Multipart.
 MessageFlags getFlags()
          Returns the flag mask for this message.
 Address getFrom()
          Get the sender address.
 int getGlobalLaziness()
           
 java.lang.String getKey()
          Get the Message key (maybe null if the client did not set it)
 int getLaziness()
           
 java.lang.String getMessageId()
          Returns the String representing the ID of this Message.
 int getNumberOfRecipients()
          Returns the number of recipients of this email.
 Folder getParent()
          Returns this message's parent Folder
 java.util.Date getReceivedDate()
          Returns the received date of this message.
 long getReceivedTime()
          Returns the received date of this message as long.
 int getRecordId()
           
 Address[] getReplyTo()
          Get the REPLY-TO addresses.
 java.util.Date getSentDate()
          Returns the sent date of this message.
 long getSentTime()
          Returns the sent date of this message as long.
 java.lang.String getSubject()
          Get the message subject.
 java.lang.String getTextContent()
          Convenience method to get the body for text messages
 Address[] getTo()
          Get the TO addresses.
 boolean hasAttachments()
           
static boolean isSupportedStream(char prefix)
          Check whether the provided prefix char represents a Message DataInputStream
 void reloadMessage()
          This method forces a method to be fetched from the store and brought into memory.
 void removeAllRecipients(int type)
          This method removes all the recipients of the specified type from this message.
 void serialize(java.io.DataOutputStream dout)
           
 void setBcc(Address[] bcclist)
          Set the content of the RFC 2822 "Bcc:" (blind carbon copy) header with the provided addresses, passed as an Address array
 void setCc(Address[] cclist)
          Set the content of the RFC 2822 "Cc:" (carbon copy) header with the provided addresses, passed as an Address array
 void setComposedMessageLength(int length)
           
 void setContent(java.lang.Object content)
          Sets the content of this Message.
 void setContent(java.lang.Object content, java.lang.String type)
          Sets the content of this Message.
 void setFlags(MessageFlags flags)
          Sets the flag mask for this message.
 void setFrom(Address from)
          This method sets the content of the RFC 2822 "From:" header with the given Address.
static void setGlobalLaziness(int value)
          Set the default value for laziness behavior.
 void setKey(java.lang.String key)
          Allows a client to set the Message key.
 void setLaziness(int value)
          Set this message laziness behavior.
 void setMessageId(java.lang.String messageId)
          Sets the String representing the unique ID of this Message
 void setParent(Folder parent)
          Sets a reference to the Folder this Message is contained in
 void setReceivedDate(java.util.Date received)
          Set the received date
 void setRecordId(int id)
           
 void setReplyTo(Address[] replytolist)
          Set the content of the RFC 2822 "Bcc:" (blind carbon copy) header with the provided addresses, passed as an Address array
 void setSentDate(java.util.Date sent)
          Set the sent date
 void setSubject(java.lang.String subject)
          Set the content of the RFC 2822 "Subject:" header.
 void setTextBody(java.lang.String text)
          Sets the body text of this Message.
 void setTo(Address[] tolist)
          Set the content of the RFC 2822 "To:" header with the provided addresses, passed as an Address array
protected  void writeRecordPrefix(java.io.DataOutputStream dout)
           
 
Methods inherited from class com.funambol.mail.Part
addHeader, getAllHeaders, getContentType, getHeader, getSize, isMultipart, isText, isTextHtml, isTextPlain, removeHeader, setContentType, setHeader, setSize
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MESSAGE_ITEM_PREFIX

public static final char MESSAGE_ITEM_PREFIX
See Also:
Constant Field Values

TO

public static final java.lang.String TO
TO header name

See Also:
Constant Field Values

FROM

public static final java.lang.String FROM
FROM header name

See Also:
Constant Field Values

CC

public static final java.lang.String CC
CC header name

See Also:
Constant Field Values

BCC

public static final java.lang.String BCC
BCC header name

See Also:
Constant Field Values

REPLYTO

public static final java.lang.String REPLYTO
REPLY-TO header name

See Also:
Constant Field Values

SUBJECT

public static final java.lang.String SUBJECT
SUBJECT header name

See Also:
Constant Field Values

msgid

protected java.lang.String msgid
The unique ID of this message. This is a string containing the global-unique message ID. It is generated by the application for outgoing messages and is taken from the received message otherewise. By the standard definition this field should be present and unique, but there are buggy servers/clients that do not define it or define it as not unique. It is also important to notice that this is an email message id. Being unique means there is just an email with this id, but we could have more than one message on the client with this id. Suppose for example we have 2 email accounts: A and B and B is just a forward to A. If an email message is sent to A and B, the client will get two messages with the same ID. This means that in practice if a key is needed for a Message, it is better to avoid using the msgid. (@see key field)


flags

protected MessageFlags flags
A combination of status flags for this Message within a folder, e.g. 'read', 'forwarded', 'draft' etc.


parent

protected Folder parent
A Folder can contain many Messages, and each Message has a reference to its Folder


sent

protected long sent
The sent date of this message


received

protected long received
The received date of this message


content

protected java.lang.Object content
The content of this Message as an Object (it can be a Multipart or a String) When it is a String, it is stored in the native encoding of the application, regardless of how it has been transferred. During parsing operation, the String is decoded according to the 'Content-Transfer-Encoding' field.


key

protected java.lang.String key
Message key. This key is used by the client to identify its messages. The information is not generated by the API and when a Message is created it is left empty (null). It is up to the client to set the key properly. This allows the client to have maximum freedom on how the key is generated (it is even possible for a client to avoid defining a key if not needed).


NO_LAZY

public static final int NO_LAZY
Do not be lazy

See Also:
Constant Field Values

LAZY_CONTENT

public static final int LAZY_CONTENT
Lazy content. The content is loaded only when needed

See Also:
Constant Field Values

LAZY_HEADERS

public static final int LAZY_HEADERS
Lazy headers. Headers are loaded only when needed

See Also:
Constant Field Values

CACHE_TO

public static final int CACHE_TO
Cached "to" addresses. Even if headers are lazy, this value can be cached (read through cache)

See Also:
Constant Field Values

CACHE_CC

public static final int CACHE_CC
Cached "cc" addresses. Even if headers are lazy, this value can be cached (read through cache)

See Also:
Constant Field Values

CACHE_BCC

public static final int CACHE_BCC
Cached "bcc" addresses. Even if headers are lazy, this value can be cached (read through cache)

See Also:
Constant Field Values

CACHE_FROM

public static final int CACHE_FROM
Cached "from" addresses. Even if headers are lazy, this value can be cached (read through cache)

See Also:
Constant Field Values

CACHE_SUBJECT

public static final int CACHE_SUBJECT
Cached "subject". Even if headers are lazy, this value can be cached (read through cache)

See Also:
Constant Field Values

CACHE_REPLYTO

public static final int CACHE_REPLYTO
Cached "reply to" addresses. Even if headers are lazy, this value can be cached (read through cache)

See Also:
Constant Field Values

composedMessageLength

public int composedMessageLength
Constructor Detail

Message

public Message()
The default constructor

Initialize the message with default values suitable for sending it (content-type: text/plain, sent and received date equal to current time). The caller must override these values with the desired content.

Method Detail

setGlobalLaziness

public static void setGlobalLaziness(int value)
Set the default value for laziness behavior. This value will be applied to any newly created message (existing ones are left unchanged).

Parameters:
value - is a bitmask obtained using LAZY and CACHE constants

getGlobalLaziness

public int getGlobalLaziness()
Returns:
global laziness value

setLaziness

public void setLaziness(int value)
Set this message laziness behavior. This value is for this message only.

Parameters:
value - is a bitmask obtained using LAZY and CACHE constants

getLaziness

public int getLaziness()
Returns:
laziness value

reloadMessage

public void reloadMessage()
                   throws MailException
This method forces a method to be fetched from the store and brought into memory. The message is entirely loaded, regardless of the laziness settings. For the method to be really reloaded it must belong to an existing and available folder.

Throws:
MailException - if the message cannot be re-read from the store.

addRecipients

public void addRecipients(Address[] list)
                   throws MailException
Add the specified recipients to the correct header, based on the Address type.

Parameters:
list - list of Adresses to add to the recipient header. Null items are simply ignored.
Throws:
MailException

addRecipient

public void addRecipient(Address address)
                  throws MailException
Add the specified recipient to the correct header, based on the Address type (see com.funambol.mail.Address for the defined types).

Parameters:
address - the address to add to the recipient header. If it is null then it is simply ignored
Throws:
MailException

setKey

public void setKey(java.lang.String key)
Allows a client to set the Message key. The key should be unique, but the API does not use this field, therefore it is up to the client to define it in some meaningful way.

Parameters:
key - is the new key

getKey

public java.lang.String getKey()
Get the Message key (maybe null if the client did not set it)


getFrom

public Address getFrom()
                throws MailException
Get the sender address. If the value is in cache then we use that value. Otherwise we check if it is in the headers (in memory). If we cannot find it, then we check if the value is in the store (provided the message belongs to a folder). IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Returns:
the address if it has been defined, null otherwise
Throws:
MailException - if the address cannot be parsed

getTo

public Address[] getTo()
                throws MailException
Get the TO addresses. If the value is in cache then we use that value. Otherwise we check if it is in the headers (in memory). If we cannot find it, then we check if the value is in the store (provided the message belongs to a folder).IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Returns:
the addresses if they have been defined, null otherwise
Throws:
MailException - if at least one address cannot be parsed

getCc

public Address[] getCc()
                throws MailException
Get the CC addresses. If the value is in cache then we use that value. Otherwise we check if it is in the headers (in memory). If we cannot find it, then we check if the value is in the store (provided the message belongs to a folder).IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Returns:
the addresses if they have been defined, null otherwise
Throws:
MailException - if at least one address cannot be parsed

getBcc

public Address[] getBcc()
                 throws MailException
Get the BCC addresses. If the value is in cache then we use that value. Otherwise we check if it is in the headers (in memory). If we cannot find it, then we check if the value is in the store (provided the message belongs to a folder).IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Returns:
the addresses if they have been defined, null otherwise
Throws:
MailException - if at least one address cannot be parsed

getReplyTo

public Address[] getReplyTo()
                     throws MailException
Get the REPLY-TO addresses. If the value is in cache then we use that value. Otherwise we check if it is in the headers (in memory). If we cannot find it, then we check if the value is in the store (provided the message belongs to a folder). If the reply to has not been specified, then "from" is returned. IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Returns:
the addresses if they have been defined, null otherwise
Throws:
MailException - if at least one address cannot be parsed

getFlags

public MessageFlags getFlags()
Returns the flag mask for this message.

Returns:
the flag mask for this message.

getMessageId

public java.lang.String getMessageId()
Returns the String representing the ID of this Message.

Returns:
The unique ID of this Message

getSubject

public java.lang.String getSubject()
Get the message subject. If the value is in cache then we use that value. Otherwise we check if it is in the headers (in memory). If we cannot find it, then we check if the value is in the store (provided the message belongs to a folder). IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Returns:
the subject if is has been defined, null otherwise

getSentDate

public java.util.Date getSentDate()
Returns the sent date of this message.

Returns:
the sent date of this message.

getSentTime

public long getSentTime()
Returns the sent date of this message as long. the result is the same as getSentDate().getTime(), but this way is faster

Returns:
the sent date of this message as long

setFlags

public void setFlags(MessageFlags flags)
Sets the flag mask for this message.

Parameters:
flags - the flag mask for this message.

getReceivedDate

public java.util.Date getReceivedDate()
Returns the received date of this message.

Returns:
the received date of this message.

getReceivedTime

public long getReceivedTime()
Returns the received date of this message as long. the result is the same as getReceivedDate().getTime(), but this way is faster

Returns:
the received date of this message as long

getNumberOfRecipients

public int getNumberOfRecipients()
                          throws MailException
Returns the number of recipients of this email. The number includes addresses in to, cc e bcc.

Returns:
the total count
Throws:
MailException - if at least one address in the recipients is invalid

removeAllRecipients

public void removeAllRecipients(int type)
This method removes all the recipients of the specified type from this message. IMPORTANT: a parent MUST be set for this message before calling this method, otherwise the implicit call to the private method getHeaders() will fail

Parameters:
type - one of the defined types in

setFrom

public void setFrom(Address from)
This method sets the content of the RFC 2822 "From:" header with the given Address.


setTo

public void setTo(Address[] tolist)
Set the content of the RFC 2822 "To:" header with the provided addresses, passed as an Address array

Parameters:
tolist - list of Adresses to put in the To: list

setCc

public void setCc(Address[] cclist)
Set the content of the RFC 2822 "Cc:" (carbon copy) header with the provided addresses, passed as an Address array

Parameters:
cclist - list of Adresses to put in the Cc: list

setBcc

public void setBcc(Address[] bcclist)
Set the content of the RFC 2822 "Bcc:" (blind carbon copy) header with the provided addresses, passed as an Address array

Parameters:
bcclist - list of Adresses to put in the bcclist

setReplyTo

public void setReplyTo(Address[] replytolist)
Set the content of the RFC 2822 "Bcc:" (blind carbon copy) header with the provided addresses, passed as an Address array

Parameters:
replytolist - list of Adresses to put in the bcclist

setSubject

public void setSubject(java.lang.String subject)
Set the content of the RFC 2822 "Subject:" header.

Parameters:
subject - The text to put in the Subject

getParent

public Folder getParent()
Returns this message's parent Folder

Returns:
A reference to the Folder object this Message is contained in

setParent

public void setParent(Folder parent)
Sets a reference to the Folder this Message is contained in

Parameters:
parent - The folder this Message is a child of

setSentDate

public void setSentDate(java.util.Date sent)
Set the sent date

Parameters:
sent - the sent date

setReceivedDate

public void setReceivedDate(java.util.Date received)
Set the received date

Parameters:
received - the received date

getContent

public java.lang.Object getContent()
Get the content of this message: can be a String or a Multipart.

Specified by:
getContent in class Part
Returns:
the content of this Part

getTextContent

public java.lang.String getTextContent()
Convenience method to get the body for text messages

Returns:
the text content of the message, or null this message has no text content.

setContent

public void setContent(java.lang.Object content)
                throws MailException
Sets the content of this Message. It can be a Multipart or a String. This method sets also the contentType: multipart/mixed if the content is Multipart, text/plain if it's a String

Specified by:
setContent in class Part
Throws:
MailException

setTextBody

public void setTextBody(java.lang.String text)
Sets the body text of this Message.


setContent

public void setContent(java.lang.Object content,
                       java.lang.String type)
                throws MailException
Sets the content of this Message. This can be another Multipart (in case of a multi-content message) or a String (in case of a 'single-content' message)

Specified by:
setContent in class Part
Parameters:
content - The content object
type - The MIME type of the content
Throws:
MailException

setMessageId

public void setMessageId(java.lang.String messageId)
Sets the String representing the unique ID of this Message


hasAttachments

public boolean hasAttachments()

attachmentsNumber

public int attachmentsNumber()

serialize

public void serialize(java.io.DataOutputStream dout)
               throws java.io.IOException,
                      MailException
Throws:
java.io.IOException
MailException
See Also:
com.funambol.storage.Serializable#serialize(java.io.DataOutputStream)

deserialize

public void deserialize(java.io.DataInputStream din)
                 throws java.io.IOException
Throws:
java.io.IOException
See Also:
com.funambol.storage.Serializable#deserialize(java.io.DataInputStream)

setRecordId

public void setRecordId(int id)
See Also:
com.funambol.storage.RmsRecordItem#setRecordId(int)

getRecordId

public int getRecordId()
See Also:
com.funambol.storage.RmsRecordItem#getRecordId()

getComposedMessageLength

public int getComposedMessageLength()

setComposedMessageLength

public void setComposedMessageLength(int length)

createUniqueMessageIDValue

public java.lang.String createUniqueMessageIDValue()
Creates a unique value for use in the Message ID

This implementation generates it by concatenating a newly created object's hashCode(), a random long with seed from the the current time, and the string "@Funambol.mail". TODO: usually the message ID ends with the domain name of the host originating the message, or the one of the user's mail address, but this is not easy to do on the phone.


isSupportedStream

public static boolean isSupportedStream(char prefix)
Check whether the provided prefix char represents a Message DataInputStream

Parameters:
prefix - The item prefix.
Returns:
true If supported.

writeRecordPrefix

protected void writeRecordPrefix(java.io.DataOutputStream dout)
                          throws java.io.IOException
Throws:
java.io.IOException


Copyright © 2001-2009 Funambol.