net.rim.blackberry.api.mail
Class Store

java.lang.Object
  net.rim.blackberry.api.mail.Service
      net.rim.blackberry.api.mail.Store

public abstract class Store
extends Service

Represents a message store and its access protocol, for storing and retrieving messages on the handheld.

Invoke Session.getStore() to retrieve a Store instance.

See Also:

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

Method Summary
	void	addFolderListener(FolderListener l) Adds a folder listener to this store.
	void	addSendListener(SendListener listener) Adds a SendListener to this Store.
	void	addStoreListener(StoreListener l) Adds a store listener to this store.
	boolean	equals(Object o) Compares another store object to this instance.
	Folder[]	findFolder(String substring) Retrieves folders in this store that match the provided substring.
	Folder	getFolder(String name) Retrieves a folder by name.
	Folder	getFolder(long folderId) Retrieves a folder by ID.
	static Message	getMessage(int id) Retrieves a message by ID from all the stores in the system.
	static Message	getMessage(int id, ServiceRecord serviceRecord) Retrieves a message by ID associated with the provided ServiceRecord.
	int	getUnreadMessageCount() Returns the number of unread message in the store.
	Folder[]	list() Retrieves a list of folders directly under this Store.
	Folder[]	list(int type) Retrieves the set of folders under this store that match provided type.
	void	removeFolderListener(FolderListener l) Removes a folder listener from the root level.
	void	removeSendListener(SendListener l) Removes a SendListener from the Store
	void	removeStoreListener(StoreListener l) Removes a store listener from this store.

Methods inherited from class net.rim.blackberry.api.mail.Service

addServiceListener, getServiceConfiguration, isConnected, removeServiceListener, setConnected, toString

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

list

public Folder[] list(int type)

Retrieves the set of folders under this store that match provided type.

Note that this method iterates over all sub-folders of the given Store to find those that match type criteria.

Parameters:

type - Type of folder(s) to retrieve.

Returns:

List of folders matching your type, or an empty array if no folders match your type.

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(long folderId)
                 throws FolderNotFoundException

Retrieves a folder by ID.

Parameters:

folderId - ID of the folder to retrieve.

Returns:

Folder with provided ID.

Throws:

FolderNotFoundException - If no folder exists with provided ID.

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 a folder by name.

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

• /
• :
• \

Parameters:

name - Name of the folder to retrieve. The name must be an absolute path, starting with the hierarchy delimiter, but not ending with the delimiter. For example, "/abc/efg" is correct, where abc is a direct subfolder of this Store.

Returns:

Folder with provided absolute name.

Throws:

FolderNotFoundException - If no folder exists with provided 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

findFolder

public Folder[] findFolder(String substring)

Retrieves folders in this store that match the provided substring.

Parameters:

substring - Substring to match against folder names.

Returns:

List of folders in this store with names matching the provided substring, or an empty array if no folders exist that match.

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 a list of folders directly under this Store.

Returns:

An array of Folder objects or an empty array if no folders are 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

addFolderListener

public void addFolderListener(FolderListener l)

Adds a folder listener to this store.

The listener is invoked when FolderEvents occur on any folder in the store.

Parameters:

l - The FolderListener to add to this Store.

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 listener from the root level.

Parameters:

l - The FolderListener to remove from this Store.

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

addStoreListener

public void addStoreListener(StoreListener l)

Adds a store listener to this store.

Parameters:

l - StoreListener to add to this Store.

Throws:

NullPointerException - if l is null.

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

removeStoreListener

public void removeStoreListener(StoreListener l)

Removes a store listener from this store.

Parameters:

l - StoreListener to remove from this Store.

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)

Compares another store object to this instance.

Store instances are equal if they are represented by the same ServiceConfiguration object.

Overrides:

equals in class Object

Parameters:

o - The object to compare this store to.

Returns:

true if this object is the same as the obj argument; false otherwise.

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 4.0.0

getMessage

public static Message getMessage(int id)

Retrieves a message by ID from all the stores in the system.

Parameters:

id - ID for the message to retrieve.

Returns:

Message associated with your ID, or null if no such message exists or if your ID is 0.

Throws:

ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device.

See Also:

Message.getMessageId()

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

getMessage

public static Message getMessage(int id,
                                 ServiceRecord serviceRecord)

Retrieves a message by ID associated with the provided ServiceRecord.

Parameters:

id - ID for the message to retrieve.

serviceRecord - ServiceRecord for the email service to search in.

Returns:

Message associated with the id and serviceRecord, or null if no such message exists or if the id is 0.

Throws:

ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device.

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 6.0.0

addSendListener

public void addSendListener(SendListener listener)

Adds a SendListener to this Store. This listener is invoked before a message is sent

Parameters:

listener - The SendListener to add to this Store

Throws:

NullPointerException - If listener is null

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

removeSendListener

public void removeSendListener(SendListener l)

Removes a SendListener from the Store

Parameters:

l - The SendListener to remove from this Store.

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

getUnreadMessageCount

public int getUnreadMessageCount()

Returns the number of unread message in the store.

Returns:

The number of unread 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.2.1