back to

WMA 2.0 

This document is the API documentation for the Wireless Messaging API (WMA) 2.0.


javax.wireless.messaging Provides classes and interfaces as specified in the WMA 2.0 specification.


The messaging API is based on the Generic Connection Framework (GCF), which is defined in the Connected Limited Device Configuration (CLDC) 1.0 specification. The package defines the framework and supports input/output and networking functionality in J2ME profiles. It provides a coherent way to access and organize data in a resource-constrained environment.

The design of the messaging functionality is similar to the datagram functionality that is used for UDP in the Generic Connection Framework. Like the datagram functionality, messaging provides the notion of opening a connection based on a string address and that the connection can be opened in either client or server mode. However, there are differences between messages and datagrams, so messaging interfaces do not inherit from datagram. It might also be confusing to use the same interfaces for messages and datagrams.

The interfaces for the messaging API have been defined in the javax.wireless.messaging package.

Representation of a message

A message can be thought of as having an address part and a data part. A message is represented by a class that implements the interface defined for messages in the API. This interface provides methods that are common for all messages. In the javax.wireless.messaging package, the base interface that is implemented by all messages is named Message. It provides methods for addresses and timestamps.

For the data part of the message, the API is designed to handle text, binary and multipart messages. These are represented by three subinterfaces of Message: TextMessage, BinaryMessage and MultipartMessage. These subinterfaces provide ways to manipulate the payload of the message as Strings, byte arrays and message parts, respectively.

Other subinterfaces of Message can be defined for message payloads which are neither pure text nor pure binary. It is also possible to create further subinterfaces of TextMessage, BinaryMessage and MultipartMessage for possible protocol-specific features.

Sending and receiving messages

As defined by the Generic Connection Framework, the message sending and receiving functionality is implemented by a Connection interface, in this case, MessageConnection. To make a connection, the application obtains an object implementing the MessageConnection from the Connector class by providing a URL connection string that identifies the address.

If the application specifies a full destination address that defines a recipient to the Connector, it gets a MessageConnection that works in a "client" mode. This kind of Connection can only be used for sending messages to the address specified when creating it.

The application can create a "server" mode MessageConnection by providing a URL connection string that includes only an identifier that specifies the messages intended to be received by this application. Then it can use this MessageConnection object for receiving and sending messages.

The format of the URL connection string that identifies the address is specific to the messaging protocol used.

For sending messages, the MessageConnection object provides factory methods for creating Message objects. For receiving messages, the MessageConnection supports an event listener-based receiving mechanism, in addition to a synchronous blocking receive() method. The methods for sending and receiving messages can throw a SecurityException if the application does not have the permission to perform these operations.

The generic connection framework includes convenience methods for getting InputStream and OutputStream handles for connections which are StreamConnections. The MessageConnection does not support stream based operations. If an application calls the*Stream methods, it will receive an IllegalArgumentException.

Bearer-specific Adapter

The basic MessageConnection and Message framework provides a general mechanism with establishing a messaging application. The appendices describe the specific adapter requirements for URL connection string formatting and bearer-specific message handling requirements.

The appendices of this specification include the definition of SMS, CBS and MMS URL connection strings. These connection schemes MAY be reused in other adapter specifications, as long as the specified syntax is not modified and the usage does not overlap with these specified adapters (that is, no platform can be expected to implement two protocols for which the URI scheme would be the same, making it impossible for the platform to distinguish which is desired by the application). Other adapter specifications MAY define new connection schemes, as long as these do not conflict with any other connection scheme in use with the Generic Connection Framework.

The appendices describe how the SMS, CBS and MMS adpaters MUST be implemented to conform to the requirements of their specific wireless network environments and how these adapters supply the functionality defined in the javax.wireless.messaging package.

When a GSM SMS message connection is established, the platform MUST use the rules in Appendix A for the syntax of the URL connection string and for treatment of the message contents.

When a GSM CBS message connection is established, the platform MUST use the rules in Appendix B for the syntax of the URL connection string and for treatment of the message contents.

When a CDMA SMS message connection is established, the platform MUST use the rules in Appendix C for the syntax of the URL connection string and for treatment of the message contents.

When a MMS message connection is established, the platform MUST use the rules in Appendix D for the syntax of the URL connection string and for treatment of the message contents.


To send and receive messages using this API, applications MUST be granted a permission to perform the requested operation. The mechanisms for granting a permission are implementation dependent.

The permissions for sending and receiving MAY depend on the type of messages and addresses being used. An implementation MAY restrict an application's ability to send some types of messages and/or sending messages to certain recipient addresses. These addresses can include device addresses and/or identifiers, such as port numbers, within a device.

An implementation MAY restrict certain types of messages or connection addresses, such that the permission would never be available to an application on that device.

The applications MUST NOT assume that successfully sending one message implies that they have the permission to send all kinds of messages to all addresses.

An application should handle SecurityExceptions when a connection handle is provided from and for any message receive() or send() operation that potentially engages with the network or the privileged message storage on the device.

Permissions for MIDP 1.0 Platform

When the JSR 205 interfaces are deployed on a MIDP 1.0 device, there is no formal mechanism to identify how a permission to use a specific feature can be granted to a running application. On some systems, the decision to permit a particular operation is left in the hands of the end user. If the user decides to deny the required permission, then a SecurityException can be thrown from the, the MessageConnection.send(), or the MessageConnection.receive() method.

Permissions for MIDP 2.0 Platform

When the JSR 205 interfaces are deployed on a MIDP 2.0 device, permissions must be granted to open a connection and to send and receive messages. Separate permissions are provided for the SMS and CBS protocols.

To open a connection, a MIDlet suite must have the appropriate permission to access the MessageConnection implementation. If the permission is not granted, then must throw a SecurityException. To send and receive messages, the MIDlet suite can restrict certain types of messages or connection addresses. If the application attempts to send or receive either a restricted type of message or a message with a restricted connection address, then a SecurityException must be thrown.

For more information on the permissions that are provided by WMA 2.0, see Appendix E "Deploying JSR 205 Interfaces on a MIDP 2.0 Platform".

How to Use the Messaging API

This section provides some examples of how the messaging API can be used.

Sending a text message to an end user

The following sample code sends the string "Hello World!" to an end user as a normal SMS message.

try {
  String addr = "sms://+358401234567";
  MessageConnection conn = (MessageConnection);
  TextMessage msg =   
  msg.setPayloadText("Hello World!");
} catch (Exception e) {

A server that responds to received messages

The following sample code illustrates a server application that waits for messages sent to port 5432 and responds to them.

try {
  String addr = "sms://:5432";
  MessageConnection conn = (MessageConnection);
  Message msg = null;
  while (someExitCondition) {
  // wait for incoming messages
  msg = conn.receive();
  // received a message
  if (msg instanceof TextMessage) {
     TextMessage tmsg = (TextMessage)msg;
     String receivedText = tmsg.getPayloadText();
     // respond with the same text with "Received:" 
     // inserted in the beginning

     tmsg.setPayloadText("Received:" + receivedText);
     // Note that the recipient address in the	message is
     // already correct as we are reusing the same object
     } else {

     // Received message was not a text message, but e.g. binary
} catch (Exception e) {

Copyright (C) 2004 Siemens AG, Germany. All rights reserved. Use is subject to license terms.