net.rim.blackberry.api.messagelist
Interface ApplicationMessage


public interface ApplicationMessage

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.

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

Nested Class Summary
Category: Signed static interface ApplicationMessage.Status
          Defines generic application message statuses that may be optionally supported by application.
 
Method Summary
Category: Signed  String getContact()
          Returns string representation of the contact.
Category: Signed  Object getCookie(int cookieId)
          Returns optional cookie value by its ID.
Category: Signed  Object getPreviewPicture()
          Returns optional preview picture.
Category: Signed  String getPreviewText()
          Returns optional preview text
Category: Signed  int getStatus()
          Returns status of the message.
Category: Signed  String getSubject()
          Returns subject
Category: Signed  long getTimestamp()
          Returns message timestamp.
Category: Signed  int getType()
          Returns type of the message.
 



Method Detail

getType

int getType()
Returns type of the message. The type and status attributes define group of messages that share the same icon and menu items.

Returns:
message type
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

getStatus

int getStatus()
Returns status of the message. The type and status attributes define group of messages that share the same icon and menu items.

Returns:
message status
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

getContact

String getContact()
Returns string representation of the contact.

Returns:
contact
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

getSubject

String getSubject()
Returns subject

Returns:
subject
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

getPreviewText

String getPreviewText()
Returns optional preview text

Returns:
preview text if defined, null otherwise
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

getPreviewPicture

Object getPreviewPicture()
Returns optional preview picture. This is for future use.

Returns:
preview picture if provided by the message, null otherwise
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

getCookie

Object getCookie(int cookieId)
Returns optional cookie value by its ID. This is for future use.

Parameters:
cookieId - ID of the cookie
Returns:
cookie value if provided by the message, null otherwise
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

getTimestamp

long getTimestamp()
Returns message timestamp. Messages are sorted in most graphical representations from the most recent to the oldest.

Returns:
non-zero timestamp
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.