|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Defines an application message interface which instances are stored in
ApplicationMessageFolder. Message can represent any communication
object, it can be an email message, a personal chat, public discussion, blog,
etc. The message has the following general attributes:
The contact, subject and time stamp are required attributes of message.
The contact attribute can be an email address, first and last name of the chat participant or name of the discussion group. It shouldn't be a very long string because most phones show only first 20 symbols of the contact field in the message list.
The subject attribute represents a short message description. It is also displayed in the message list of up to 20 symbols.
The timestamp attribute is used to sort messages in the message list. The oldest messages may be automatically deleted to save memory.
The optional type attribute is defined by an application and can be used to distinguish various messages. Type can represent a public chat, a private message, a group discussion. The type attribute is used to link message with its icon in the global list.
The optional status attribute define different states of the message. Common statuses are Open and Unopen, Replied, Current or Closed conversation. The status may also define a specific icon in the global message list. Status value is usually handled in bit-wise operations. For example, application may define three bit flags for the following statuses: Opened/Unopened, Replied, Active/Inactive. Each bit in the status may be set to indicate that message has corresponding property.
There is a list of pre-defined message statuses that are used by RIM internal
procedures. Currently these statuses are used in the message search and
message draw functions. Check the ApplicationMessage.Status interface for status values.
The lower 16 bits of the status value are reserved for internal RIM statuses
while application specific statuses should be placed in higher 16 bits in the
integer value. If application assigns the ApplicationMessage.Status.UNOPENED status to
its messages then they will be highlighted with bold font as new messages.
Application should register icons and context menu items for each possible
status combination. Refer to the ApplicationMessageFolderRegistry for
type and status registration methods. If, for instance, application supports
3 statuses - Open/Unopen, Replied/NotReplied, Current/Closed Conversation
then there will be 2 power 3 total 8 possible combinations. If some status
combinations are not supported by the application, e.g. both Unopen and
Replied in the same message then this status combination may be omitted.
Another optional attribute is preview text. Its value is used on message preview screens, for example, when user scrolls messages through Next&Previous buttons. Also, the value is subject for text searches, both global and message search.
Any updates on the message object should be followed by
ApplicationMessageFolder.fireElementAdded(ApplicationMessage) call.
This will notify the library about the changes and update corresponding
message element if currently displayed. If multiple messages were updated
then application should call ApplicationMessageFolder.fireReset() for
better performance.
All messages are kept in memory even if its application is not running. That is why it is best practice to keep the implementation objects as small as possible. The message values are cached in memory for faster access so it is allowed to use lazy initialization logic in the getXXX() methods.
Application may create new object instances of the same message for the
ApplicationMessageFolder.fireElementAdded(ApplicationMessage) and
ApplicationMessageFolder.fireReset() methods. However, in such case
it must implement the Object.equals(Object) and
Object.hashCode() object methods so that the correct element is
updated. The best practice is to have a message ID attribute and use its
value in the equals() method. Similarly, the
equals() method must return false for different messages,
otherwise updates operations may affect wrong elements.
| Inner Class Summary | ||
|
static interface |
ApplicationMessage.Status
Defines generic application message statuses that may be optionally supported by application. |
| Method Summary | ||
|
String |
getContact()
Returns string representation of the contact. |
|
Object |
getCookie(int cookieId)
Returns optional cookie value by its ID. |
|
Object |
getPreviewPicture()
Returns optional preview picture. |
|
String |
getPreviewText()
Returns optional preview text |
|
int |
getStatus()
Returns status of the message. |
|
String |
getSubject()
Returns subject |
|
long |
getTimestamp()
Returns message timestamp. |
|
int |
getType()
Returns type of the message. |
| Method Detail |
public String getContact()
public Object getCookie(int cookieId)
cookieId - ID of the cookiepublic Object getPreviewPicture()
public String getPreviewText()
public int getStatus()
public String getSubject()
public long getTimestamp()
public int getType()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.