|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--net.rim.blackberry.api.messagelist.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 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.
| 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 |
| Method Detail |
public void addListener(ApplicationMessageFolderListener listener)
This is a shortcut method to the
addListener(ApplicationMessageFolderListener, int, ApplicationDescriptor)
with ApplicationDescriptor.currentApplicationDescriptor()
parameter value.
listener - listener to addpublic 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 callbacksIllegalArgumentException - 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 fireElementAdded(ApplicationMessage appMsg)
appMsg - message that was added to the collectionpublic boolean fireElementRemoved(ApplicationMessage appMsg) throws IllegalArgumentException
equals() and hashCode() must be implemented
for such case.appMsg - message that was removed from the collectionpublic void fireElementUpdated(ApplicationMessage oldAppMsg, ApplicationMessage newAppMsg) throws IllegalArgumentException
equals() and
hashCode() must be implemented for such case.IllegalArgumentException - if no existent element found in the collectionpublic void fireReset()
public long getId()
public ReadableList getMessages()
public String getName()
public ApplicationMessageSearchProperties getSearchProperties()
public void removeListener(ApplicationMessageFolderListener listener)
listener - listener to removepublic void setSearchProperties(ApplicationMessageSearchProperties props)
props - new search properties, if NULL is passed then defaults are
used
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2008 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.