SHOW Signed

net.rim.blackberry.api.mail
Class Message

java.lang.Object
  |
  +--net.rim.blackberry.api.mail.Message

All Implemented Interfaces:

Part

public class Message

extends Object

implements Part

Represents an email message.

Message implements the Part interface. A Message contains a set of header fields (attributes) and a body (contents). Messages in 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 provide addressing and descriptive information about the message.

Message objects can be obtained from a Folder. Received messages are normally retrieved from a folder named "INBOX". A Message object obtained from a folder is just a reference to the actual message. The Message is filled up on demand when each item is requested from the message. Note that certain folder implementations might return Message objects that are pre-filled with certain user-specified items.

To send a message, create a Message object, fill in the attributes and content, and invoke Transport.send(Message msg).

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

See Also:

Folder, Address

Inner Class Summary

	static interface	Message.Flag Defines the flags supported by the Message class.
	static interface	Message.Icons Defines character representations of the various message status icons.
	static interface	Message.RecipientType Defines the types of recipients supported by the Message class.
	static interface	Message.Status Defines the status options supported by the Message class.

Fields inherited from interface net.rim.blackberry.api.mail.Part

ATTACHMENT, INLINE

Constructor Summary

	Message() Default constructor, with no parameters.
	Message(Folder folder) Constructor that takes a Folder Events on the message, such as status changes, are not distributed until this message is added to a folder, or sent via Transport.

Method Summary

	void	addHeader(String header, String value) Adds this value to the existing values for the specified header.
	void	addMessageListener(MessageListener l) Adds a MessageListener to this Message.
	void	addRecipients(int type, Address[] addresses) Adds recipient addresses.
	void	clearFlags(int mask) Clears flags for the message.
	boolean	equals(Object o) Determines if two Message instances are the same.
	Message	forward() Creates a new Message to forward this message.
	Enumeration	getAllHeaders() Retrieves all the headers from this part as an Enumeration of Header objects.
	String	getBodyText() Retrieves the text of the message body, or null if no body text is present.
	Object	getContent() Retrieves the contents of the Part.
	String	getContentType() Retrieves the Content-Type header field of this Part.
	int	getFlags() Retrieves the flags for the message.
	Folder	getFolder() Retrieves the folder from which this message was obtained.
	Address	getFrom() Retrieves the "From" attribute.
	String[]	getHeader(String header) Retrieves all the headers for this header name.
	InputStream	getInputStream() Retrieves an input stream for this part's contents.
	Date	getReceivedDate() Retrieves the date on which this message was received.
	Address[]	getRecipients(int type) Retrieves all the recipient addresses for the message based on recipient type.
	Address[]	getReplyTo() Retrieves the addresses to which replies should be directed.
	Date	getSentDate() Retrieves the date on which this message was sent.
	int	getSize() Retrieves the size of the content of this part in bytes.
	int	getStatus() Retrieves the status of the message.
	String	getSubject() Retrieves the subject of this message.
	int	getTransmissionError() Retrieves the transmission status of the message.
	int	hashCode() Returns a hash code value for the object.
	boolean	isInbound() Determines if this message is an inbound (received) message.
	boolean	isMimeType(String mimeType) Compares the message content type to the specified MIME type.
	boolean	isSet(int flag) Determines if the specified flag is set on this message.
	void	removeHeader(String header) Removes all headers with this name.
	void	removeMessageListener(MessageListener l) Removes a MessageListener on this Message.
	Message	reply(boolean replyToAll) Retrieves a new Message suitable for a reply to this message.
	void	setContent(Object content) Sets the message contents (body).
	void	setFlag(int flag, boolean set) Sets or clears the specified flag on this message.
	void	setFlags(int mask) Sets flags for the message.
	void	setFrom(Address address) Sets the "From" attribute in this Message.
	void	setHeader(String header, String value) Sets the value for this header_name.
	void	setReplyTo(Address[] addresses) Sets the addresses to which replies should be directed.
	void	setSentDate(Date date) Sets the sent date of this message.
	void	setStatus(int messageStatus, int messageTransmissionError) Sets the status for the message.
	void	setSubject(String subject) Sets the subject of this message.
	void	writeTo(OutputStream os) Outputs the message as an RFC 822 format stream.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Message

public Message()

Default constructor, with no parameters.

Events on the message, such as status changes, are not distributed until this message is added to a folder, or sent using Transport.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Message

public Message(Folder folder)

Constructor that takes a Folder

