net.rim.blackberry.api.mail
Class Folder

java.lang.Object
  net.rim.blackberry.api.mail.Folder

public class Folder
extends Object

Represents a mailbox folder on the handheld.

Folders can contain Message objects, other Folder objects or both. This nesting capability enables a folder hierarchy for stored messages. The different levels of hierarchy in a folder's full name are separated by the hierarchy separator character, which you can retrieve using Folder.getSeparator().

You can retrieve a contained folder by name using getFolder, or a list of contained folders by using Folder.list(). Both these methods return folders not cached by the Store owning this folder, so invoking either method multiple times on the folder returns distinct Folder objects.

Note: Multiple Folder objects can refer to the same physical folder on device. As a result, you should invoke addFolderListener to register a FolderListener to listen for any FolderEvent affecting a folder. When finished, you can remove the listener with removeFolderListener.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Field Summary
	static int	DELETED A Folder containing deleted messages.
	static int	DRAFT A Folder containing draft messages.
	static int	FILED Contains items that are filed in a Folder.
	static int	INBOX A Folder containing received messages.
	static int	INVALID A Folder containing items marked as invalid.
	static int	INVALID_FOLDER_ID Indicates an invalid folder ID.
	static int	JUNK A Folder for junk mail This Folder type may be used in Folder.getType() and Folder.list(int).
	static String	NEW_FOLDER_NAME Default name for new folders.
	static int	ORPHAN A Folder containing items who's 'parent' has been deleted.
	static int	OTHER A Folder that the user created - a personal folder.
	static int	OUTBOX A Folder containing messages in the process of being sent.
	static char	ROOT_SEPARATOR Character that separates the user's root folder from subfolders.
	static String	ROOT_SEPARATOR_STRING String that separates the user's root folder from subfolders.
	static int	SENT A Folder containing sent messages.
	static char	SEPARATOR_CHAR Character that separates folders in a hierarchy.
	static int	SUBTREE A Folder that is contained within another Folder.
	static int	UNFILED Contains items that are not currently filed in a Folder.

Method Summary
	void	addFolderListener(FolderListener l) Adds a listener for folder events on this folder.
	void	addFolderListener(FolderListener l, ListenerInvocationProperties props) Adds a listener for folder events on this folder and specifies how the listener should be invoked.
	boolean	appendMessage(Message msg) Saves a message to this folder.
	boolean	appendMessages(Message[] msgs) Saves several messages to this folder.
	boolean	deleteMessage(Message msg) Deletes a message from this folder.
	boolean	deleteMessage(Message msg, boolean forceDeleteSaved) Deletes a message from this folder.
	boolean	equals(Object o) Determines if an object refers to the same physical folder as this folder.
	Message[]	getDraftMessages(Message[] array) Retrieves draft messages from a list of messages.
	Folder	getFolder(String name) Retrieves the Folder object corresponding to the given name.
	String	getFullName() Retrieves this folder's full name.
	long	getId() Retrieves this folder's internal ID.
	Message[]	getMessages() Retrieves the messages contained in this folder.
	String	getName() Retrieves this folder's friendly name.
	Folder	getParent() Retrieves this folder's parent folder.
	static char	getSeparator() Retrieves the delimiter character that separates sub-folders.
	Store	getStore() Retrieves the store containing this folder.
	int	getType() Retrieves this folder's type.
	int	hashCode() Retrieves a hash of this folder's ID.
	Folder[]	list() Retrieves this folder's sub-folders.
	Folder[]	list(int type) Retrieves this folder's sub-folders only of provided type.
	void	removeFolderListener(FolderListener l) Removes a folder-event listener.
	String	toString() Retrieves this folder's full name.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

SUBTREE

public static final int SUBTREE

A Folder that is contained within another Folder. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

DELETED

public static final int DELETED

A Folder containing deleted messages. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

INBOX

public static final int INBOX

A Folder containing received messages. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

OUTBOX

public static final int OUTBOX

A Folder containing messages in the process of being sent. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

SENT

public static final int SENT

A Folder containing sent messages. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

OTHER

public static final int OTHER

A Folder that the user created - a personal folder. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

JUNK

public static final int JUNK

A Folder for junk mail This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

ORPHAN

public static final int ORPHAN

A Folder containing items who's 'parent' has been deleted. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

INVALID

public static final int INVALID

A Folder containing items marked as invalid. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

FILED

public static final int FILED

Contains items that are filed in a Folder. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

UNFILED

public static final int UNFILED

Contains items that are not currently filed in a Folder. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

DRAFT

public static final int DRAFT

A Folder containing draft messages. This Folder type may be used in Folder.getType() and Folder.list(int).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

SEPARATOR_CHAR

public static final char SEPARATOR_CHAR

Character that separates folders in a hierarchy.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

ROOT_SEPARATOR

public static final char ROOT_SEPARATOR

Character that separates the user's root folder from subfolders.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

ROOT_SEPARATOR_STRING

public static String ROOT_SEPARATOR_STRING

String that separates the user's root folder from subfolders.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

INVALID_FOLDER_ID

public static final int INVALID_FOLDER_ID

Indicates an invalid folder ID.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

NEW_FOLDER_NAME

public static String NEW_FOLDER_NAME

Default name for new folders.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Method Detail

getName

public String getName()

Retrieves this folder's friendly name.

Use this method to retrieve the friendly name (base name with no heirarchy delimiter or path).

Returns:

Friendly name for this folder.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getFullName

public String getFullName()

Retrieves this folder's full name.

The returned name is an absolute name, which starts with the hierarchy delimiter.

Returns:

Full name for this folder.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getStore

public Store getStore()

Retrieves the store containing this folder.

Returns:

Store that owns this folder.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getParent

