SHOW Signed

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 Messages, other Folders, 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 can be retrieved using getSeparator().

You can get a Folder by invoking the getFolder() or the list() method. These methods return Folder objects that are not cached by the Store, so invoking either method multiple times on the same folder returns distinct Folder objects.

Note: Multiple Folder objects can refer to same physical folder on device. As a result, you should invoke addFolderListener and removeFolderListener methods for a FolderListener on the same 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.

See Also:

FolderEvent, FolderListener, Message, Store

Field Summary

	protected Store	_store The Store that contains this Folder.
	static int	DELETED Folder type, used in getType() and list(int type).
	static int	FILED Folder type, used in getType() and list(int type).
	static int	INBOX Folder type, used in getType() and list(int type).
	static int	INVALID Folder type, used in getType() and list(int type).
	static int	INVALID_FOLDER_ID An invalid folder id.
	static String	NEW_FOLDER_NAME Default name for new folders.
	static int	ORPHAN Folder type, used in getType() and list(int type).
	static int	OTHER Folder type, used in getType() and list(int type).
	static int	OUTBOX Folder type, used in getType() and list(int type).
	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 Folder type, used in getType() and list(int type).
	static char	SEPARATOR_CHAR Character that separates folders in a hierarchy.
	static int	SUBTREE Folder type, used in getType() and list(int type).
	static int	UNFILED Folder type, used in getType() and list(int type).

Method Summary

	void	addFolderListener(FolderListener l) Adds a listener for folder events on this folder.
	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	equals(Object o) Determines if two Folder objects refer to the same physical folder.
	Folder	getFolder(String name) Retrieves the Folder object corresponding to the given name.
	String	getFullName() Retrieves the full name of this folder.
	long	getId() Retrieves the internal ID of the folder.
	Message[]	getMessages() Retrieves an array that contains references to messages in this folder only, not in subfolders.
	String	getName() Retrieves the name of this folder.
	Folder	getParent() Retrieves the parent folder of this folder.
	static char	getSeparator() Retrieves the delimiter character that separates subfolders.
	Store	getStore() Retrieves the Store that owns this Folder object.
	int	getType() Retrieves the type of this Folder.
	int	hashCode() override to the basic Object method
	Folder[]	list() Retrieves subfolders under this folder.
	Folder[]	list(int type) Retrieves the subfolders of a specified type under this folder.
	void	removeFolderListener(FolderListener l) Removes a Folder event listener.
	String	toString() Retrieves the full name of the folder.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

SUBTREE

public static final int SUBTREE

Folder type, used in getType() and list(int type).

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.

DELETED

public static final int DELETED

Folder type, used in getType() and list(int type).

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.

INBOX

public static final int INBOX

Folder type, used in getType() and list(int type).

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.

OUTBOX

public static final int OUTBOX

Folder type, used in getType() and list(int type).

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.

SENT

public static final int SENT

Folder type, used in getType() and list(int type).

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.

OTHER

public static final int OTHER

Folder type, used in getType() and list(int type).

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.

ORPHAN

public static final int ORPHAN

Folder type, used in getType() and list(int type).

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.

INVALID

public static final int INVALID

Folder type, used in getType() and list(int type).

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.

FILED

public static final int FILED

Folder type, used in getType() and list(int type).

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.

UNFILED

public static final int UNFILED

Folder type, used in getType() and list(int type).

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.

SEPARATOR_CHAR

public static final char SEPARATOR_CHAR

Character that separates folders in a hierarchy.

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.

ROOT_SEPARATOR

public static final char ROOT_SEPARATOR

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

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.

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

INVALID_FOLDER_ID

public static final int INVALID_FOLDER_ID

An invalid folder id.

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.

NEW_FOLDER_NAME

public static String NEW_FOLDER_NAME

Default name for new folders.

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.

_store

protected Store _store

The Store that contains this Folder.

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

getName

public String getName()

Retrieves the name of this folder.

Returns:

Name of the Folder.

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.

getFullName

public String getFullName()

Retrieves the full name of this folder.

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

Returns:

Full name of the Folder.

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.

getStore

public Store getStore()

Retrieves the Store that owns this Folder object.

Returns:

Store that owns this Folder.

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.

getParent

public Folder getParent()

Retrieves the parent folder of this 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 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.

list

public Folder[] list()

Retrieves subfolders under this folder.

Returns:

Array of Folder objects that this folder contains, or an empty array if no folders are 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.

list

public Folder[] list(int type)

Retrieves the subfolders of a specified type under this folder.

Parameters:

the - type for which to search

Returns:

An array of Folder objects matching the specified type, or an empty array if no folders are present.

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.

getSeparator

public static char getSeparator()

Retrieves the delimiter character that separates subfolders.

Returns:

Delimiter character that separates folders in a path name.

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.

getType

public int getType()

Retrieves the type of this Folder.

Returns:

Type of folder.

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.

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 subfolder of this folder.

Returns:

A Folder object

Throws:

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

getMessages

public Message[] getMessages()
                      throws MessagingException

Retrieves an array that contains references to messages in this folder only, not in subfolders.

Returns:

An array of messages, or an empty array if no messages are contained within this folder.

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.

appendMessage

public boolean appendMessage(Message msg)

Saves a message to this folder. An appropriate FolderEvent is delivered to any FolderListener registered on this Folder when the message arrives in the Folder.

Parameters:

msg - The Message to save.

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.

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.

appendMessages

public boolean appendMessages(Message[] msgs)

Saves several messages to this folder. An appropriate FolderEvent is delivered to any FolderListener registered on this Folder when the messages arrive in the Folder.

Folder implementations must not abort this operation if a Message in the given message array turns out to be an expunged Message.

Parameters:

msgs - An array of Message objects.

Returns:

True if the messages are saved successfully, 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.

deleteMessage

public boolean deleteMessage(Message msg)

Deletes a message from this folder.

An appropriate FolderEvent is delivered to any FolderListener registered on this Folder when the message is removed from the Folder.

Parameters:

msg - The Message object to delete.

Returns:

True if the message is successfully deleted, otherwise false (false if for instance the message is not part of the specified folder)

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.

addFolderListener

public void addFolderListener(FolderListener l)

Adds a listener for folder events on this folder.

Parameters:

l - FolderListener to add to this Folder.

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.

removeFolderListener

public void removeFolderListener(FolderListener l)

Removes a Folder event listener. Should be called on the same Folder object on which addFolderListener(FolderListener l) was called.

Parameters:

l - FolderListener to add to this Folder.

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.

getId

public long getId()

Retrieves the internal ID of the folder.

Returns:

The folder ID, or Folder.INVALID_FOLDER_ID if the folder is invalid.

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 Folder objects refer to the same physical folder.

Overrides:

equals in class Object

Parameters:

f - The Folder object to compare to this folder.

Returns:

True if the two folders are equal, 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()

override to the basic Object method

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.

toString

public String toString()

Retrieves the full name of the folder. Overrides the default toString(). It returns the String from Folder.getFullName() or, if that is null, it uses the default toString() behavior.

Overrides:

toString in class Object

Returns:

The full name of the folder.

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.