MOTOROKR E6/E6e Java ME Developer Guide. Version 02.00

Transcription

1 MOTOROKR E6/E6e Version 02.00

2 Copyright 2007, Motorola, Inc. All rights reserved. This documentation may be printed and copied solely for use in developing products for Motorola products. In addition, two (2) copies of this documentation may be made for archival and backup purposes. Except for the foregoing, no part of this documentation may be reproduced or transmitted in any form or by any means or used to make any derivative work (such as translation, transformation, or adaptation) without express written consent from Motorola, Inc. Motorola reserves the right to make changes without notice to any products or services described herein. "Typical" parameters, which may be provided in Motorola Data sheets and/or specifications, can and do vary in different applications and actual performance may vary. Customer's technical experts will validate all "Typicals" for each customer application. No warranty is made as to coverage, availability, or grade of service provided by the products or services, whether through a service provider or otherwise. No warranty is made that the software will meet your requirements or will work in combination with any hardware or application software products provided by third parties, that the operation of the software products will be uninterrupted or error free, or that all defects in the software products will be corrected. In no event shall Motorola be liable, whether in contract or tort (including negligence), for any damages resulting from use of a product or service described herein, or for any indirect, incidental, special or consequential damages of any kind, or loss of revenue or profits, loss of business, loss of information or data, or other financial loss arising out of or in connection with the ability or inability to use the Products, to the full extent these damages may be disclaimed by law. Some states and other jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, or limitation on the length of an implied warranty, therefore the above limitations or exclusions may not apply to you. This warranty gives you specific legal rights, and you may also have other rights, which vary from jurisdiction to jurisdiction. Motorola products or services are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the Motorola product or service could create a situation where personal injury or death may occur. Should the buyer purchase or use Motorola products or services for any such unintended or unauthorized application, the buyer shall release, indemnify and hold Motorola and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that Motorola was negligent regarding the designing or manufacturing of the product or service. Motorola recommends that if you are not the author or creator of the graphics, video, or sound, you obtain sufficient license rights, including the rights under all patents, trademarks, trade names, copyrights, and other third party proprietary rights. MOTOROLA and the Stylized M Logo are registered in the U.S. Patent & Trademark Office. All other product or service names are the property of their respective owners. Java and all other Java based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. If this documentation is provided on compact disc, the other software and documentation on the compact disc are subject to the license agreement accompanying the compact disc. MOTOROKR E6/E6e Version APR-2007 For the latest version of this document, visit Motorola, Inc. Page 2

3 Table of Contents TABLE OF CONTENTS Java ME Introduction... 7 THE JAVA PLATFORM, MICRO EDITION (JAVA ME)... 7 THE MOTOROLA JAVA ME PLATFORM... 8 RESOURCES AND APIS AVAILABLE Developing and Packaging Java ME Applications GUIDE TO DEVELOPMENT IN JAVA ME Downloading Applications METHODS OF DOWNLOADING ERROR LOGS Application Management DOWNLOADING A JAR FILE WITHOUT A JAD MIDLET UPGRADE INSTALLATION AND DELETION STATUS REPORTS itap INTELLIGENT KEYPAD TEXT ENTRY API Record Management System RECORD MANAGEMENT SYSTEM API Downloading MIDlet Through Browser START ACTIVE BROWSER SESSION FROM MAIN MENU FIND A LOCATION WITH JAVA ME APPLICATION DOWNLOADING MIDLETS DIFFERENT ERROR CHECKS MEMORY FULL MEMORY FULL DURING INSTALLATION PROCESS APPLICATION VERSION ALREADY EXISTS NEWER APPLICATION VERSION EXISTS JAD Attributes JAD / MANIFEST ATTRIBUTE IMPLEMENTATIONS Network APIs NETWORK CONNECTIONS USER PERMISSION INDICATING A CONNECTION TO THE USER HTTPS C ONNECTION DNS IP PUSH REGISTRY MECHANISMS FOR PUSH Page 2

4 PUSH REGISTRY DECLARATION DELIVERY OF A PUSH MESSAGE DELETING AN APPLICATION REGISTERED FOR PUSH SECURITY FOR PUSH REGISTRY NETWORK ACCESS Platform Request API PLATFORM REQUEST API MIDLET REQUEST OF A URL THAT INTERACTS WITH BROWSER MIDLET REQUEST OF A URL THAT INITIATES A VOICE CALL JSR-75: PIM API OVERVIEW REQUIREMENTS FIELDS AND ATTRIBUTES CONTACT LIST EVENT LIST TODO LIST JSR-75: FileConnection API OVERVIEW REQUIREMENTS INTERFACE SECURITY PERMISSIONS JSR-82: Bluetooth API OVERVIEW BLUETOOTH API SYSTEM REQUIREMENTS BLUETOOTH CONTROL CENTER DEVICE PROPERTIES SERVICE REGISTRATION CONNECTABLE MODE NON-CONNECTABLE MODE DEVICE MANAGEMENT GENERIC ACCESS PROFILE (GAP) SECURITY COMMUNICATION SERIAL PORT PROFILE (SPP) OBJECT EXCHANGE (OBEX) SECURITY POLICY EXTERNAL EVENTS INCOMING CALL INCOMING MESSAGE ALARM AND DATEBOOK BEHAVIOR PRESSING OF END KEY HARDWARE REQUIREMENTS INTEROPERABILITY REQUIREMENTS Page 3

5 14 JSR-118: MIDP 2.0 Security Model UNTRUSTED MIDLET SUITES UNTRUSTED DOMAIN TRUSTED MIDLET SUITES PERMISSION TYPES CONCERNING THE HANDSET USER PERMISSION INTERACTION MODE IMPLEMENTATION BASED ON RECOMMENDED SECURITY POLICY TRUSTED THIRD-PARTY DOMAIN SECURITY POLICY FOR PROTECTION DOMAINS DISPLAYING PERMISSIONS TRUSTED MIDLET SUITES USING X.509 PKI SIGNING A MIDLET SUITE SIGNER OF MIDLET SUITES MIDLET ATTRIBUTES USED IN SIGNING MIDLET SUITES CREATING THE SIGNING CERTIFICATE INSERTING CERTIFICATES INTO JAD CREATING THE RSA SHA-1 S IGNATURE OF THE JAR AUTHENTICATING A MIDLET SUITE VERIFYING THE SIGNER CERTIFICATE VERIFYING THE MIDLET SUITE JAR CARRIER SPECIFIC SECURITY MODEL JSR-120: Wireless Messaging API WIRELESS MESSAGING API (WMA) SMS CLIENT MODE AND SERVER MODE CONNECTION SMS PORT NUMBERS SMS STORING AND DELETING RECEIVED MESSAGES SMS MESSAGE TYPES SMS MESSAGE STRUCTURE SMS NOTIFICATION JSR-135: Mobile Media API MOBILE MEDIA API TONECONTROL VOLUMECONTROL STOPTIMECONTROL MANAGER CLASS SUPPORTED MULTIMEDIA FILE TYPES AUDIO MEDIA IMAGE MEDIA VIDEO MEDIA MEDIA LOCATORS RTSP LOCATOR HTTP LOCATOR FILE LOCATOR CAPTURE LOCATOR SECURITY Page 4