public Folder getParent()

Retrieves this folder's parent folder.

Returns:

Parent folder or null if there is no parent folder (the folder is already at the root level).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

list

public Folder[] list()

Retrieves this folder's sub-folders.

Returns:

List of folders that this folder contains, or an empty array if no sub-folders present.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

list

public Folder[] list(int type)

Retrieves this folder's sub-folders only of provided type.

Note that this method iterates over direct children of the folder only. Refer to the Store.list(int) method documentation.

Parameters:

type - Type of folder to retrieve.

Returns:

List of folders of your provided type that this folder contains, or an empty array if no such sub-folders present.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSeparator

public static char getSeparator()

Retrieves the delimiter character that separates sub-folders.

Returns:

Delimiter character that separates folders in a path name.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getType

public int getType()

Retrieves this folder's type.

Returns:

Type of this folder.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getFolder

public Folder getFolder(String name)
                 throws FolderNotFoundException

Retrieves the Folder object corresponding to the given name.

Folder objects are not cached by the Store, so invoking this method on the same name multiple times will return that many distinct Folder objects.

This API does not support the following characters appearing in folder names:

• /
• :
• \

Parameters:

name - Name of the folder, specified as a path relative to this folder; for example, specify "abc" if "abc" is a direct sub-folder of this folder.

Returns:

A Folder object

Throws:

FolderNotFoundException - General messaging error.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getMessages

public Message[] getMessages()
                      throws MessagingException

Retrieves the messages contained in this folder.

This method retrieves only the messages contained directly in this folder, not from any sub-folders.

Returns:

Array of messages contained in this folder, or an empty array if this folder does not directly contain any messages.

Throws:

MessagingException

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getDraftMessages

public Message[] getDraftMessages(Message[] array)

Retrieves draft messages from a list of messages.

This method retrieves only the draft messages contained in the message array.

Parameters:

array - A list of messages.

Returns:

Array of draft messages contained in the message list, or an empty array if the message list does not contain any draft messages.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

appendMessage

public boolean appendMessage(Message msg)

Saves a message to this folder.

This method delivers an appropriate FolderEvent to any registered FolderListener when the message arrives in this folder.

This method reassignes the internal folder object on the message to this folder.

Parameters:

msg - Message to save in this folder.

Returns:

True if the message was saved successfully; false if the message append failed, for instance, if the message is already part of the list.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

appendMessages

public boolean appendMessages(Message[] msgs)

Saves several messages to this folder.

This method delivers an appropriate FolderEvent to any registered FolderListener when the messages arrive in this folder.

Implementations of this class must not abort this operation if a message in the provided list turns out to be an expunged message.

Parameters:

msgs - Messages to append to this folder.

Returns:

True if the messages are saved successfully; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

deleteMessage

public boolean deleteMessage(Message msg)

Deletes a message from this folder. If the message is marked as SAVED, then the message is deleted from this folder but is not deleted from the device.

This method delivers an appropriate FolderEvent to any registered FolderListener when the message is removed from this folder.

Parameters:

msg - Message to delete from this folder.

Returns:

True if the message is successfully deleted; otherwise, false (for example, if the message does not exist in this folder).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

deleteMessage

public boolean deleteMessage(Message msg,
                             boolean forceDeleteSaved)

Deletes a message from this folder.

This method delivers an appropriate FolderEvent to any registered FolderListener when the message is removed from this folder.

Parameters:

msg - Message to delete from this folder.

forceDeleteSaved - If the message is saved, force it's deletion.

Returns:

True if the message is successfully deleted; otherwise, false (for example, if the message does not exist in this folder).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.2

addFolderListener

public void addFolderListener(FolderListener l)

Adds a listener for folder events on this folder.

This is just a convenience method with a consequent call to Folder.addFolderListener(FolderListener, ListenerInvocationProperties) with NULL invocation properties argument.

Parameters:

l - Listener to add to this folder.

See Also:

Folder.addFolderListener(FolderListener, ListenerInvocationProperties)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

removeFolderListener

public void removeFolderListener(FolderListener l)

Removes a folder-event listener.

Note: You should only invoke this with listeners that have already been added with Folder.addFolderListener(net.rim.blackberry.api.mail.event.FolderListener).

Parameters:

l - Listener to remove from this folder.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

addFolderListener

public void addFolderListener(FolderListener l,
                              ListenerInvocationProperties props)

Adds a listener for folder events on this folder and specifies how the listener should be invoked.

If the invocation properties are not specified then the listener will be invoked in a system proxy process.

It is advised to catch exceptions in the listening application code in order to recover properly.

Parameters:

l - Listener to add to this folder.

props - specifies how the listener should be invoked, if NULL is given then defaults are used

See Also:

ListenerInvocationProperties

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 7.0.0

getId

public long getId()

Retrieves this folder's internal ID.

Returns:

This folder's ID, or Folder.INVALID_FOLDER_ID if this folder is invalid.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

equals

public boolean equals(Object o)

Determines if an object refers to the same physical folder as this folder.

Overrides:

equals in class Object

Parameters:

o - Object to compare to this folder.

Returns:

True if the object is equal to this folder; otherwise, false.

See Also:

Boolean.hashCode(), Hashtable

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

hashCode

public int hashCode()

Retrieves a hash of this folder's ID.

Overrides:

hashCode in class Object

Returns:

SHA1 hash produced from this folder's ID.

See Also:

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

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

toString

public String toString()

Retrieves this folder's full name.

Note: This method overrides the default toString() functionality; instead, it retrieves the full name string from Folder.getFullName(). If getFullName() returns null, this method falls back on the default toString() behaviour.

Overrides:

toString in class Object

Returns:

This folder's full name.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0