net.rim.device.api.io.messaging
Interface Message

All Known Subinterfaces:
ByteMessage, StreamMessage

public interface Message

Contains data sent or received via the Messaging API. In addition to main payload, metadata are provided in the form of headers and other special fields.

For efficiency, Message implementations normally keep a reference to the data they contain instead of a copy. Once a Message has been submitted to a Destination, it is locked and read-only. Attempts to modify the contents of the Message result in an exception being thrown.

Since:
BlackBerry API 6.0.0

Field Summary
static int PRIORITY_MAX
          Maximum priority value for the message queued.
static int PRIORITY_MIN
          Minimum priority value for the message queued.
 
Method Summary
 void cancel()
          Tries to cancel the message.
 int getCorrelatedMessageId()
          Returns the message ID.
 int getMessageId()
          Returns the ID of the message
 String getMessageProperty(String key)
          Returns the value of a message property by name.
 Object getObjectPayload()
          Returns an object reference to the body of the message.
 int getPriority()
          Returns the priority value of this message.
 String getTransportHeader(String key)
          Returns the value of the transport header specified.
 Headers getTransportHeaders()
          Returns all transport headers.
 String[] getTransportHeadersForKey(String key)
          Returns the values of transport header specified.
 boolean isCancellable()
          Indicates whether or not this message can be cancelled.
 void setCancellable(boolean cancellable)
          Configures the message so that it can be cancelled.
 void setMessageProperty(String key, String value)
          Sets a given message property.
 void setPriority(int priority)
          Sets the priority of this message.
 void setTTL(int ttl)
          Sets the Time-to-Live (TTL) for this message.
 void setTransportHeader(String key, String value)
          Sets a transport header to the value specified.
 void setTransportHeader(String key, String[] values)
          Sets a transport header to the set of values specified.
 void setTransportHeaders(Headers headers)
          Sets all transport headers.
 



Field Detail

PRIORITY_MAX

static final int PRIORITY_MAX
Maximum priority value for the message queued.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_MIN

static final int PRIORITY_MIN
Minimum priority value for the message queued.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Method Detail

getMessageId

int getMessageId()
Returns the ID of the message

Returns:
int ID of the message
Since:
BlackBerry API 6.0.0

getObjectPayload

Object getObjectPayload()
Returns an object reference to the body of the message.

Returns:
An Object representation of this Message.
Since:
BlackBerry API 6.0.0

setMessageProperty

void setMessageProperty(String key,
                        String value)
                        throws MessageModificationException
Sets a given message property. Property names are currently undefined.

Parameters:
key - Name of the property.
value - Value of the property.
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.0

getMessageProperty

String getMessageProperty(String key)
Returns the value of a message property by name. Property names are currently undefined.

Parameters:
key - Name of the property.
Returns:
Value of the message property.
Since:
BlackBerry API 6.0.0

setTransportHeader

void setTransportHeader(String key,
                        String value)
                        throws MessageModificationException
Sets a transport header to the value specified.

Parameters:
key - Name of the transport header
value - Value of the transport header
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.0

setTransportHeader

void setTransportHeader(String key,
                        String[] values)
                        throws MessageModificationException
Sets a transport header to the set of values specified.

Parameters:
key - Name of the transport header.
values - Array of values for the transport header.
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.0

getTransportHeader

String getTransportHeader(String key)
Returns the value of the transport header specified.

Parameters:
key - Name of the transport header.
Returns:
The value of the transport header. If multiple values exist for the transport header, then only the first will be returned.
Since:
BlackBerry API 6.0.0

getTransportHeadersForKey

String[] getTransportHeadersForKey(String key)
Returns the values of transport header specified.

Parameters:
key - Name of the transport header.
Returns:
Array of values for the transport header.
Since:
BlackBerry API 6.0.0

getTransportHeaders

Headers getTransportHeaders()
Returns all transport headers.

Returns:
Headers object containing all transport headers.
Since:
BlackBerry API 6.0.0

setTransportHeaders

void setTransportHeaders(Headers headers)
                         throws MessageModificationException
Sets all transport headers.

Parameters:
headers - Headers object containing all transport headers.
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.0

cancel

void cancel()
Tries to cancel the message.

Since:
BlackBerry API 6.0.0

setCancellable

void setCancellable(boolean cancellable)
                    throws MessageModificationException
Configures the message so that it can be cancelled.

Parameters:
cancellable - The value to use with this message.
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.0

isCancellable

boolean isCancellable()
Indicates whether or not this message can be cancelled.

Returns:
cancellable state
Since:
BlackBerry API 6.0.0

setPriority

void setPriority(int priority)
                 throws MessageModificationException
Sets the priority of this message.

Parameters:
priority - An integer from PRIORITY_MIN to PRIORITY_MAX where PRIORITY_MIN is the lowest priority.
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.0

getPriority

int getPriority()
Returns the priority value of this message.

Returns:
An integer from PRIORITY_MIN to PRIORITY_MAX where PRIORITY_MIN is the lowest priority.
Since:
BlackBerry API 6.0.0

getCorrelatedMessageId

int getCorrelatedMessageId()
Returns the message ID. In a request-response scenario, the ID of the response will be the same as the request. If this message is a failure response message, the ID will reference the message for which delivery failed.

Returns:
The message ID.
Since:
BlackBerry API 6.0.0

setTTL

void setTTL(int ttl)
            throws MessageModificationException
Sets the Time-to-Live (TTL) for this message.

Parameters:
ttl - The Time-to-Live value.
Throws:
MessageModificationException
Since:
BlackBerry API 6.0.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.