javax.wireless.messaging
Interface MessageConnection

All Superinterfaces:

Connection

public interface MessageConnection
extends Connection

The MessageConnection interface defines the basic functionality for sending and receiving messages. It contains methods for sending and receiving messages, factory methods to create a new Message object, and a method that calculates the number of segments of the underlying protocol that are needed to send a specified Message object.

This class is instantiated by a call to Connector.open(String). An application SHOULD call Connection.close() when it is finished with the connection. An IOException is thrown when any method (except close()), which is declared to throw an IOException, is called on the MessageConnection after the connection has been closed.

Messages are sent on a connection. A connection can be defined as server mode or client mode.

In a client mode connection, messages can only be sent. A client mode connection is created by passing a string identifying a destination address to the Connector.open() method. This method returns a MessageConnection object.

In a server mode connection, messages can be sent or received. A server mode connection is created by passing a string that identifies an end point (protocol dependent identifier, for example, a port number) on the local host to the Connector.open() method. If the requested end point identifier is already reserved, either by some system application or by another Java application, Connector.open() throws an IOException. Java applications can open MessageConnection connections for any unreserved end point identifier, although security permissions might not allow it to send or receive messages using that end point identifier.

The scheme that identifies which protocol is used is specific to the given protocol. This interface does not assume any specific protocol and is intended for all wireless messaging protocols.

An application can have several MessageConnection instances open simultaneously; these connections can be both client and server mode.

The application can create a class that implements the MessageListener interface and register an instance of that class with the MessageConnection object(s) to be notified of incoming messages. With this technique, a thread does not have to be blocked, waiting to receive messages.

This interface is defined in JSR 205: Wireless Messaging API 2.0, which extends and enhances JSR 120: Wireless Messaging API

Since:

BlackBerry API 4.0.0

Field Summary
static String	BINARY_MESSAGE Constant for a message type for binary messages (value = “binary”).
static String	MULTIPART_MESSAGE Constant for a message type for multipart MIME messages (value = “multipart”).
static String	TEXT_MESSAGE Constant for a message type for text messages (value = “text”).

Method Summary
Message	newMessage(String type) Constructs a new message object of a given type.
Message	newMessage(String type, String address) Constructs a new Message object of a given type and initializes it with the given destination address.
int	numberOfSegments(Message msg) Returns the number of segments in the underlying protocol that would be needed for sending the specified Message.
Message	receive() Receives a message.
void	send(Message msg) Sends a message.
void	setMessageListener(MessageListener l) Registers a MessageListener object that the platform can notify when a message has been received on this MessageConnection.

Methods inherited from interface javax.microedition.io.Connection

close

Field Detail

BINARY_MESSAGE

static final String BINARY_MESSAGE

Constant for a message type for binary messages (value = “binary”). If this constant is used for the type parameter in the newMessage() methods, then the newly created Message will be an instance implementing the BinaryMessage interface.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

MULTIPART_MESSAGE

static final String MULTIPART_MESSAGE

Constant for a message type for multipart MIME messages (value = “multipart”). Using this constant as the type parameter in the newMessage() methods will cause the newly created Message to be an instance implementing the MultipartMessage interface.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0, WMA 2.0

TEXT_MESSAGE

static final String TEXT_MESSAGE

Constant for a message type for text messages (value = “text”). If this constant is used for the type parameter in the newMessage() methods, then the newly created Message will be an instance implementing the TextMessage interface.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Method Detail

newMessage

Message newMessage(String type)

Constructs a new message object of a given type. When the type TEXT_MESSAGE is passed in, the created object implements the TextMessage interface. When type BINARY_MESSAGE constant is passed in, the created object implements the BinaryMessage interface. When type MULTIPART_MESSAGE is passed in, the created object implements the MultipartMessage interface. Adapter definitions for messaging protocols can define new constants and new subinterfaces for the Messages. The type strings are case-sensitive. The parameter is compared with the String.equals(Object) method and does not need to be instance equivalent with the constants specified in this class.

For adapter definitions that are not defined within the JCP process, the strings used MUST begin with an inverted domain name controlled by the defining organization, as is used for Java package names. Strings that do not contain a full stop character "." are reserved for specifications done within the JCP process and MUST NOT be used by other organizations defining adapter specification.

When this method is called from a client mode connection, the newly created Message has the destination address set to the address identified when this Connection was created.

When this method is called from a server mode connection, the newly created Message does not have the destination address set. It must be set by the application before trying to send the message.

