net.rim.blackberry.api.messagelist
Class ApplicationMessageFolder

java.lang.Object
  extended by net.rim.blackberry.api.messagelist.ApplicationMessageFolder
All Implemented Interfaces:
PersistentContentListener

public final class ApplicationMessageFolder
extends Object
implements PersistentContentListener

Folder to store application messages. Folder messages will appear in the global message list. Messages are not automatically persisted and it is an application task to save them. Similarly, messages are not automatically purged on Low Memory event.

Folder is initialized with a collection of messages and message attributes are cached for faster access. If a message has changed, added or removed from underlying collection then application should notify message folder about the change. This is achieved through one of the following methods:

Messages from the collection are always kept in memory until the application is uninstalled. The collection should be treated as a singleton object. It is an application responsibility to perform any message persistence, backup/restore and any other server synchronizations.

Application must not change its collection during the ApplicationMessageFolder.fireReset() and other fireXXX method calls. If application accesses the collection in multithreaded fashion then it must lock until the fireXXX call finishes.

Application can register folder listener to be notified on message list events. These include bulk operations performed on range of messages such as bulk delete and mark opened. Check ApplicationMessageFolderListener for more actions. The callback operation will be performed in the application environment. If the application is not running at the time a message action is performed then it will be started automatically. One of the listener registration methods accepts an ApplicationDescriptor parameter that points to the application to run the callback in. It is a best practice to have a running daemon process that performs all the callback notifications and message context menu logic.

Applications are responsible for purging their stale messages on Low Memory Event. This logic is applicable to standard email and phone 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.6.0

Field Summary
 
Fields inherited from interface net.rim.device.api.system.PersistentContentListener
PERSISTENT_CONTENT_LOCKED_INSECURE, PERSISTENT_CONTENT_LOCKED_SECURE, PERSISTENT_CONTENT_LOCKING, PERSISTENT_CONTENT_UNLOCKED
 
Method Summary
Category: Signed  void addListener(ApplicationMessageFolderListener listener)
          Adds a folder listener for all the actions.
Category: Signed  void addListener(ApplicationMessageFolderListener listener, int actions, ApplicationDescriptor appDescr)
          Adds a folder listener for specific actions only and with specified callback application.
Category: Signed  void fireElementAdded(ApplicationMessage appMsg)
          Notifies the library that the collection was expaned with a new message.
Category: Signed  boolean fireElementRemoved(ApplicationMessage appMsg)
          Notifies the library that a message was removed from the collection.
Category: Signed  void fireElementUpdated(ApplicationMessage oldAppMsg, ApplicationMessage newAppMsg)
          Notifies that existent message was updated in the collection.
Category: Signed  void fireReset()
          Notifies that the corresponding collection has changed dramatically and should be re-initializded.
Category: Signed  long getId()
          Returns folder ID assigned during registration
Category: Signed  ReadableList getMessages()
          Returns all messages from this folder.
Category: Signed  String getName()
          Returns folder name assigned during registration
Category: Signed  ApplicationMessageSearchProperties getSearchProperties()
          Retrieves search properties for messages in this folder.
Category: Signed  void removeListener(ApplicationMessageFolderListener listener)
          Removes folder listener
Category: Signed  void setSearchProperties(ApplicationMessageSearchProperties props)
          Assigns search properties for messages in this folder.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface net.rim.device.api.system.PersistentContentListener
persistentContentModeChanged, persistentContentStateChanged
 



Method Detail

getMessages

public ReadableList getMessages()
Returns all messages from this folder. Note that any calls to add or remove elements from the folder after this method call will not affect the returned enumeration.

Returns:
enumeration of messages at the point of execution
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.6.0

addListener

public void addListener(ApplicationMessageFolderListener listener)
Adds a folder listener for all the actions. Callback notifications will be performed in the current application based on current application descriptor.