6 POLICY PERMISSIONS JSR-139: CLDC JSR-30 CLDC NO FLOATING POINT SUPPORT CLASSFILE FORMAT AND CLASS LOADING SUPPORTED FILE FORMATS PUBLIC REPRESENTATION OF JAVA APPLICATIONS AND RESOURCES CLASSFILE LOOKUP ORDER JSR-139 CLDC JSR-172: Java ME Web Services Specification OVERVIEW JAXP JAX-RPC S UBSET OVERVIEW JSR-184: Mobile 3D Graphics API OVERVIEW MOBILE 3D API MOBILE 3D FILE FORMAT SUPPORT MOBILE 3D GRAPHICS M3G API TYPICAL M3G APPLICATION SIMPLE MIDLETS INITIALIZING THE WORLD USING THE GRAPHICS3D OBJECT INTERROGATING AND INTERACTING WITH OBJECTS ANIMATIONS AUTHORING M3G FILES JSR-185: Java Technology for the Wireless Industry OVERVIEW CLDC RELATED CONTENT FOR JTWI MIDP 2.0 SPECIFIC INFORMATION FOR JTWI WIRELESS MESSAGING API 1.1 (JSR-120) S PECIFIC CONTENT FOR JTWI MOBILE MEDIA API 1.1 (JSR-135) S PECIFIC CONTENT FOR JTWI JSR-205: WMA OVERVIEW MESSAGING FUNCTIONALITY MMS MESSAGE STRUCTURE MMS MESSAGE ADDRESSING MMS MESSAGE TYPES MULTIPARTMESSAGE MESSAGEPART MULTIMEDIA MESSAGE SERVICE CENTER ADDRESS APPLICATION ID MMS PUSH REQUIREMENTS FOR WMA INITIAL SETUP Page 5

7 HANDLING THE INCOMING MMS MESSAGE APPLICATION IS RUNNING/RESUMING APPLICATION IS RUNNING/BACKGROUND APPLICATION IS SUSPENDING APPLICATION IS ENDING MMS PUSH REQUIREMENTS TO THE NATIVE MMS CLIENT ANONYMOUS REJECTION FEATURE COINCIDENTAL ADDRESSES IN THE NATIVE CLIENT AND JAVA CLIENTS ADDRESS FILTERS 147 SECURITY POLICY VMVM SUPPORT EXTERNAL EVENT INTERACTION Motorola Get URL from Flex API OVERVIEW FLEXIBLE URL FOR DOWNLOADING FUNCTIONALITY SECURITY POLICY APPENDIX A: Key Mapping KEY MAPPING APPENDIX B: Memory Management Calculation AVAILABLE MEMORY APPENDIX C: FAQ ONLINE FAQ APPENDIX D: HTTP Range GRAPHIC DESCRIPTION Page 6

8 Chapter 1 - Java ME Introduction 1 Java ME Introduction The MOTOROKR E6/E6e handset includes the Java Micro Edition (Java ME) Platform, Micro Edition, also known as the Java ME platform. The Java ME platform enables developers to easily create a variety of Java applications ranging from business applications to games. Prior to its inclusion, services or applications residing on small consumer devices like cell phones could not be upgraded or added to without significant effort. By implementing the Java ME platform on devices like the MOTOROKR E6/E6e handset, service providers, as well as customers, can easily add and remove applications allowing for quick and easy personalization of each device. This chapter presents a quick overview of the Java ME environment and the tools that can be used to develop applications for the MOTOROKR E6/E6e handset. The Java Platform, Micro Edition (Java ME) The Java ME platform is a very small application environment. It is a framework for the deployment and use of Java technology in small devices (such as cell phones and pagers) and includes a set of APIs and a virtual machine that is designed in a modular fashion, allowing for scalability among a wide range of devices. The Java ME architecture contains three layers consisting of the Java Virtual Machine, the Configuration Layer, and the Profile Layer. The Virtual Machine (VM) supports the Configuration Layer by providing an interface to the host operating system. Above the VM Layer is the Configuration Layer, which can be thought of as the lowest common denominator of the Java Platform available across devices of the same "horizontal market." Built upon this Configuration Layer is the Profile Layer, Page 7

