SHOW Signed
 

net.rim.blackberry.api.messagelist
Class ApplicationMessageFolder

java.lang.Object
  |
  +--net.rim.blackberry.api.messagelist.ApplicationMessageFolder

public final class ApplicationMessageFolder
extends Object

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 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:
JDE 4.6.0

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
 

Method Detail

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 addListener(ApplicationMessageFolderListener, int, ApplicationDescriptor) with ApplicationDescriptor.currentApplicationDescriptor() parameter value.

Parameters:
listener - listener to add
Since:
JDE 4.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.

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

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

fireElementRemoved

public boolean fireElementRemoved(ApplicationMessage appMsg)
                           throws IllegalArgumentException
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 equals() and 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
Since:
JDE 4.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.

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 oldElement 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 equals() and hashCode() must be implemented for such case.
Throws:
IllegalArgumentException - if no existent element found in the collection
Since:
JDE 4.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.

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 elementUpdated(), elementAdded() and elementRemoved() methods that it doesn't redraw elements until the whole process finishes.
Since:
JDE 4.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()
Returns folder ID assigned during registration
Returns:
folder ID
Since:
JDE 4.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 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
Since:
JDE 4.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()
Returns folder name assigned during registration
Returns:
folder name
Since:
JDE 4.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.

getSearchProperties

public ApplicationMessageSearchProperties getSearchProperties()
Retrieves search properties for messages in this folder.
Returns:
search properties for messages in this folder
Since:
JDE 4.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.

removeListener

public void removeListener(ApplicationMessageFolderListener listener)
Removes folder listener
Parameters:
listener - listener to remove
Returns:
true if listener was successfully removed, false otherwise
Since:
JDE 4.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.

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