This is a shortcut method to the ApplicationMessageFolder.addListener(ApplicationMessageFolderListener, int, ApplicationDescriptor) with ApplicationDescriptor.currentApplicationDescriptor() parameter value.

Parameters:
listener - listener to add
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.6.0

addListener

public void addListener(ApplicationMessageFolderListener listener,
                        int actions,
                        ApplicationDescriptor appDescr)
                 throws IllegalArgumentException
Adds a folder listener for specific actions only and with specified callback application. Action codes from ApplicationMessageFolderListener can be used in bitwise OR operation to define the target actions.

Parameters:
listener - listener to add
actions - actions from ApplicationMessageFolderListener interface packed by bitwise OR operation
appDescr - pointer to the daemon application that will handle listener callbacks
Throws:
NullPointerException - If listener is null.
IllegalArgumentException - if actions value is equal to 0 which means no actions to subscribe to OR if appDescr points to an application from another module group
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.6.0

removeListener

public void removeListener(ApplicationMessageFolderListener listener)
Removes folder listener

Parameters:
listener - listener to remove
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.6.0

fireElementAdded

public void fireElementAdded(ApplicationMessage appMsg)
Notifies the library that the collection was expaned with a new message. Message attributes values are cached and corresponding message element is updated if currently visible.

Parameters:
appMsg - message that was added to the collection
Throws:
NullPointerException - If appMsg is null. Also, any exception caught from the calls to any of the get methods in ApplicationMessage will be passed on to fireElementAdded and as a result the message list will remain unchanged.
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.6.0

fireElementRemoved

public boolean fireElementRemoved(ApplicationMessage appMsg)
Notifies the library that a message was removed from the collection. An application may give an object instance that doesn't belong to the collection but then it must be equal to the original element. The methods Object.equals(java.lang.Object) and Object.hashCode() must be implemented for such case.

Parameters:
appMsg - message that was removed from the collection
Returns:
true if message was removed from folder, false otherwise
Throws:
NullPointerException - If appMsg 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.6.0

fireElementUpdated

public void fireElementUpdated(ApplicationMessage oldAppMsg,
                               ApplicationMessage newAppMsg)
                        throws IllegalArgumentException
Notifies that existent message was updated in the collection. This method should be called to redraw corresponding visual element if visible. The oldAppMsg parameter doesn't have to be the same object that was originally added to the collection, however, it must be equal to the original element. The methods Object.equals(java.lang.Object) and Object.hashCode() must be implemented for such case.

Throws:
IllegalArgumentException - if no existent element found in the collection
NullPointerException - If oldAppMsg is null, or newAppMsg is null. Also, any exception caught from the calls to any of the get methods in ApplicationMessage will be passed on to fireElementUpdated and as a result the message list will remain unchanged.
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.6.0

fireReset

public void fireReset()
Notifies that the corresponding collection has changed dramatically and should be re-initializded. This method should be called in such cases when application retrieves a bulk of updates from server or user tries to delete number of existent messages. The method has advantage over the individual fireElementUpdated(ApplicationMessage oldAppMsg, ApplicationMessage newAppMsg), fireElementAdded(ApplicationMessage appMsg), and fireElementRemoved(ApplicationMessage appMsg) methods because it doesn't redraw elements until the whole process finishes.

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

getName

public String getName()
Returns folder name assigned during registration

Returns:
folder 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 4.6.0

getId

public long getId()
Returns folder ID assigned during registration

Returns:
folder 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 4.6.0

setSearchProperties

public void setSearchProperties(ApplicationMessageSearchProperties props)
Assigns search properties for messages in this folder. By default folder messages are subject to all search operations by all the message attributes. Application may disable any search functions on its folder by specifying corresponding search properties.

Parameters:
props - new search properties, if NULL is passed then defaults are used
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.6.0

getSearchProperties

public ApplicationMessageSearchProperties getSearchProperties()
Retrieves search properties for messages in this folder.

Returns:
search properties for messages 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.6.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.