Wireless Messaging API: JSR 120 Recommended Practices

[Skip TOC]

Table of Contents

Introduction

Security

Permissions for Opening Connections

Permissions for Send and Receive Operations

WMA Push Capabilities

WMA Push Registration Entry

Portable WMA Applications

This document addresses features that are planned for JSR 118 MIDP 2.0 that will be available to WMA applications. Since the MIDP 2.0 specification will be finalized after the WMA 1.0 release, this document will serve as a recommended practices document until a maintenance release of the WMA specification can be released. Please send comments to wma-comments@sun.com.

Introduction

This document provides implementation notes for platform developers deploying the JSR 120 interfaces on a MIDP 2.0 platform. This document will be released with the WMA 1.0 specification, which is initially targeted at MIDP 1.0 devices. Once the MIDP 2.0 release has been finalized, a future revision of this document will become an official part of the JSR 120 specification as part of a maintenance release of the WMA 1.0 specification.

This document addresses features available in a MIDP 2.0 device that can be used to enhance WMA applications. In particular, this document describes how to:

• use the MIDP 2.0 security features to control access to WMA capabilities
• use the MIDP 2.0 Push mechanism with SMS and CBS messages
• write applications to remain portable between the MIDP 1.0 and MIDP 2.0 platforms

[Top]

Security

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.

Permissions for Opening Connections

The JSR 118 MIDP NG specification defines a mechanism for granting permissions to use privileged features. This mechanism is based on a policy mechanism enforced in the platform implementation. The following permissions are defined for the JSR 120 messaging functionality, when deployed with a JSR 118 MIDP 2.0 implementation.

To open a connection, a MIDlet suite requires an appropriate permission to access the MessageConnection implementation. If the permission is not granted, then Connector.open methods MUST throw a SecurityException. The following table indicates the permission that must be granted for each protocol.

Permission	Protocol
javax.microedition.io.Connector.sms	sms
javax.microedition.io.Connector.cbs	cbs

[Top]

Permissions for Send and Receive Operations

To send and receive messages, the MIDlet suite requires the appropriate permissions. If the permission is not granted, then the MessageConnection.send and the MessageConnection.receive methods MUST throw a SecurityException. The following table indicates the permission that must be granted for each requested operation.

Permission	Protocol
javax.wireless.messaging.sms.send	sms
javax.wireless.messaging.sms.receive	sms
javax.wireless.messaging.cbs.receive	CBS

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 sending such messages will fail and throw a SecurityException even when the application has the permission to send messages in general.

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 Connector.open(url) and for any message receive or send operation that potentially engages with the network or the privileged message storage on the device.

[Top]

WMA Push Capabilities

MIDP 2.0 includes a mechanism to register a MIDlet when a connection notification event is detected. Once the MIDlet has been launched it performs the same I/O operations it would normally use to open a connection and read and write data.

For WMA applications this capability allows the application to be launched if messages arrive either while the MIDlet is not running or while another MIDlet is running.

[Top]

WMA Push Registration Entry

Push Registrations are either defined in the application descriptor or made dynamically at runtime via PushRegistry. The entry for a WMA protocol will include the connection URL string which identifies the scheme and port number of the inbound message connection. The entry also contains a filter field that designates which senders are permitted to send messages that launch the registered MIDlet. An asterisk ("*") and question mark ("?") can be used in the filter field as a wild cards as specified in the MIDP 2.0 specification.

For the sms: protocol, the filter field is matched against the MSISDN part of the sender address, as defined by the msisdn element of the sms: URL syntax in section A.2.0 of the WMA API specification. The sender port number is not included in matching the filter. Wildcard characters can be used in the filter as specified in the MIDP 2.0 specification.

For the CBS: protocol, the filtering is not performed and only "*" MUST be used as the filter.

For example :
   MIDlet-Push-1: sms://:12345, SmsExample, 123456789
   MIDlet-Push-2: CBS://:54321, CbsExample, *
    

Unlike the initial push connections defined in JSR 118 for MIDP 2.0, the SMS protocol includes an explicit buffering mechanism where messages are held until processed by some application that reads and deletes messages when they are done with data. If a message is delivered to the device and does not pass the specified filter, the message will be deleted by the Application Management Software.

When the application is started in response to a Push message, the application SHOULD read and process all messages that are buffered for it. If an application fails to read and process the messages when started or if starting of the application is denied (e.g. by the end user), the platform implementation MAY delete unread messages from the buffer, if it becomes necessary to do so, e.g. because of the buffer becomes full.

Another difference between the WMA interface and other JSR 118 protocol handlers in MIDP 2.0, is that WMA includes a MessageListener which provides asynchronous callbacks when messages become available while the application in running.

[Top]

Portable WMA Applications

If permitted by the device security policy, a WMA application written for a MIDP 1.0 platform will work without any modification on a MIDP 2.0 system. This is behavior is defined by the JSR 118 specification of untrusted applications.

MIDP 2.0 also supports the concept of trusted applications. For these applications, the device can automatically handle trust decisions based on signed JAR files and a platform-specific policy mechanism that associates specific permissions with the signed application. The security model also allows for the definition of user-granted permissions on a one-shot, session or blanket authorization. In many cases the platform dependent policy for permissions on MIDP 1.0 will be able to be mapped onto the MIDP 2.0 defined permissions.

An application designed to work only on a MIDP 2.0 device can use the methods in the PushRegistry class to check if there are active connections (listConnections) or to add or remove registered connections at runtime ( registerConnection or unregisterConnection).

An application designed to run portably on MIDP 1.0 or MIDP 2.0 platforms will only use the application descriptor and attributes in the manifest to describe requested permissions and push registration entries. See the JSR 118 MIDP 2.0 specification for details about the MIDlet-Permissions and MIDlet-Push-<n> attributes. On a MIDP 1.0 platforms these properties will be ignored. On a MIDP 2.0 platform, these properties will direct the application management software to perform the necessary checks and registrations when the application is installed and removed from the system.

[Top]

Copyright © 2002 Siemens AG. All rights reserved.