|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.blackberry.api.messagelist.ApplicationMessageFolder
public final class ApplicationMessageFolder
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.
| 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 | ||
|---|---|---|
|
void |
addListener(ApplicationMessageFolderListener listener)
Adds a folder listener for all the actions. |
|
void |
addListener(ApplicationMessageFolderListener listener,
int actions,
ApplicationDescriptor appDescr)
Adds a folder listener for specific actions only and with specified callback application. |
|
void |
fireElementAdded(ApplicationMessage appMsg)
Notifies the library that the collection was expaned with a new message. |
|
boolean |
fireElementRemoved(ApplicationMessage appMsg)
Notifies the library that a message was removed from the collection. |
|
void |
fireElementUpdated(ApplicationMessage oldAppMsg,
ApplicationMessage newAppMsg)
Notifies that existent message was updated in the collection. |
|
void |
fireReset()
Notifies that the corresponding collection has changed dramatically and should be re-initializded. |
|
long |
getId()
Returns folder ID assigned during registration |
|
ReadableList |
getMessages()
Returns all messages from this folder. |
|
String |
getName()
Returns folder name assigned during registration |
|
ApplicationMessageSearchProperties |
getSearchProperties()
Retrieves search properties for messages in this folder. |
|
void |
removeListener(ApplicationMessageFolderListener listener)
Removes folder listener |
|
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 |
|---|
public ReadableList getMessages()
public void addListener(ApplicationMessageFolderListener listener)
This is a shortcut method to the
ApplicationMessageFolder.addListener(ApplicationMessageFolderListener, int, ApplicationDescriptor)
with ApplicationDescriptor.currentApplicationDescriptor()
parameter value.
listener - listener to add
NullPointerException - If listener is null.
public void addListener(ApplicationMessageFolderListener listener,
int actions,
ApplicationDescriptor appDescr)
throws IllegalArgumentException
ApplicationMessageFolderListener can be used in bitwise OR
operation to define the target actions.
listener - listener to addactions - actions from ApplicationMessageFolderListener
interface packed by bitwise OR operationappDescr - pointer to the daemon application that will handle
listener callbacks
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 grouppublic void removeListener(ApplicationMessageFolderListener listener)
listener - listener to removepublic void fireElementAdded(ApplicationMessage appMsg)
appMsg - message that was added to the collection
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.public boolean fireElementRemoved(ApplicationMessage appMsg)
Object.equals(java.lang.Object) and Object.hashCode() must be implemented
for such case.
appMsg - message that was removed from the collection
NullPointerException - If appMsg is null.
public void fireElementUpdated(ApplicationMessage oldAppMsg,
ApplicationMessage newAppMsg)
throws IllegalArgumentException
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.
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.public void fireReset()
fireElementUpdated(ApplicationMessage oldAppMsg, ApplicationMessage newAppMsg),
fireElementAdded(ApplicationMessage appMsg), and fireElementRemoved(ApplicationMessage appMsg) methods
because it doesn't redraw elements until the whole process finishes.
public String getName()
public long getId()
public void setSearchProperties(ApplicationMessageSearchProperties props)
props - new search properties, if NULL is passed then defaults are
usedpublic ApplicationMessageSearchProperties getSearchProperties()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.