|
Wireless Messaging API
This package defines an API which
allows applications to send and receive wireless
messages. The API is generic and independent of the
underlying messaging protocol. The underlying protocol
can be, for example, GSM Short Message Service, CDMA SMS, and so on.
Overview
This package is designed to work with Message objects that may
contain different elements depending on the underlying
messaging protocol. This is different from Datagrams that are
assumed always to be blocks of binary data.
An adapter specification for a given messaging protocol may define
further interfaces derived from the Message interfaces included in
this generic specification.
Unlike network layer
datagrams, the wireless messaging protocols that are accessed by using
this API are typically of store-and-forward nature. Messages will usually
reach the recipient,
even if the recipient is not connected at the time of sending. This may
happen significantly later if the
recipient is disconnected for a long period of time. Sending and possibly
also receiving these wireless messages typically involves a
financial cost to the end user that cannot be neglected. Therefore,
applications should not send unnecessary messages.
The MessageConnection and Message Interfaces
The MessageConnection interface represents a
Connection that can be used for sending and receiving
messages. The application opens a MessageConnection
with the Generic Connection Framework by providing a URL
connection string.
The MessageConnection can be opened either in
"server" or in "client" mode. A "server" mode connection is
opened by providing a URL that specifies an identifier for
an application on the local device for incoming messages. A port number
is an example of an identifier.
Messages received with this identifier will then be
delivered to the application by using this connection.
A "server" mode connection can be used both for sending and
for receiving messages.
A "client" mode connection
is opened by providing a URL that points to another device. A "client"
mode connection can only be used for sending messages.
The messages are represented by the Message interface
and interfaces derived from it. The Message interface
has the very basic functions that are common to all messages.
Derived interfaces represent messages of different types and provide
methods for accessing type-specific features. The kinds of derived
interfaces that are supported depends on the
underlying messaging protocol. If necessary, interfaces derived
from Message can be defined in the adapter definitions
for mapping the API to an underlying protocol.
The mechanism to derive new interfaces from the
Message is intended
as an extensibility mechanism allowing new protocols to be supported
in platforms. Applications are not expected to create their own
classes that implement the
Message interface. The only correct way for
applications to create object instances implementing the
Message
interface is to use the MessageConnection.newMessage
factory method.
BinaryMessage and TextMessage are
subinterfaces of Message
representing binary and text messages. They have methods to get and set the
binary/text data payloads. To create instances of these classes, use the
MessageConnection.newMessage factory method, using
MessageConnection.BINARY_MESSAGE or
MessageConnection.TEXT_MESSAGE for the message type.
The MessageListener interface provides a mechanism for
the application to be notified of incoming messages. The listener
mechanism allows applications to receive incoming messages without
needing to have a thread blocked in the receive() method call.
|