9 Chapter 1 - Java ME Introduction typically encompassing the presentation layer of the Java Platform. Figure 1 Layer Architecture The Configuration Layer used in the iden handsets is either the Connected Limited Device Configuration 1.1 (CLDC 1.1 ) or the Connected Limited Device Configuration 1.0 (CLDC 1.0), depending on the phone model. The Profile Layer used is the Mobile Information Device Profile 2.0 (MIDP 2.0). Together, the CLDC and MIDP provide common APIs for I/O, simple math functionality, UI, and more. For more information on Java ME see the Sun Java ME documentation ( The Motorola Java ME Platform Functionality not covered by the CLDC and MIDP APIs is left for individual OEMs to implement and support. By adding to the standard APIs, manufacturers can allow developers to access and take advantage of the unique functionality of their handsets. The MOTOROKR E6/E6e handset contains OEM APIs for extended functionality ranging from enhanced UI to advanced data security. While the MOTOROKR E6/E6e handset can run any application written in standard MIDP, it can also run applications that take advantage of the unique functionality provided by these APIs. These OEM APIs are described in this guide. Page 8

10 Chapter 1 - Java ME Introduction Resources and APIs Available MIDP 2.0 provides support to the following functional areas on the MOTOROKR E6/E6e handset: Application delivery and billing Application lifecycle Application signing model and privileged security model End-to-end transactional security (HTTPS) MIDlet push registration (server push model) Networking Persistent storage Sounds Timers User Interface File Image Support (.PNG,.JPEG,.GIF,.BMP) Additional Functionality: JSR-118 JSR-120 JSR-135 JSR-139 JSR-172 JSR-184 JSR-185 JSR-205 JSR-75 FileConnection API JSR-75 PIM API JSR-82 Motorola Get URL from Flex API Page 9

11 Chapter 2 - Developing and Packaging Java ME Applications 2 Developing and Packaging Java ME Applications Guide to Development in Java ME Introduction to Development This chapter assumes you have previous experience in Java ME development and can appreciate the development process for Java MIDlets. This chapter provides some information that a beginner in development can use to gain an understanding of MIDlets for Java ME handsets. There is a wealth of material on this subject on the following web sites maintained by Motorola, Sun Microsystems, and others. Please refer to the following URLs for more information: Page 10

12 Chapter 2 - Developing and Packaging Java ME Applications As an introduction, brief details of Java ME are explained below. The MIDlet consists of two core specifications, namely Connected Limited Device Configuration (CLDC) and Mobile Information Device Profile (MIDP). Both of these specifications (JSR - Java Specification Requests) are located at site for reading. For For For For MIDP 1.0; JSR-37 should be reviewed. MIDP 2.0; JSR-118 should be reviewed. CLDC 1.0.4; JSR-30 should be reviewed. CLDC 1.1; JSR-139 should be reviewed. For beginning development, key points to remember are memory size, processing power, screen capabilities, and wireless network characteristics. These all play an important part in the development of a MIDlet. The specifications listed above are designed to work upon devices that have these characteristics. Network conditions would only apply for networked applications such as streaming tickers, clients, etc. In addition to the specifications, arrays of tools are available to assist the development cycle. These range from the command line tools provided with by Software Development Kit (SDK) from Sun to Integrated Development Environments (IDEs) that are either free or purchased. These IDEs come from a range of sources such as Sun, IBM, and Borland to name a few. In addition to the IDEs and Sun SDK for development, Motorola offers access to our own SDK that contains Motorola device emulators. From here, a MIDlet can be built and then deployed onto an emulated target handset. This enables debugging and validation of the MIDlet before deployment to a real, physical handset. The latest Motorola SDK can be downloaded from the MOTODEV web site. Please refer to the product specifications at the end of this guide for detailed information on each handset. Page 11

13 Chapter 3 - Downloading Applications 3 Downloading Applications Methods of Downloading There are two options open to the developer for deploying the MIDlet to a physical Motorola device. These are OTA (over-the-air) downloading or direct cable (Serial) downloading through a PC to the target device. Method 1 - OTA To use the OTA method, the developer will have a connection through a wireless network to a content server. This content server could be, for example, Apache ( which is free to use, deployable on multiple operating systems, and has extensive documentation on how to configure the platform. The required file will be downloaded (either.jad and/or.jar) by issuing a direct URL request to the file in question or it could be a URL request to a WAP page and a hyperlink on that page to the target file. This request will be made through the browser. In MIDP 2.0, the need for a JAD file before download is not required, so the JAR file can be downloaded directly. The information about the MIDlet will be pulled from the manifest file. The transport mechanism used to download the file will be one of two depending on the support from the network operators WAP Gateway and the size of the file requested. HTTP Range - see specification RFC 2068 at if content greater than 30k in size. Below is a ladder diagram showing the flow Page 12

14 Chapter 3 - Downloading Applications through HTTP range transfer, although recall use of the.jad is optional. SAR (Segmentation & Reassembly) - see specification of wireless transaction protocol at the if less than 30k in size. During a download of the application, the user will see the Opera 8 displaying 'Downloading' followed by "x% completed" for either SAR or HTTP Byte Range type downloads. A basic Over the Air Server Configuration document can be found in our Technical Articles section at This includes details of configuring the server and also example WAP pages. In these handsets, the user is given an option of deleting any MIDlets that are on the phone if an OTA download cannot be achieved due to lack of space. The following error codes are supported: Success Insufficient Memory User Cancelled Loss Of Service JAR Size Mismatch Attribute Mismatch Invalid Descriptor Invalid JAR Incompatible Configuration or Profile Application Authentication Failure Application Authorization Failure Push Registration Failure Deletion Notification Please be aware that the method used by the handset, as per the specifications, is POST. Using a GET (URL encoding) style for the URL will fail. This is not the correct use of the MIDlets JAD parameters. Possible Screen Messages Seen With Downloading: If JAR -file size does not match with specified size, it displays "Failed Invalid File". Upon time-out, the handset goes back to browser. When downloading is done, the handset displays a transient notice "Download Completed" and starts to install the application. Upon completing installation, the handset displays a transient notice "Installed" and returns to Browser after time-out. If the MANIFEST file is wrong, the handset displays a transient notice "Failed File Corrupt" and returns to Browser after time-out. Page 13

15 Chapter 3 - Downloading Applications If JAD does not contain mandatory attributes, "Failed Invalid File" notice appears The USER-AGENT String Table 1 describes USER_AGENT strings associated with Motorola devices: Motorola Device USER_AGENT STRING MOTOROKR E6/E6e MOT-E6/xx.xx.xxR Opera/8 Profile/MIDP-2.0 Configuration/CLDC-1.1 Table 1 USER_AGENT String The USER_AGENT string can be used to identify a handset and render specific content to it based on it information provided in this string (example CGI on a content server). These strings can be found in the connection logs at the content server. 1. WAP Browser Release, Opera 8 2. MIDP version CLDC version 1.1 Error Logs Table 2 represents the error logs associated with downloading applications. Error Dialog Scenario Possible Cause Install-Notify Failed: Inval- JAD Downid File load Missing or incorrectly formatted mandatory JAD attributes Mandatory: MIDlet-Name MIDlet-Version MIDlet-Vendor MIDlet-JAR-URL MIDlet-JAR_Size 906 Invalid descriptor Download Failed OTA JAR Download The received JAR size does not match the size indicated 904 JAR Size Mismatch Cancelled: <Icon> <Filename> OTA JAR Download User cancelled download 902 User Cancelled Download Failed OTA JAR Download Browser lost connection with serv- 903 Loss of Service er Certification path cannot be valid- Page 14

16 Chapter 3 - Downloading Applications ated JAD signature verification failed Unknown error during JAD validation See 'Details' field in the dialog for information about specific error Insufficient Storage OTA JAR Download Insufficient data space to tempor- 901 Insufficient arily store the JAR file Memory Application Already Exists OTA JAR Download MIDlet version numbers are identical Different Version Exists OTA JAR Download MIDlet version on handset supercedes version being downloaded Failed File Corrupt Installation Attributes are not identical to respective JAD attributes Insufficient Storage Installation Insufficient Program Space or Data Space to install suite Application Error Installation Class references non-existent class or method Security Certificate verification failure Checksum of JAR file is not equal to Checksum in MIDlet-JAR-SHA attribute Application not authorized Application Expired MIDlet Launching Security Certificates expired or removed Application Error MIDlet Execution Authorization failure during MIDlet execution Incorrect MIDlet 905 Attribute Mismatch 901 Insufficient Memory Table 2 Error Logs Page 15

17 Chapter 4 - Application Management 4 Application Management The following sections describe the application management scheme for the MOTOROKR E6/E6e handset. This chapter discusses the following: Downloading a JAR without a JAD MIDlet upgrade Installation and Deletion Status Reports Downloading a JAR File Without a JAD In Motorola's MIDP 2.0 implementation, a JAR file can be downloaded without a JAD. In this case, the user clicks on a link for a JAR file, the file is downloaded, and confirmation is obtained before the installation begins. The information presented is obtained from the JAR manifest instead of the JAD. Page 16

18 Chapter 4 - Application Management MIDlet Upgrade Rules from the JSR-118 (MIDP 2.0) are followed to help determine if the data from an old MIDlet should be preserved during a MIDlet upgrade. When these rules cannot determine if the RMS should be preserved, the user is given an option to preserve the data. The data is saved if the new MIDlet-version is the same or newer, and if the new MIDlet-data-space requirements are the same or more than the current MIDlet. The data is not saved if the new MIDlet-data-space requirement is smaller than the current MIDlet requirement. The data is not saved if the new MIDlet-version is older than the current version. If the data cannot be saved, the user is warned about losing the data. If the user proceeds, the application is downloaded. If the user decides to save the data from the current MIDlet, the data is preserved during the upgrade and the data is made available for the new application. In any case, an unsigned MIDlet is not allowed to update a signed MIDlet. Installation and Deletion Status Reports The status (success or failure) of an installation, upgrade, or deletion of a MIDlet suite is sent to the server according to the JSR-118 specification. If the status report cannot be sent, the MIDlet suite is still enabled and the user is allowed to use it. In some instances, if the status report cannot be sent, the MIDlet is deleted by operator's request. Upon successful deletion, the handset sends the status code 912 to the MIDlet-Delete-Notify URL. If this notification fails, the MIDlet suite is still deleted. If this notification cannot be sent due to lack of network connectivity, the notification is sent at the next available network connection. Page 17

19 Chapter 4 - Application Management Table 3 lists the application management feature/class support for MIDP 2.0: Feature/Class Application upgrades performed directly through the AMS. When removing a MIDlet suite, the user is prompted to confirm the entire MIDlet suite is removed. Application Descriptor included the attribute MIDlet-Delete-Confirm, its value is included in the prompt. Prompt for user approval when the user has chosen to download an application that is identical to the application currently in the handset. An older version cannot be installed. Unauthorized MIDlets will not have access to any restricted function calls. AMS checks the JAD for security indicated every time a download is initiated. Application descriptor or MIDlet fails the security check, the AMS prevents the installation of that application and notifies the user that the MIDlet could not be installed. Application descriptor and MIDlet pass the security check, the AMS installs the MIDlet and grants it the permissions specified in the JAD. A method for launching Java application that maintains the same look and feel as other features on the device is provided. User is informed of download and installation with a single progress indicator and is given an opportunity to cancel the process. User is prompted to launch the MIDlet after installation. A method for creating shortcuts to Java applications are provided. A no forward policy on DRM issues, included but not limited to transferring the application over-the-air, IRDA, Bluetooth, I/O Cables, External storage devices, etc., until further guidance is provided. Table 3 Application Management Feature Page 18

20 Chapter 5 - itap 5 itap Intelligent Keypad Text Entry API When users are using features such as SMS (short message service), or "Text Messaging," they can opt for a predictive text entry method from the handset. The Java ME environment has the ability to use SMS in its API listing. The use of a predictive entry method is a compelling feature to the MIDlet. This API enables a developer to access itap, Numeric, Symbol, and Browse text entry methods. With previous Java ME products, the only method available was the standard use of TAP. Predictive text entry allows a user to simply type in the letters of a word using only one key press per letter, as opposed to the TAP method that can require as many as four or more key presses. The use of the itap method can greatly decrease text-entry time. Its use extends beyond SMS text messaging, but into other functions such as phonebook entries. The following Java ME text input components support itap. javax.microedition.lcdui.textbox The TextBox class is a Screen that allows the user to edit and enter text. javax.microedition.lcdui.textfield A TextField is an editable text component that is placed into a Form. It is given a piece of text that is used as the initial value. Page 19

21 Chapter 5 - itap Refer to Table 4 for itap feature/class support for MIDP 2.0: Feature/Class Predictive text capability is offered when the constraint is set to ANY. User is able to change the text input method during the input process when the constraint is set to ANY (if predictive text is available). Multi-tap input is offered when the constraint on the text input is set to ADDR, PASSWORD, or URL. Table 4 itap Feature/Class Page 20

22 Chapter 6 - Record Management System 6 Record Management System Record Management System API If the MIDlet has not specified a data space requirement in the JAD attribute (MIDlet_data_space_requirement) or the manifest file, a limit of 1Mb is used as the maximum RMS space for that MIDlet. No additional Motorola implementation clarifications are necessary. Table 5 lists the RMS feature/class support for MIDP 2.0: Feature/Class Implementation All constructors, methods, and inherited methods for the InvalidRecordDException class in the javax.microedition.rms package Supported All fields and methods for the RecordComparator interface in the javax.microedition.rms package Supported All methods for the RecordEnumeration interface in the javax.microedition.rms package Supported All methods for the RecordFilter interface in the javax.microedtition.rms package Supported All methods for the RecordListener interface in the javax.microedition.rms package Supported All fields, methods, and inherited methods fortify the RecordStore interface in the javax.microedition.rms package Supported Initial version number of a record to be zero Supported Page 21

23 Chapter 6 - Record Management System All constructors, methods, and inherited methods for the RecordStoreException class in the javax.microedition.rms package Supported All constructors, methods, and inherited methods for the RecordStoreFullException class in the javax.microedition.rms package Supported All constructors, methods, and inherited methods for the RecordStoreNotOpenException class in the javax.microedition.rms package Supported All constructors, methods, and inherited methods for the InvalidRecordIDException class in the javax.microedition.rms package Supported All fields and methods for the RecordComparator interface in the javax.microedition.rms package Supported All methods for the RecordEnumeration interface in the javax.microedition.rms package Supported All methods for the RecordFilter interface in the javax.microedition.rms package Supported All methods for the RecordListener interface in the javax.microedition.rms package Supported All fields, methods, and inherited methods for the ReSupported cordstore interface in the javax.microedition.rms package All constructors, methods, and inherited methods for the RecordStoreException class in the javax.microedition.rms package Supported All constructors, methods, and inherited methods for the RecordStoreNotFoundException class in the javax.microedition.rms package Supported All constructors, methods, and inherited methods for the RecordStoreNotOpenException class in the javax.microedition.rms package Supported Table 5 RMS Feature/Class Page 22

24 Chapter 7 - Downloading MIDlet Through Browser 7 Downloading MIDlet Through Browser The Download MIDlet Through Browser requires the browser to be connected before performing any downloads on the handset. The example shows how to access the Browser application by any of the following methods: Selecting 'Browser' from the Main Menu. Pressing a dedicated 'Browser' key on the keypad (if available on the handset). Pressing a 'Browser' soft key from the idle display (if assigned). Using 'Browser' shortcut (if assigned). Selecting URL from a message. Selecting GetJavaApps from the Main Menu or Java Settings. Start Active Browser Session from Main Menu Figure 2 describes Starting Active Browser Session from Main Menu: Page 23

25 Chapter 7 - Downloading MIDlet Through Browser Figure 2 Starting Active Browser Session from Main Menu GetJavaApps is a feature that allows an operator to insert a WAP designated URL that links to a Java ME site with MIDlet suites. This feature can be found under Java Settings or in the Main Menu as it is flexible for either menu item. Find a Location with Java ME Application Once connected to the WAP browser, different locations may be visited where Java ME Applications may be downloaded. From here, a MIDlet may be selected to download to the handset. Handset initially receives information from the Java Application Descriptor (JAD) file. The JAD includes information about MIDlet-name, version, vendor, MIDlet-Jar-URL, MIDlet-Jar-size, and MIDlet-Data-size. Two additional JAD attributes are Mot-Data-Space-Requirements and Mot-Program-Space-Requirements. These attributes help the KVM determine whether there is enough memory to download and install the selected MIDlet suite. If there is not enough memory, 'Memory Full' dialog is displayed before the download begins. Page 24

26 Chapter 7 - Downloading MIDlet Through Browser Downloading MIDlets Figure 3 represents Java ME Application (MIDlets) Download and Installation. Figure 3 Downloading and Installing Java ME Application (MIDlets) Page 25

27 Chapter 7 - Downloading MIDlet Through Browser Steps to Download and Install Java ME Application: BACK shows previous screen to the user. If the SELECT softkey is selected, the handset displays the application size, time to install, and version. If an error occurs with the descriptor file, the handset then displays the transient notice 'Failed Invalid File.' Upon Time-out, the handset goes back to Browser. If the CANCEL softkey is selected, it shows the Browser Application Card from where the application was selected. If the DOWNLD softkey is selected, the handset starts downloading the application. The handset displays 'Downloading...% Complete' along with the percentage of downloading completed at a time. 'Downloading...% Complete' shall use static dots, not dynamic. Before downloading the MIDlet, handset checks for available memory. Mot-Data-Space-Requirements and Mot-Program-Space-Requirements are two JAD attributes that will help the KVM determine whether there is enough memory to download and install the selected MIDlet suite. If there is not enough memory, 'Insufficient storage' transient dialog is displayed before the download begins. Upon time-out, the handset goes back to Browser. If an error occurs during download, such as a loss of service, then the transient notice 'Download Failed' must be displayed. Upon time-out, the handset goes back to idle state. A downloading application can be cancelled by pressing the END key. The transient notice, 'Download Cancelled' displays. Upon time-out, handset goes back to Browser. If JAR -file size does not match with specified size, it displays 'Failed Invalid File.' Upon time-out, the handset goes back to Browser. When the downloading application is cancelled, handset cleans up all files, including any partial JAR files and temporary files created during the download process. When downloading is done, the handset displays a transient notice 'Download Completed.' The handset then starts to install the application. The handset displays 'Installing...' After an application is successfully downloaded, a status message must be sent back to the network server. This allows for charging of the downloaded application. Charging is per the Over the Air User Initiated Provisioning specification. The status of an install is reported by means of an HTTP POST request to the URL contained in the MIDlet-Install-Notify attribute. The only protocol that MUST be supported is ' Page 26

28 Chapter 7 - Downloading MIDlet Through Browser If the browser connection is interrupted/ended during the download/installation process, the device is unable to send the HTTP POST with the MIDlet-Install Notify attribute. In this case, the MIDlet is deleted to ensure the user does not get a free MIDlet. The use case can occur when a phone call is accepted and terminated during the installation process, because then the browser is not in the needed state to return the MIDlet Install Notify attribute. Upon completing Installation, the handset displays a transient notice 'Installed to Games and Apps'. Upon time-out, the handset goes back to Browser. During Installation if the MANIFEST file is wrong, the handset displays a transient notice 'Failed File Corrupt'. Upon time-out, the handset goes back to Browser. During the installation process, if the flip is closed on a flip handset, the installation process continues and the handset does not return to the idle display. When the flip is opened, the 'Installing...' dialog should appear on the screen and should be dynamic. During download or install of application, voice record, voice commands, voice shortcuts, and volume control is not supported. However, during this time, incoming calls and SMS messages are able to be received. The handset must support sending and receiving at least 30 kilobytes of data using HTTP either from the server to the client or the client to the server, per Over the Air User Initiated Provisioning specification. If JAD does not contain mandatory attributes, 'Failed Invalid File' notice appears. If JAD does not contain mandatory attributes, 'Failed Invalid File' notice appears. Figure 4 Application Does Not Have Mandatory Attributes in ADF Page 27

29 Chapter 7 - Downloading MIDlet Through Browser Different Error Checks Memory Full There are two distinct cases when a Memory Full error can occur during the download process. Memory Full is displayed when the device does not have enough memory to completely download the MIDlet. The JAD of the MIDlet has two attributes, Mot-Data-Space-Requirements and Mot-Program-Space-Requirements. If an application developer adds these attributes to their JAD file, a Motorola device can determine if enough memory exists on the phone before the MIDlet is downloaded. These attributes may or may not be provided in all MIDlets. Two separate prompts are displayed, depending on whether these attributes are present. In cases where there is not enough memory to download the application, the user must be given a message to delete existing applications to free additional memory. The following messages and screen flows are displayed depending on whether specific JAD attributes are present or not. Page 28

30 Chapter 7 - Downloading MIDlet Through Browser Page 29

31 Chapter 7 - Downloading MIDlet Through Browser Figure 5 Memory Full Error Rules: If Mot-Data-Space-Requirements and Mot-Program-Space-Requirements attributes are present in the JAD, the above noted prompt is displayed. This value takes into account the memory requirements of the MIDlet and the current memory usage on the phone to tell the user exactly how much memory to free. The memory usage is based in kilobyte units. 'Data Space:' and the value of the data space should be on separate lines. 'Prog. Space:' and the value of the program space should be on separate lines. The download process is canceled when this error condition occurs. The Memory Full error is no longer a transient prompt. A dialog screen with a Help softkey and a Back softkey is displayed instead. DETAILS will give the user the above detailed Help screen describing the memory required to be able to download the MIDlet. The Help dialog includes a 'More' right softkey label (for those products in which not all the help data can be displayed on a single screen). This label should disappear when the user has scrolled to the bottom of the dialog. BACK from this message takes the user back to the browser page from which the user selected the MIDlet to download. Page 30

32 Chapter 7 - Downloading MIDlet Through Browser Figure 6 Mot-Data-Space and Mot-Program-Space Attributes If Mot-Data-Space-Requirements and Mot-Program-Space-Requirements JAD attributes are not present in the JAD file, the handset can not determine how much memory to free and displays the above help dialog. The Help dialog includes a 'More' right softkey label (for those products in which not all the help data can be displayed on a single screen). This label should disappear when the user has scrolled to the bottom of the dialog. All rules stated in the previous figure must also be followed for the above stated prompt. Page 31

33 Chapter 7 - Downloading MIDlet Through Browser Memory Full During Installation Process Once the MIDlet is successfully downloaded, the installation process begins. During the installation of the MIDlet, the phone may determine there is insufficient memory to complete the installation. This error can occur whether the Mot-Data-Space-Requirements and Mot-Program-Space-Requirements JAD attributes are present or not. The following message and Figure Figure 7 must be displayed: Figure 7 Memory Full Help Message During Installation Process Page 32

34 Chapter 7 - Downloading MIDlet Through Browser The installation process is canceled when this error condition occurs. The Memory Full error is no longer a transient prompt. A dialog screen with a Help softkey and a Back softkey is displayed instead. DETAILS give the user the above Help screen explaining that additional memory is required to be able to install the MIDlet. The Help dialog includes a 'More' right softkey label (for those products in which not all the help data can be displayed on a single screen). This label should disappear when the user has scrolled to the bottom of the dialog. BACK from this message takes the user back to the browser page from which the user selected the MIDlet to download. Application Version Already Exists Compares the version number of the application with that already present on the handset. If the versions are the same, the following message is displayed. The error occurred can be queried by selecting DETAILS. Page 33

35 Chapter 7 - Downloading MIDlet Through Browser Figure 8 Same Version of Application Already Exists on the Handset Rules: Handset checks for MIDlet-Name, MIDlet-vendor, and version number. If they are the same, a dialog 'Application Already Exists' is displayed. To know more about this error, select the DETAILS softkey. Handset displays the new version of the application, as well as the existing application. Page 34

36 Chapter 7 - Downloading MIDlet Through Browser Newer application version exists If the application version on the handset is newer than the downloaded version of application, the following message is displayed. The error occurred can be queried by selecting DETAILS. Figure 9 (Newer) Version of Application Exists Rules: If the latest or newer version of application is already present on the handset, it cannot be downloaded. Page 35

37 Chapter 8 - JAD Attributes 8 JAD Attributes JAD / Manifest Attribute Implementations The JAR manifest defines attributes to be used by the Application Manager Software (AMS) to identify and install the MIDlet suite. These attributes may or may not be found in the application descriptor. The application descriptor is used, in conjunction with the JAR manifest, by the Application Manager Software to manage the MIDlet. The application descriptor is also used for the following: By the MIDlet, for configuration specific attributes. Allows the Application Manager Software on the handset to verify the MIDlet is suited to the handset before loading the JAR file. Allows configuration-specific attributes (parameters) to be supplied to the MIDlet(s) without modifying the JAR file. Motorola has implemented the following support for the MIDP 2.0 Java Application Descriptor attributes as outlined in the JSR-118. Table 6 lists all MIDlet attributes, descriptions, and its location in the JAD and/or JAR manifest that are supported in the Motorola implementation. Please note that the MIDlet does not install if the MIDlet-Data-Size is greater than 512k. Page 36

38 Chapter 8 - JAD Attributes Attribute Name Attribute Description JAR Manifest JAD MIDlet-Name The name of the MIDlet suite that identifies the MIDlets to the user. Yes Yes MIDlet-Version The version number of the MIDlet suite. Yes Yes MIDlet-Vendor The organization that provides the MIDlet suite. Yes Yes MIDlet-Icon The case-sensitive absolute name of a PNG file within the JAR, used to represent the MIDlet suite. Yes Yes MIDlet-Description The description of the MIDlet suite. No No MIDlet-Info-URL A URL for information further describing the MIDlet suite. Yes No MIDlet-<n> The name, icon, and class of the Yes, or no if nth MIDlet in the JAR file. Name is included in used to identify this MIDlet to the the JAD. user. Icon is as stated above. Class is the name of the class extending the. MIDlet-Jar-URL Yes, or no if included in the JAR manifest. The URL from which the JAR file is loaded. Yes MIDlet-Jar-Size The number of bytes in the JAR file. Yes MIDlet-Data-Size The minimum number of bytes of persistent data required by the MIDlet. MicroEdition-Profile The Java ME profiles required. If Yes, or no if any of the profiles are not imple- included in mented the installation fails. the JAD. Yes, or no if included in the JAR manifest. MicroEdition-Configuration The Java ME Configuration required, that is, CLDC. Yes, or no if included in the JAR manifest. MIDlet-Permissions Zero or more permissions that are critical to the function of the MIDlet suite. Yes Yes MIDlet-Permissions-Opt Zero or more permissions that are non-critical to the function of the MIDlet suite. Yes Yes Yes Yes, or no if included in the JAD. Yes Page 37

39 Chapter 8 - JAD Attributes MIDlet-Push-<n> Register a MIDlet to handle inbound connections Yes Yes MIDlet-Install-Notify The URL to which a POST request is sent to report installation status of the MIDlet suite. Yes Yes MIDlet-Delete-Notify The URL to which a POST request is sent to report deletion of the MIDlet suite. Yes Yes MIDlet-Delete-Confirm A text message to be provided to the user when prompted to confirm deletion of the MIDlet suite. Yes Yes Table 6 MIDlet Attributes, Descriptions, and its Location in the JAD and/or JAR Manifest Page 38

40 Chapter 9 - Network APIs 9 Network APIs Network Connections The Motorola implementation of Networking APIs will support several network connections. The network connections necessary for Motorola implementation are the following: CommConnection for serial interface HTTP connection HTTPS connection Push registry SSL (secure socket) Datagram (UDP) Refer to Table 7 for Network API feature/class support for MIDP 2.0: Feature/Class Implementation All fields, methods, and inherited methods for the Connector class in the javax.microedition.io package Supported Mode parameter for the open () method in the Connector class READ, WRITE, the javax.microedition.io package READ_WRITE The timeouts parameter for the open () method in the Connector class of the javax.microedition.io package HttpConnection interface in the javax.microedition.io package Supported HttpsConnection interface in the javax.microedition.io package Supported SecureConnection interface in the javax.microedition.io package Supported SecurityInfo interface in the javax.microedition.io package Supported UDPDDatagramConnection interface in the javax.microedition.io package Supported Connector class in the javax.microedition.io.package Supported PushRegistry class in the javax.microedition.io package Supported Page 39

41 Chapter 9 - Network APIs CommConnection interface in the javax.microedition.io package Supported Dynamic DNS allocation through DHCP Supported HttpConnection interface in the javax.microedition.io.package. Supported HttpsConnection interface in the javaxmicroedition.io.package Supported SecureConnection interface in the javax.microedition.io.package Supported SecurityInfo Interface in the javax.microedition.io.package Supported UDPDatagramConnection interface in the javax.microedition.io.package Supported Table 7 Network API feature/class support for MIDP Code Sample 1 shows the implementation of Socket Connection: Socket Connection import javax.microedition.io.*; import java.io.*; import javax.microedition.midlet.*;... try { //open the connection and io streams sc = (SocketConnection)Connector.open ("socket:// Connector.READ_WRITE, true); is = sc[i].openinputstream(); os = sc[i].openoutputstream(); catch (Exception ex) { closeallstreams(); System.out.println("Open Failed: " + ex.getmessage()); if (os!= null && is!= null) { try { os.write(somestring.getbytes()); //write some data to server int bytes_read = 0; int offset = 0; int bytes_left = BUFFER_SIZE; //read data from server until done Page 40

42 Chapter 9 - Network APIs do { bytes_read = is.read(buffer, offset, bytes_left); if (bytes_read > 0) { offset += bytes_read; bytes_left -= bytes_read; while (bytes_read > 0); catch (Exception ex) { System.out.println("IO failed: "+ ex.getmessage()); finally { closeallstreams(i); //clean up Code Sample 1 Socket Connection User Permission The user of the handset will explicitly grant permission to add additional network connections. Indicating a Connection to the User When the java implementation makes any of the additional network connections, it will indicate to the user that the handset is actively interacting with the network. To indicate this connection, the network icon will appear on the handset's status bar as shown in Figure 10. Page 41

43 Chapter 9 - Network APIs Figure 10 Network Connections example Conversely, when the network connection is no longer used the network icon will be removed from the status bar. If the handset supports applications that run when the flip is closed, the network icon on the external display will be activated when the application is in an active network connection with the flip closed. Please note that this indication is done by the implementation. HTTPS Connection Motorola implementation supports a HTTPS connection on the MOTOROKR E6/E6e handset. Additional protocols that will be supported are the following: TLS protocol version 1.0 as defined in SSL protocol version 3.0 as defined in Code Sample 2 shows the implementation of HTTPS: HTTPS import javax.microedition.io.*; import java.io.*; import javax.microedition.midlet.*; try { hc[i] = (HttpConnection)Connector.open(" + url[i] + "/"); catch (Exception ex) { Page 42

44 Chapter 9 - Network APIs hc[i] = null; System.out.println("Open Failed: " + ex.getmessage()); if (hc[i]!= null) { try { is[i] = hc[i].openinputstream(); bytecounts[i] = 0; readlengths[i] = hc[i].getlength(); System.out.println("readLengths = " + readlengths[i]); if (readlengths[i] == -1) { readlengths[i] = BUFFER_SIZE; int bytes_read = 0; int offset = 0; int bytes_left = (int)readlengths[i]; do { bytes_read = is[i].read(buffer, offset, bytes_left); offset += bytes_read; bytes_left -= bytes_read; bytecounts[i] += bytes_read; while (bytes_read > 0); System.out.println("byte read = " + bytecounts[i]); catch (Exception ex) { System.out.println("Downloading Failed: "+ ex.getmessage()); numpassed = 0; finally { try { is[i].close(); is[i] = null; catch (Exception ex) { Page 43

45 Chapter 9 - Network APIs /** * close http connection */ if (hc[i]!= null) { try { hc[i].close(); catch (Exception ex) { hc[i] = null; Code Sample 2 HTTPS DNS IP The DNS IP will be flexed on or off (per operator requirement) under Java Settings as read only or as user-editable. In some instances, it will be flexed with an operator-specified IP address. Push Registry The push registry mechanism allows an application to register for notification events that are meant for the application. The push registry maintains a list of inbound connections. Mechanisms for Push Motorola implementation for push requires the support of certain mechanisms. The mechanisms that will be supported for push are the following: SMS push: an SMS with a port number associated with an application used to deliver the push notification. The formats for registering any of the above mechanisms will follow those detailed in JSR-118 specification. Page 44

46 Chapter 9 - Network APIs Push Registry Declaration The application descriptor file will include information about static connections that are needed by the MIDlet suite. If all static push declarations in the application descriptor cannot be fulfilled during the installation, the MIDlet suite will not be installed. The user will be notified of any push registration conflicts despite the mechanism. This notification will accurately reflect the error that has occurred. Push registration can fail as a result of an Invalid Descriptor. Syntax errors in the push attributes can cause a declaration error resulting in the MIDlet suite installation being cancelled. A declaration referencing a MIDlet class not listed in the MIDlet-<n> attributes of the same application descriptor will also result in an error and cancellation of the MIDlet installation. Two types of registration mechanisms will be supported. The registration mechanisms to be supported are the following: Registration during installation through the JAD file entry using a fixed port number Dynamically register using an assigned port number If the port number is not available on the handset, an installation failure notification will be displayed to the user while the error code 911 push is sent to the server. This error will cease the download of the application. Applications that wish to register with a fixed port number will use the JAD file to identify the push parameters. The fixed port implementation will process the MIDlet-Push-n parameter through the JAD file. Code Sample 3 shows the implementation of Push Registry: Push Registry Declaration import javax.microedition.lcdui.*; import javax.microedition.midlet.*; import javax.microedition.io.pushregistry; public class PushTest_1 extends MIDlet implements CommandListener{ public Display display; Page 45

47 Chapter 9 - Network APIs public public public public static static static static Form Form Form Form regform; unregform; mainform; messageform; public public public public static static static static Command Command Command Command public public public public static static static static TextField regconnection; TextField regfilter; ChoiceGroup registeredconnscg; String[] registeredconns; exitcommand; backcommand; unregcommand; regcommand; public static Command mc; public static Displayable ms; public PushTest_1(){ regconnection = new TextField("Connection port:", "1000", 32, TextField.PHONENUMBER); regfilter = new TextField("Filter:", "*", 32, TextField.ANY); display = Display.getDisplay(this); regform = new Form("Register"); unregform = new Form("Unregister"); mainform = new Form("PushTest_1"); messageform = new Form("PushTest_1"); exitcommand = new Command("Exit", Command.EXIT, 0); backcommand = new Command("Back", Command.BACK, 0); unregcommand = new Command("Unreg", Command.ITEM, 1); regcommand = new Command("Reg", Command.ITEM, 1); mainform.append("press \"Reg\" softkey to register a new connection.\n" + "Press \"Unreg\" softkey to unregister a connection."); mainform.addcommand(exitcommand); mainform.addcommand(unregcommand); mainform.addcommand(regcommand); mainform.setcommandlistener(this); regform.append(regconnection); regform.append(regfilter); Page 46

48 Chapter 9 - Network APIs regform.addcommand(regcommand); regform.addcommand(backcommand); regform.setcommandlistener(this); unregform.addcommand(backcommand); unregform.addcommand(unregcommand); unregform.setcommandlistener(this); messageform.addcommand(backcommand); messageform.setcommandlistener(this); public void pauseapp(){ protected void startapp() { display.setcurrent(mainform); public void destroyapp(boolean unconditional) { notifydestroyed(); public void showmessage(string s) { if(messageform.size()!= 0 ) messageform.delete(0); messageform.append(s); display.setcurrent(messageform); public void commandaction(command c, Displayable s) { if((c == unregcommand) && (s == mainform)){ mc = c; ms = s; new runthread().start(); if((c == regcommand) && (s == mainform)){ display.setcurrent(regform); if((c == regcommand) && (s == regform)){ mc = c; ms = s; Page 47

49 Chapter 9 - Network APIs new runthread().start(); if((c == unregcommand) && (s == unregform)){ mc = c; ms = s; new runthread().start(); if((c == backcommand) && (s == unregform )){ display.setcurrent(mainform); if((c == backcommand) && (s == regform )){ display.setcurrent(mainform); if((c == backcommand) && (s == messageform)){ display.setcurrent(mainform); if((c == exitcommand) && (s == mainform)){ destroyapp(false); public class runthread extends Thread{ public void run(){ if((mc == unregcommand) && (ms == mainform)){ try{ registeredconns = PushRegistry.listConnections(false); if(unregform.size() > 0) unregform.delete(0); registeredconnscg = new ChoiceGroup("Connections", ChoiceGroup.MULTIPLE, registeredconns, null); if(registeredconnscg.size() > 0) unregform.append(registeredconnscg); else unregform.append("no registered connections found."); display.setcurrent(unregform); catch (Exception e) { showmessage("unexpected " + e.tostring() + ": " + e.getmessage()); Page 48

50 Chapter 9 - Network APIs if((mc == regcommand) && (ms == regform)){ try{ PushRegistry.registerConnection("sms://:" + regconnection.getstring(), "Receive", regfilter.getstring()); showmessage("connection successfully registered"); catch (Exception e){ showmessage("unexpected " + e.tostring() + ": " + e.getmessage()); if((mc == unregcommand) && (ms == unregform)){ try{ if(registeredconnscg.size() > 0){ for(int i=0; i<registeredconnscg.size(); i++){ if(registeredconnscg.isselected(i)){ PushRegistry.unregisterConnection(registeredConnsCG. getstring(i)); registeredconnscg.delete(i); if(registeredconnscg.size() == 0){ unregform.delete(0); unregform.append("no registered connections found."); catch (Exception e) { showmessage("unexpected " + e.tostring() + ": " + e.getmessage()); WakeUp.java import import import import import import javax.microedition.midlet.*; javax.microedition.lcdui.*; javax.microedition.io.pushregistry; javax.microedition.rms.*; java.util.*; javax.microedition.io.*; Page 49

51 Chapter 9 - Network APIs public class WakeUp extends MIDlet implements CommandListener{ public public public public public static static static static static Display display; Form mainform; Command exitcommand; TextField tf; Command registercommand; public void startapp() { display = Display.getDisplay(this); mainform = new Form("WakeUp"); exitcommand = new Command("Exit", Command.EXIT, 0); registercommand = new Command("Register", Command.SCREEN, 0); tf = new TextField("Delay in seconds", "10", 10, TextField.NUMERIC); mainform.addcommand(exitcommand); mainform.addcommand(registercommand); mainform.append(tf); mainform.setcommandlistener(this); display.setcurrent(mainform); public void pauseapp() { public void destroyapp(boolean unconditional) { notifydestroyed(); public void commandaction(command c, Displayable s) { if((c == exitcommand) && (s == mainform)){ destroyapp(false); if(c == registercommand){ new regthread().start(); Page 50

52 Chapter 9 - Network APIs public class regthread extends Thread{ public void run(){ try { long delay = Integer.parseInt(tf.getString()) * 1000; long curtime = (new Date()).getTime(); System.out.println(curTime + delay); PushRegistry.registerAlarm("WakeUp", curtime + delay); mainform.append("alarm registered successfully"); catch (NumberFormatException nfe) { mainform.append("failed\ncan not decode delay " + nfe); catch (ClassNotFoundException cnfe) { mainform.append("failed\nregisteralarm thrown " + cnfe); catch (ConnectionNotFoundException cnfe) { mainform.append("failed\nregisteralarm thrown " + cnfe); SMS_send.java import import import import import javax.microedition.lcdui.*; javax.microedition.midlet.*; javax.microedition.io.pushregistry; javax.wireless.messaging.*; javax.microedition.io.*; public class SMS_send extends MIDlet implements CommandListener{ public Display display; public static Form messageform; public static Form mainform; public static Command exitcommand; Page 51

53 Chapter 9 - Network APIs public static Command backcommand; public static Command sendcommand; public static TextField address_tf; public static TextField port_tf; public static TextField message_text_tf; String[] binary_str = {"Send BINARY message"; public static ChoiceGroup binary_cg; byte[] binary_data = {1, 2, 3, 4, 5, 6, 7, 8, 9; String address; String text; MessageConnection conn = null; TextMessage txt_message = null; BinaryMessage bin_message = null; public SMS_send(){ address_tf = new TextField("Address:", "", 32, TextField.PHONENUMBER); port_tf = new TextField("Port:", "1000", 32, TextField.PHONENUMBER); message_text_tf = new TextField("Message text:", "test message", 160, TextField.ANY); binary_cg = new ChoiceGroup(null, Choice.MULTIPLE, binary_str, null); display = Display.getDisplay(this); messageform = new Form("SMS_send"); mainform = new Form("SMS_send"); exitcommand = new Command("Exit", Command.EXIT, 0); backcommand = new Command("Back", Command.BACK, 0); sendcommand = new Command("Send", Command.ITEM, 1); mainform.append(address_tf); mainform.append(port_tf); mainform.append(message_text_tf); mainform.append(binary_cg); mainform.addcommand(exitcommand); mainform.addcommand(sendcommand); mainform.setcommandlistener(this); messageform.addcommand(backcommand); Page 52

54 Chapter 9 - Network APIs messageform.setcommandlistener(this); public void pauseapp(){ protected void startapp() { display.setcurrent(mainform); public void destroyapp(boolean unconditional) { notifydestroyed(); public void showmessage(string s) { if(messageform.size()!= 0 ) messageform.delete(0); messageform.append(s); display.setcurrent(messageform); public void commandaction(command c, Displayable s) { if((c == backcommand) && (s == messageform)){ display.setcurrent(mainform); if((c == exitcommand) && (s == mainform)){ destroyapp(false); if((c == sendcommand) && (s == mainform)){ address = "sms://" + address_tf.getstring(); if(port_tf.size()!= 0) address += ":" + port_tf.getstring(); text = message_text_tf.getstring(); new send_thread().start(); public class send_thread extends Thread{ public void run(){ try{ conn = (MessageConnection) Connector.open(address); if(!binary_cg.isselected(0)){ txt_message = (TextMessage) conn.newmessage(messageconnection.text_message); txt_message.setpayloadtext(text); Page 53

55 Chapter 9 - Network APIs conn.send(txt_message); else { bin_message = (BinaryMessage) conn.newmessage(messageconnection.binary_message); bin_message.setpayloaddata(binary_data); conn.send(bin_message); conn.close(); showmessage("message sent"); catch (Throwable t) { showmessage("unexpected " + t.tostring() + ": " + t.getmessage()); Code Sample 3 Push Registry Delivery of a Push Message A push message intended for a MIDlet on the MOTOROKR E6/E6e handset will handle the following interactions: MIDlet running while receiving a push message - if the application receiving the push message is currently running, the application will consume the push message without user notification. No MIDlet suites running - if no MIDlets are running, the user will be notified of the incoming push message and will be given the option to run the intended application as shown in Figure 11. Page 54

56 Chapter 9 - Network APIs Figure 11 Intend Application Run Option Push registry with Alarm/Wake-up time for application - push registry supports one outstanding wake-up time per MIDlet in the current suite. An application will use the TimerTask notification of time-based events while the application is running. Another MIDlet suite is running during an incoming push - if another MIDlet is running, the user will be presented with an option to launch the application that had registered for the push message. If the user selects the launch, the current MIDlet is terminated. Stacked push messages - it is possible for the handset to receive multiple push messages at one time while the user is running a MIDlet. The user will be given the option to allow the MIDlets to end and new MIDlets to begin. The user will be given the ability to read the messages in a stacked manner (stack of 5 supported), and if not read, the messages should be discarded. No applications registered for push - if there are no applications registered to handle this event, the incoming push message will be ignored. Deleting an Application Registered for Push If an application registered in the Push Registry is deleted, the corresponding push entry will be deleted, making the PORT number available for future Push Registrations. Page 55