User’s Guide Sun JavaTM Wireless Toolkit for CLDC Version 2.5.2 Sun Microsystems, Inc. www.sun.com v252 September 2007 Copyright © 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, Javadoc, Java Community Process, JCP,JDK, JRE, J2ME, and J2SE are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. OpenGL is a registered trademark of Silicon Graphics, Inc. Products covered by and information contained in this service manual are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright © 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés. Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie inclus dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plus des brevets américains listés à l'adresse http://www.sun.com/patents et un ou les brevets supplémentaires ou les applications de brevet en attente aux Etats - Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence. Cette distribution peut comprendre des composants développés par des tierces parties. Sun, Sun Microsystems, le logo Sun, Java, Javadoc, Java Community Process, JCP,JDK, JRE, J2ME, et J2SE sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Ètats-Unis et dans d'autres pays. OpenGL est une marque déposée de Silicon Graphics, Inc. Les produits qui font l'objet de ce manuel d'entretien et les informations qu'il contient sont regis par la legislation americaine en matiere de controle des exportations et peuvent etre soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucleaires, des missiles, des armes biologiques et chimiques ou du nucleaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou reexportations vers des pays sous embargo des Ètats-Unis, ou vers des entites figurant sur les listes d'exclusion d'exportation americaines, y compris, et de maniere non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une facon directe ou indirecte, aux exportations des produits ou des services qui sont regi par la legislation americaine en matiere de controle des exportations et la liste de ressortissants specifiquement designes, sont rigoureusement interdites. LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON. Contents Preface xiii 1. Introduction 1–1 1.1 About the Multiple User Environment 1–1 1.1.1 The Installation Directory and the Working Directory 1–1 1.1.2 Working Directory Files 1–2 1.2 Quick Start 1–4 1.3 Toolkit Components 1–5 1.4 Toolkit Features 1–6 1.5 Toolkit Updates 1–6 1.6 Supported Technology 1–7 2. Developing MIDlet Suites 2–1 2.1 About Projects 2–1 2.2 Simple Development Cycle 2–3 2.2.1 Edit Source Code 2–4 2.2.2 Build 2–4 2.2.3 Run 2–5 2.3 Full Development Cycle 2–7 2.3.1 Package 2–8 iii 2.3.2 Install 2–8 2.3.3 Run 2–12 2.4 Creating a Project from a MIDlet Suite 2–13 2.5 Using an Obfuscator 2–14 2.5.1 Installing ProGuard 2–14 2.5.2 Using ProGuard 2–14 2.6 Using a Debugger 2–15 2.7 Deploying Applications on a Web Server 2–16 3. Working With Projects 3–1 3.1 Selecting APIs 3–1 3.2 Changing MIDlet Suite Attributes 3–3 3.3 Manipulating MIDlets 3–5 3.4 Using the Push Registry 3–6 3.5 Setting Up Content Handlers 3–7 3.6 Project Directory Structure 3–11 3.7 Using Third-Party Libraries 3–11 3.7.1 Using External APIs 3–12 3.7.2 Third-Party Libraries for One Project 3–13 3.7.3 Third-Party Libraries for All Projects 3–14 3.8 Configuring the Wireless Toolkit 3–14 3.8.1 Changing the Console Font 3–14 3.8.2 Setting the Application Directory 3–15 3.8.3 Setting the javac Encoding Property 3–15 3.8.4 Working with Revision Control Systems 3–15 4. Using the Emulator 4–1 4.1 Emulator Skins 4–1 4.2 Emulator Controls 4–2 iv Sun Java Wireless Toolkit for CLDC User’s Guide • September 2007 4.3 Setting Emulator Preferences 4–3 4.3.1 Network Proxies 4–3 4.3.2 Storage Sizes 4–4 4.3.2.1 Persistent Storage 4–5 4.3.2.2 Heap Size 4–5 4.3.3 Adjusting Emulator Performance 4–6 4.4 Pausing and Resuming 4–8 4.5 Running the Emulator Solo 4–8 4.6 Using Third-Party Emulators 4–9 5. Monitoring Applications 5–1 5.1 Using the Profiler 5–1 5.1.1 Call Graph 5–3 5.1.2 Execution Time and Number of Calls 5–4 5.1.3 Saving and Loading Profiler Information 5–4 5.2 Using the Memory Monitor 5–4 5.2.1 Saving and Loading Memory Monitor Information 5–7 5.3 Using the Network Monitor 5–7 5.3.1 Filtering Messages 5–8 5.3.2 Sorting Messages 5–9 5.3.3 Saving and Loading Network Monitor Information 5–10 5.3.4 Clearing the Message Tree 5–10 6. Security and MIDlet Signing 6–1 6.1 Permissions 6–1 6.2 Selecting the Security Policy 6–3 6.2.1 MSA Protection Domains 6–3 6.2.2 Java for the Wireless Toolkit Industry Protection Domains 6–4 6.3 Signing a MIDlet Suite 6–4 Contents v 6.4 Managing Keys 6–5 6.4.1 Creating a New Key Pair 6–5 6.4.2 Getting Real Keys 6–7 6.4.3 Importing an Existing Key Pair 6–7 6.4.4 Removing a Key Pair 6–8 6.5 Managing Certificates 6–8 6.5.1 Enabling and Disabling Certificates 6–9 6.5.2 Importing Certificates 6–9 6.5.3 Removing Certificates 6–10 6.6 USB Token Support 6–10 6.6.1 Installing USB Token Drivers 6–10 6.6.2 Using the USB Token 6–11 7. Using the Wireless Messaging API 7–1 7.1 Setting Emulator Phone Numbers 7–1 7.2 Simulating an Unreliable Network 7–3 7.3 Sending Messages With the WMA Console 7–3 7.3.1 Sending a Text SMS Message 7–4 7.3.2 Sending a Binary SMS Message 7–5 7.3.3 Sending Text or Binary CBS Messages 7–6 7.3.4 Sending MMS Messages 7–7 7.4 Receiving Messages in the WMA Console 7–9 7.5 Using the Network Monitor with WMA 7–9 8. Using the Mobile Media API 8–1 8.1 Supported Formats and Protocols 8–1 8.2 Adaptive Multi-Rate (AMR) Content 8–2 8.2.1 Windows 8–2 8.2.2 Linux 8–2 vi Sun Java Wireless Toolkit for CLDC User’s Guide • September 2007 8.2.2.1 Enabling AMR Support 8–2 8.2.2.2 AMR Format Support 8–3 8.3 Using MediaControlSkin 8–4 8.4 Media Capture 8–4 8.5 Well-Behaved MIDlets 8–4 8.6 Ring Tones 8–5 8.6.1 Download Ring Tones 8–5 8.6.2 Ring Tone Formats 8–5 9. Working With Mobile Graphics 9–1 9.1 Using the Mobile 3D Graphics API 9–1 9.1.1 Immediate Mode 9–2 9.1.2 Retained Mode 9–2 9.1.3 Trading Quality for Speed 9–2 9.1.4 Creating Mobile 3D Graphics Content 9–3 9.2 Rendering Scalable Vector Graphics Content 9–3 9.3 OpenGL® ES Overview 9–4 10.