Events on the message, such as status changes, are not distributed until this message is added to a folder, or sent via Transport.

This method does not add the message to the folder, it merely associates it for later transport.

Parameters:

folder - Folder in which to create the Message object.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

getFolder

public Folder getFolder()

Retrieves the folder from which this message was obtained.

Returns:

A Folder object.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setFrom

public void setFrom(Address address)

Sets the "From" attribute in this Message.

Parameters:

address - Address for the sender.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getFrom

public Address getFrom()
                throws MessagingException

Retrieves the "From" attribute.

Returns:

An Address object, or null if no from address has ben set.

Throws:

MessagingException - A general messaging error.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

addRecipients

public void addRecipients(int type,
                          Address[] addresses)

Adds recipient addresses.

Parameters:

type - The type of message recipient. The currently defined types are TO, CC and BCC.

addresses - An array of Address objects.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getRecipients

public Address[] getRecipients(int type)
                        throws MessagingException

Retrieves all the recipient addresses for the message based on recipient type.

Parameters:

type - Type of message recipient. The currently defined types are TO, CC and BCC.

Returns:

An array of Address objects.

Throws:

MessagingException - A general messaging error.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setReplyTo

public void setReplyTo(Address[] addresses)

Sets the addresses to which replies should be directed.

Parameters:

addresses - An array of Address objects.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getReplyTo

public Address[] getReplyTo()
                     throws MessagingException

Retrieves the addresses to which replies should be directed.

Returns:

An an array of Address objects.

Throws:

MessagingException - A general messaging error.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setSubject

public void setSubject(String subject)

Sets the subject of this message.

Parameters:

subject - A string of text to display in the message subject line.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getSubject

public String getSubject()

Retrieves the subject of this message.

Returns:

Text string that appears in the message subject line.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setSentDate

public void setSentDate(Date date)

Sets the sent date of this message.

Parameters:

date - The date when the message was sent.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getSentDate

public Date getSentDate()

Retrieves the date on which this message was sent.

Returns:

The date on which this message was sent, or null if no sent date is available for this message.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getReceivedDate

public Date getReceivedDate()

Retrieves the date on which this message was received.

Returns:

The date on which this message was received, or the creation date for an outbound message.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setFlags

public void setFlags(int mask)

Sets flags for the message.

Parameters:

mask - a bitfield of flags to set for the message

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

clearFlags

public void clearFlags(int mask)

Clears flags for the message.

Parameters:

mask - a bitfield of flags to clear

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getFlags

public int getFlags()

Retrieves the flags for the message.

Returns:

A bitfield of set flags.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setFlag

public void setFlag(int flag,
                    boolean set)

Sets or clears the specified flag on this message.

Parameters:

flag - Flag to set or clear for this message.

set - True to set the specified flag, false to clear the flag.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isSet

public boolean isSet(int flag)

Determines if the specified flag is set on this message.

Parameters:

flag - A flag, as defined in Flag.

Returns:

True if the specified flag is set, otherwise false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isInbound

public boolean isInbound()

Determines if this message is an inbound (received) message.

Returns:

True if the message is an inbound (received) message, otherwise false.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

reply

public Message reply(boolean replyToAll)
              throws MessagingException

Retrieves a new Message suitable for a reply to this message.

Parameters:

replyToAll - True for reply to all; false for reply to sender only.

Returns:

A Message object to send in reply to a message.

Throws:

MessagingException - A general messaging error.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

forward

public Message forward()

Creates a new Message to forward this message. This method uses the capability of the BlackBerry system to forward messages from the mail server.

Returns:

A new message appropriate for forwarding this message

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

addHeader

public void addHeader(String header,
                      String value)

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

• For TO, BCC, REPLY_TO, FROM and SENDER a simple email address is expected for value.
• For DATE, a long date encoded as a string is expected.

Specified by:

addHeader in interface Part

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setHeader

public void setHeader(String header,
                      String value)

Sets the value for this header_name.

This will OVERWRITE any existing headers matching the specified header name

• For TO, BCC, REPLY_TO, FROM and SENDER a simple email address is expected for value.
• For DATE, a long date encoded as a string is expected.

Specified by:

setHeader in interface Part

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

removeHeader

public void removeHeader(String header)

Removes all headers with this name.

Specified by:

removeHeader in interface Part

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getHeader

public String[] getHeader(String header)

Retrieves all the headers for this header name.

