SHOW Signed
 

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:
JDE 4.6.0

Inner 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

getContact

public String getContact()
Returns string representation of the contact.
Returns:
contact
Since:
JDE 4.6.0
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.

getCookie

public 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
Since:
JDE 4.6.0
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.

getPreviewPicture

public Object getPreviewPicture()
Returns optional preview picture. This is for future use.
Returns:
preview picture if provided by the message, null otherwise
Since:
JDE 4.6.0
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.

getPreviewText

public String getPreviewText()
Returns optional preview text
Returns:
preview text if defined, null otherwise
Since:
JDE 4.6.0
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.

getStatus

public 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
Since:
JDE 4.6.0
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.

getSubject

public String getSubject()
Returns subject
Returns:
subject
Since:
JDE 4.6.0
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.

getTimestamp

public long getTimestamp()
Returns message timestamp. Messages are sorted in most graphical representations from the most recent to the oldest.
Returns:
non-zero timestamp
Since:
JDE 4.6.0
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.

getType

public 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
Since:
JDE 4.6.0
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.



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.