net.rim.blackberry.api.mail
Class Store

java.lang.Object
  extended by net.rim.blackberry.api.mail.Service
      extended by 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
Category: Signed  void addFolderListener(FolderListener l)
          Adds a folder listener to this store.
Category: Signed  void addFolderListener(FolderListener l, ListenerInvocationProperties props)
          Adds a folder listener to this store and specifies how the listener should be invoked.
Category: Signed  void addSendListener(SendListener listener)
          Adds a SendListener to this Store.
Category: Signed  void addStoreListener(StoreListener l)
          Adds a store listener to this store.
Category: Signed  boolean equals(Object o)
          Compares another store object to this instance.
Category: Signed  Folder[] findFolder(String substring)
          Retrieves folders in this store that match the provided substring.
Category: Signed  Folder getFolder(String name)
          Retrieves a folder by name.
Category: Signed  Folder getFolder(long folderId)
          Retrieves a folder by ID.
Category: Signed static Message getMessage(int id)
          Retrieves a message by ID from all the stores in the system.
Category: Signed static Message getMessage(int id, ServiceRecord serviceRecord)
          Retrieves a message by ID associated with the provided ServiceRecord.
Category: Signed  int getUnreadMessageCount()
          Returns the number of unread message in the store.
Category: Signed  Folder[] list()
          Retrieves a list of folders directly under this Store.
Category: Signed  Folder[] list(int type)
          Retrieves the set of folders under this store that match provided type.
Category: Signed  void removeFolderListener(FolderListener l)
          Removes a folder listener from the root level.
Category: Signed  void removeSendListener(SendListener l)
          Removes a SendListener from the Store
Category: Signed  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.

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

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

addFolderListener

public void addFolderListener(FolderListener l,
                              ListenerInvocationProperties props)
Adds a folder listener to this store 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

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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal