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. The application messages will display in the global message list in the Messages application. Messages are not automatically persisted and it is an application's task to save them. Similarly, messages are not automatically purged on the Low Memory event.

The folder is initialized with a collection of messages, and message attributes are cached for faster access. If a message has changed, been added, or been removed from the underlying collection, the application should notify the 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's responsibility to perform any message persistence, backup/restore, and any other server synchronizations.

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

An application can register a folder listener to be notified on message list events. These include bulk operations performed on a range of messages such as bulk delete and mark opened. See 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 the application 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 the 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 a specified callback application.
Category: Signed  void fireElementAdded(ApplicationMessage appMsg)
          Notifies the folder that a new message has been added to the collection.
Category: Signed  void fireElementAdded(ApplicationMessage appMsg, boolean newMessage)
          Notifies the folder that a new message has been added to the collection.
Category: Signed  boolean fireElementRemoved(ApplicationMessage appMsg)
          Notifies the folder that a message was removed from the collection.
Category: Signed  void fireElementUpdated(ApplicationMessage oldAppMsg, ApplicationMessage newAppMsg)
          Notifies the folder that an existing message was updated in the collection.
Category: Signed  void fireReset()
          Notifies the folder that the associated collection has changed dramatically and should be re-initialized.
Category: Signed  void fireReset(boolean hasNewMessages)
          Similar to the ApplicationMessageFolder.fireReset() method but takes an extra parameter specifying whether the collection contains at least one new message.
Category: Signed  long getId()
          Returns the folder ID that was assigned during registration.
Category: Signed  ReadableList getMessages()
          Returns all messages from this folder.
Category: Signed  String getName()
          Returns the folder name that was assigned during registration.
Category: Signed  ApplicationMessageSearchProperties getSearchProperties()
          Returns search properties for messages in this folder.
Category: Signed  boolean hasNewMessages()
          Determines whether the folder contains messages that have never been seen by the user.
Category: Signed  void removeListener(ApplicationMessageFolderListener listener)
          Removes a 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 the current application descriptor.

This is a shortcut method to ApplicationMessageFolder.addListener(ApplicationMessageFolderListener, int, ApplicationDescriptor) for all actions, with ApplicationDescriptor.currentApplicationDescriptor() as the last 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 a specified callback application. Action codes from ApplicationMessageFolderListener can be used in a bitwise OR operation to define the target actions.

Parameters:
listener - Listener to add.
actions - Actions from the ApplicationMessageFolderListener interface combined using the bitwise OR operator.
appDescr - Pointer to the daemon application that will handle the listener callbacks.
Throws:
NullPointerException - if listener is null.
IllegalArgumentException - if actions equals 0 which means no actions to listen for, 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 a 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 folder that a new message has been added to the collection. Message attribute values are cached and the 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 this method 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

fireElementAdded

public void fireElementAdded(ApplicationMessage appMsg,
                             boolean newMessage)
Notifies the folder that a new message has been added to the collection. Message attribute values are cached and the corresponding message element is updated if currently visible.

This method takes a second parameter - newMessage - that defines whether the message was ever seen by the user. If newMessage is true, then the global message list will display the "new message" indicator on the Home screen. A message is considered "new" until the user opens the global message list, which displays partial message information such as the subject, contact name, and time. Note that this is not the same as the UNOPENED status, because the user might mark a message as unopened after viewing it.

Also, if you move a message from one application message folder to another, then the message will be re-added to the second folder and will, by default, be considered new. In this situation, you can set newMessage to false because the user is already aware of the message.

Parameters:
appMsg - Message that was added to the collection.
newMessage - If true this message is considered new and never seen by the user, if false the message is considered to have been seen.
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 this method 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 6.0.0

fireElementRemoved

public boolean fireElementRemoved(ApplicationMessage appMsg)
Notifies the folder that a message was removed from the collection. An application can give an object instance that doesn't belong to the collection, but it must be equal to the original element. You must implement Object.equals(java.lang.Object) and Object.hashCode() in this situation.

Parameters:
appMsg - Message that was removed from the collection.
Returns:
true if the message was removed from the 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 the folder that an existing message was updated in the collection. This method should be called to redraw the corresponding visual element if visible. The oldAppMsg parameter doesn't have to be the same object that was originally added to the collection, but it must be equal to the original element. You must implement Object.equals(java.lang.Object) and Object.hashCode() in this situation.

Parameters:
oldAppMsg - The original message.
newAppMsg - The updated message.
Throws:
IllegalArgumentException - if oldAppMsg is not 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 this method 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 the folder that the associated collection has changed dramatically and should be re-initialized. You should call this method in cases such as when the application retrieves bulk updates from a server or when the user tries to delete a number of messages. This method is preferable to a series of individual calls to ApplicationMessageFolder.fireElementUpdated(ApplicationMessage oldAppMsg, ApplicationMessage newAppMsg), ApplicationMessageFolder.fireElementAdded(ApplicationMessage appMsg), and ApplicationMessageFolder.fireElementRemoved(ApplicationMessage appMsg), 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

fireReset

public void fireReset(boolean hasNewMessages)
Similar to the ApplicationMessageFolder.fireReset() method but takes an extra parameter specifying whether the collection contains at least one new message.

Parameters:
hasNewMessages - If true the collection contains new message(s), if false all the messages in the collection have been seen by the user.
See Also:
ApplicationMessageFolder.fireElementAdded(ApplicationMessage, boolean), ApplicationMessageFolder.hasNewMessages()
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

hasNewMessages

public boolean hasNewMessages()
Determines whether the folder contains messages that have never been seen by the user. An application can also register a listener to be notified when the folder messages are opened in the global message list.

Returns:
true if the folder contains new messages not seen by the user, false otherwise.
See Also:
ApplicationMessageFolderListener.MESSAGES_MARKED_OLD
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

getName

public String getName()
Returns the folder name that was 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 the folder ID that was 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. Applications can disable any search functions on its folder by specifying corresponding search properties.

Parameters:
props - New search properties; if null, the 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()
Returns 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.