18 JSR 120: Wireless Messaging

Oracle Java ME SDK 8 supports the Wireless Messaging API (WMA) with a sophisticated simulation environment. WMA 1.1 (JSR 120) enables IMlets to send and receive Short Message Service (SMS) or Cell Broadcast Service (CBS) messages.

This chapter describes the tools you can use to develop WMA applications. It begins by showing you how to configure the emulator's support of WMA. Next, it describes the WMA console, a tool for testing WMA applications.

Many of the tasks in this topic can also be accomplished from the command line. For more information, see Running the WMA Tool.

Using the WMA Console to Send and Receive Messages

The WMA console is a tool that enables you to send messages to and receive messages from applications. You can, for example, use the WMA console to send SMS messages to an IMlet running on the emulator.

To start the WMA console in NetBeans IDE 8.0, open the Tools menu, select Java ME, and then WMA Console. Messages can be sent from the WMA Console to an emulator instance.

The console opens as a tab in NetBeans IDE 8.0. The console phone number is displayed as part of the WMA Console tab label (for example, 987654321).

The WMA console phone number is an editable CLDC property. In the Device Selector, right-click the CLDC, Java(TM) ME Platform SDK 8.0 node and select Properties. Enter a new value in the WMA Console Phone Number field. If the number is available, it is assigned to the console. If the number is in use, it is assigned to the console the next time you restart NetBeans IDE 8.0.

Each instance of the emulator has a simulated phone number that is shown in the emulator window. The phone numbers are important because they are used as addresses for WMA messages. The phone number is a device property, and it can be changed. In the Device Selector, right-click a device and select Properties. Enter a new value in the Phone Number field.

Sending a Text or Binary SMS Message

To send a text SMS message, open the WMA Console and click Send SMS.

The To Clients list contains phone numbers of all running emulator instances. Select one or more destinations and enter a port number.
To send a text message, select the Text Message tab, enter your message and click Send.
To send the contents of a file as a binary message, click the Binary Message tab. Enter the path of a file directly, or click Browse to select it in the file system explorer.

Note:

The maximum message length for text and binary messages is 4096 bytes.

Sending Text or Binary CBS Messages

To send a text or binary CBS message, click Send CBS in the WMA Console. Sending CBS messages is similar to sending SMS messages, except that recipients are unnecessary because it is a broadcast. Specify a message identifier and enter the text or binary content of your message. The maximum message length for text and binary messages is 4096 bytes.

Note:

The application running on the emulator receives only the first 160 symbols of the CBS message.

Receiving Messages in the WMA Console

To access the WMA Output Window, open the Window menu, select Java ME and then WMA Console Output. The WMA Output Window has its own phone number displayed in the label. You can send messages from your applications running on the emulator to the WMA console.

Received messages are displayed in the WMA Output Window.

Running the WMA Tool

wma-tool is the command-line version of the WMA Console. It is located under bin in the Java ME SDK installation directory. The Device Manager must be running before you start wma-tool. When the tool is started, it outputs the phone number it is using.

wma-tool has the following syntax:

wma-tool <command> [options]

Each protocol has send and receive commands. The requested command is passed to the tool as the first argument. The following commands are available:

receive: Receive any message
smsreceive: Receives SMS messages
cbsreceive: Receives CBS messages
smssend: Sends SMS message
cbssend: Sends CBS message

All *send commands send the specified message and exit. All *receive commands print incoming messages until they are explicitly stopped.

The following options are available:

-o: Stores binary content to the output directory specified after a space.
-t: After starting in non-interactive mode, waits for a message for the number of seconds specified after a space.
-f: Stores text content as files instead of printing it.
-q: Runs in quite mode.

Examples of smsreceive and cbsreceive

The syntax for receiving a message is similar for both protocols:

smsreceive [-o <output_dir>] [-t <timeout>] [-q]

cbsreceive [-o <output_dir>] [-t <timeout>] [-q]

The following example demonstrates how to receive a message from an emulator:

Start the Java ME Embedded Emulator. Click the Windows Start menu, open All Programs, select Java ME Platform SDK 8.0, and then Java ME Embedded Emulator.

Use the following command to run wma-tool:

C:\Java_ME_platform_SDK_8.0\bin> wma-tool smsreceive

WMA tool started with phone number: 987654321
press <Enter> to exit.

In the emulator, run the SMS Send IMlet and send a message to the WMA Console. Enter the console phone number.

The console receives the message as follows:

SMS Received:
          From: 123456789
Timestamp: Thu Aug 23 23:31:26 PDT 2012
          Port: 50000
  Content type: Text
      Encoding: GSM7BIT
       Content: A message from EmbeddedDevice1 to wma-tool
Waiting for another message, press <Enter> to exit.

Example of smssend

The following syntax is used for sending SMS messages:

wma-tool smssend <target_phone> <target_port> <message_content>

The message content can be specified either as text or using the -f option with the name of the file that you want to send as a binary message.

For example, to send a text message to phone number 123456789 on port number 50000, use the following command:

C:\Java_ME_platform_SDK_8.0\bin> wma-tool smssend 123456789 50000 "smssend message from wma-tool"

Example cbssend

The following syntax is used for sending CBS messages:

wma-tool cbssend <message_id> <message_content>

The message content can be specified either as text or using the -f option with the name of the file that you want to send as a binary message.

For example, to send a text message with message identifier 50001, use the following command:

C:\Java_ME_platform_SDK_8.0\bin> wma-tool cbssend 50001 "cbssend message from wma-tool"