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 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 getSeparator().

You can retrieve a contained folder by name using getFolder, or a list of contained folders by using 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:
JDE 3.6.0

Field Summary
 Category: Signed static int DELETED
          A Folder containing deleted messages.
 Category: Signed static int DRAFT
          A Folder containing draft messages.
 Category: Signed static int FILED
          Contains items that are filed in a Folder.
 Category: Signed static int INBOX
          A Folder containing received messages.
 Category: Signed static int INVALID
          A Folder containing items marked as invalid.
 Category: Signed static int INVALID_FOLDER_ID
          Indicates an invalid folder ID.
 Category: Signed static String NEW_FOLDER_NAME
          Default name for new folders.
 Category: Signed static int ORPHAN
          A Folder containing items who's 'parent' has been deleted.
 Category: Signed static int OTHER
          A Folder that the user created - a personal folder.
 Category: Signed static int OUTBOX
          A Folder containing messages in the process of being sent.
 Category: Signed static char ROOT_SEPARATOR
          Character that separates the user's root folder from subfolders.
 Category: Signed static String ROOT_SEPARATOR_STRING
          String that separates the user's root folder from subfolders.
 Category: Signed static int SENT
          A Folder containing sent messages.
 Category: Signed static char SEPARATOR_CHAR
          Character that separates folders in a hierarchy.
 Category: Signed static int SUBTREE
          A Folder that is contained within another Folder.
 Category: Signed static int UNFILED
          Contains items that are not currently filed in a Folder.
 
Method Summary
 Category: Signed  void addFolderListener(FolderListener l)
          Adds a listener for folder events on this folder.
 Category: Signed  boolean appendMessage(Message msg)
          Saves a message to this folder.
 Category: Signed  boolean appendMessages(Message[] msgs)
          Saves several messages to this folder.
 Category: Signed  boolean deleteMessage(Message msg)
          Deletes a message from this folder.
 Category: Signed  boolean deleteMessage(Message msg, boolean forceDeleteSaved)
          Deletes a message from this folder.
 Category: Signed  boolean equals(Object o)
          Determines if an object refers to the same physical folder as this folder.
 Category: Signed  Message[] getDraftMessages(Message[] array)
          Retrieves draft messages from a list of messages.
 Category: Signed  Folder getFolder(String name)
          Retrieves the Folder object corresponding to the given name.
 Category: Signed  String getFullName()
          Retrieves this folder's full name.
 Category: Signed  long getId()
          Retrieves this folder's internal ID.
 Category: Signed  Message[] getMessages()
          Retrieves the messages contained in this folder.
 Category: Signed  String getName()
          Retrieves this folder's friendly name.
 Category: Signed  Folder getParent()
          Retrieves this folder's parent folder.
 Category: Signed static char getSeparator()
          Retrieves the delimiter character that separates sub-folders.
 Category: Signed  Store getStore()
          Retrieves the store containing this folder.
 Category: Signed  int getType()
          Retrieves this folder's type.
 Category: Signed  int hashCode()
          Retrieves a hash of this folder's ID.
 Category: Signed  Folder[] list()
          Retrieves this folder's sub-folders.
 Category: Signed  Folder[] list(int type)
          Retrieves this folder's sub-folders only of provided type.
 Category: Signed  void removeFolderListener(FolderListener l)
          Removes a folder-event listener.
 Category: Signed  String toString()
          Retrieves this folder's full name.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Field Detail


DELETED

public static final int DELETED
A Folder containing deleted messages. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

DRAFT

public static final int DRAFT
A Folder containing draft messages. This Folder type may be used in getType() and list(int).
Since:
JDE 4.1.0
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.

FILED

public static final int FILED
Contains items that are filed in a Folder. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

INBOX

public static final int INBOX
A Folder containing received messages. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

INVALID

public static final int INVALID
A Folder containing items marked as invalid. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

INVALID_FOLDER_ID

public static final int INVALID_FOLDER_ID
Indicates an invalid folder ID.
Since:
JDE 3.6.0
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.

NEW_FOLDER_NAME

public static String NEW_FOLDER_NAME
Default name for new folders.
Since:
JDE 3.6.0
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.

ORPHAN

public static final int ORPHAN
A Folder containing items who's 'parent' has been deleted. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

OTHER

public static final int OTHER
A Folder that the user created - a personal folder. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

OUTBOX

public static final int OUTBOX
A Folder containing messages in the process of being sent. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

ROOT_SEPARATOR

public static final char ROOT_SEPARATOR
Character that separates the user's root folder from subfolders.
Since:
JDE 3.6.0
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.

ROOT_SEPARATOR_STRING

public static String ROOT_SEPARATOR_STRING
String that separates the user's root folder from subfolders.
Since:
JDE 3.6.0
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.

SENT

public static final int SENT
A Folder containing sent messages. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

SEPARATOR_CHAR

public static final char SEPARATOR_CHAR
Character that separates folders in a hierarchy.
Since:
JDE 3.6.0
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.

SUBTREE

public static final int SUBTREE
A Folder that is contained within another Folder. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.

UNFILED

public static final int UNFILED
Contains items that are not currently filed in a Folder. This Folder type may be used in getType() and list(int).
Since:
JDE 3.6.0
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.
Method Detail

addFolderListener

public void addFolderListener(FolderListener l)
Adds a listener for folder events on this folder.
Parameters:
l - Listener to add to this folder.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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).
Since:
JDE 3.6.0
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.

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).
Since:
JDE 4.0.2
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 4.1.0
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

getId

public long getId()
Retrieves this folder's internal ID.
Returns:
This folder's ID, or INVALID_FOLDER_ID if this folder is invalid.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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).
Since:
JDE 3.6.0
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.

getSeparator

public static char getSeparator()
Retrieves the delimiter character that separates sub-folders.
Returns:
Delimiter character that separates folders in a path name.
Since:
JDE 3.6.0
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.

getStore

public Store getStore()
Retrieves the store containing this folder.
Returns:
Store that owns this folder.
Since:
JDE 3.6.0
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.

getType

public int getType()
Retrieves this folder's type.
Returns:
Type of this folder.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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 addFolderListener(net.rim.blackberry.api.mail.event.FolderListener).

Parameters:
l - Listener to remove from this folder.
Since:
JDE 3.6.0
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.

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 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.
Since:
JDE 3.6.0
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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.