For the DATE header, returns both the received data (index 0) and the sent date (index 1) if applicable. That is, for an inbound message, the received date is the date the device received the message where as the sent date is the date the sender sent the message.

Specified by:

getHeader in interface Part

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getAllHeaders

public Enumeration getAllHeaders()

Retrieves all the headers from this part as an Enumeration of Header objects.

the DATE header will always occur twice, the FIRST entry is always the date RECEIVED (by the handheld) the SECOND is the date SENT (by the originating machine)

a new message created on the device will contain at least one header, the RECEIVED date.

Specified by:

getAllHeaders in interface Part

Following copied from interface: net.rim.blackberry.api.mail.Part

Returns:

An enumeration of header fields.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setContent

public void setContent(Object content)
                throws MessagingException

Sets the message contents (body). Content can be either a String or a Multipart object.

This method will REPLACE all existing body parts with the specified object (or set if it is a Multipart object).

a null content is acceptable and will clear the existing message of all it's parts

Specified by:

setContent in interface Part

Parameters:

content - The message body as a DataHandler object.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getContent

public Object getContent()

Description copied from interface: Part

Retrieves the contents of the Part.

Specified by:

getContent in interface Part

Returns:

Object representing the message body (contents). This is typically a BodyPart object for a text message. For a message that includes attachments, a Multipart object is returned.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getBodyText

public String getBodyText()

Retrieves the text of the message body, or null if no body text is present.

Returns:

The text of the text/plain part, or null if no such part is present

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getContentType

public String getContentType()

Description copied from interface: Part

Retrieves the Content-Type header field of this Part.

Specified by:

getContentType in interface Part

Following copied from interface: net.rim.blackberry.api.mail.Part

Returns:

The MIME data type of the contents.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isMimeType

public boolean isMimeType(String mimeType)

Compares the message content type to the specified MIME type. This method compares only the primaryType and subType in the ContentHandler.

Specified by:

isMimeType in interface Part

Parameters:

mimeType - The MIME type to which to compare the message; for example, "text/plain".

Returns:

True if the message has the specified MIME type; otherwise false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getInputStream

public InputStream getInputStream()

Retrieves an input stream for this part's contents.

Specified by:

getInputStream in interface Part

Returns:

The message contents in an input byte stream.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeTo

public void writeTo(OutputStream os)
             throws IOException

Outputs the message as an RFC 822 format stream. Not implemented now, reserved for future use.

Specified by:

writeTo in interface Part

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getSize

public int getSize()

Retrieves the size of the content of this part in bytes.

Specified by:

getSize in interface Part

Returns:

The size of the contents of the message in bytes or -1 if it cannot be determined.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setStatus

public void setStatus(int messageStatus,
                      int messageTransmissionError)

Sets the status for the message. If messageStatus is TX_ERROR (a transmission error), then the transmission error code in the model will be set to the value of messageTransmissionError. If message status is not Status.TX_ERROR, then the transmission error code in the model will be cleared.

Parameters:

messageStatus - The new status of the message.

messageTransmissionError - The transmission error status code to set if the message status is Status.TX_ERROR.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getStatus

public int getStatus()

Retrieves the status of the message. One of the TX or RX constants defined in Status class

Returns:

The current message status.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getTransmissionError

public int getTransmissionError()

Retrieves the transmission status of the message. The transmission error will be 0 unless the message status (returned by getStatus()) is Status.TX_ERROR.

Returns:

The current transmission status code.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

addMessageListener

public void addMessageListener(MessageListener l)

Adds a MessageListener to this Message.

Invoke this method only after invoking Folder.appendMessage(Message msg) or Transport.send(Message msg).

Parameters:

l - MessageListener to add to this Message

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

removeMessageListener

public void removeMessageListener(MessageListener l)

Removes a MessageListener on this Message. You should invoke this method on the Message object on which addMessageListener(MessageListener l) was called.

Parameters:

l - MessageListener to add to this Message

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

equals

public boolean equals(Object o)

Determines if two Message instances are the same. Many Message objects can refer to the same message ultimately. Therefore, use this method to determine if two Message instances are identical

Overrides:

equals in class Object

Parameters:

m - The Message to compare with this Message.

Returns:

True if the two Message objects are identical; otherwise false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

hashCode

public int hashCode()

Description copied from class: Object

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java^TM programming language.)

Overrides:

hashCode in class Object

Following copied from class: java.lang.Object

Returns:

a hash code value for this object.

See Also:

Object.equals(java.lang.Object), Hashtable

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.