JSR 120

Introduction

Wireless Messaging API (WMA) is an optional package based on the Generic Connection Framework (GCF)

It supports Java 2 Platform, Mobile Edition (J2ME) applications targeted at cell phones and other devices that can send and receive wireless messages

The design of the messaging functionality is similar to datagram functionality that is used for UDP in the Generic Connection Framework

The WMA provides a common interface you can use to enable an application based on the Mobile Information Device Profile (MIDP) to send and receive short text and binary messages

Check WMA API

To determine if the optional WMA API is available and which version is available you have to call:

String currentVersion = System.getProperty(“javax.wireless.messaging”)

If the WMA API is available a string with the version will be returned (eg: “1.0”)

If the WMA API is not available a null value is returned

Interfaces Description

Message Base Message interface, from which subinterfaces (such as TextMessage and BinaryMessage) are derived

BinaryMessage Subinterface of Message that provides methods to set and get the binary payload

TextMessage Subinterface of Message that provides methods to set and get the text payload

MessageConnection Subinterface of the GCF Connection, which provides a factory of Messages, and methods to send and receive Messages

MessageListener Defines the listener interface to implement asynchronous notification of Message objects

WMA 1.0 Package

All WMA-specific interfaces and classes are contained in a single package, javax.wireless.messaging, which defines all the APIs required for sending and receiving wireless text, binary

WMA 1.0 Overview

The J2ME Wireless Messaging API (WMA) specifies a standard set of APIs

that J2ME applications running on SMS-enabled devices can use to

communicate with network peers via the SMS and CBS protocols

WMA API Overview

The interface javax.wireless.messaging.Message is the base for all types of messages communicated using the WMA

In some respects, a Message looks similar to a Datagram: it has source and destination addresses, a payload, and ways to send and block for a message

WMA provides Listener for receiving text and binary message

A MessageConnection can be created in one of two modes: as a client connection or as a server connection

In a client mode connection, messages can only be sent and the URL for a client connection includes a destination address, as in

MessageConnection clientConn = (MessageConnection)Connector.open("sms:// +18643630999:5000");

In a server mode connection, messages can be sent or received and the URL for a server connection specifies a local address, as in

serverConn = (MessageConnection)Connector.open("sms://:5000");

Trying to bind to an already reserved local address causes an IOException to be thrown.

Message Connection and Its Relationship to GCF

WMA API Overview

The URL scheme for creating a MessageConnection is not specific to a single protocol instead it is intended to support many wireless protocols

The WMA specification defines the following protocol adapters:

"sms" for Short Messaging System. SMS is bi-directional: you can create, send, and receive messages (and thus support both client and server connections).

"cbs" for Cell Broadcast Short Message. CBS messages are broadcast by a base station, and can only be received. Attempting to send on a cbs connection results in an IOException.

How To Send A Text Message

Destination address with telephone number and port numberString addr = “sms://+358401234567:1234”;

A client mode connection is created by passing a string identifying a destination address to the Connector.open() method. This method returns a MessageConnection MessageConnection conn = (MessageConnection)Connector.open(addr);

String constant TEXT_MESSAGE of MessageConnection class is passed to the newMessage() factory method TextMessage msg =(TextMessage)conn.newMessage(MessageConnection.TEXT_MESSAGE);

The message is passed as parameter in setPayloadText() of TextMessagemsg.setPayloadText(“Hello World!”);

Now pass TextMessage object to send() method to send a messageconn.send(msg);

How To Send a Binary Message

Destination address with telephone number and port numberString addr = “sms://+358401234567:1234”;

A client mode connection is created by passing a string identifying a destination address to the Connector.open() method. This method returns a MessageConnection MessageConnection conn = (MessageConnection)Connector.open(addr);

String constant BINARY_MESSAGE of MessageConnection class is passed to the newMessage() factory method BinaryMessage bmsg =

(BinaryMessage)conn.newMessage(MessageConnection.BINARY_MESSAGE);

The message in byte array is passed as parameter in setPayloadData() of TextMessagebyte[] msg=“HelloWorld”.getBytes();msg.setPayloadData(msg);

Now pass BinaryMessage object to send() method to send a messageconn.send(msg);

Waiting for Incoming Message

Only a server-mode MessageConnection can receive messages.

There are two approaches to receiving messages:

Synchronously, having a thread wait for incoming messages

Asynchronously, having the system notify the application when new

messages directed to the application have arrived

Synchronous messaging

This thread loops for messages, invoking Message.receive() to block while it waits for incoming messages

Create a server mode connection MessageConnection sconn = (MessageConnection) Connector.open("sms://:3333");

Now check in a new thread for a message continuouslywhile (true) { //listen for a new message and handle the incomming message Message msg = sconn.receive();

//checks whether the received message is TextMessage if (msg instanceof TextMessage) { TextMessage tmsg = (TextMessage) msg;

//getPayloadText() of TextMessage returns the message String msgText = tmsg.getPayloadText();

// Construct the return message TextMessage rmsg = (TextMessage) sconn.newMessage( MessageConnection.TEXT_MESSAGE); rmsg.setAddress ( tmsg.getAddress() ); rmsg.setPayloadText( "Thanks!" ); sconn.send(rmsg); }

Asynchronous Messaging

WMA defines the MessageListener interface, with a single method, notifyIncomingMessage(), which the platform invokes each time it receives a Message Asynchronously.

public class MyClass implements MessageListener { public void notifyIncomingMessage(MessageConnection connection) { //read the message in a new thread } ... }

to enable asynchronous messaging, the application must register a message listenerwith the connection

... MessageConnection sconn = (MessageConnection) Connector.open("sms://:3333");sconn.setMessageListener(MyClass); ...

Thank You