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(). An application SHOULD call close() when it is finished with the connection. An IOException is thrown when any methods are 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 MessageConnections 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(s) to be notified of incoming messages. With this technique, a thread does not have to be blocked, waiting to receive messages.

A Sample Demonstrating SMS message Send Operation

// protocol and dialnumber
String url = "sms://+0123456xxx";

// Use generic connector interface to open MessageConnection
conn = (MessageConnection) Connector.open(url);

TextMessage tm = (TextMessage) conn.newMessage(MessageConnection.TEXT_MESSAGE);

tm.setPayloadText("Hello World!");

conn.send(tm);

Field Summary

static String	BINARY_MESSAGE Constant for a message type for binary messages (value = "binary").
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

TEXT_MESSAGE

public 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

BINARY_MESSAGE

public 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

Method Detail

newMessage

public Message newMessage(String type)

Constructs a new message object of a given type. When the string text is passed in, the created object implements the TextMessage interface. When the binary constant is passed in, the created object implements the BinaryMessage interface. Adapter definitions for messaging protocols can define new constants and new subinterfaces for the Messages. The type strings are case-sensitive.

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.

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 message type is not TEXT_MESSAGE or BINARY_MESSAGE

newMessage

public 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.

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 message type is not TEXT_MESSAGE or BINARY_MESSAGE

See Also:

newMessage(String type)

send

public 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 or because of network failure

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.

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:

receive()

receive

public 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 an error occurs while receiving a message

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:

send(Message)

setMessageListener

public 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 currenly registered listener.

Parameters:

l - MessageListener object to be registered. If null, any currently registered listener will be de-registered 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

numberOfSegments

public 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.

Parameters:

msg - the message to be used for the calculation

Returns:

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