net.rim.blackberry.api.messagelist.ApplicationMessageFolder
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public final class ApplicationMessageFolder
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:
fireElementAdded() - should be called when a new message was added to
the collectionfireElementRemoved() - should be called when a message was removed
from the collectionfireElementUpdated() - should be called when message attribute(s)
changedfireReset() - should be called when the collection changed dramatically
and should be reinitialized, for example on initial messages load or purging of
old messagesMessages 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.
| 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 a specified callback application. |
|
void |
fireElementAdded(ApplicationMessage appMsg)
Notifies the folder that a new message has been added to the collection. |
|
void |
fireElementAdded(ApplicationMessage appMsg,
boolean newMessage)
Notifies the folder that a new message has been added to the collection. |
|
boolean |
fireElementRemoved(ApplicationMessage appMsg)
Notifies the folder that a message was removed from the collection. |
|
void |
fireElementUpdated(ApplicationMessage oldAppMsg,
ApplicationMessage newAppMsg)
Notifies the folder that an existing message was updated in the collection. |
|
void |
fireReset()
Notifies the folder that the associated collection has changed dramatically and should be re-initialized. |
|
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. |
|
long |
getId()
Returns the folder ID that was assigned during registration. |
|
ReadableList |
getMessages()
Returns all messages from this folder. |
|
String |
getName()
Returns the folder name that was assigned during registration. |
|
ApplicationMessageSearchProperties |
getSearchProperties()
Returns search properties for messages in this folder. |
|
boolean |
hasNewMessages()
Determines whether the folder contains messages that have never been seen by the user. |
|
void |
removeListener(ApplicationMessageFolderListener listener)
Removes a 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
ApplicationMessageFolder.addListener(ApplicationMessageFolderListener, int, ApplicationDescriptor)
for all actions, with ApplicationDescriptor.currentApplicationDescriptor()
as the last 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 a bitwise OR
operation to define the target actions.
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.
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.public void removeListener(ApplicationMessageFolderListener listener)
listener - Listener to remove.public 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 this method
and as a result the message list will remain unchanged.
public void fireElementAdded(ApplicationMessage appMsg,
boolean newMessage)
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.
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.
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.
public boolean fireElementRemoved(ApplicationMessage appMsg)
Object.equals(java.lang.Object) and Object.hashCode()
in this situation.
appMsg - Message that was removed from the collection.
true if the message was removed from the folder, false otherwise.
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, but it must be equal to the
original element. You must implement Object.equals(java.lang.Object) and
Object.hashCode() in this situation.
oldAppMsg - The original message.newAppMsg - The updated message.
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.
public void fireReset()
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.
public void fireReset(boolean hasNewMessages)
ApplicationMessageFolder.fireReset() method but takes an extra parameter specifying whether the collection contains at least
one new message.
hasNewMessages - If true the collection contains new message(s),
if false all the messages in the collection have been seen by the user.ApplicationMessageFolder.fireElementAdded(ApplicationMessage, boolean),
ApplicationMessageFolder.hasNewMessages()public boolean hasNewMessages()
true if the folder contains new messages not seen by the user, false otherwise.ApplicationMessageFolderListener.MESSAGES_MARKED_OLDpublic String getName()
public long getId()
public void setSearchProperties(ApplicationMessageSearchProperties props)
props - New search properties; if null, the defaults are
used.public 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.