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.