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