If the connection has been closed, this method still returns a Message instance.

Parameters:

type - the type of message to be created. There are constants for basic types defined in this interface.

Returns:

Message object for a given type of message.

Throws:

IllegalArgumentException - if the type parameters is not equal to the value of TEXT_MESSAGE, BINARY_MESSAGE, MULTIPART_MESSAGE, or any other type value specified in a private or publicly standardized adapter specification that is supported by the implementation

See Also:

MessageConnection.newMessage(String, String)

Since:

BlackBerry API 4.0.0

newMessage

Message newMessage(String type,
                   String address)

Constructs a new Message object of a given type and initializes it with the given destination address. The semantics related to the parameter type are the same as for the method signature with just the type parameter.

If the connection has been closed, this method still returns a Message instance.

Parameters:

type - the type of message to be created. There are constants for basic types defined in this interface.

address - destination address for the new message.

Returns:

Message object for a given type of message.

Throws:

IllegalArgumentException - if the type parameters is not equal to the value of TEXT_MESSAGE, BINARY_MESSAGE, MULTIPART_MESSAGE, or any other type value specified in a private or publicly standardized adapter specification that is supported by the implementation

See Also:

MessageConnection.newMessage(String)

Since:

BlackBerry API 4.0.0

numberOfSegments

int numberOfSegments(Message msg)

Returns the number of segments in the underlying protocol that would be needed for sending the specified Message.

Note that this method does not actually send the message. It will only calculate the number of protocol segments needed for sending the message.

This method will calculate the number of segments needed when this message is split into the protocol segments using the appropriate features of the underlying protocol. This method does not take into account possible limitations of the implementation that may limit the number of segments that can be sent using this feature. These limitations are protocol-specific and are documented with the adapter definition for that protocol.

If the connection has been closed, this method returns a count of the message segments that would be sent for the provided Message.

Parameters:

msg - the message to be used for the calculation.

Returns:

number of protocol segments needed for sending the message. Returns 0 (zero) if the Message object cannot be sent using the underlying protocol.

Since:

BlackBerry API 4.0.0

receive

Message receive()
                throws IOException,
                       InterruptedIOException

Receives a message.

If there are no messages for this MessageConnection waiting, this method will block until either a message for this Connection is received or the MessageConnection is closed.

Returns:

a Message object representing the information in the received message.

Throws:

IOException - if any of these situations occur:

• there is an error while receiving a message
• this method is called while the connection is closed
• this method is called on a client mode MessageConnection

InterruptedIOException - if this MessageConnection object is closed during this receive method call.

SecurityException - if the application does not have permission to receive messages using the given port number.

See Also:

MessageConnection.send(Message)

Since:

BlackBerry API 4.0.0

send

void send(Message msg)
          throws IOException,
                 InterruptedIOException

Sends a message.

Parameters:

msg - the message to be sent.

Throws:

IOException - if the message could not be sent due to a network failure or if the connection is closed.

IllegalArgumentException - if the message is incomplete or contains invalid information. This exception is also thrown if the payload of the message exceeds the maximum length for the given messaging protocol. One specific case when the message is considered to contain invalid information is if the Message is not of the right type to be sent using this MessageConnection; the Message should be created using the newMessage() method of the same MessageConnection instance as will be used for sending it to ensure that it is of the right type.

InterruptedIOException - if a timeout occurs while either trying to send the message or if this Connection object is closed during this send operation.

NullPointerException - if the parameter is null.

SecurityException - if the application does not have permission to send the message.

See Also:

MessageConnection.receive()

Since:

BlackBerry API 4.0.0

setMessageListener

void setMessageListener(MessageListener l)
                        throws IOException

Registers a MessageListener object that the platform can notify when a message has been received on this MessageConnection.

If there are incoming messages in the queue of this MessageConnection that have not been retrieved by the application prior to calling this method, the newly registered listener object will be notified immediately once for each such incoming message in the queue.

There can be at most one listener object registered for a MessageConnection object at any given point in time. Setting a new listener will de-register any previously-set listener.

Passing null as the parameter will de-register any currently registered listener.

Parameters:

l - MessageListener object to be registered. If null, any currently registered listener will be deregistered and will not receive notifications.

Throws:

SecurityException - if the application does not have permission to receive messages using the given port number.

IOException - if the connection has been closed, or if an attempt is made to register a listener on a client connection.

Since:

BlackBerry API 4.0.0