Sprint Userguide

User’s Guide

Sprint Wireless Toolkit 3.2Powered by Java Technology

Part No. sprintwtk32December 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. Inparticular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed athttp://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 andapplicable 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, Jini, Solaris, J2SE, Java SE, J2ME, Java ME, Netbeans, java, the Duke logo and the Java Coffee Cuplogo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

The Adobe logo is a registered trademark of Adobe Systems, Incorporated.

Sprint, the "Going Forward" logo, and other trademarks are trademarks of Sprint Nextel.

This product is covered and 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 orreexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the deniedpersons and specially designated nationals lists is strictly prohibited.

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é intellectuels relatifs à la technologie incorporée dans le produit qui est décrit dans cedocument. 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 etdans 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, Jini, Solaris, J2SE, Java SE, J2ME, Java ME, Netbeans, java, le logo Duke et le logo Java Coffee Cup sontdes marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays.

Le logo Adobe est une marque déposée de Adobe Systems, Incorporated.

Sprint, the "Going Forward" logo, and other trademarks are trademarks of Sprint Nextel .

Ce produit est soumis à la législation américaine en matière de contrôle des exportations et peut être soumis à la règlementation en vigueurdans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires,desmissiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Lesexportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportationaméricaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directeou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en matière de contrôle des exportations etla liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.

http://www.sun.com/patents




Contents

Preface xiii

1. Introduction 1–1

1.1 Quick Start 1–1

1.2 The Tools in the Toolkit 1–2

1.3 Toolkit Features 1–3

1.4 Supported Technology 1–4

2. Developing MIDlet Suites 2–1

2.1 About Projects 2–1

2.2 The Simple Development Cycle 2–4

2.2.1 Source Code 2–5

Open With 2–5

2.2.2 Build 2–6

2.2.3 Run 2–7

2.3 The Full Development Cycle 2–8

2.3.1 Package 2–9

2.3.2 Install 2–10

2.3.3 Run 2–12

2.4 Opening a Project in the Sprint IDE 2–13

iii

2.5 Creating a Project from a MIDlet Suite 2–14

2.6 Using an Obfuscator 2–15

2.7 Using a Debugger 2–17

2.8 Deploying Applications on a Web Server 2–20

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–7

3.5 Project Directory Structure 3–8

3.6 Using Third-Party Libraries 3–8

3.6.1 Using External APIs 3–9

3.6.2 Third-Party Libraries for One Project 3–11

3.6.3 Third-Party Libraries for All Projects 3–11

3.7 Configuring KToolbar 3–12

3.7.1 Changing the Console Font 3–12

3.7.2 Setting the Application Directory 3–12

3.7.3 Setting the javac Encoding Property 3–12

3.7.4 Working with Revision Control Systems 3–13

4. Using the Emulator 4–1

4.1 Emulator Skins 4–1

4.2 Emulator Controls 4–2

4.3 Setting Emulator Preferences 4–6

4.3.1 Network Proxies 4–6

4.3.2 Heap Size 4–7

4.3.3 Storage and Cleaning 4–7

4.3.4 Adjusting Emulator Performance 4–8

iv Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

4.4 Pausing and Resuming 4–10

4.5 Multitasking VM and the Emulator 4–10

4.6 Running the Emulator Solo 4–12

4.7 Using Third Party Emulators 4–13

4.8 Additional Sprint Features 4–13

4.8.1 Editing Source Files or Resources 4–13

4.8.2 Device Selection 4–17

4.8.3 Setting the Classpath 4–18

4.8.4 Console Message Colors 4–20

4.8.5 Zoom In 4–21

4.8.6 Additional Media Types 4–22

4.8.6.1 QuickTime Plug-In 4–22

4.8.6.2 Qcelp Media Type 4–23

5. Monitoring Applications 5–1

5.1 Using the Profiler 5–1

5.1.1 The Call Graph 5–4

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 Monty Memory Observe Tool 5–5

5.3 Using the Network Monitor 5–9

5.3.1 Filtering Messages 5–11

5.3.2 Sorting Messages 5–11

5.3.3 Saving and Loading Network Monitor Information 5–12

5.3.4 Clearing the Message Tree 5–12

5.4 Tracing 5–12

6. Working With a Real Device 6–1

6.1 GCD File Creator 6–1

Contents v

6.1.1 Creating a New GCD File 6–2

6.1.2 Editing a GCD File 6–3

6.1.3 Possible GCD Properties and Property Values 6–3

6.2 Sprint JAD Multitasking VM Attributes 6–8

6.3 COMM Terminal 6–10

7. Security and MIDlet Signing 7–1

7.1 Permissions 7–1

7.2 Setting Security Preferences 7–3

7.2.1 MSA Protection Domains 7–4

7.2.2 Java for the Wireless Toolkit Industry Protection Domains 7–4

7.3 Signing a MIDlet Suite 7–5

7.4 Signing a GCD File 7–6

7.5 Managing Keys 7–8

7.5.1 Creating and Using Keystores 7–8

7.5.2 Creating a New Key Pair 7–10

7.5.3 Getting Real Keys 7–12

7.5.4 Removing a Key Pair 7–13

7.6 Managing Certificates 7–13

7.6.1 Enabling and Disabling Certificates 7–14

7.6.2 Importing Certificates 7–15

7.6.3 Removing Certificates 7–15

8. Using the Wireless Messaging API 8–1

8.1 Setting Emulator Phone Numbers 8–1

8.2 Simulating an Unreliable Network 8–2

8.3 Sending Messages With the WMA Console 8–3

8.3.1 Sending a Text SMS Message 8–4

8.3.2 Sending a Binary SMS Message 8–5

vi Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

8.3.3 Sending MMS Messages 8–6

8.4 Receiving Messages in the WMA Console 8–8

9. Using the Mobile Media API 9–1

9.1 Supported Formats and Protocols 9–1

9.2 Media Capture 9–2

9.3 Well-Behaved MIDlets 9–3

10. Working With Mobile Graphics 10–1

10.1 Rendering Scalable Vector Graphics (SVG) Content 10–1

10.2 Using the Mobile 3D Graphics API 10–2

10.2.1 Immediate Mode 10–2

10.2.2 Retained Mode 10–2

10.2.3 Trading Quality for Speed 10–3

10.2.4 Creating Mobile 3D Graphics Content 10–3

11. Using the PIM and FileConnection APIs 11–1

11.1 The FileConnection API 11–1

11.2 The PIM API 11–3

12. Using the Bluetooth API 12–1

12.1 Bluetooth Simulation Environment 12–1

12.2 Setting Bluetooth Preferences 12–1

12.2.1 Bluetooth Internal Properties 12–2

12.2.2 Bluetooth System Properties 12–2

12.2.3 Bluetooth BCC Properties 12–3

13. Using Web Services 13–1

14. Using the Location API 14–1

14.1 Setting the Emulator’s Location at Runtime 14–1

Contents vii

14.2 Configuring the Location Provider 14–3

14.3 Setting Up Landmarks 14–4

15. Using SATSA 15–1

15.1 Card Slots in the Emulator 15–2

15.2 Using the Java Card Platform Simulator 15–2

15.3 Adjusting Access Control 15–3

15.3.1 Specifying PIN Properties 15–3

15.3.2 Specifying Application Permissions 15–4

15.3.3 Access Control File Example 15–6

16. Using SIP 16–1

16.1 Understanding the Registrar and Proxy 16–1

16.2 SIP Settings 16–2

16.3 SIP Proxy Server and Registrar 16–2

17. Working with the Payment API 17–1

17.1 Project Settings for Payment 17–1

17.2 Editing Payment Attributes Directly 17–4

17.3 Payment Preferences 17–4

17.4 Viewing Transaction History 17–5

17.5 Monitoring Payments 17–7

18. Using the Mobile Internationalization API 18–1

18.1 Setting the Emulator’s Locale 18–1

18.2 Viewing Application Resources 18–1

18.3 Working With Locales 18–3

18.4 Working With Resource Files 18–3

18.5 Working With Resources 18–3

19. Working with the Sprint API 19–1

viii Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

19.1 External Canvas 19–1

19.2 Sprint Location 19–1

19.3 Muglet 19–4

19.3.1 Writing Code Using the Muglet 19–6

19.4 System 19–7

A. Application Demonstrations A–1

A.1 Overview A–1

A.2 General Instructions A–4

A.3 Advanced Multimedia Supplements A–7

A.4 Bluetooth Demo A–9

A.5 CHAPIDemo A–10

A.6 CityGuide A–13

A.7 DebugApp A–15

A.8 Demo3D A–17

A.8.1 Life3D A–17

A.8.2 PogoRoo A–18

A.8.3 retainedmode A–19

A.9 Demos A–20

A.9.1 Colors A–20

A.9.2 Properties A–20

A.9.3 Http A–21

A.9.4 FontTestlet A–22

A.9.5 Stock A–22

A.9.5.1 Working with Settings A–22

A.9.5.2 Stock Tracker A–23

A.9.5.3 What If? A–23

A.9.5.4 Alerts A–23

A.9.6 Tickets A–24

Contents ix

A.9.7 ManyBalls A–25

A.10 GoSIP A–25

A.11 i18nDemo A–27

A.12 JBricks A–29

A.13 JSR172Demo A–33

A.14 KeyEventDemo A–33

A.15 LX260-Test-S05 A–34

A.16 MobileMediaAPI A–36

A.16.1 Simple Tones A–36

A.16.2 Simple Player A–36

A.16.3 Pausing Audio Test A–40

A.16.4 Attributes for MobileMediaAPI A–40

A.17 MP4Player Demo A–40

A.18 Muglet Demo A–43

A.19 Multitasking VM Demo A–45

A.20 Network Demo A–47

A.20.1 Socket Demo A–47

A.20.2 Datagram Demo A–48

A.21 ObexDemo A–49

A.22 PDAPDemo A–50

A.22.1 Browsing Files A–51

A.22.2 Browsing Files A–51

A.22.3 The PIM API A–53

A.23 Razr2Demo A–55

A.24 RecordStoreDemo A–56

A.25 SATSADemos A–62

A.25.1 APDUMIDlet A–62

A.25.2 SATMIDlet A–63

x Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

A.25.3 CryptoMIDlet A–63

A.25.4 MohairMIDlet A–63

A.26 SATSAJCRMIDemo A–64

A.27 SIPDemo A–64

A.28 SprintDemo A–65

A.28.1 External Canvas Demo A–65

A.28.2 SystemStates Demo A–66

A.28.3 Media Demo A–68

A.29 SVGContactList A–69

A.30 SVGDemo A–70

A.30.1 SVG Browser A–71

A.30.2 Render SVG Image A–71

A.30.3 Play SVG Animation A–71

A.30.4 Create SVG Image From Scratch A–72

A.30.5 Bouncing Balls A–72

A.30.6 Optimized Menu A–72

A.30.7 Picture Decorator A–73

A.30.8 Location-Based Service A–75

A.31 UIDemo A–76

A.32 VirtualKeypadDemo A–77

A.33 WMADemo A–79

B. Command Line Reference B–1

B.1 Prerequisites B–1

B.2 The Development Cycle B–1

B.2.1 Build B–2

B.2.2 Package B–3

B.2.3 Run B–4

B.2.4 Debugging B–5

Contents xi

B.3 Launching Toolkit GUI Components B–6

B.4 Setting Emulator Preferences B–6

B.5 Using Security Features B–8

B.5.1 Changing the Emulator’s Default Protection Domain B–9

B.5.2 Signing MIDlet Suites B–9

B.5.3 Managing Certificates B–10

C. Localization C–1

C.1 Locale Setting C–1

C.2 Emulated Locale C–2

C.3 Character Encodings C–2

C.4 Font Support in the Default Emulator C–3

Index Index–1

xii Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

Preface

This document describes how to work with Sprint Wireless Toolkit 3.2 Powered bySun Java Technology (the toolkit).

Who Should Use This BookThis guide is intended for developers creating Mobile Information Device Profile(MIDP) applications with the toolkit. You should already understand how to useMIDP and the Connected Limited Device Configuration (CLDC).

If you need help getting started with Java programming, try the New to Java Center:

http://java.sun.com/learning/new2java/

For an introduction to MIDP programming, read Learning Path: Getting Started withMIDP 2.0:

http://developers.sun.com/techtopics/mobility/learn/midp/midp20/

Related DocumentationThis section lists related specifications. Although specifications are definitive, theyare not always the most accessible kind of information. For a variety ofdeveloper-centered articles, try Sun’s mobility web site:

http://developers.sun.com/techtopics/mobility/

Preface xiii







TABLE P-1 Related Documentation

Topic Title

Release Notes Sprint Wireless Toolkit 3.2 Powered by Sun JavaTechnology Release Notes

CLDC 1.0 - JSR 30 J2ME Connected Limited Device Configuration

MIDP 1.0 - JSR 37 Mobile Information Device Profile for the J2ME™Platform

PDAP Optional Packages - JSR 75 PDA Optional Packages for the J2ME Platform

Bluetooth and OBEX - JSR 82 Java APIs for Bluetooth

MIDP 2.1 - JSR 118 Mobile Information Device Profile 2.0(Final Release 2 is referred to as MIDP 2.1)

WMA 1.1 - JSR 120 Wireless Messaging API 1.1

CLDC 1.1 - JSR 139 J2ME Connected Limited Device Configuration

MMAPI - JSR 135 Mobile Media API

J2ME Web Services - JSR 172 J2ME Web Services Specification

SATSA - JSR 177 Security and Trust Services APIs for J2ME

Location API - JSR 179 Location API for J2ME

SIP API - JSR 180 SIP API for J2ME

Mobile 3D Graphics - JSR 184 Mobile 3D Graphics API for J2ME

JTWI - JSR 185 Java Technology for the Wireless Industry

WMA 2.0 - JSR 205 Wireless Messaging API (WMA)

CHAPI 1.0 - JSR 211 Content Handler API

SVG API - JSR 226 Scalable 2D Vector Graphics API for J2ME

Payment API (PAPI) - JSR 229 Payment API

AMMS - JSR 234 Advanced Multimedia Supplements

MIA- JSR 238 Mobile Internationalization API

MSA - JSR 248 Mobile Service Architecture

xiv Book Title without trademarks, or an abbreviated book title • December 2007

How This Book Is OrganizedThis guide contains the following chapters and appendixes:

Chapter 1 introduces the Sprint Wireless Toolkit and the development features itprovides.

Chapter 2 describes the development processes for creating and running MIDlets.

Chapter 3 explains how to work with projects in KToolbar. You will learn how toadjust project properties, manipulate MIDlets, work with the push registry, andunderstand the project directory structure.

Chapter 4 describes the emulator and explains how to adjust its options and takeadvantage of its many features.

Chapter 5 shows how you can examine the performance of your application usingthe method profiler, memory monitor, and network monitor.

Chapter 6 describes how to use the toolkit with a real device.

Chapter 7 describes how to sign MIDlet suites and manage keys and certificates.

Chapter 8 details support for running and testing wireless messaging applications.

Chapter 9 explains how the toolkit supports the Mobile Media API.

Chapter 10 contains information about developing 3D graphics content.

Chapter 11 describes how the toolkit implements access to local files and personalinformation like contacts and calendar appointments.

Chapter 12 covers the toolkit’s Bluetooth and OBEX simulation environment.

Chapter 13 shows how to use the web services stub generator.

Chapter 14 describes how to work with the emulator’s location features.

Chapter 15 discusses the toolkit’s support for SATSA.

Chapter 16 discusses the toolkit’s support for the SIP API for J2ME.

Chapter 17 describes the toolkit’s Payment API features

Chapter 18 describes how to manage resources for the Mobile InternationalizationAPI.

Chapter 19 describes how to work with the Sprint APIs.

Preface xv

Appendix A describes the application demonstrations that are included in thetoolkit.

Appendix B explains how to use the functionality of the toolkit from the commandline.

Appendix C describes localization features in the toolkit.

Typographic Conventions

Accessing Sun Documentation OnlineThe following sites provide technical documentation related to Java technology.

http://developer.sun.com/

http://java.sun.com/docs/

TABLE P-2

Typeface Meaning Examples

AaBbCc123 The names of commands, files,and directories; on-screencomputer output

Edit your .login file.Use ls -a to list all files.% You have mail.

AaBbCc123 What you type, whencontrasted with on-screencomputer output

% su

Password:

AaBbCc123 Book titles, new words orterms, words to beemphasized

Command-line variable;replace with a literal value

Read Chapter 6 in the User’s Guide.These are called class options.You must be superuser to do this.

To delete a file, type: rm filename

AaBbCc.dir Variable file names anddirectories.

In the book, toolkit always refers to theinstallation directory of the Sprint WirelessToolkit.

xvi Book Title without trademarks, or an abbreviated book title • December 2007





We Welcome Your CommentsWe are interested in improving our documentation and welcome your commentsand suggestions. You can email your comments to us at:

[email protected]

Preface xvii

[email protected]

mailto:[email protected]

xviii Book Title without trademarks, or an abbreviated book title • December 2007

CHAPTER 1

Introduction

This book describes how to use Sprint Wireless Toolkit 3.2 - Powered by JavaTechnology (the toolkit).

The toolkit is a set of tools that makes it possible to create applications for mobilephones and other wireless devices. Although it is based on the Mobile InformationDevice Profile (MIDP) 2.1, the toolkit also supports many optional packages, makingit a widely capable development toolkit.

1.1 Quick StartIf you’d like to get started right away, try the demonstration applications that areincluded with the toolkit.

To run the demonstrations, start KToolbar. On Microsoft Windows choose Start >Programs > Sprint Wireless Toolkit 3.2 - Powered by Java Technology > KToolbar.1You see a window like that shown in FIGURE 1-1.

1. Depending on how Microsoft Windows is configured, you might need to choose Start > All Programs insteadof Start > Programs.

1-1

FIGURE 1-1 The KToolbar Window

To open a demonstration application, click the Open Project... button.

A window displays a list of projects. Pick a project and click the Open Project buttonat the bottom of the window.

The demonstration application opens. Press the Run button. The emulator pops uprunning the application.

Most demonstrations are self-explanatory, but some have additional instructions. SeeAppendix A for additional details.

All the source code for the demonstration applications is available in the toolkit\appsdirectory. Each demonstration has its own project directory. Inside the projectdirectory, the source files are in the src directory. For example, the source code forthe games demonstration is in toolkit\apps\games\src directory.

1.2 The Tools in the ToolkitThe toolkit has three main components:

■ KToolbar automates many of the tasks involved in creating MIDP applications.

■ The emulator is a simulated mobile phone. It is useful for testing MIDPapplications.

1-2 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

■ A collection of utilities provides other useful functionality, including a textmessaging console and cryptographic utilities.

KToolbar is the center of the toolkit. You can use it to build applications, launch theemulator, and start the utilities. Alternately, the emulator and utilities can be run bythemselves, which is useful in many situations. If you want to demonstrate MIDPapplications, for example, it’s useful to run the emulator by itself.

The only additional tool you need is a text editor for editing source code.

1.3 Toolkit FeaturesThe toolkit supports the creation of MIDP applications with the following mainfeatures:

■ Building and packaging: You write the source code and the toolkit takes care ofthe rest. With the push of a button, the toolkit compiles the source code,preverifies the class files, and packages a MIDlet suite.

■ Running and monitoring: You can run a MIDlet suite directly in the emulator orinstall it using a process that resembles application installation on a real device. Amemory monitor, network monitor, and method profiler are provided to analyzethe operation of your MIDlets.

■ MIDlet suite signing: The toolkit contains tools for cryptographically signingMIDlet suites. This is useful for testing the operation of MIDlets in differentprotection domains.

Chapter 1 Introduction 1-3

1.4 Supported TechnologyThe toolkit supports many standard Application Programming Interfaces (APIs)defined through the Java Community Process (JCP). TABLE 1-1 shows the APIs andincludes links to the specifications.

TABLE 1-1 Supported JCP APIs in the Sprint Wireless Toolkit 3.2

JSRAPI

NameURL

JSR 75PIM and File

PDA Optional Packages for the J2ME Platformhttp://jcp.org/en/jsr/detail?id=75

JSR 82Bluetooth and OBEX

Java APIs for Bluetoothhttp://jcp.org/en/jsr/detail?id=82

JSR 118MIDP 2.1

Mobile Information Device Profilehttp://jcp.org/en/jsr/detail?id=118

JSR 120WMA 1.1

Wireless Messaging APIhttp://jcp.org/en/jsr/detail?id=120

JSR 135MMAPI 1.1

Mobile Media APIhttp://jcp.org/en/jsr/detail?id=135

JSR 139CLDC 1.1

Connected Limited Device Configurationhttp://jcp.org/en/jsr/detail?id=139

JSR 172Web Services

J2ME Web Services Specificationhttp://jcp.org/en/jsr/detail?id=172

JSR 177SATSA

Security and Trust Services API for J2MEhttp://jcp.org/en/jsr/detail?id=177

JSR 179Location

Location API for J2MEhttp://jcp.org/en/jsr/detail?id=179

JSR 180SIP

SIP API for Java MEhttp://jcp.org/en/jsr/detail?id=180

JSR 1843D Graphics

Mobile 3D Graphics API for J2MEhttp://jcp.org/en/jsr/detail?id=184

JSR 185JTWI 1.0

Java Technology for the Wireless Industryhttp://jcp.org/en/jsr/detail?id=185

JSR 205WMA 2.0

Wireless Messaging APIhttp://jcp.org/en/jsr/detail?id=205


http://jcp.org/en/jsr/detail?id=82


























JSR 211CHAPI

Content Handler APIhttp://jcp.org/en/jsr/detail?id=211

JSR 226SVG

Scalable 2D Vector Graphics for J2MEhttp://jcp.org/en/jsr/detail?id=226

JSR 229PAPI

Payment APIhttp://jcp.org/en/jsr/detail?id=229

JSR 234AMMS

Advanced Multimedia Supplementshttp://jcp.org/en/jsr/detail?id=234

JSR 238MIA

Mobile Internationalization APIhttp://jcp.org/en/jsr/detail?id=238

JSR 248MSA

Mobile Service Architecturehttp://jcp.org/en/jsr/detail?id=248

TABLE 1-1 Supported JCP APIs in the Sprint Wireless Toolkit 3.2 (Continued)

JSRAPI

NameURL

Chapter 1 Introduction 1-5












CHAPTER 2

Developing MIDlet Suites

This chapter describes how you can use the Sprint Wireless Toolkit 3.2 (the toolkit)to create applications. It begins with a description of toolkit projects, then worksthrough the development process.

When creating MIDlet suite applications you are likely to follow one of two basicdevelopment cycles. The first cycle described in this chapter is quick and simple.You might use it in your initial development. The second cycle is longer, but allowsfor more comprehensive and realistic testing.

Toward the end of the chapter, read about how to use the toolkit with advanceddevelopment tools like an obfuscator and a debugger. A final section brieflydescribes how to configure a web server to serve MIDP applications.

2.1 About ProjectsIn the toolkit, MIDlet suites are organized into projects, where the end result of oneproject is one MIDlet suite. A project contains all of the files that are used to build aMIDlet suite, including Java source files, resource files, and the MIDlet descriptor.

The toolkit works on one project at a time. You can create a new project or open anexisting project.

In this chapter you work with a very simple example project. As you read abouteach step in the development cycles, you can work along in the toolkit.

To create a new project, first start KToolbar. On Microsoft Windows, choose Start >Programs > Sprint Wireless Toolkit 3.2 - Powered by Java Technology > KToolbar.1You see the KToolbar window.

1. Depending on how Microsoft Windows is configured, you might need to choose Start > All Programs insteadof Start > Programs.

2-1

FIGURE 2-1 The KToolbar Window

Click New Project... An appropriate directory is supplied by default. Enter theProject Name. Leave the Package Name field empty. In the MIDlet Class Name field,enter TinyMIDlet. Uncheck the Generate sample MIDlet box. Click Create Project.


FIGURE 2-2 Creating a New Project

The Settings window opens with API Selection displayed so that you can set up thebuild environment for the project. The default options are fine for this example, soclick OK to dismiss the window. In the KToolbar console, you see some messagestelling you exactly where to store the source code and resource files for this project.

Chapter 2 Developing MIDlet Suites 2-3

FIGURE 2-3 File Locations in the Console

2.2 The Simple Development CycleThe simple development cycle looks like this:

Edit source code > Build > Run

1. Edit source code. In this step, you create Java source files and resource files thatare used by your application.

2. Build. The toolkit compiles and preverifies your Java source files.

3. Run. The compiled Java class files are run on the emulator.

If an error occurs when the toolkit attempts to compile your source files, go back andedit them again. If you find a bug when you are testing your application in theemulator, edit the source files to fix the bug.

Now that you understand the simple development cycle at a high level, the rest ofthis section illustrates how you can accomplish each step using the toolkit.it


2.2.1 Source CodeYou can use the text editor of your choice to create and edit source code files. (If youdon’t have a favorite text editor, try jEdit, at http://jedit.org/.)

If you are following along with the example project, create a new Java source fileTinyMIDlet.java. It should be saved in the source directory of your project,which is toolkit\apps\Tiny\src\TinyMIDlet.java where toolkit is theinstallation directory of the toolkit. The file contains a very simple MIDlet:

Save the file when you’re finished.

Open With

The main window displays the hierarchy of the open project. Within the hierarchy,you can open a file with an external application. Right-click the file and select OpenWith... as shown in FIGURE 2-4.

import javax.microedition.lcdui.*;import javax.microedition.midlet.MIDlet;

public class TinyMIDlet extends MIDlet implements CommandListener { public void startApp() { Display display = Display.getDisplay(this);

Form mainForm = new Form("TinyMIDlet"); mainForm.append("Welcome to the world of MIDlets!");

Command exitCommand = new Command("Exit", Command.EXIT, 0); mainForm.addCommand(exitCommand); mainForm.setCommandListener(this);

display.setCurrent(mainForm); }

public void pauseApp () {}

public void destroyApp(boolean unconditional) {}

public void commandAction(Command c, Displayable s) { if (c.getCommandType() == Command.EXIT) notifyDestroyed(); }}


http://jedit.org/

http://jedit.org/

FIGURE 2-4 Open a File with an External Application

The Open With menu options are as follows:

■ Choose Program - select a .jar or .exe file that launches a program. Forexample, you might want to open a source file in a text editor. When you selectthe application, it application opens the selected file. At that time the toolkit alsoadds the program’s name to the Open With menu.

■ Remove Entries - This option clears the list of programs on the Open With menu.

2.2.2 BuildThe next step is to build your source code. The toolkit makes this part very easy.

In the KToolbar window, click the Build button. Assuming you saved your sourcefile in the right place, the toolkit finds it and compiles it. Compilation errors aredisplayed in the KToolbar console. If you have errors, go back and edit the sourcecode to fix them. Once you’ve eliminated your errors, the KToolbar console tells youthe project was successfully built.


FIGURE 2-5 Messages about Building

Behind the scenes, the toolkit also preverifies the compiled class files. MIDlet classfiles must be preverified before they can be run on a MIDP device or emulator. Thetoolkit quietly handles this detail for you; you probably won’t ever realize it’shappening. See the CLDC specification for more information on preverification.

2.2.3 RunOnce the project builds successfully, you are ready to try it out in the emulator. Clickthe Run button. If you’re following along with the TinyMIDlet example, theemulator show something like FIGURE 2-6:


FIGURE 2-6 TinyMIDlet in Action

2.3 The Full Development CycleThe second development cycle is slightly more complicated:

Edit source code > Package > Install > Run

1. Edit source code. This is the same as in the simple cycle.

2. Package. In this step, the toolkit compiles and preverifies the source files(essentially the same as the Build step from before). Then it bundles the Java classfiles and resource files into a MIDlet suite JAR file and a MIDlet suite descriptor.

3. Install. MIDlet suites need to be installed before they can be run. You can installthe MIDlet suite into the toolkit emulator or a real device.

4. Run. As in the simple development cycle, run your application and test for bugs.

In the full development cycle, the first step is identical to the simple developmentcycle. Editing source code is the same as always. The Build step is now incorporatedin packaging.

The full development cycle includes two new steps, packaging and installing.Finally, running an installed application is different in important ways from runningan application in the simple development cycle.


2.3.1 PackageThe toolkit automates the task of packaging a MIDlet suite. The end result ofpackaging is two files, a MIDlet descriptor and a MIDlet suite JAR. The descriptor isa small text file that contains information about the MIDlet suite. The JAR containsthe class files and resources that make up the MIDlet suite. Devices can use thedescriptor to learn about the application before downloading the entire JAR, animportant consideration in a memory-lean, bandwidth-starved wireless world.

Open a project. In the main window, select a MIDlet suite, then choose Project >Package > Create Package from the KToolbar menu, or click the Package button, asshown in FIGURE 2-7. The MIDlet suite descriptor and JAR are generated and placedin the selected project’s bin directory.

FIGURE 2-7 Package the MIDlet Suite

Packaging might involve additional steps. You can use a code obfuscator to shrinkthe size of the MIDlet suite JAR, a technique that is described later in this chapter. Inaddition, the toolkit provides tools to allow you to cryptographically sign MIDletsuites. See Chapter 7 for more information.


2.3.2 InstallTo properly test a MIDlet suite, you should install it into the toolkit’s emulator or areal device. When you press the Run button in KToolbar, the MIDlet suite is notinstalled into the emulator. Instead, the emulator runs the MIDlet classes directly.

The emulator also has the capability of installing applications into its memory in aprocess that resembles how applications are transmitted and installed on realdevices. To install the current application in the toolkit emulator, choose Project >Run via OTA or click the Run via OTA button.

The emulator window opens, but instead of running your MIDlet classes directly,this time the emulator shows the welcome screen of its Application ManagementSoftware (AMS). The emulator’s AMS is an example of the type of software that realdevices must have to manage MIDlet suites.

FIGURE 2-8 Emulator AMS Welcome Screen

Select Install Applications. Select the Launch soft menu button. The emulatorprompts you for the URL location of the application you want to install. In thedemos provided the URL is already filled in for you.


FIGURE 2-9 URL Prompt

Choose 2 (Go to) from the menu to begin the installation. After a download, theemulator shows a list of the applications it finds at the URL. Choose one and clickthe Install soft button. The emulator gives you one last chance to confirm yourintentions.

FIGURE 2-10 Confirming the Installation

Choose Install again. You might see a security confirmation message. PressContinue.

You are asked if you want to launch Tiny.jad. Click the OK soft button and you seethe MIDlet’s welcome message. Select Exit and you are returned to the Applicationsscreen. Tiny is now listed as an installed application.


FIGURE 2-11 The Application Menu

Run via OTA is an extremely useful mechanism that makes it easy to install yourMIDlet suite on the toolkit emulator. Some features must be tested using thistechnique, including the push registry and the installation of signed MIDlet suites.

If you want to test your MIDlet suite on a real device, you must install it first. Howthis happens depends heavily on the device you are using. There are two likelypossibilities:

■ You can deploy the application on a web server, then transmit the applicationfrom server to device using the Over the Air (OTA) protocol described in theMIDP 2.0 specification. This is most likely the same mechanism that usersencounter when the purchase or install your application.

■ You might be able to transfer the MIDlet suite to the device using a Bluetooth,infrared, or serial connection. This is quite a bit simpler than running a webserver, and although it won’t give you any insights into the process of installingyour application on the device via OTA, it allows you to see how your applicationperforms on the device.

2.3.3 RunOnce the application is installed, choose the application from the list and chooseLaunch from the menu.


FIGURE 2-12 Launching the Installed Application

Running an application on a real device depends heavily on the device itself.Consult your device documentation for information.

2.4 Opening a Project in the Sprint IDEProjects created with the Sprint Wireless Toolkit 3.2 can also be opened in the SprintIDE. There is no need to import the project into the IDE.

To open a project in the IDE, run the IDE and select File > Open Project. Select aproject from your toolkit installation. For example, choose a project from:C:\SPRINT_WTK_32\apps, as shown in FIGURE 2-13.


FIGURE 2-13 Sprint IDE Open Project Window

2.5 Creating a Project from a MIDlet SuiteYou can also create a toolkit project from a MIDlet suite archive (.jar file) anddescriptor (.jad file). This is useful for running MIDlet suites from KToolbar evenwhen you don’t have the source code available. You can use the toolkit to easilymanipulate the attributes in the descriptor, or you can run the project and use thetoolkit’s monitoring tools (described in Chapter 5) to scrutinize its behavior.

To create a project based on a MIDlet suite choose File > Create project fromJAD/JAR. Navigate to the descriptor you wish to use and click Open. Note that thedescriptor and the JAR should be in the same directory.


FIGURE 2-14 Creating a New Project from JAD and JAR Files

2.6 Using an ObfuscatorAn obfuscator is a tool that reduces the size of class files. MIDlet suites need to becompact, both to minimize download times and to comply with sometimes stringentlimits on JAR size imposed by manufacturers or carriers. Using an obfuscator is oneway (not the only way) that you can keep your MIDlet suite JAR small.

You can use an obfuscator in the packaging step of the development cycle. Althoughthe toolkit doesn’t come with an obfuscator, it is already configured to use theProGuard obfuscator. All you need to do is download ProGuard and put it in a placewhere the toolkit can find it.

ProGuard is published under the terms of the GNU General Public License (GPL). Ifyou are comfortable with the terms of the license, you can download and useProGuard free of charge.


Installing ProGuard in the toolkit is straightforward:

1. Go to the ProGuard web site, http://proguard.sourceforge.net/.

2. Download the latest version.

3. Uncompress the proguard.jar file from the lib directory of the ProGuardinstallation to the bin directory of your toolkit installation.

Once ProGuard is installed, you can use it by choosing Project > Package > CreateObfuscated Package.

In some cases you must provide a script file that controls how the obfuscator works.If you are loading classes using Class.forName(), for example, you need to tellProGuard to leave the class names unchanged.

Create a script file using a text editor, then save it under the project’s main directory.Consult the ProGuard documentation for information on script files. Next you needto tell the toolkit how to find this file. To do this, edit toolkit\wtklib\platform\ktools.properties, where platform is the name of your underlying platform(most likely Windows or Linux). Add a line as follows:

obfuscate.script.name: scriptfile

Replace “scriptfile” with the name you used for the script file. You need to quit andrestart KToolbar for the change to take effect.

The toolkit also includes support for RetroGuard. If you want to use RetroGuard,you must download it separately and change the toolkit’s configuration.

1. Go to the RetroGuard web site, http://www.retrologic.com/retroguard-main.html.

2. Download the latest version.

3. Extract the retroguard.jar file from downloaded zip file to the bin directory ofyour toolkit installation.

4. Edit toolkit\wtklib\platform\ktools.properties so that it uses theRetroGuard obfuscator plug-in:

obfuscator.runner.class.name: com.sun.kvem.ktools.RunRetro

obfuscator.runner.classpath: wtklib\\ktools.zip

Retroguard is used when you create an obfuscated package.

To switch back to ProGuard, edit the obfuscator lines in the ktools.propertiesfile as follows:

obfuscator.runner.class.name: com.sun.kvem.ktools.RunPro

obfuscator.runner.classpath: wtklib\\ktools.zip


http://proguard.sourceforge.net/

http://www.retrologic.com/retroguard-main.html



http://proguard.sourceforge.net/

If you want to use a different obfuscator, you’ must implement an obfuscator plug-inyourself.

2.7 Using a DebuggerA variation on running your application is running it with a debugger. A debuggerallows you to monitor the running application more closely, set breakpoints, andexamine variables.

You must supply your own debugger. You can use the jdb debugger from J2SE™ oranother debugger of your choice. If you want to use a debugger, you are likely to usean Integrated Development Environment (IDE) that is aware of the toolkit. Forexample the NetBeans Mobility pack. Seehttp://www.netbeans.org/products/mobility/. Information about usingjdb with the toolkit is here:

http://developers.sun.com/techtopics/mobility/midp/questions/jdb/

The general steps for debugging are as follows:

1. Choose Project > Debug from the KToolbar menu.

2. Enter the TCP/IP port number that the debugger must use to connect to theemulator. Click Debug.

The port number can be any legal port between 1024 and 65546. When you clickDebug, the emulator begins running and waits for a connection from a debugger.

3. Start up your debugger and attach it to the port you specified.

Make sure to set the debugger to run in remote mode and to use TCP/IP. Formore information, consult the debugger’s documentation.

The following procedure applies these steps using the NetBeans IDE and the toolkit.

▼ Setting a Breakpoint with the NetBeans IDEThese instructions assume you have the NetBeans Mobility Pack and the SprintWireless Toolkit installed.

■ In NetBeans, select Tools > Java Platforms. In the Platforms area under the J2MEyou must have a platform named “Sprint Wireless Toolkit Powered by Sun JavaTechnology.” Note that the platform name does not have a version number. To


http://www.netbeans.org/products/mobility/

http://developers.sun.com/techtopics/mobility/midp/questions/jdb/

http://www.netbeans.org/products/mobility/

add this platform, click Add Platform and use the wizard to add a Java ME MIDPPlatform Emulator of that name and specify the path to your Sprint WirelessToolkit 3.2 installation.

■ You might need to customize your firewall settings or disable your firewall toensure the toolkit successfully attaches to the external debugger.

1. Launch KToolbar and open a project.

2. In NetBeans, open the same toolkit project and view the source.

a. Open a source file.

In this example we use the UIDemo project and open TextFieldDemo.java.

b. Place the cursor in a method and type CTRL-F8 to set a breakpoint

The breakpoint is highlighted in red, as shown in FIGURE 2-15.

FIGURE 2-15 Breakpoint in NetBeans IDE

3. In KToolbar, open the project with the breakpoint.

a. Select Project > Debug.

Accept the default port number as shown in FIGURE 2-16, or enter any numberbetween 1024 and 65536.


FIGURE 2-16 Ktoolbar Remote Debugging Port

b. Click Debug.

The emulator runs. Before it launches you see the following benign messagesin the console:

KVMListener: Exception java.net.ConnectException:Connection refused: connect KVM not ready

4. In the NetBeans IDE, right-click the Debug Main Project button and selectAttach Debugger... as shown in FIGURE 2-17.

FIGURE 2-17 Debug Main Application With Attach Debugger Selected

5. In the Attach window (FIGURE 2-18), set the host to localhost, and specify thesame port number that you specified in Step 3. Click OK.

The connection is made. In the NetBeans IDE debugger console you see thefollowing message:

Attaching to 127.0.0.1:5000User program running

When the connection succeeds the MIDlet is started in the emulator.


FIGURE 2-18 Attach Window

6. Launch the application (in this case TextFieldDemo).

The application stops at the breakpoint. In NetBeans, the breakpoint is nowcolored green.

2.8 Deploying Applications on a Web ServerThe MIDP 2.0 specification includes the Over The Air User Initiated ProvisioningSpecification, which describes how MIDlet suites can be transferred over-the-air(OTA) to a device. You can test this type of scenario using the toolkit emulator.

To deploy a packaged MIDP application remotely on a Web server, change the JADfile’s MIDlet-Jar-URL property to the URL of the JAR file. The URL should be anabsolute path. For example:

MIDlet-Jar-URL: http://your.server.com/midlets/example.jar

Next, ensure that the Web server uses the correct MIME types for JAD and JAR files:

■ For MIDlet suite descriptors, map the .jad extension to thetext/vnd.sun.j2me.app-descriptor MIME type.

■ For MIDlet suite JARs, map the .jar extension to the application/java-archive MIME type.

The details of how to configure a Web server depend on the specific software used.


The emulator implements the device behavior during OTA provisioning. You canuse the emulator to test and demonstrate the full provisioning process of MIDletsuites from a server to the device. All you need to do is launch the emulator’s AMS.You may already be familiar with the AMS if you have used the Run via OTAoption.

To launch the emulator’s AMS, you have two options:

■ In the Microsoft Windows start menu, choose Start > Programs > Sprint WirelessToolkit 3.2 - Powered by Java Technology> OTA Provisioning.

■ From the command line, run:

toolkit\bin\emulator -Xjam

Now follow the AMS prompts to install your application. This process is verysimilar to the Run via OTA option described earlier in this chapter, except you mustenter the URL of your own server to install your application.



CHAPTER 3

Working With Projects

In the last chapter, you learned how the Sprint Wireless Toolkit 3.2 (the toolkit) helpsyou with the MIDP development cycle. This chapter delves more deeply into thedetails of working with projects, including the following:

■ Selecting the target APIs for a project

■ Manipulating MIDlet suite attributes, including the list of MIDlets

■ Understanding the project directory structure

■ Including third-party libraries in a project

3.1 Selecting APIsEach project is built against some set of APIs. The toolkit supports many APIs; thefull list is detailed in Chapter 1. The toolkit allows you to develop applications forsome subset of APIs based on the type of devices you expect to run your software.

For example, even though the toolkit supports JSR 184, the Mobile 3D Graphics API,you might want to develop applications that don’t make use of that API. Theproject’s API Selection settings make it possible to choose only the APIs you want touse.

To see how this works, launch KToolbar and open a project. Click Settings... to bringup the window shown in FIGURE 3-1.

3-1

FIGURE 3-1 The Project Settings Window


On the API Selection pane, the Target Platform setting controls the appearance ofthe rest of the pane. Choose the setting that best suits your need and select optionalAPIs or extensions.

The toolkit applies your selections when you compile your source code.

Note – API selections do not apply to the emulator. The emulator always supportsall the available APIs. The API selections you make in the project settings apply onlyto building a project. In essence, the API selections choose which classpath thetoolkit uses for compiling and preverifying your source files.

3.2 Changing MIDlet Suite AttributesThe project settings window also allows you to control the MIDlet suite attributes,which are stored in the descriptor as well as the manifest file of the MIDlet suiteJAR.

Note – If you change any settings on an existing project you must package and signthe project again. See Section 7.3, “Signing a MIDlet Suite” on page 7-5.

To see the attributes, run KToolbar and open a project and click Settings.... TheSettings window divides attributes into Required, Optional, and User Definedgroups.

Consult the MIDP 2.0 specification for the definitions of the required and optionalattributes. The toolkit takes care of most of the details. In the early stages ofdevelopment, you might not have to worry about the attributes, so you can just clickOK to accept the defaults. Once your application is stable and you’re starting tothink about deploying on real devices and going to market, you should come backand adjust the values.

To change an attribute, from the Settings window, select the Required, Optional, orUser Defined icon on the left, as shown in FIGURE 3-2. Click in the cell next to theattribute key you wish to change.

While you are editing a value the OK button is disabled. When you leave a field (forexample, you type Tab to move to another field), the toolkit performs a validation. Ifthe value you edited is invalid, you receive an error message. See FIGURE 3-3.

Chapter 3 Working With Projects 3-3

FIGURE 3-2 Editing a Project Setting

FIGURE 3-3 Error Message for Incorrect Value


To create new user-defined attributes, click the User Defined icon. Press Add and fillin the key name. You can then edit the attribute value by clicking in the valuecolumn next to the key, just as you would with required or optional attributes.

Select an attribute and click Remove if you wish to remove the key and valueentirely.

3.3 Manipulating MIDletsThe project settings also provide a way to add or modify the MIDlets that arecontained in the current MIDlet suite project. To see how this works, start the toolkitand open an existing project. Click Settings... and choose the MIDlets pane. You seea list of all MIDlets in the project. If you just created a new project, the toolkitautomatically fills in the first MIDlet entry.

Note – If you change any settings you must package and sign the project again. SeeSection 7.3, “Signing a MIDlet Suite” on page 7-5.


FIGURE 3-4 The List of MIDlets in a Project

To add a new MIDlet, click Add. Fill in the name, icon file name, and class name.You can leave the icon file name blank if you wish. To change values or removeMIDlet entries, use the Edit and Remove buttons.

The MIDlet names are presented to the user in the order shown when the MIDletsuite is launched. You can modify the order by selecting a MIDlet and clicking MoveUp or Move Down. FIGURE 3-4 shows the Demo project MIDlets been placed inalphabetical order by name.


3.4 Using the Push RegistryYou can also use project settings to work with a MIDlet suite’s push registry settings.Click Settings... and choose the Push Registry pane.

FIGURE 3-5 Project Push Registry Settings

To add an entry to the push registry, press Add and fill in values for the connectionURL, MIDlet class, and allowed sender. To edit an entry, select the entry and pressthe Edit button. To remove a push registry entry, select it and press Remove.


If you do make push registry entries for your application, make sure you also enterthe appropriate permissions. See Chapter 7 for details.

3.5 Project Directory StructureProjects have a standard directory structure. The project itself is represented by adirectory in toolkit\apps. For example, the demos project is contained in toolkit\apps\demos. Inside a project directory, the following directories are used:

In addition, the project directory contains a project.properties file whichcontains information about the project.

If you want to remove temporary directories and files from the project, chooseProject > Clean from the KToolbar menu.

3.6 Using Third-Party LibrariesThe toolkit allows you to incorporate third-party libraries in your applications.Using third-party libraries can cut down on your development time by providingfunctionality you don’t wish to build yourself, but you should keep a close eye onthe size of your MIDlet suite JAR.

TABLE 3-1 Project directory structure

Directory Description

bin The MIDlet suite descriptor and JAR are placed in this directorywhen you package the project.

classes This directory is used by the toolkit to store compiled class files.

lib Place a third-party library in this directory to include it in thisproject.

res Images, sounds, and other resource files go in this directory. They arepackaged into the root of the MIDlet suite JAR.

src Place source files in this directory.

tmpclasses This directory is used by the toolkit.

tmpsrc This directory is used by the toolkit.


When you use a third-party library in your application, your JAR expands by thesize of the third-party library. You can use an obfuscator to reduce the code size, anda good obfuscator even eliminates portions of the library that you are not using.Even with the use of an obfuscator, a third-party library is probably larger than yourown custom code, carefully written from scratch. You must evaluate the trade-offbetween reducing your development time and the size of your MIDlet suite JAR.

The toolkit supplies two methods for incorporating third-party libraries. TheExternal APIs pane in the project settings makes it easy to include or excludelibraries in a project. In addition, you can place libraries in specific locations to makethem available to one or all projects.

3.6.1 Using External APIsTo specify which APIs should be included, click Settings... and click the ExternalAPIs pane. You see a list of available external APIs (initially the list is empty).

To add an API to the list, click the Add button.

Navigate to the directory containing the API, as shown in FIGURE 3-6. Select an APIand click Open.


FIGURE 3-6 Choosing External APIs

The API is added to the list.

To add the API to the classpath at build time, check the box in the Use column (seeFIGURE 3-7). If you intend to deploy your application on devices where your selectedexternal APIs are not present, you must bundle those APIs in your application. Tobundle the API into your application, check the Bundle box. Click OK when you arefinished.


FIGURE 3-7 Adding the API to the Classpath

The External APIs tab shows all JARs in the toolkit\lib\ext directory. If themanifest file for a JAR contains an API-Name attribute, the name is shown. If theattribute is missing, the name of the file is shown instead.

3.6.2 Third-Party Libraries for One ProjectAny library files placed in your project’s lib directory are included in the buildingand packaging of your project. Libraries should be JAR or Zip files of Java classes.

For example, if you installed the toolkit in C:\SPRINT_WTK_32 and yourapplication is called Tiny, the class library would go in C:\SPRINT_WTK_32\apps\Tiny\lib. When you build, run, debug, and package your project, the classfiles in the lib directory are used.

3.6.3 Third-Party Libraries for All ProjectsSome devices have libraries available to all installed MIDlet suites. A manufacturer,for example, can make additional APIs available on all their devices. In this case,you want to be able to use these libraries when you build and test your application.You don’t want the libraries to be included in your packaged MIDlet suite becauseyou might be installing the MIDlet suite on devices where the library is alreadypresent.

You can accomplish this by placing libraries in the toolkit\apps\lib directory. Forexample, if you installed the toolkit in C:\SPRINT_WTK_32, you would place theclass libraries in C:\SPRINT_WTK_32\apps\lib. Libraries in this directory areavailable for all projects.


3.7 Configuring KToolbarKToolbar includes some advanced configuration options. You can use these optionsby editing the toolkit\wtklib\platform\ktools.properties file. To see the effectsof your changes, restart KToolbar.

3.7.1 Changing the Console FontYou can change the font that’s used in the KToolbar console (and other text areas) byediting two properties. Here is one example that changes the font to Times NewRoman 20 point.

font.JTextArea=Times New Roman

font.size.JTextArea=20

To restore the default font and size, remove both properties.

3.7.2 Setting the Application DirectoryBy default, the toolkit stores applications in directories under toolkit\apps. You canchange this by adding a line to ktools.properties of the following form:

kvem.apps.dir: application_directory

Any backslash ('\') characters in the directory’s path should be preceded by anotherbackslash. Also, the directory’s path should not contain any spaces.

For example, to set the application directory to D:\dev\midlets, you would use:

kvem.apps.dir: D:\\dev\\midlets

3.7.3 Setting the javac Encoding PropertyBy default, the Java compiler uses the encoding set in the J2SE environment that youare running. For information on how to override the default source file encoding, seeAppendix C.


3.7.4 Working with Revision Control SystemsUsing the filterRevisionControl property, you can configure KToolbar torecognize and ignore auxiliary files created by the SCCS, RCS and CVS revisioncontrol systems.

To recognize and ignore auxiliary files, include the following line inktools.properties:

kvem.filterRevisionControl: true

As a result, you prevent KToolbar from treating revision control files as source andresource files. For example, KToolbar would treat a file named src\SCCS\s.MyClass.java as being an SCCS revision control file and not a Java source file.



CHAPTER 4

Using the Emulator

The Sprint Wireless Toolkit 3.2 (the toolkit) emulator simulates a MIDP device onyour desktop computer. It is a convenient way to see how your application performsin a MIDP environment and gives you a tight development cycle that is entirelycontained on your desktop computer.

The emulator does not represent a specific device, but it provides correctimplementations of its supported APIs.

4.1 Emulator SkinsA skin is a thin layer on top of the emulator implementation that provides it with acertain appearance, screen characteristics, and input controls. The toolkit comes withskins that represent different kinds of devices.

The toolkit supports skins from Sprint MIDP 1.0 Vision, MIDP 2.0 Vision, and MIDP2.0 Power Vision, and MIDP 2.0 Multitasking VM (MVM) platforms. Make aselection from the Platform menu (FIGURE 4-1) and the supported devices are shownon the Devices tab.

4-1

FIGURE 4-1 Platforms and Devices

To view the specification for a given emulator skin, go to the Devices tab, right-clicka device, and select Device’s spec... from the context menu (FIGURE 4-2).

FIGURE 4-2 Devices and Device Specification Launcher

4.2 Emulator ControlsThe emulator looks and acts like a mobile phone inside a standard desktop window.In this section you learn how to control the emulator. Although the description andfigures are based on the SamsungA900 skin, all the skins operate in a similar way.


FIGURE 4-3 The Samsung A900 Emulator Skin

You can use the mouse to click the buttons. Most buttons also have keyboardshortcuts, which are generally easier to use. Keyboard numbers 0 through 9correspond to the emulator’s 0 through 9 buttons. Some less obvious keyboardshortcuts are in TABLE 4-1.

Chapter 4 Using the Emulator 4-3

Entering text works much as it does on many real devices. Press a number keymultiple times to get the letter you want. For example, press the 5 key twice for theletter K. When you are entering text, the asterisk key (*) switches between uppercase, lower case, numbers, and symbols. The indicator at the top of the screen showsyour current mode. The pound key (#) enters a space.

Alternately, you can just type on your keyboard to enter text. Although this isconvenient for entering text, you must remember that it is a convenience most usersdo not have.

Another convenience is the capability to copy and paste information in text areas.You can paste text from the clipboard into a TextBox or TextField by pressingCtrl-V. To copy the contents of a TextBox or TextField, press Ctrl-C. The contentsof the text field are placed on the clipboard.

The UIDemo is useful for trying the different types of input methods. For example,you might select a text box. You then have the option to select a text box type, asshown in FIGURE 4-4. The selection Any Character results in the choices in FIGURE 4-4.In this MIDlet the programmer has predetermined the input method. For each field,there is a tooltip that hints the expected method.

TABLE 4-1 Keyboard Shortcuts

Emulator button Keyboard key

Left soft button F1

Right soft button F2

Power button Esc

SELECT Enter


FIGURE 4-4 Text Box Types

If you select Any Character you see something like FIGURE 4-5. Note the tooltiphinting that Qwerty (keyboard) input is expected. Other input types are 123(numeric) and ABC (text). These modes imply you can use the skin to enter numbersand text, respectively. Usually you can also use the keyboard to enter theinformation, as long as it complies.

FIGURE 4-5 Qwerty Mode

FIGURE 4-6 shows the Number field with the numeric 123 tooltip.


FIGURE 4-6 123 (Numeric) Mode

4.3 Setting Emulator PreferencesYou can adjust the emulator settings to more closely resemble a specific device or totest your application under different resource conditions.

4.3.1 Network ProxiesThe emulator uses your desktop network connection. For example, if the emulatorruns a MIDlet that makes an HTTP connection, the emulator attempts to make theHTTP connection using the desktop’s network setup.

If your development computer is behind a firewall, you might use a proxy server tomake HTTP connections. If you’re not sure, try examining your browser’s settings tosee if it uses proxy servers.

If you are using proxy servers, you need to configure the emulator to use the sameproxy servers. To do this, choose Edit > Preferences.... On the NetworkConfiguration pane, check Use proxy server and fill in the names and port numbersfor the proxy server. You can also select which version of HTTP you wish to use.

If your proxy servers use HTTP Basic authentication (see RFC 2617), checkAuthentication and fill in the user name and password.


4.3.2 Heap SizeThe heap is memory where your application’s objects are stored. Many real deviceshave limited heap size. You can set a maximum heap size to more closely simulatethe conditions on a real device. Choose Edit > Preferences... from the KToolbarmenu and selecting the Storage item. Fill in the maximum heap size in the HeapSize field. Remember, one kilobyte (kB) is 1024 bytes.

If you don’t specify a heap size, the default is 1 megabyte.

FIGURE 4-7 KToolbar Preferences Storage Tab

4.3.3 Storage and CleaningThe emulator has persistent storage, which by default is placed in toolkit\appdb\skin in files with a .db extension. For example, the persistent storage for theSamsung A940 emulator skin is stored in toolkit\appdb\SamsungA940. There is nolimit on the size of the persistent storage.

Note – If multiple instances of the same emulator skin run simultaneously, thetoolkit generates unique file paths for each one. For example, a second instance ofSamsungA940 might have a file path name of toolkit\appdb\temp.SamsungA9401139929445509.

The toolkit enables you to choose a different location for the storage files, and youcan limit the size of the storage. This is useful if you wish to test your application’sbehavior when a small amount of persistent storage is available.

To adjust the persistent storage settings, choose Edit > Preferences... and clickStorage in the left pane. Enter the name of the directory you wish to use forpersistent storage. You can only enter a relative path, and the directory you specifyis created in the toolkit\appdb directory.


If you wish, you can enter a limit in kilobytes for the size of the persistent storage.Bear in mind that the storage implementation has some overhead in addition to thespace your application uses. For example, if you enter 8 kB for the persistent storagesize, 8192 bytes is available for both your application data and the storage overhead.

If you wish to erase the persistent storage of the emulator, choose File > Utilities...from the KToolbar menu. Click the Clean Database button to wipe the persistentstorage clean.

4.3.4 Adjusting Emulator PerformanceThe emulator uses many of the resources of your desktop computer, including itsdisplay and network connection. Compared to the desktop-based emulator, a realMIDP device usually has a slower processor, less memory, and a slower networkconnection, and might have a different type of display.

The toolkit allows you to simulate the constrained environment of a real device.Although the emulator does not represent a real device, adjusting the performancesettings gives you useful information about how your application performs undervarying runtime conditions.

Choose Edit > Preferences... and click Performance in the left pane.


FIGURE 4-8 Adjusting the Emulator’s Performance

Adjust the Graphics primitives latency to have an effect on the amount of time thatelapses between your application’s calls to drawing methods in the Graphics classand when the drawing actually takes place.

To change the screen characteristics, choose one of the Display refresh types. If youchoose a Periodic type, you must also specify the Refresh Rate.

To simulate the slower speed of a real device, check Enable VM speed emulationand choose the speed you want.

You can adjust the simulated network speed by checking Enable networkthroughput emulation and choosing a speed.


4.4 Pausing and ResumingMIDlets have a life cycle that is defined by the MIDP specification. MIDlets can bestarted and stopped by the device. Furthermore, external events like incomingphone calls can cause the device to pause a MIDlet.

The emulator provides a simple mechanism to pause and resume running MIDlets.This is very helpful for testing your application’s behavior when it is paused. Thebehavior is slightly different depending on the platform:

■ MIDP 1.0 Vision, MIDP 2.0 Vision, and MIDP 2.0 Power Vision

When the emulator is running, choose MIDlet > Pause MIDlet. To resume theMIDlet’s operation, choose MIDlet > Resume MIDlet.

■ MIDP 2.0 MVM Platform

When running a Multitasking VM device in OTA mode, select MIDlet > PauseVM. The resume action is handled from the AMS menu as described inSection 4.5, “Multitasking VM and the Emulator” on page 4-10. When you runlocally the option is Pause MIDlet and Resume MIDlet.

4.5 Multitasking VM and the EmulatorThe multitasking virtual machine (VM) feature means the Java VM is always on!This feature works with MIDP 2.0 MVM Platform devices.

Each application runs in its own logical Java virtual machine that is referred to as anisolate. MIDlets are assigned a foreground or background state.

A foreground application controls the display and handles user input. Only oneapplication can be in the foreground. Multiple applications can run in thebackground.

To see the Multitasking VM in practice, start with multiple MIDlets installed on aMIDP 2.0 MVM Platform device. Each MIDlet can be launched from the AMS.

1. Launch a MIDlet and it runs in the foreground.

2. Press END.

You have a choice of actions (FIGURE 4-9).


FIGURE 4-9 Options Available After End is Pressed

To start another application, return to the application manager. If the MIDlet hasbeen programmed with the Multitasking VM in mind the application mightautomatically go to the background after you press End, or, you can use Send toBackground to send the application to the background manually. Resumeapplication returns you to the first application, and Exit application closes theapplication without closing the emulator.

3. In the AMS, launch a second MIDlet.

4. In the second MIDlet, press END to return to the AMS.

The AMS shows that two MIDlets are running simultaneously (FIGURE 4-10).MIDlets with green checks are running.

FIGURE 4-10 AMS with Two MIDlets Running.

When running multiple applications using the End key to move from the applicationto the AMS.


The MIDlet determines what happens when it is in the back ground. For exampleyou can program the following behaviors:

■ Allow an application, such as a media player, to remain audible while in thebackground.

■ Suspend games when they are in the background.

■ Launch applications in the background at boot time. For example, instantmessaging, stock tickers, news, and more.

■ Use alerts to notify the user when something interesting happens in a backgroundapplication.

To see the Multitasking VM in action, go to installdir/docs/MVMTutorialMovieand run the .html file, or try Section A.19, “Multitasking VM Demo” on page A-45.

4.6 Running the Emulator SoloDuring development, you typically run the emulator directly from KToolbar bypressing the Run button or using the Project > Run via OTA feature. For testing ordemonstrations, you might wish to run the emulator by itself. Several differentapproaches are described in this section. The program group created by the toolkitinstaller includes several items that pertain to running the emulator by itself.

■ To run an application directly, which is analogous to pressing KToolbar’s Runbutton, choose the Run MIDP Application... item. The toolkit prompts you tolocate a MIDlet descriptor file on your local disk. Note that the correspondingMIDlet suite JAR must also be present.

■ To run the emulator’s Application Management Software (AMS), choose the OTAProvisioning item, which is roughly analogous to KToolbar’s Run via OTAfeature. The emulator pops up with the AMS welcome screen, and you can installapplications by typing in a URL.

■ To change the emulator’s preferences, choose the Preferences item from thetoolkit program group. This pulls up the same preferences window as choosingEdit > Preferences... from the KToolbar menu.

■ The toolkit utilities are also accessible without running KToolbar. Just choose theUtilities item.

■ Finally, you can change which emulator skin is used by default. Choose theDefault Device Selection item, and choose one of the available emulator skins.Next time you launch the emulator the selected skin is used.

You can also run the emulator from a command prompt. See Appendix B for moreinformation.


4.7 Using Third Party EmulatorsThird party companies, like device manufacturers and wireless carriers, sometimescreate device emulators that are compatible with the toolkit. You can gain experiencerunning your application on a wider variety of implementations by installingadditional emulators into the toolkit. The procedure is usually to unpack or installthe third party emulator, then copy its directory into the<toolkit>/wtklib/devices directory. Next time you run KToolbar, the emulatoris available.

A partial listing of some of the currently available emulators is available here:

http://developers.sun.com/techtopics/mobility/midp/articles/emulators/

4.8 Additional Sprint FeaturesThis section describes features in Sprint Wireless Toolkit 3.2 that are not available inthe Sun Java Wireless Toolkit version 2.5.1.

4.8.1 Editing Source Files or ResourcesWhen you open a project a tree representing the file structure is shown in the leftpane (see FIGURE 4-11).


http://developers.sun.com/techtopics/mobility/midp/articles/emulators/

FIGURE 4-11 Project Tree

To expand the tree, click + or double-click on a directory name. You see the files orresources in each directory.

To open a file or resource, double-click its name or right-click the name and selectOpen (see FIGURE 4-12). This opens the resource using your system defaultapplication. For example, Notepad.


FIGURE 4-12 Opening a Source File

As shown in FIGURE 4-13, open with allows you to choose a program. The Open Withmenu options are as follows:

■ Choose Program - select a .jar or .exe file that launches a program. Forexample, you might want to open a source file in a text editor. When you selectthe application, it application opens the selected file. At that time the toolkit alsoadds the program’s name to the Open With menu.

■ Remove Entries - This option clears the list of programs on the Open With menu.


FIGURE 4-13 Using Open With from the Context Menu

To add a new or existing source or resource file, right-click one of the directorynames and make a selection from the context menu. Add existing allows you tobrowse for a file and copies the selected file into the selected directory (seeFIGURE 4-14). Add new opens a dialog in which you specify the file name.

FIGURE 4-14 Add File to Directory


You can also drag and drop a file into the project’s tree from the Windows explorer.

4.8.2 Device SelectionYou can select the device that appears in the emulator window.

1. In the main window, select a platform.

2. Click the Devices tab. The devices displayed are appropriate for the selectedplatform and its supported JSRs.

3. Click a device.

Follow these steps to view the supported JSRs for a platform:

1. In the main window, open a project.

2. Select Project > Settings.

3. In the left pane, click API Selection.

The toolkit displays the supported JSRs (see FIGURE 4-15).


FIGURE 4-15 API Selection with Supported JSRs

4.8.3 Setting the ClasspathThe toolkit provides a simple way to add and remove external APIs.

1. Open a project. Go to the tool bar and click Settings.

2. Choose the External APIs option from the left pane.

3. Press the Add button then browse to and select a JAR file to add (seeFIGURE 4-16. Click Open.

A new line is added to the API list.


FIGURE 4-16 Choosing an External API

4. To use the API, check the box in front of the name. Click OK.

The new API is added, as shown in FIGURE 4-17.


FIGURE 4-17 New API Added

To remove an API, check the Use box, and then click the Delete button.

4.8.4 Console Message ColorsIn the main window Console tab, messages from the MIDlet are written in blue,while all other messages are written in black. See FIGURE 4-18.


FIGURE 4-18 Output Message Colors

4.8.5 Zoom InThe Zoom In feature displays a larger version of the device emulator screen. Tozoom, double-click the device screen, or select MIDlet > Zoom In. An additionalwindow opens displaying the device screen contents. See FIGURE 4-19.


FIGURE 4-19 Zoom In Feature

4.8.6 Additional Media TypesJSR135 (MMAPI) makes it possible to play the media types described in this section.

4.8.6.1 QuickTime Plug-In

The Sprint Wireless Toolkit 3.2 uses a QuickTime plug-in to play additional mediatypes and RTSP protocol.

Media Types

The following types can be played using QuickTime:

■ 3GPP

■ 3GPP2

■ AAC


■ AAC+

■ AMR

■ H263

■ H264

■ MP3

■ MP4

Rtsp Support

The Rtsp protocol is supported. When creating a Player you need to give the file'sfull path in the following format:

rtsp://<streaming server name>/<file name>

Rtsp supports the following media types:

■ 3GPP

■ 3GPP2

■ MOV

■ MP3

■ MP4

4.8.6.2 Qcelp Media Type

To support Qcelp you must download and install a DLL from the Qualcommwebsite.

1. Go tohttp://www.umtschips.com/products/purevoice_download_sdk.jsp

2. Press Accept and you'll be able to download a zip file.

3. Save the qscl.dll file under the bin directory. The rest of the files in thezip file are not required for Qcelp to run.


http://www.umtschips.com/products/purevoice_download_sdk.jsp

http://www.umtschips.com/products/purevoice_download_sdk.jsp


CHAPTER 5

Monitoring Applications

The toolkit provides several tools to monitor the behavior of your applications.These tools are helpful in debugging and optimizing your code.

■ The profiler lists the frequency of use and execution time for every method in yourapplication.

■ The memory monitor shows the usage of memory while your application runs.

■ The network monitor shows network data transmitted and received by yourapplication. It supports many network protocols including HTTP, HTTPS, andSMS.

■ Tracing outputs low-level information to the console tab.

Note – Monitoring features might slow down the execution of your application.

5.1 Using the ProfilerThe profiler keeps track of every method in your application. For a particular run, itfigures out how much time was spent in each method and how many times eachmethod was called. After you finish running your application and shut down theemulator, the profiler pops up, allowing you to browse through the method callinformation.

To turn on the profiler, choose Edit > Preferences... from the main window. ClickMonitor in the left pane then check Enable Profiling in the Preferences window. Bydefault the profiler shows only system methods that contain calls to your applicationmethods. If you are interested in seeing profiling information for all the systemimplementation methods, check Show System Classes.

5-1

FIGURE 5-1 Turning on the Profiler

Now click the Run button to run your application. When you are finished, shutdown the emulator. The profiler pops up with information about all the method callsin your application.


FIGURE 5-2 The Method Profiler

The profiler displays two types of information:

■ Method relationships are shown in a hierarchical list, the Call Graph.

■ The right side of the profiler shows the execution time and number of calls foreach method and its descendants.

Note – The profiling values obtained from the emulator do not reflect actual valueson a real device.

Chapter 5 Monitoring Applications 5-3

5.1.1 The Call GraphThe call graph (in the profiler’s left pane in FIGURE 5-2) shows a hierarchy of methodcalls. Methods that call other methods are shown as folders. Double-click on amethod to open it and see the methods it calls. Methods that do not call any othermethod are shown as gray circles.

You can search for a particular class or method name. Click Find... and fill in a name.The search is performed from the current selection in the call graph to the end. Ifyou want to search the entire call graph, check Wrap before you click the Findbutton.

As you click different nodes in the call graph, the right side of the profiler showsdetails about the methods for that node.

5.1.2 Execution Time and Number of CallsThe right side of the profiler window (FIGURE 5-2) displays detailed informationabout methods. You can see the method name, the number of times it was called,and the amount of time that the emulator spent in the method. The execution time isdescribed as follows:

■ Count is the number of calls.

■ Cycles shows the amount of processor time spent in the method itself.

■ %Cycles is the percentage of the total execution time that is spent in the methoditself.

■ Cycles with Children is the amount of time spent in the method and its calledmethods.

■ %Cycles with Children shows the time spent in the method and its calledmethods as compared to the total execution time.

Click any column to sort by that column. Click a second time to switch the sortbetween ascending and descending.

The right pane shows the methods contained in the currently selected node in thecall graph. If you want to see every method, click the <root> node in the call graph.

5.1.3 Saving and Loading Profiler InformationTo save your profiler session, click the Save button in the profiler window. Choose afile name.


To load a profiler session, choose File > Utilities.... Click Profiler and press Launch.When you select a file, the profiler window appears with all the session information.

5.2 Using the Monty Memory Observe ToolMemory is scarce on many MIDP devices. The toolkit includes the Monty MemoryObserve tool (the memory monitor) to make it easy to examine the memory usage ofyour application as it is running. The memory monitor takes a snapshot of the heapat any point in the virtual machine execution. The memory monitor collects anddisplays:

■ global pointers

■ data for all objects (classes, sizes, addresses and references)

■ addresses for all roots

■ names of all classes

When running the memory monitor, remember the following facts:

■ The memory monitor slows down your application startup because every objectcreated is recorded.

■ The memory usage you observe with the emulator is not going to be exactly thesame as memory usage on a real device. Remember, the emulator does notrepresent a real device, it is just one possible implementation of its supportedAPIs.

■ Because the memory monitor and the Java debugger use the same transport layer,the monitor and the debugger cannot be used at the same time.

To turn on the memory monitor, choose Edit > Preferences.... Click Monitor in theleft pane. Check Enable Memory Monitor. The next time you run the emulator theMonty Memory Observe Tool displays a window similar to FIGURE 5-3.


FIGURE 5-3 Monty Memory Observe Tool

To take a snapshot of the heap, click the Pause button on the bottom right. Thevirtual machine is suspended while the profiler collects the snapshot information.The memory panel is then repopulated and the Resume button becomes active.

The memory monitor elements are as follows:

■ memory panel - At the top of the Monty window you see a grid of rectanglesrepresenting memory blocks. This is the memory panel. The key on the top rightindicates the meaning of each graphical image. For example, in FIGURE 5-3, themajority of blocks are completely black, meaning they are at 100% utilization.

Clicking a single block opens a dialog showing all the objects in that block. SeeFIGURE 5-4.


FIGURE 5-4 Objects Dialog

■ loaded classes - A list of loaded classes is displayed in the lower-left corner (seeFIGURE 5-3). Choosing a class from the list causes the location of all objects in theclass to be displayed in class objects list immediately to the right.

■ class objects - The class objects list is populated when you select a class from thelist of loaded classes. Select an object to see the class details. These include theaddress of the object, its type, and all references to and from the object. If theobject is live, the “Show path from the root” button is enabled. Clicking thisbutton opens the Path from the Root dialog (see FIGURE 5-5), which displaysdependencies that prevent this object from being garbage collected.


FIGURE 5-5 Path from the Root Dialog

■ statistics - At the bottom of the Monty Memory Observer tool (see FIGURE 5-3),click the Statistics button to see a table showing the information for each class (seeFIGURE 5-6). Some objects are internal to the virtual machine. For each class, yousee the Object number, size of all objects in the heap, the average size of theobject, the percentage of the heap used by the selected class, the percentage ofobjects live in the selected class, and the percentage of objects that are in the oldgeneration.


FIGURE 5-6 Heap Statistics

5.3 Using the Network MonitorMIDP applications, at a minimum, are capable of HTTP network connections, butmany other types of network connections are also possible. The network monitorprovides a convenient way to see the information your application is sending andreceiving on the network. This is helpful if you are debugging network interactionsor looking for ways to optimize network traffic.

■ To turn on the network monitor, choose Edit > Preferences.... Click Monitor inthe left pane. Check Enable Network Monitoring.

Next time you run the emulator, the network monitor window pops up.


FIGURE 5-7 The Network Monitor

When your application makes any type of network connection, information aboutthe connection is captured and displayed. The figure shows HTTP requests andresponses.

The display on the left side shows a hierarchy of messages and message pieces. Clicka message or a portion of a message to see details in the right side of the networkmonitor. Double-click on messages or message portions to expand or collapse them.

Message bodies are shown as raw hexadecimal values and the equivalent text.

Note – You can examine messages that are still in the process of being sent.Incomplete messages are indicated by bold highlighting in the message tree.


5.3.1 Filtering MessagesFilters are useful for examining some subset of the total network traffic. Filtersettings are specific to the network protocol used.

Press the Filter Settings button to use the filter. Change the filter settings to suityour needs.

When you are done entering filter settings, press OK to return to the networkmonitor. The Filter checkbox is checked, indicating that a filter is in use. To disablethe filter and see all messages, uncheck the checkbox.

5.3.2 Sorting MessagesTo arrange the message tree in a particular order, click the Sort By combo box andchoose a criteria.

■ Time. Messages are sorted in chronological order of time sent or received.

■ URL. Messages are sorted by URL address. Multiple messages with the sameaddress are sorted by time.

■ Connection. Messages are sorted by communication connection. Messages usingthe same connection are sorted by time. This sort type enables you to seemessages grouped by requests and their associated responses.

TABLE 5-1 Network Monitor Filter Settings

Network Protocol Filter Settings

HTTP/HTTPS Enter text to match the various parts of HTTP messages: URL, statusline, headers, or body. For example, entering “slashdot” in the URLfield would filter to show only messages whose URL contained“slashdot”.

SMS You can specify a protocol, message type, and direction to match.Furthermore, you can enter text to match in the sender, receiver, andmessage content.

MMS Enter text to match the direction, sender, receiver, and copied (cc)and blind copied (bcc) receivers. In addition, you can filter on thesubject, content ID, content location, MIME type, and encoding.

SPP/L2CAP You can filter using the URL or header content.

APDU/JCRMI Filter on the URL or the message content.

Socket/SSL/Datagram/Comm

Enter text to match in either the connection string (URL) or content.


■ Sorting parameters are dependent on the message protocol you choose. Forinstance, sorting by time is not relevant for socket messages.

5.3.3 Saving and Loading Network MonitorInformationTo save your network monitor session, choose File > Save or File > Save As... fromthe network monitor window menu. Choose a file name.

To load a network monitor session, choose File > Utilities... from the KToolbarmenu. Select Network Monitor from the list and press Launch. When you select afile, the network monitor window appears with all the session information.

5.3.4 Clearing the Message TreeTo remove all messages from the network monitor, choose Edit > Clear from thenetwork monitor menu.

5.4 TracingTo turn on tracing, select Edit > Preferences and select Monitor. In the Trace area,select the type(s) of tracing you want to see. Click OK. The trace information isdisplayed to the console tab whenever the emulator runs.

To save the contents of the console, click the Save Console button.


CHAPTER 6

Working With a Real Device

The toolkit provides two utilities to help you work with a real device. The mobiledevice must be connected to your PC’s COM port with a serial cable or a USB cable.

■ The GCD File Creator helps you create a General Content Descriptor (GCD) file.You must provide a GCD file if you are downloading to a Sprint device.

■ The COMM Terminal utility uses a standard communication interface to receiveand send input and output between a real mobile device and the toolkit. Thisutility is useful for debugging.

6.1 GCD File CreatorA General Content Descriptor (GCD) is a plain text file that describes a download(such as an image or a ringtone) for a mobile device. The Application ManagementSoftware (AMS) on the device validates based on the descriptor information.Validation confirms that all required properties (TABLE 6-1) are present, and that theinformation is feasible. For example, it checks the length or size of a property againstthe device limitations, or checks that URLs are valid.

A GCD file can reference a Java Application Descriptor (JAD) file, which in turndescribes a JAR containing a Java MIDlet. The AMS checks to ensure that theMIDlet-Name, MIDlet-Version, and MIDlet-Vendor match those in the JAR manifest.Also, if the MIDlet suite is trusted, then the values in the application descriptor forMIDlet-* attributes must be identical to the corresponding attribute values in themanifest.

The download can only occur when validation is successful and processing iscomplete. If a problem is found, the device displays an error message and thedownload does not take place.

6-1

6.1.1 Creating a New GCD FileThe GCD File Creator application is a simple wizard for creating and editing GCDfiles.

1. From KToolbar select File > Utilities.

2. Choose GCD File Creator. Click the Launch button.

3. From the File menu, choose New.

You see three tabs: Required, Optional, and User Defined. Required and Optionaltabs show a table with pre-specified attributes in the Name column on the left. TheValue column on the right is initially empty.

4. To enter a value, double-click in a cell in the value column and type yourinformation.

For information on Required attributes, see TABLE 6-1. For information onOptional attributes, consult TABLE 6-2. You can click another tab and continue todefine properties.

The User Defined tab starts with empty Name and Value columns. Click Add todefine a new property. Fill in the Add Property form and click OK.


The new property is added.

5. Click Save As.

Specify a file name and click save. All Required options are saved, even if there isno value specified. For the Optional and User Defined tabs, only the propertieswith values are saved.

By default the file is saved in My Documents, but you can browse to anydirectory.

6. Once the GCD file is created, it can be signed as described in Section 7.4,“Signing a GCD File” on page 7-6.

6.1.2 Editing a GCD File1. To open the wizard from KToolbar, select File > Utilities.

2. Choose GCD File Creator. Click the Launch button.

3. From the File menu, choose Open.

4. Browse to an existing GCD file and click Open.

6.1.3 Possible GCD Properties and Property ValuesThis section gives a brief explanation of the pre-specified properties and theirpossible values.

TABLE 6-1 lists the required properties and TABLE 6-2 lists optional properties.

Note that the Length column appears in both tables. Device manufacturers mustsupport at least the number of characters shown in the Length column. For somedevices the supported length might be greater than the value shown here. Forexample, Content-Name must support between one and 32 characters, but amanufacturer might choose to support 48 characters. In that case, an error isdisplayed if a user enters more than 48 characters.

Chapter 6 Working With a Real Device 6-3

TABLE 6-1 Required GCD Properties

GCD Attribute JAD Attribute Description Length Validity Criteria

Content-Type (Implicit) MIME type of the content.For Java applications, thisis alwaysapplication/java-archive

64 • Must be a properly constructedMIME type per RFC 2045.

• If supported length is exceeded yousee an error in the status report.

Content-Name MIDlet-Name A vendor-selected namefor the content.

32 • Can be any text string.• If supported length is exceeded you

see an error in the status report.

Content-Version MIDlet-Version Identifies the version ofthe content inmajor.minor[.micro]format

8 • Proper Format = xx.xx[.xx]. (See theMIDP specification)

• If there is a format error you see anerror in the status report.

Content-Vendor MIDlet-Vendor Identifies the vendor(creator) of the content.

32 • Can be any text string.• If supported length is exceeded you


Content-URL MIDlet-Jar-URL The location from whichthe device can downloadthe content

512 • Must be a valid relative URL to theJAR or other content-types or anabsolute URL (beginning withhttp://, https://).

• If supported length is exceeded yousee an error in the status report.

• If the URL is not found you see anerror in the status report.

Content-Size MIDlet-Jar-Size The number of bytesdownloaded from thecontent-URL

8 • Must be an integer value.• If supported length is exceeded you



http://tools.ietf.org/html/rfc2045

RFC2045

TABLE 6-2 Optional GCD Properties

GCD Attribute JAD Attribute Description Length Validity criteria

Content-ID Content-ID Identifier for thecontent so that it canbe launched fromoutside the AMS.e.g.‘sprintpcs.com/12345’

128 • Any text string.• If supported length is

exceeded, the attributeis ignored

Content-Install-Notify MIDlet-Install-Notify The URL to whichthe AMS MUST postthe result code forthe download andinstallation of thecontent.

512 • Must be a validabsolute URL(http://, https://)

• If supported length isexceeded, the attributeis ignored

Content-Delete-Notify MIDlet-Delete-Notify The deletenotification URL is tomake the vendingmachine aware ofcontent which is nolonger present on thedevice.


• If supported length isexceeded, the attributeis ignored

Content-Description MIDlet-Description Text describing thecontent


exceeded, the field istruncated and processedas a valid field.

Content-Info-URL MIDlet-Info-URL URL that a userMAY link to, toobtain moreinformation aboutthe content,including onlinehelp


• If supported length isexceeded and/or theprotocol invalid, theattribute is ignored.


Content-Icon-URL MIDlet-Icon URL of an icon to beused to represent thecontent. Note: inJAD, the MIDlet-iconattribute points to afile in the JAR, notan absolute URL.Icons are PNG files,with a maximumsize of 15 x 15 pixels.

512 • Content-Icon-URL -Must be a validabsolute URL(beginning withhttp:// orhttps://)

• MIDlet-Icon URL –Must reference imagein JAR file.

• If supported length isexceeded and/orprotocol invalid, theattribute must beignored.

Content-Folder Content-Folder Name of folder inthe AMS where thisdownload is stored.Case is ignored.


exceeded, the attributeis ignored.

Content-Forward-Lock Content-Forward-Lock If this attribute isNO (caseinsensitive), thenapplications on thedevice can allow thecontent to be sent offof the device.

8 • If the attribute isanything but NO, thecontent isautomatically lockedand cannot be sent offthe device.

Complete-Launch-Label Complete-Launch-Label The character stringindicated in thisattribute is to beused for theDownload Completescreen.

32 • This is primarily usedto initiate a launchrequest.

• If the parameterexceeds the number ofcharacters, this value istruncated.

Complete-Web-Label Complete-Web-Label The character stringindicated in thisattribute is to beused for theDownload Completescreen.

32 • This is primarily usedto initiate a launchrequest.

• If the parameterexceeds the number ofcharacters, this value istruncated.

TABLE 6-2 Optional GCD Properties (Continued)



Complete-Description Complete-Description The character stringindicated in thisattribute is used toinform the user atthe DownloadComplete Screen.

128 • If the parameterexceeds the number ofcharacters, this value istruncated.

Content-Assign N/A Tells the AMS toautomatically assignthis content to acertain function.

32 • If the content type doesnot match theassignment you see anerror.

Content-RSA-SHA1 MIDlet-JAR-RSA-SHA1 If present, the JARmust beauthenticated byverifying the signercertificates and JARsignature.

176 • See MIDP 2.0 OTAspecification – TrustedMIDlet Suites

Content-Certificate-1-<m> MIDlet-Certificate-1-<m> Certificate Path 2048 • See MIDP 2.0 OTAspecification – TrustedMIDlet Suites

Video-Playback N/A Attribute is used todeclare that thiscontent is intendedfor immediateplayback and issaved from theplayback screen.

• TRUE (case insensitive)is the only valid entry.

• All other parameters orabsence of thisattribute means thedownload is nothandled as Downloadand Play

Video-Ringer N/A Attribute is used todeclare video contentto be acceptablewithout userconfirmation forVideo Ringers.

• TRUE (case insensitive)is the only valid entry.

TABLE 6-2 Optional GCD Properties (Continued)



6.2 Sprint JAD Multitasking VM AttributesThe Sprint specification supports the JAD attributes in TABLE 6-3. To include theseattributes in a project’s JAD file, open the project the click the Settings button. In theSettings window, click the User Defined icon on the left. You can add and removeattributes as described in Section 3.2, “Changing MIDlet Suite Attributes” onpage 3-3. For example, you can add user defined attributes as shown in FIGURE 6-1.

FIGURE 6-1 Adding Sprint JAD Attributes

Note that the attribute names are in violation of the MIDP specification because theystart with “MIDlet“. Consequently, you see the dialog in FIGURE 6-2 every time youadd JAD attributes:

FIGURE 6-2 Benign Warning for JAD Attributes

Click Yes to continue and the attribute is added properly.


Note – Remember to package and sign the application whenever you add or modifyits attributes.

.

TABLE 6-3 JAD Attributes

JAD Attribute Description Length Validity Criteria

MIDlet-Launch-Background If the value is “yes” (caseinsensitive); when theMIDlet is launched, it mustbe launched to thebackground (not visible onUI). The splash screenMUST NOT be displayed.

3 • If the parameters are not valid (or notpresent) according to the description,the attribute MUST be ignored and notassigned on device power on.

• If the midlet is not signed (e.g. MIDlet-JAR-RSA-SHA1 present and valid),then this attribute MUST be ignored.

• Multitasking VM ONLY (ignoreattribute for single instance VM).

MIDlet-Launch-Power-On If the value is “yes” (caseinsensitive), then theapplication MUST belaunched when the device ispowered on.

3 • If the parameters are not valid (or notpresent) according to the description,the attribute MUST be ignored and notassigned on device power on.

• If the midlet is not signed (e.g. MIDlet-JAR-RSA-SHA1 present and valid),then this attribute MUST be ignored.


MIDlet-Heap-Size Heap memory required bythe MIDlet in order toexecute. This value isconsidered a maximumvalue in bytes.

5 • Must be an integer value,• If supported length is exceeded,

descriptor is invalid• If the amount declared exceeds the

available heap space allowed for asingle applications, then a 901Insufficient Memory – Heap isreturned.


MIDlet-Background-No-Pause When an application is sentto the background,pauseApp is called. Addingthis attribute with the value“yes” overwrites thisfunctionality and keeps theapplication running in thebackground.

3 • If the parameters are not validaccording to the description (or notpresent), the AMS MUST ignore theattribute and allow application to exit.



6.3 COMM TerminalThe COMM Terminal utility uses a standard communication interface to receive andsend input and output between a real mobile device and the toolkit. The mobiledevice must be connected to your PC’s COM port with a serial cable or a USB cable.

To aid in debugging, the COMM Terminal displays the System.out andSystem.err streams coming from a MIDlet running on the mobile device. You canuse the terminal to write an instruction to the input stream.

To launch the terminal from KToolbar, select File > Utilities. In the Utilities window,select COMM Terminal. The COMM Terminal opens (FIGURE 6-3).

FIGURE 6-3 COMM Terminal

Menus

The File and Edit menus are as follows:

File

■ Save Console - Saves the contents of the Terminal Log area to a text file of yourchoice.

■ Close - Closes the terminal.

Edit

■ Clear Console - Erases the Terminal Log area.

■ Preferences - Preferences for the six COM connection parameters and values.This is a standard communication interface. The default settings are those mostappropriate for Sprint devices (see FIGURE 6-4).


FIGURE 6-4 COMM Terminal Preferences

Terminal Log - Displays the output that comes from the mobile device.

Input - Input entry field for sending data from the toolkit to the device. Enter dataand click Send or press the enter key.

Buttons

■ Connect - Initiates the communication between the device and the toolkit usingthe preferences that were last set.

■ Disconnect - Terminates the communication between the device and the toolkit.

Available Ports: COM1 (default) or COM2

Data Bits: 5, 6, 7, or 8 (default).

Baud Rate: 300, 2400, 9600, 14400, 28800, 38400, 57600, 115200 (default)

Parity: None (default), Even or Odd.

Stop Bits: 1 (default) or 2. 1.5 is not supported.

Flow Control: None, Xon/Xoff Out, Hardware (default)


■ Save Console - Save the contents of the Terminal Log area to a file.

■ Clear Console - Erases the Terminal Log area.


CHAPTER 7

Security and MIDlet Signing

MIDP 2.0 includes a comprehensive security model based on protection domains.MIDlet suites are installed into a protection domain which determines access toprotected functions. The MIDP 2.0 specification also includes a recommendedpractice for using public key cryptography to verify and authenticate MIDlet suites.

For definitive information, consult the MIDP 2.0 specification. For an overview ofMIDlet signing using the J2ME Wireless Toolkit, read this article:

Understanding MIDP 2.0's Security Architecture

http://developers.sun.com/techtopics/mobility/midp/articles/permissions/

If you need more background on public key cryptography, try this article:

MIDP Application Security 1: Design Concerns and Cryptography

http://developers.sun.com/techtopics/mobility/midp/articles/security1/

This chapter describes support for protection domains, permissions, and MIDletsigning in the Sprint Wireless Toolkit 3.2 (the toolkit).

7.1 PermissionsMIDlets must have permission to perform sensitive operations, like connecting tothe network. Permissions have specific names, and MIDlet suites can indicate theirneed for certain kinds of permissions through attributes in the MIDlet suitedescriptor.

7-1







In the toolkit, you can add these permission attributes to a project by clicking on theSettings... button. Select the Permissions icon. The MIDlet-Permissions box showspermissions which the MIDlet must possess, while the MIDlet-Permissions-Opt boxcontains permissions that are optional.

FIGURE 7-1 MIDlet Suite Permissions

To add a permission to either box, Add and choose the permission you want to add.To remove a permission, highlight it and click Remove.


7.2 Setting Security PreferencesThe Sprint Wireless Toolkit 3.2 supports the security policies defined by both JSR 185(Java Technology for the Wireless Industry) and JSR 248 (Mobile Service Architectureor MSA). The protection domains are further described in Section 7.2.1, “MSAProtection Domains” on page 7-4 and Section 7.2.2, “Java for the Wireless ToolkitIndustry Protection Domains” on page 7-4.

To choose the security policy you want the emulator to use, select Edit > Preferencesand select Security in the Category list. From the Security Policy combo box, chooseeither MSA or JTWI. Select one of the available security policies, and select acertificates database. See FIGURE 7-2.

The Sprint database is appropriate for Sprint devices. It contains the Sprintcertificate and the Verisign root certificate used to authenticate the Sprint certificate.

The Developer database can contain certificates used for applications that run onplatforms other than Sprint. JDK certificates and TCK certificates fall in this category.

FIGURE 7-2 Security Preferences

When you use Run via OTA. your packaged MIDlet suite is installed directly intothe emulator and it is placed in a protection domain at installation time. Theemulator uses public key cryptography to determine the protection domain ofinstalled MIDlet suites.

If the MIDlet suite is not signed, it is placed in the default protection domain. Thedefault is different for MSA and JTWI, as explained in Sections 7.2.1 and 7.2.2. If theMIDlet is signed, it is placed in the protection domain that is associated with theroot certificate of the signing key’s certificate chain.

For example, suppose Respectable Software, a hypothetical company, wants todistribute a cryptographically signed MIDlet suite. Respectable Software buys asigning key pair from Super-Trustee, a hypothetical certificate authority. Using thesigning key, Respectable Software signs the MIDlet suite and distributes theircertificate with the MIDlet suite. When the MIDlet suite is installed on the emulator

Chapter 7 Security and MIDlet Signing 7-3

or on a device, the implementation verifies Respectable’s certificate using its owncopy of Super-Trustee’s root certificate. Then it uses Respectable’s certificate to verifythe signature on the MIDlet suite. Assuming everything checks out, the device oremulator installs the MIDlet suite into the protection domain that is associated withSuper-Trustee’s root certificate, most likely identified_third_party.

The toolkit provides tools to sign MIDlet suites, manage keys, and manage rootcertificates.

7.2.1 MSA Protection DomainsThe toolkit supports five protection domains for MSA:

■ manufacturer - Intended for MIDlet suites whose credentials originate from themanufacturer’s root certificate.

■ minimum - All permissions are denied to MIDlets in this domain.

■ identified_third_party - Intended for MIDlets whose origins weredetermined using cryptographic certificates. Permissions are not grantedautomatically, but the user is prompted less often than for theunidentified_third_party domain.

■ unidentified_third_party - Provides a high level of security for applicationswhose origins and authenticity cannot be determined. The user is promptedfrequently when the application attempts a sensitive operation

■ maximum - All permissions are granted to MIDlets in this domain.

When you press the Run button to run your application in the emulator, your coderuns in the unidentified_third_party protection domain by default.

7.2.2 Java for the Wireless Toolkit Industry ProtectionDomainsThe Sun Java Wireless Toolkit includes the following protection domains:

■ untrusted - Provides a high level of security for applications whose origins andauthenticity cannot be determined. The user is prompted frequently when theapplication attempts a sensitive operation.

■ trusted - All permissions are granted to MIDlets in this domain.

■ minimum - All permissions are denied to MIDlets in this domain.

■ maximum - All permissions are granted to MIDlets in this domain (equivalent totrusted.).


When you press the Run button to run your application in the emulator, your coderuns in the untrusted protection domain by default.

7.3 Signing a MIDlet SuiteTo sign a MIDlet suite, you must package it first. See Section 2.3.1, “Package” onpage 2-9.

Select the packaged MIDlet, then choose Project > Sign or click the Sign button.

The Sign Application window appears (FIGURE 7-3).

FIGURE 7-3 The Sign Application Window

Select the keystore you want to use from the Alias List and click the SignApplication ... button.

The Sprint keystore will work in most cases. If you chose the Developer database, asdescribed in Section 7.2, “Setting Security Preferences” on page 7-3, you shouldchoose a keystore from the TCK or JDK.


7.4 Signing a GCD FileYou can use the toolkit to sign a General Content Descriptor (GCD) file. A GCD filemight look like this:

1. In the main window click the Sign button.

The Sign Application window appears (see FIGURE 7-3).

2. Select Action > Sign Application.

The Select JAD or GCD File window opens (FIGURE 7-4). Choose a GCD file andclick the Sign Application button.

FIGURE 7-4 Choose a GCD File

Content-Name: My Content NameContent-Size: 2135Content-Type: image/jpegContent-URL: my_image.jpgContent-Vendor: my_vendorContent-Version: 1.0


The Security Tool window notifies you that the file is signed. Click OK.

Suppose you specify the following GCD file, test.gcd:

The signed file might look like this:

Content-Type: audio/wavContent-Name: test-wavContent-Version:Content-Vendor: SunContent-URL: http://java.sun.com/products/java-media/mma/media/test-wav.wavContent-Size: 217

Content-Type: audio/wavContent-Name: test-wavContent-Version:Content-Vendor: SunContent-URL: http://java.sun.com/products/java-media/mma/media/test-wav.wavContent-Size: 217Content-Certificate-1-1:MIIE8DCCA9igAwIBAgIQR/meD3uDWU1ghEQEBxudSzANBgkqhkiG9w0BAQUFADCBtDELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNDEuMCwGA1UEAxMlVmVyaVNpZ24gQ2xhc3MgMyBDb2RlIFNpZ25pbmcgMjAwNCBDQTAeFw0wNjEwMzEwMDAwMDBaFw0wOTEwMzAyMzU5NTlaMIGzMQswCQYDVQQGEwJVUzEPMA0GA1UECBMGS2Fuc2FzMRYwFAYDVQQHEw1PdmVybGFuZCBQYXJrMQ8wDQYDVQQKFAZTcHJpbnQxMTAvBgNVBAsTKERpZ2l0YWwgSUQgQ2xhc3MgMyAtIEphdmEgT2JqZWN0IFNpZ25pbmcxJjAkBgNVBAsUHUFwcGxpY2F0aW9uIERldmVsb3BlciBQcm9ncmFtMQ8wDQYDVQQDFAZTcHJpbnQwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKm4Fe21dKk8Duj/qllZQZWgUOcVHJYqzHTXyj1Ar2Xq6T7zImJFURsocM6a/+ZplUbRxG8rTm7cgM+PferIRfsQlLPdjrIRhv8DJNOXfBAexq0lcuU03f6m/0NrlDigt0zG47iBIMqkw4IRIazaIB4knpHzkOHGhZOvtJCYrZtLAgMBAAGjggF/MIIBezAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIHgDBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vQ1NDMy0yMDA0LWNybC52ZXJpc2lnbi5jb20vQ1NDMy0yMDA0LmNybDBEBgNVHSAEPTA7MDkGC2CGSAGG+EUBBxcDMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8vd3d3LnZlcmlzaWduLmNvbS9ycGEwEwYDVR0lBAwwCgYIKwYBBQUHAwMwdQYIKwYBBQUHAQEEaTBnMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC52ZXJpc2lnbi5jb20wPwYIKwYBBQUHMAKGM2h0dHA6Ly9DU0MzLTIwMDQtYWlhLnZlcmlzaWduLmNvbS9DU0MzLTIwMDQtYWlhLmNlcjAfBgNVHSMEGDAWgBQI9VHo+/49PWQ2fGjPW3io37nFNzARBglghkgBhvhCAQEEBAMCBBAwFgYKKwYBBAGCNwIBGwQIMAYBAQABAf8wDQYJKoZIhvcNAQEFBQADggEBADjcMgcgK0gGfRSzbaGGpHk6/6t3Ko2LqV5XtrVY78xTnbtiq8JvPuwny9fwKcGBt31V4Rd/cvmwyL8BNlcGX8b7DTmwvm3wbRLpe0qXPCnLG88xsRNLlvIUDX/TyfAIXrU0y/O0n8nXnWej1509M+sXW4ogNPXadZ4xrqbqiBdgw1G8NR9JAe2gqmmSEVWjZvm1ao34mqD/J4J/1fAsfCJXsmiRef3OawvtVMvGiBg2jOtZcgMv3m641/8T0qsASCW9CLnvBvIjiqJaXkqC1JXZRbGBo2mJwXGOu1fhH7naU+JJAPOGUhn3GwpvR1sy5GwND13A6L3xGaNl8qIAIZs=Content-RSA-SHA1:WGIfzY2kcQdKHXFQ/TYFhnTO8ZhemdUt07VY6AaExIRb6o06LlFOsx7/77jncIFa1851+UDXq/2Iu/8vtb36BCgaIDcyW/4r0URGibQajow5+8ToosOrwJPYcsp2/ujlt7hftLCN4dw5B1/v4YGwvp7rExltxnwDfCJEMQSIfZg=


7.5 Managing KeysThe MIDlet signing widow can also be used to manage keys and keystores.

7.5.1 Creating and Using KeystoresA keystore file can contain one or more keys. By default the toolkit uses the keystorefile toolkit/appdb/keystore.sks.

From the Sign Application window click the New Keystore button to create a new.sks keystore file in a location you specify. The new keystore is empty.

To modify a keystore, click the Open Keystore button and browse for the newkeystore or another keystore you want to change. You can add keys to the keystoreby creating a new key pair as described in Section 7.5.2, “Creating a New Key Pair”on page 7-10. Alternatively, you can click Import Key Pair to copy a key pair fromanother keystore to the current keystore.

You are prompted to choose the keystore that contains the key pair you want toimport.


FIGURE 7-5 Import Key Pair

After you select the file, you must select the key pair you want from the alias list. InFIGURE 7-6 the current keystore, mykeystore, has a key pair named respectable.A key pair named mykey is being imported from another keystore.


FIGURE 7-6 Importing a Key Pair

As shown in FIGURE 7-6, each key pair in the keystore is identified by an aliasdisplayed in the Alias List on the left.

The toolkit prompts you to choose a protection domain, as explain in sections 7.2.1and 7.2.2.

7.5.2 Creating a New Key PairTo create an entirely new key pair, click New Key Pair... The toolkit prompts you fora key alias and information that is to be associated with the key pair.


FIGURE 7-7 Creating a New Key Pair

After you click Create, the toolkit prompts you to choose a protection domain, asexplained in See Sections 7.2.1 and 7.2.2.

FIGURE 7-8 Choosing a Protection Domain for a New KeyStore

The key pair is created in the keystore that is currently open.


The connection between the key pair you just created and a protection domain isestablished as follows:

■ The toolkit creates a self-signed root certificate using the key pair you just created.

■ The root certificate is added to the emulator’s list of root certificates.

■ The toolkit needs to associate the root certificate with a protection domain.

Now imagine what happens when you install a MIDlet suite signed with your newkey:

■ The implementation examines the certificate chain in the MIDlet suite descriptor.In this case the certificate chain is a single certificate, the self-signed root.

■ The implementation tries to find the root of the certificate chain in its internal list.This succeeds because the root certificate was added when you create the keypair.

■ The implementation considers the certificate valid and uses it to verify thesignature on the MIDlet suite.

■ The MIDlet suite is installed into whatever protection domain you picked.

7.5.3 Getting Real KeysThe ability to create a key pair and sign a MIDlet within the toolkit environment isfor testing purposes only. When you run your application on an actual device, youmust obtain a signing key pair from a certificate authority recognized by the device.

The procedure for signing MIDlet suites with real keys works like this:

1. Generate a new key pair. In the toolkit you can do this by pressing New KeyPair... in the MIDlet signing window, as described above.

2. Generate a Certificate Signing Request (CSR). Press Generate CSR... in thesigning window. To change the location of the CSR file, enter a new path or pressBrowse... and choose a new file location. Press Create to write the CSR file. Afterthe CSR is written, you see a message that indicates success.

3. Send the CSR to a certificate authority (CA). The CA requires more informationfrom you to verify your identity. You also need to pay the CA for the certificatethey generate for you.

4. Once the CA has verified your identity and taken your money, you receive acertificate from the CA that certifies your public key.

5. Import the certificate into the toolkit by pressing Import Certificate... in theMIDlet signing window.

You can now use your own private key to sign MIDlet suites. The toolkit takes careof the details of placing the signature and your certificate into the MIDlet suite.


7.5.4 Removing a Key PairTo remove a key pair from the MIDlet signing window, select its alias and chooseAction > Delete Selection.

7.6 Managing CertificatesYou’ve already heard about the emulator’s list of root certificates. In this section, youlearn how you can manage this list using the toolkit.

Real devices have similar lists of root certificates, although they cannot usually bemodified by the user. When you want to deploy your application on a real device,you must use signing keys issued by a certificate authority whose root certificate ispresent on the device. Otherwise, the device is unable to verify your application.

While you’re developing your application, the toolkit’s certificate managementutility provides a convenient way to manipulate the emulator’s list of rootcertificates for testing purposes.

Choose File > Utilities... from the KToolbar menu. Select Manage Certificates andpress Launch to open up the certificate manager window.


FIGURE 7-9 The Certificate Manager

Each certificate is shown as a single line in the left part of the window, theCertificate List. When you select a certificate, its details are shown in the right partof the window. You also see the certificate’s associated protection domain.

7.6.1 Enabling and Disabling CertificatesCertificates can be enabled or disabled. This is handy if you want to makecertificates temporarily unavailable without removing them from the keystore. Toenable or disable a certificate, select it in the list and press Enable/DisableCertificate. The toolkit asks you to confirm the action. Choose Yes to proceed.


7.6.2 Importing CertificatesYou can import certificates either from certificate files or from Java SE keystore files.

To import a certificate from a file, click Import Certificate... in the certificatemanager window. After you locate the certificate file, choose which protectiondomain is associated with the certificate.

To import a certificate from a Java SE keystore, choose Action > Import J2SECertificate from the menu in the certificate manager window. First, choose aprotection domain for the certificate. Then select the keystore file and enter thekeystore password. Finally, select the alias for the certificate you wish to import.

7.6.3 Removing CertificatesTo remove a certificate from the list, select the certificate and choose Action > DeleteSelection.



CHAPTER 8

Using the Wireless Messaging API

The Sprint Wireless Toolkit 3.2 (the toolkit) supports the Wireless Messaging API(WMA) with a sophisticated simulation environment. WMA 1.1 (JSR 120) enablesMIDlets to send and receive Short Message Service (SMS) messages. WMA 2.0 (JSR205) includes support for MMS messages as well.

This chapter describes the tools you can use to develop WMA applications. It beginsby showing how to configure the emulator’s support of WMA. Next, you will learnabout the WMA console, a handy utility for testing WMA applications. The chapterconcludes with a brief description of the network monitor’s WMA support.

8.1 Setting Emulator Phone NumbersEach running instance of the emulator has a simulated phone number that is shownin the title bar of the emulator window. The phone numbers are important becausethey are used as addresses for WMA messages. By default, the first emulatorinstance has a phone number of +5555555555. Subsequent instances of the emulatorhave unique numbers in ascending order: +5555555556, +5555555557, +5555555558,etcetera.

You can affect the assigned phone numbers by choosing Edit > Preferences... fromthe KToolbar menu and selecting WMA in the left pane.

8-1

FIGURE 8-1 Setting WMA Preferences

The Phone Number of Next Emulator field is just what it sounds like. If you fill in anumber for this field, the next emulator instance has that number.

If the Phone Number of Next Emulator is already in use, or if the field is blank, thenthe First Assigned Phone Number is used for the next emulator instance.Subsequent instances count up.

For example, suppose you fill in +6269333333 for the Phone Number of NextEmulator and +5555555555 for the First Assigned Phone Number. If you launchfour emulator instances, their numbers are +6269333333, +5555555555, +5555555556,and +55555555557.

8.2 Simulating an Unreliable NetworkLong messages are sent by splitting them up, sending the fragments separately, andreassembling the fragments on the receiving end. You can simulate some of thehazards of the wireless network in the toolkit. As before, choose Edit > Preferences...from the KToolbar menu and select WMA.


If you’d like the toolkit to lose some message fragments, adjust the RandomMessage Fragment Loss slider to the desired percentage. If you would like tosimulate a delay between the time message fragments are sent and received, enterthe delay in milliseconds in the Message Fragment Delivery Delay field.

8.3 Sending Messages With the WMAConsoleThe WMA console is a handy utility that allows you to send and receive messages.You can, for example, use the WMA console to send SMS messages to a MIDletrunning on the emulator.

To launch the WMA console, choose File > Utilities... from the KToolbar menu. ClickWMA Console and press Launch.

Chapter 8 Using the Wireless Messaging API 8-3

FIGURE 8-2 The WMA Console

8.3.1 Sending a Text SMS MessageTo send a text SMS message, click Send SMS... The send window pops up.


FIGURE 8-3 Sending a Text Message

The window automatically lists the phone numbers of all running emulatorinstances. Select a destination (Control-click to select multiple destinations) andenter a port number if you wish. Type your message and click Send.

8.3.2 Sending a Binary SMS MessageYou can use the WMA console to send the contents of a file as a binary message.Click Send SMS... to bring up the send window. Click the Binary SMS tab.


FIGURE 8-4 Sending a Binary Message

Selecting recipients is the same as for sending text SMS messages. You can type inthe path of a file directly, or click Browse... to open up a file chooser.

8.3.3 Sending MMS MessagesMMS messages consist of one or more files, usually images or sounds. MMSmessage can be sent to multiple recipients. To send an MMS message from the WMAconsole, click the Send MMS... button.

The window for composing MMS messages has two tabs, one for recipients and onefor content. Begin by filling in a subject and recipient. If you wish to add morerecipients, click the Add button. For example, to send a message to a runningemulator whose number is +5555555551, you would fill in the To line asmms://+5555555551. To remove a recipient, first select its line, then click Remove.


FIGURE 8-5 Adding Recipients for an MMS Message

To add media files to the message, click the Parts tab. Click Add to add a part to themessage. To remove a part, select it and click Remove.

FIGURE 8-6 Adding Parts to an MMS Message


8.4 Receiving Messages in the WMAConsoleThe WMA console can also receive messages. If you look at the WMA consolewindow, you can see it has its own phone number in the title bar. You can sendmessages to the WMA console from your applications running on the emulator.

Received messages are shown in the WMA console’s text area.


CHAPTER 9

Using the Mobile Media API

The Mobile Media API (MMAPI) provides a standard API for rendering andcapturing time-based media, like audio or video. The API was designed to beflexible with respect to the media formats, protocols, and features supported byvarious devices. For information on programming with MMAPI, see:

Mobile Media API Overview

http://developers.sun.com/techtopics/mobility/apis/articles/mmapi_overview/

The J2ME Mobile Media API

http://developers.sun.com/techtopics/mobility/midp/articles/mmapioverview/

9.1 Supported Formats and ProtocolsThe emulator’s MMAPI implementation supports the following media types:

TABLE 9-1 Supported MMAPI media formats

MIME Type Description

audio/3gpp Third Generation Partnership Project (3GPP) for audio

audio/3gpp2 Third Generation Partnership Project 2 (3GP2P) for audio

audio/aac Advanced Audio Coding (ACC)

audio/amr Adaptive Multi-Rate (AMR)

audio/midi Musical Instrument Digital Interface (MIDI) files

audio/mp3 MPEG Audio Layer 3 (MP3)

9-1

http://developers.sun.com/techtopics/mobility/apis/articles/mmapi_overview/

http://developers.sun.com/techtopics/mobility/midp/articles/mmapioverview/

The Sprint Wireless Toolkit 3.2 supports additional media types. See Section 4.8.6,“Additional Media Types” on page 4-22.

9.2 Media CaptureThe toolkit emulator supports audio and video capture. Audio capture is supportedby using the capture capabilities of the system upon which the emulator runs.

Video capture is supported by simulating a camera input.

Consult the mmademo example application for details and source code thatdemonstrates how to capture audio and video.

audio/qcelp Qualcomm PureVoice

audio/sp-midi Scalable Polyphony MIDI

audio/vnd.qcelp Qualcomm PureVoice

audio/x-tone-seq MIDP 2.0 tone sequence

audio/x-wav WAV PCM sampled audio

image/gif GIF 89a (animated GIF)

video/3gpp Third Generation Partnership Project (3GPP) for video

video/3gpp2 Third Generation Partnership Project 2 (3GP2P) for video

video/mp4 MPEG-4

video/mpeg Moving Picture Experts Group) MPEG video

video/quicktime QuickTime

video/vnd.sun.rgb565 Video capture

video/x-h264 MPEG-4 Part 10

TABLE 9-1 Supported MMAPI media formats

MIME Type Description


9.3 Well-Behaved MIDletsMIDlets have a life cycle that is defined in the MIDP specification. MIDlets can bepaused by events such as incoming phone calls. A well-behaved MIDlet releasesimportant device resources when it is paused and reallocates or restarts thoseresources when the MIDlet is resumed. In the MMAPI arena, any Players that arerendering content should be stopped when a MIDlet is paused.

The toolkit prints a message to the console if you pause a MIDlet and it does notstop its running Players. You can test this feature yourself using thePausingVideoTest MIDlet in the mmademo demonstration application. SeeAppendix A for details.

The warning message is printed once only for each running emulator.

Chapter 9 Using the Mobile Media API 9-3


CHAPTER 10

Working With Mobile Graphics

This chapter provides a brief overview of working with graphics content. The SprintWireless Toolkit 3.2 (the toolkit) offers two APIs which provide comprehensivecapabilities for interactive 2D and 3D graphics.

■ The Scalable 2D Vector Graphics API for J2ME, JSR 226, support renderingsophisticated and interactive 2D content.

■ The Mobile 3D Graphics API for J2ME, JSR 184, provides 3D graphics capabilitieswith a low-level API and a high-level scene graph API. This chapter provides abrief overview and general guidelines for working with JSR 184.

10.1 Rendering Scalable Vector Graphics(SVG) ContentThe toolkit emulator support JSR 226, the Scalable 2D Vector Graphics API for J2ME.SVG is a standard defined by the World Wide Web Consortium. It is an XMLgrammar for describing rich, interactive 2D graphics.

While it is possible to produce SVG content with a text editor, many people prefer anauthoring tool. Here are three possibilities:

■ BeatWare Mobile Designer(http://www.beatware.com/products/md_golive.html)

■ Ikivo Animator (http://www.ikivo.com/animator/)

■ Adobe Illustrator CS2(http://www.adobe.com/products/illustrator/main.html)

10-1

http://www.beatware.com/products/md_golive.html

http://www.ikivo.com/animator/

http://www.adobe.com/products/illustrator/main.html

http://www.adobe.com/products/illustrator/main.html

http://www.ikivo.com/animator/

http://www.beatware.com/products/md_golive.html

10.2 Using the Mobile 3D Graphics APIJSR 184 is a specification that defines the Mobile 3D Graphics (M3G) API for J2ME.This API provides 3D functionality in a compact package that’s appropriate forCLDC/MIDP devices. The API provides two methods for displaying 3D graphicscontent. The immediate mode API makes it possible for applications to directlycreate and manipulate 3D elements. Layered on top of this is a scene graph API, alsocalled retained mode, that makes it possible to load and display entire 3D scenesthat have been designed ahead of time. Applications are free to use whicheverapproach is most appropriate or to use a combination of the retained mode andimmediate mode APIs. The JSR 184 specification also defines a file format (.m3g) forscene graphs.

For more information, consult the JSR 184 specification:


JSR 184 provides a standard API for CLDC/MIDP devices, enabling a newgeneration of 3D applications. The immediate mode API, in turn, is compatible withOpenGL ES, a standard lightweight API for 3D graphics. Seehttp://khronos.org/ for more information on OpenGL ES.

10.2.1 Immediate ModeImmediate mode is appropriate for applications that generate 3D graphics contentalgorithmically, like scientific visualizations or statistical graphs. The applicationcreates 3D objects and manipulates them directly.

For an example of immediate mode, see the Life3D MIDlet in the Demo3D exampleapplication.

10.2.2 Retained ModeMost applications, particularly games, use the retained mode or scene graph API. Inthis approach, a graphic designer or artist uses 3D modeling software to create ascene graph. The scene graph is saved in the JSR 184 file format. The scene graph fileis bundled with the application. At runtime, the application uses the scene graphAPI to load and display the file.



http://khronos.org/

http://khronos.org/


Applications can manipulate parts of a loaded scene graph to animate characters orcreate other effects. The basic strategy is to do as much work as possible in themodeling software. At runtime, the application can grab and manipulate parts of thescene graph, which can also include paths for animation or other effects.

For an example of retained mode, see the retainedmode MIDlet in the Demo3Dexample application.

10.2.3 Trading Quality for SpeedOne of the challenges of MIDP development is the constrained environment oftypical devices. Compared to desktop computers, MIDP devices have slowprocessors and little memory. These challenges extend into the arena of 3D graphics.To accommodate a wide variety of implementations, the JSR 184 specificationprovides various mechanisms to make the display of a 3D scene as efficient aspossible.

One approach is scoping, a technique where you tell the 3D graphicsimplementation when objects are not going to interact with each other. For example,if you defined a scene graph for a house, you could use scoping to specify that thelight in the basement doesn’t affect the appearance of the bedroom on the secondfloor. Scoping makes the implementation’s job easier by reducing the number ofcalculations required to show a scene.

In general, however, the best way to improve the rendering speed of 3D scenes is tomake some compromises in quality. The Mobile 3D Graphics API includes renderinghints so that applications can suggest how the implementation can compromisequality to improve rendering speed.

10.2.4 Creating Mobile 3D Graphics ContentMost mobile 3D applications use scene graphs in resource files to describe objects,scenes, and characters. Usually it is not programmers but graphic designers or artistswho create the scene graphs, using standard 3D modeling tools.

Several vendors offer tools for authoring content and converting files to the JSR 184format. Superscape (http://superscape.com/) is one such vendor.

Because it is relatively difficult to create and manipulate 3D graphics content in anapplication using the immediate mode API, most applications rely as much aspossible on a scene graph file. Putting as much as possible into the scene graph fileat design time simplifies the application’s job at runtime.

Chapter 10 Working With Mobile Graphics 10-3

http://superscape.com/

http://superscape.com/


CHAPTER 11

Using the PIM and FileConnectionAPIs

The Sprint Wireless Toolkit 3.2 (the toolkit) supports JSR 75, the PDA OptionalPackages for the J2ME Platform. JSR 75 includes two independent APIs:

■ The FileConnection optional package allows MIDlets access to a local devicefile system.

■ The Personal Information Management (PIM) optional package includes APIs formanipulating contact lists (address book), calendars, and to-do lists.

This chapter describes how the toolkit implements the FileConnection and PIMAPIs.

11.1 The FileConnection APIOn a real device, the FileConnection API typically provides access to files storedin the device’s memory or on a memory card.

In the toolkit emulator, the FileConnection API allows MIDlets to access filesstored on your desktop computer’s hard disk.

The files that can be accessed using FileConnection are stored in subdirectories oftoolkit\appdb\skin\filesystem. For example, the SamsungA940 emulator skincomes with a root directory installed called memorycard, which contains a directorycalled photos. The full path of the file is toolkit\appdb\SamsungA940\filesystem\memorycard\photos.

11-1

Note – If multiple instances of the same emulator skin run simultaneously, thetoolkit generates unique file paths for each one. For example, a second instance ofSamsung940 might have a file system path name of toolkit\appdb\temp.SamsungA940.1145262863406\filesystem.

Each subdirectory of filesystem is called a root. The toolkit provides a mechanismfor managing roots. While the emulator is running, choose MIDlet > External eventsfrom the emulator window’s menu. You see a utility window for adding andremoving roots (FIGURE 11-1).

FIGURE 11-1 Managing Filesystem Roots

The mounted roots and their contents are available to applications using theFileConnection API.

To add a new root directory, click Mount New... Fill in a name for the directory andclick OK.

To make a directory inaccessible to the FileConnection API, select it in the listand click Unmount.


11.2 The PIM APIThe toolkit emulator stores contact, calendar, and to-do information in standard fileson your desktop computer’s hard disk. When PIM objects are created, (Section A.22,“PDAPDemo” on page A-50 has an example of PIM object creation) a directorynamed toolkit\appdb\skin\pim is created. This directory is shared by all runningemulators. Lists are stored in subdirectories of the contacts, events, and tododirectories. For example, a contact list called Contacts is contained in toolkit\appdb\skin\pim\contacts\Contacts.

Inside the list directory, items are stored in vCard or vCalendar format (seehttp://www.imc.org/pdi/). Contacts are stored in vCard format, while calendarand to-do items are both stored in vCalendar format.

Chapter 11 Using the PIM and FileConnection APIs 11-3

http://www.imc.org/pdi/

http://www.imc.org/pdi/


CHAPTER 12

Using the Bluetooth API

The toolkit emulator supports JSR 82, the Java APIs for Bluetooth. JSR 82 includestwo independent APIs, however, only the Bluetooth API is supported. The BluetoothAPI provides an interface to Bluetooth wireless networking, including devicediscovery and data exchange. The emulator is fully compliant with version 1.1 of thespecification, which describes integration with the push registry.

12.1 Bluetooth Simulation EnvironmentThe toolkit emulator allows you to develop and test application that use Bluetoothwithout having actual Bluetooth hardware. The toolkit simulates a Bluetoothenvironment for running emulators. Multiple emulator instances can discover eachother and exchange data using the Bluetooth API.

For an example, see the documentation of BluetoothDemo in Appendix A.

12.2 Setting Bluetooth PreferencesThe toolkit allows you to configure the Bluetooth and simulation environment.Choose Edit > Preferences... from the KToolbar menu and select Bluetooth to see thefollowing window.

12-1

FIGURE 12-1 Bluetooth Preferences

12.2.1 Bluetooth Internal PropertiesIn the Bluetooth section of the preferences window, the Device discovery timeout isthe amount of time, in milliseconds, the emulator waits while attempting to locateother devices in the simulated Bluetooth environment.

Bluetooth Address of Next Emulator is the Bluetooth address that is assigned to thefirst emulator instance. Subsequent instances of the emulator receive anautomatically generated address.

12.2.2 Bluetooth System PropertiesThe System Properties tab in the Bluetooth section of the preferences containsproperties that can be retrieved in an application using the getProperty() methodin javax.bluetooth.LocalDevice.

The Bluetooth properties are fully described in the JSR 82 specification.


12.2.3 Bluetooth BCC PropertiesThe Bluetooth Control Center (BCC) controls Bluetooth settings. Some devices mayprovide a GUI to customize Bluetooth settings. In the toolkit, the BCC is configuredusing the BCC Properties tab of the Bluetooth preferences. The properties are asfollows:

TABLE 12-1 BCC Properties

Property Description

Encryption This property determines whether connection encryption issupported (on) or not (off). In addition, the force settings meansall connections must be encrypted. See the documentation forRemoteDevice’s encrypt() method for details.

Authorization This is similar to the Encryption property. See RemoteDevice’sauthorize() method.

Authentication This is similar to Encryption and Authorization. SeeRemoteDevice’s authenticate() method.

Chapter 12 Using the Bluetooth API 12-3


CHAPTER 13

Using Web Services

The Sprint Wireless Toolkit 3.2 (the toolkit) emulator supports JSR 172, the J2MEWeb Services Specification. JSR 172 provides APIs for accessing web services fromJ2ME applications. It also includes an API for parsing XML documents.

The toolkit provides a stub generator that automates creating source code foraccessing web services. To get to the stub generator, choose File > Utilities. ClickStub Generator and press Launch.

FIGURE 13-1 The Web Services Stub Generator

13-1

The WSDL Filename or URL should point to the WSDL file for the web service youwant to access. The Output Path indicates the location where you want the stub filesto be placed. Output Package indicates the Java language package name for the stubfiles. Finally, choose whether you want to generate CLDC 1.0 or CLDC 1.1 stubs.

Press OK to generate the stub files.


CHAPTER 14

Using the Location API

The JSR 179 Location API gives applications the opportunity to use a device’slocation capabilities. For example, some devices include Global Positioning System(GPS) hardware; other devices may be able to receive location information from thewireless network. The Location API provides a standard interface to locationinformation, regardless of the underlying technique.

In the Location API, a location provider encapsulates a positioning method andsupplies information about the device’s location. The application requests a providerby specifying required criteria, such as the desired accuracy and response time. If anappropriate implementation is available, the application can use it to obtaininformation about the device’s physical location.

The Sprint Wireless Toolkit 3.2 (the toolkit) includes a simulated location provider.You can use the emulator’s External Events window to specify where the emulatorshould think it is located. In addition, you can configure the properties of theprovider itself, and you can manage a database of landmarks.

14.1 Setting the Emulator’s Location atRuntimeYou can specify the simulated location of the emulator while it is running. To dothis, choose MIDlet > External Events from the emulator window’s menu. Click theLocation tab.

14-1

FIGURE 14-1 Controlling the Emulator’s Location

In the Location area of the tab, you can fill in values for the latitude, longitude,


altitude, speed, and course. Applications that use the Location API can retrieve thesevalues as the location of the emulator.

For more elaborate testing, you can set up a location script that describes motionover time. Location scripts are XML files consisting of a list of locations, calledwaypoints, and associated times. The toolkit determines the current location of theemulator by interpolating between the points in the location script. Here, forexample, is a simple location script that specifies a starting point (time="0") andmoves to a new point in ten seconds:

<waypoints>

<waypoint time="0"

latitude="14" longitude="50" altitude="310" />

<waypoint time="10000"

latitude="14.5" longitude="50.1" altitude="215" />

</waypoints>

The altitude measurement is in meters, and the time values are in milliseconds.

Use a text editor to create your location script. You can load it into the external eventwindow by pressing on the Browse... button next to the Script field. Immediatelybelow are controls for playing, pausing, stopping, and moving to the beginning andend of the script. You can also drag the time slider to a particular point.

Some devices are also capable of measuring their orientation. To make this kind ofinformation available to your application, change the State field in the Orientationbox to Supported and fill in values for azimuth, pitch, and roll. The MagneticOrientation checkbox indicates whether the azimuth and pitch measurements arerelative to the Earth’s magnetic field or relative to true north and gravity.

To test how your application handles unexpected conditions, try changing the Statefield in the Location Provider box to Temporarily Unavailable or Out of Service.When your application attempts to retrieve the emulator’s location, an exception isthrown and you can see how well your application responds.

14.2 Configuring the Location ProviderYou can configure the properties of the toolkit’s location provider using thepreferences. Choose Edit > Preferences... from KToolbar’s menu and click Location.

Chapter 14 Using the Location API 14-3

FIGURE 14-2 Configuring the Toolkit’s Location Provider

The fields in the Location tab allow you to specify the properties of the toolkit’sbuilt-in location provider. The properties you specify in the preferences correspondto the Criteria class applications use to request a location provider.

14.3 Setting Up LandmarksThe toolkit emulator includes a landmark store system, just like many real devices. Alandmark store is a collection of places with associated names and otherinformation. To manage landmark stores, choose File > Utilities from the menu,select Manage Landmarks, and press Launch.


FIGURE 14-3 The Landmark Manager

The landmark manager shows the content of a single landmark store. There is, at aminimum, a single landmark store called default store, which is required by JSR 179.Use the Landmark stores: combo box at the top of the window to select a differentlandmark store or create a new one.

You can add or remove landmark stores by clicking on the Manage LandmarkStores button. Landmark stores cannot be renamed.

Landmarks can be associated with categories, which are specific to a landmark store.The categories for the current landmark store are shown in the left pane of thewindow. You can add or remove categories using the buttons at the bottom of thelist. Check off one or more of the categories if you would like to see only thematching landmarks. You can also check off no category set to see landmarks withno associated categories.

The right pane of the landmark manager lists the landmarks in the current landmarkstore. Click a landmark to see its details listed in the bottom part of the right pane.

Chapter 14 Using the Location API 14-5

To add a new landmark, click Add and fill in the fields as appropriate. Click Edit tochange the currently selected landmark. Finally, press Remove to remove thecurrently selected landmark.

FIGURE 14-4 Adding or Editing a Landmark

You can also use the Assign Categories in the main window to specify the categoriesfor a landmark.


CHAPTER 15

Using SATSA

The Security and Trust Services APIs (SATSA) provide smart card access andcryptographic capabilities to applications running on small devices. The SATSAspecification defines four distinct APIs:

■ SATSA-APDU allows applications to communicate with smart card applicationsusing a low-level protocol.

■ SATSA-JCRMI provides an alternate method for communicating with smart cardapplications using a remote object protocol.

■ SATSA-PKI allows applications to use a smart card to digitally sign data andmanage user certificates.

■ SATSA-CRYPTO is a general-purpose cryptographic API that supports messagedigests, digital signatures, and ciphers.

The four SATSA APIs are defined by JSR 177, the Security and Trust Services APIsspecification.

The Sprint Wireless Toolkit 3.2 (the toolkit) emulator fully supports SATSA. Thischapter describes how you can use the toolkit to work with SATSA in your ownapplications.

For a more general introduction to SATSA and the fun that small devices can havewith smart cards, see the SATSA Developer’s Guide:

http://java.sun.com/j2me/docs/satsa-dg/

The toolkit includes the Java Card Platform Simulator, which you can use tosimulate smart cards in the toolkit emulator’s slots. The Java Card PlatformSimulator is toolkit\bin\cref.exe and hereafter it is referred to as simply cref.

If you need to develop your own Java Card applications, you want to download theJava Card Development Kit, available here:

http://java.sun.com/products/javacard/

15-1





15.1 Card Slots in the EmulatorReal SATSA devices are likely to have one or more slots which house smart cards.Applications that use SATSA to communicate with smart cards need to specifying aslot and a card application.

The toolkit emulator is not a real device and, therefore, does not have physical slotsfor smart cards. Instead, it communicates with a smart card application via asocketprotocol. The other end of the socket might be a smart card simulator or itcould be a proxy that talks with real smart card hardware.

The toolkit emulator includes two simulated smart card slots. Each slot has anassociated socket which represents one end of the protocol that is used tocommunicate with smart card applications. You can set the socket port number foreach slot. Choose Edit > Preferences... from the KToolbar menu, then click theSATSA tab. The default ports are 9025 for slot 0 and 9026 for slot 1.

FIGURE 15-1 Setting Port Numbers for Smart Card Slots

15.2 Using the Java Card Platform SimulatorThe basic procedure for testing SATSA applications with the toolkit is as follows:

1. Start cref with a Java Card application.

2. Start the toolkit emulator.


3. When a SATSA application attempts to communicate with a smart card, it uses asocket connection to communicate with cref.

It’s important, therefore, to make sure that you start cref with the same portnumber as one of the slot port numbers you specified in the toolkit preferences.

For example, you could run cref on port 9025 with a prebuilt memory image usinga command line like this:

cref -p 9025 -i memory_image.eeprom

The toolkit includes a demonstration application, Mohair, which illustrates how touse SATSA. For detailed instructions on running Mohair, see Appendix A.

15.3 Adjusting Access ControlAccess control permissions and PIN properties can be specified in text files. Whenthe first APDU or JCRMI connection is established, the implementation reads theACL and PIN data from the acl_<slot number> in the toolkit\appdb directory.For example, an access control file for slot 0 would be toolkit\appdb\acl_0. If thefile is absent or contains errors, the access control verification for this slot is disabled.

The file can contain information about PIN properties and application permissions.

15.3.1 Specifying PIN PropertiesPIN properties are represented by a pin_data record in the access control file.

pin_data {label <string>id <number>type <bcd | ascii | utf | half-nibble | iso>min <minLength> -stored <storedLength>max <maxLength>reference <byte>pad <byte> - optionalflag <case-sensitive | change-disabled |

unblock-disabled | needs-padding |disable-allowed | unblockingPIN>

}

Chapter 15 Using SATSA 15-3

15.3.2 Specifying Application PermissionsApplication permissions are defined in acf records.

The acf record is an Access Control File. The AID after acf identifies theapplication. A missing AID indicates that the entry applies to all applications. Theacf record can contain ace records. If there are no ace records, access to anapplication is restricted by this acf.

acf [<AID - numbers separated by blanks>] {ace {

root <CA name>...

apdu {<8 numbers separated by blanks>...

}...jcrmi {

classes {<class name>...

}hashModifier <string>methods {

<method name and signatiure>...

}}...pin_apdu {

id <number><verify | change | disable | enable | unblock><4 hexadecimal numbers>...

}...pin_jcrmi {

id <number><verify | change | disable | enable | unblock><method name and signatiure>...

}...

}...

}


The ace record is an Access Control Entry. It can contain root, apdu, jcrmi,pin_apdu and pin_jcrmi records.

The root record contains one CA name. If the MIDlet suite was authorized using acertificate issued by this CA, this ace grants access to this MIDlet. A missing rootfield indicates that the ace applies to all identified parties. One principal isdescribed by one line. This line must contain only the word root and the principalname. For example:

root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=US

The apdu or jcrmi record describes an APDU or JCRMI permission. A missingpermission record indicates that all operations are allowed.

An APDU permission contains one or more sequences of 8 hexadecimal values,separated by blanks. The first four bytes describe the APDU command and the otherfour bytes are the mask. For example:

The JCRMI permission contains information about the hash modifier (optional), classlist, and method list (optional). If the list of methods is empty, an application isallowed to invoke all the remote methods of interfaces in the list of classes. Forexample:

All the numbers are hexadecimal. Tabulation, blank, CR and LF symbols are used asseparators. Separators can be omitted before and after symbols { and }.

The pin_apdu and pin_jcrmi records contain information necessary for PIN entrymethods, which is the PIN identifier and APDU command headers, or remotemethod names.

apdu {0 20 0 82 0 20 0 82

80 20 0 0 ff ff 0 0}

jcrmi {classes {

com.sun.javacard.samples.RMIDemo.Purse}hashModifier zzzmethods {

debit(S)VsetAccountNumber([B)VgetAccountNumber()[B

}}


15.3.3 Access Control File Examplepin_data {

label Unblock pinid 44type utfmin 4stored 8max 8reference 33pad ffflag needs-paddingflag unblockingPIN

}

pin_data {label Main pinid 55type half-nibblemin 4stored 8max 8reference 12pad ffflag disable-allowedflag needs-padding

}

acf a0 0 0 0 62 ff 1 {ace {


pin_jcrmi {id 55verify enterPIN([B)Schange changePIN([B[B)Sdisable disablePIN([B)Senable enablePIN([B)Sunblock unblockPIN([B[B)S

}}

}

acf a0 0 0 0 62 ee 1 {ace {


pin_apdu {id 55verify 1 2 3 1


change 4 3 2 2disable 1 1 1 3enable 5 5 5 4unblock 7 7 7 5

}}

}

acf a0 0 0 0 62 3 1 c 8 1 {ace {


jcrmi {classes {

com.sun.javacard.samples.RMIDemo.Purse}hashModifier xxxmethods {

setAccountNumber([B)VgetBalance()Scredit(S)V

}}

}ace {

jcrmi {classes {

com.sun.javacard.samples.RMIDemo.Purse}

methods {debit(S)VgetAccountNumber()[B

}}

}}

acf a0 00 00 00 62 03 01 0c 02 01 {ace {

root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=USapdu {

0 20 0 82 0 20 0 8280 20 0 0 ff ff 0 0

}apdu {

80 22 0 0 ff ff 0 0}

}}

acf a0 00 00 00 62 03 01 0c 02 01 {


ace {apdu {

0 20 0 82 ff ff ff ff}

}}

acf a0 00 00 00 62 03 01 0c 06 01 {

ace {apdu {

0 20 0 82 ff ff ff ff}

}}



CHAPTER 16

Using SIP

The Sprint Wireless Toolkit 3.2 supports the SIP API for J2ME (JSR 180) with a proxyserver, registrar, and network monitor support.

Session Initiation Protocol (SIP) is defined by RFC 3261, available athttp://www.ietf.org/rfc/rfc3261.txt.

SIP provides a standard way for applications to set up communications. Theapplication determines what communication actually takes place. SIP can be used toset up instant messaging, text chat, voice chat, video conferencing, or other types ofsessions.

16.1 Understanding the Registrar and ProxyA SIP registrar enables client applications to associate a user name with a specificnetwork address. In essence, registering provides a way for a user to say “Here Iam!”

A SIP proxy server is really just an entry point into a larger network of proxyservers. SIP messages that arrive at one proxy are routed to an appropriatedestination, which is usually another proxy server or an end point, like a desktopcomputer or a mobile device. Although SIP messages can be sent directly betweendevices, they are usually routed through a proxy server.

For example, suppose Diggory wants to start a video conference with Polly. Polly istravelling and her mobile phone sends a message to a registrar that associates hername with the mobile phone’s network address. When Diggory tries to set up thevideo conference with Polly, his application uses SIP to ask the registrar for Polly’scurrent network location.

16-1

http://www.ietf.org/rfc/rfc3261.txt

http://www.ietf.org/rfc/rfc3261.txt

The Sprint Wireless Toolkit 3.2 includes a very simple SIP proxy and registrar serverthat you can use for testing applications that use the SIP API. You can also configurethe toolkit to use an external proxy server and registrar server.

16.2 SIP SettingsTo adjust settings for the Sprint Wireless Toolkit 3.2 SIP environment, choose Edit >Preferences from the KToolbar menu and click SIP.

FIGURE 16-1 SIP Settings

Display name and Address set the system properties sip.display.name andsip.address, respectively. Applications can use these system properties as astandard way to retrieve the identity associated with the device.

16.3 SIP Proxy Server and RegistrarThe Sprint Wireless Toolkit 3.2 provides a simple SIP proxy server and registrar tomake it easier to create SIP applications. To start the server, choose File > Utilitiesfrom the KToolbar menu. Select Start SIP Server from the list and press Launch. TheSIP server console window appears.


FIGURE 16-2 SIP Server Console

To start the server, click Start. To stop the server, click Stop.

While the server is running, the top left pane shows all users known to the registrar.Click a user name to see details about the user in the top right pane. The bottompane of the window is a console that shows SIP messages that are received and sentby the proxy.

Chapter 16 Using SIP 16-3

You can adjust the server options when the server is not running. Click Stop to halsthe server. Click the Options button to see the Options window.

On the Proxy tab, you can set the IP address and ports upon which the server listensfor incoming messages. Click Add to specify more ports and their types. Select aport and click Remove to take away a listening port.

Check Use Authentication to force connecting clients to authenticate themselves tothe server. The scheme used is digest authentication, which is described in section22.4 of RFC 3261. SIP’s digest authentication is nearly identical to HTTP digestauthentication.

FIGURE 16-3 Setting Proxy Options

On the Registrar tab, you can set up the users and domains known to the registrar.The top list contains SIP users that are automatically registered when the SIP serveris started. You can add a new user, edit an existing user, or remove a user.

In addition, you can adjust the list of domains managed by this registrar. Press Addto add a domain, Edit to edit an existing domain name, or Remove to remove adomain.


FIGURE 16-4 Setting Registrar Options

Chapter 16 Using SIP 16-5


CHAPTER 17

Working with the Payment API

JSR 229, the Payment API, enables applications to make payments on behalf of theirusers. The Payment API supports different payment mechanisms through paymentadapters. A device that implements the Payment API has one or more adapters.MIDlet suites use descriptor attributes to specify what types of payment adaptersthey can use.

The toolkit’s emulator implements the Payment API with an example paymentadapter that simulates both Premium Priced SMS (PPSMS) and credit cardpayments. In addition, the toolkit makes it easy to set the necessary attributes in theMIDlet’s descriptor and JAR file manifest. Finally, a payment console enables you toeasily track payments made or attempted by an application.

Because the Payment API is closely tied to provisioning and external devicepayment mechanisms, and because payments can only succeed in a trustedprotection domain, always test and debug your Payment API applications using thetoolkit’s Run via OTA mechanism. See Chapter 2 for details.

17.1 Project Settings for PaymentTo adjust the payment attributes for a project, click the Settings button and select thePayment icon.

17-1

FIGURE 17-1 Payment Settings

The fields and values are explained fully in JSR 229, the Payment API specification.


The General box contains information about the Payment API version in use andwhere to find payment updates. For testing, you can specify a localhost URL (asshown in the screen shot) that retrieves an update file directly from your projectdirectory.

The Debug box contains options that are useful during application testing. Eachoption is explained in the Payment API specification.

The Features box lists the features your application can charge. These featurescorrespond to the pricing information that is listed for each provider. You canmodify the list of features by using the Add and Remove buttons.

The Providers box lists specific payment providers that can be used for thisapplication. When the time comes to make a payment, the emulator (or device)matches one of its available payment adapters to one of the providers listed for theapplication. You can modify the list of providers with the Add, Edit, and Removebuttons. If you add or edit a provider, the following window appears.

FIGURE 17-2 Editing a Payment Provider

These fields are also described fully in the Payment API specification.

The Price Info box contains one line for each defined payment feature. To edit avalue for a price tag, double click the corresponding cell in the Value column.

Chapter 17 Working with the Payment API 17-3

17.2 Editing Payment Attributes DirectlyPayment attributes are stored in a payment update file with a .jpp extension. Readthe specification for full details. The Sprint Wireless Toolkit 3.2 provides a utility thatmakes it easy to edit the payment update file independently of the project settings.

To run the utility, choose File > Utilities from the KToolbar menu, select PaymentEdit Dialog, and press Launch. You are prompted to select the payment update fileyou wish to edit. After you choose a file, a window that looks nearly identical to thePayment section of the project settings appears. The debug settings are not includedin the payment edit utility.

Edit the payment update settings and press OK when you’re finished. Becausepayment update files are cryptographically signed, the toolkit shows you a list ofkeys that you can use to sign the file. Select the key you wish to use and press SignPayment Update File.

17.3 Payment PreferencesYou can adjust the Payment API settings for the toolkit by choosing Edit >Preferences from the KToolbar menu and clicking Payment.


FIGURE 17-3 Setting Payment Preferences

The Mobile Country Code (MCC) and Mobile Network Code (MNC) are used inconjunction with PPSMS payment providers. Taken together, the MCC and MNCidentify the wireless carrier of a device. At payment time, the MCC and MNC areused to find a matching provider from the list of providers in the project settings.Because the emulator is not a real device, you can simulate a carrier by filling inappropriate values for MCC and MNC. Consult the Payment API specification formore details.

Past Transactions Limit determines how many previous transactions are recorded inthe emulator. This affects the length of the list shown in the external event window,described below, as well as the number of past transactions that can be retrieved bythe application itself.

Finally, Console Phone Number determines the simulated phone number of thepayment console, which is described later.

17.4 Viewing Transaction HistoryThe emulator keeps track of payment transactions, just as a real device does. To seethe history of transactions, choose MIDlet > External Events from the emulatorwindow’s menu. Click the Payment Transactions tab.


FIGURE 17-4 Viewing Payment Transactions

Click Refresh to update the list after making more payments. Select a transactionand click Details to see all the details in a separate window.


The external events window only shows transactions that have been made while theemulator is running via OTA. Although it is possible to complete transactionswithout using OTA, such transactions are not shown. For the most realisticsimulation of payments, always use Run via OTA to test applications.

17.5 Monitoring PaymentsThe Sprint Wireless Toolkit 3.2 provides a payment console that makes it easy to seepayments passing through the example payment adapter.

FIGURE 17-5 Payment Console

In addition, you can view transactions using the network monitor. Credit cardtransactions are conducted using HTTPS, while PPSMS transactions use SMS. For afull description of the network monitor, see Chapter 5.



CHAPTER 18

Using the MobileInternationalization API

JSR 238, the Mobile Internationalization API, is designed for applications that are tobe displayed in multiple languages and used in multiple countries. The combinationof country (or region) and language is a locale.

The central concept of JSR 238 is a resource, which is a string, image, or other objectthat is suitable for a particular locale. For example, an application that is to bedistributed in Europe might include resources for Italian-speaking people living inItaly, Italian-speaking people living in Switzerland, Spanish-speaking people livingin Spain, Spanish-speaking people living in Portugal, and so on.

Resources are stored in files in a format defined in JSR 238. The resource files arebundled as part of the MIDlet suite JAR file. The Sprint Wireless Toolkit 3.2 providesa resource manager that simplifies the job of creating and maintaining resource files.

18.1 Setting the Emulator’s LocaleA device’s locale is contained in the system property microedition.locale. Youcan change the emulator’s locale by choosing Edit > Preferences from the KToolbarmenu, then selecting i18n. Choose a locale from the combo box or type it in directly.

18.2 Viewing Application ResourcesTo launch the resource manager, choose File > Utilities from the KToolbar menu.Select i18n Resources Manager and click Launch.

18-1

FIGURE 18-1 Resource Manager

First, choose your project from the Projects menu. All the resources for the selectedproject are shown in the rest of the window. If this is your first time looking at theresource manager, look at the resources for the i18nDemo demonstrationapplication, which contains lots of interesting resources.

You can click + symbols to expand directories or - symbols to collapse them.

Nearly all other operations are available by right-clicking directories or resourcefiles.

The top pane of the window shows the hierarchy of resource files in the application,while the bottom pane shows the contents of a resource file. In FIGURE 18-1, thecontents of the top-level common resource file are being displayed.


18.3 Working With LocalesLocales are represented by directories under the top-level global directory. Thelocale directories contain resource files which, in turn, hold the actual resources thatcan be used by the application.

Locales are represented by standard language and country codes as described in theMIDP 2.0 specification. For example, pt-BR represents Portuguese-speaking peopleliving in Brazil.

To add a locale directory, right-click the top-level global directory and choose AddLocale. Choose the locale from the combo box, or type it directly, and click OK.

To rename a locale, right-click the locale directory and choose Rename.

To remove a locale and all its contained resource files, right-click the locale directoryand choose Delete.

18.4 Working With Resource FilesResource files can be global (at the top level) or inside a locale directory. To create anew global resource file, right-click the top-level global directory and choose Addnew resource file. Choose a name for the file.

Rename a resource file by right-clicking the file and choosing Rename.

Remove a resource file by right-clicking the file and choosing Delete.

You can copy, cut, and paste entire resource files. Right-click a file and choose Copyor Cut. Then right-click the locale directory (or the top-level global) and choosePaste.

18.5 Working With ResourcesSelect a resource file in the top pane of the resource manager window to see itscontents in the bottom pane.

To add a new text resource, click Add and select Add string resource. An identifier isautomatically assigned, but you can enter a different one if you want. Click OK.

Chapter 18 Using the Mobile Internationalization API 18-3

To add an image or another type of data, click Add and select Add binary resource.You can browse to whatever file you want to add. Again, you can change theidentifier if you wish. Click OK to add the resource.

FIGURE 18-2 Adding an Image Resource

To edit a resource, double-click it. You can type a new value for a string resource. Ifyou double-click file resources, you can choose another file.


CHAPTER 19

Working with the Sprint API

This chapter provides a brief overview of working with the Sprint 2.0 API and theSprint 2.1 API.

19.1 External CanvasThe Sprint 2.0 extension includes an API that allows applications to display to eitherthe main screen or a secondary screen. This is relevant for flip devices. Thesecondary screen is also referred to as the “external screen“ or the “external canvas.“The Sprint API class com.sprintpcs.lcdui.ExternalCanvas allows MIDlets todraw to a secondary Liquid Crystal Display (LCD) on the device.

The setLCD method controls the display as follows:

19.2 Sprint LocationThe Sprint 2.1 extension includes an API that allows applications to get the locationof the device's BSC (Base Station Controller), which supplies Radio Frequency (RF)services to the device. The specification also includes an API that allows applicationsto get location information from a server that supplies GPS services to some ofSprint's devices. The class com.sprintpcs.util.Location is only available with

Display to primary screen: setLCD(PRIMARY_LCD)

Display to secondary screen: setLCD(SECONDARY_LCD)

Choose the screen based on device state (closed or open): setLCD(AUTO_LCD)

19-1

the 2.1 API. It enables a MIDlet to perform specific Location logic beyond the JSR179Location API: http://www.jcp.org/en/jsr/detail?id=179. The SprintLocation API is not fully implemented because the GPS server is not simulated.

The getBSCLatitude method returns the BSC latitude value and thegetBSCLongitude returns the BSC Longitude value.

The following steps describe how to edit the values of BSC Latitude and BSCLongitude to control the values that these methods return.

1. Run your project.

2. In the emulator window, select Midlet > External Events.

3. In the External Event Generator window (FIGURE 19-1), click the Location taband find the Sprint Location area at the bottom of the window.

4. Edit the values of BSCLatitude and BSCLongitude properties.


http://www.jcp.org/en/jsr/detail?id=179

http://www.jcp.org/en/jsr/detail?id=179

FIGURE 19-1 Location Panel

Chapter 19 Working with the Sprint API 19-3

19.3 MugletThe Sprint com.sprintpcs.util.Muglet class that belongs to the Sprint 1.0extension simplifies content handling. With the Muglet mechanism, a MIDlet can usecontent without knowing its format and without specifying the midlet required toprocess that format. When the content is used, the Muglet mechanism checks thecontent type and activates the appropriate midlet.

To support the Muglet mechanism, the Toolkit maintains the Generic ContentDescriptor (GCD) table. Use this table to list content you want to make available toyour applications.

The GCD table lists the following information for each content item:

■ Unique ID

■ Mime type: The file type. For example: media\x-wav

■ URL: The exact location of the file. It could be an HTTP URL, or it can be locatedin a MIDlet’s JAR.

Follow these steps to edit the GCD table:

1. Select File > Utilities.

See FIGURE 19-2.

2. Select GCD Manager and click the Launch button.

The GCD Manager window opens (FIGURE 19-3).


FIGURE 19-2 Utilities Window


FIGURE 19-3 GCD Table

3. To add a resource, click Add.

An empty row is added to the table.

4. Edit each field. See FIGURE 19-3 for an example.

Note – Muglet-related MIDlets must be run via OTA. See Section A.18, “MugletDemo” on page A-43.

The Muglet content handling process has two participants: the calling MIDlet andthe handling MIDlet.

■ The calling MIDlet needs a resource but doesn't have the ability to handle it. Itredirects the resource.

■ The implementation launches the handling midlet to handle the resource.

19.3.1 Writing Code Using the MugletBefore beginning, make sure that the content is listed in the GCD table.

The following is a sample of the code that should be written in the calling MIDlet:

// Passing resource to activate another MIDlet using Mugletcom.sprintpcs.util.System.setExitURI(“file:\\res\myWavFile.wav”);

// Exit Mugletmidlet.notifyDestroyed();


If the content file name is passed without the handling MIDlet, the implementationfinds and activates a MIDlet that can handle the file type.

Note – After calling System.setExitURI, the calling MIDlet must callnotifyDestroyed(). If it is not called the results are unpredictable.

The following code is an example of the code that should be written in the handlingMIDlet:

19.4 SystemThe Sprint 2.0 specification includes an API that supports receiving notifications andsetting different system properties. This functionality is provided by thecom.sprintpcs.util.System class and thecom.sprintpcs.util.SystemEventListener interface.

To be notified whenever properties change, an application should implementSystemEventListener and implement the systemEvent(java.lang.Stringproperty, java.lang.String value) method.

The toolkit allows the developer to edit property values.

1. Run your project.

2. In the emulator window, select Midlet menu > External Events.

3. Click the Sprint System States tab.

The properties panel (FIGURE 19-4) has two tabs: Protected Properties andNon-Protected Properties. Only non-protected properties can be edited.

// Getting the instance of the MugletmugletInstance = Muglet.getMuglet();// If the muglet instance is not null, then it was activated by another// MIDlet and the resource should be handledif (mugletInstance != null) {

audio = mugletInstance.getURI();mime = mugletInstance.getMediaType();.....// handling the resource.....

} else {// This MIDlet wasn't activated by another MIDlet

}


The Non-Protected Properties tab (FIGURE 19-4) has separate areas for 2.0, 2.1, and 2.2version properties. Selecting 2.0 excludes 2.1 and 2.2. Selecting 2.0 includes 2.1, andselecting 2.2 includes all properties. For descriptions of each property, see the Sprint2.1 and 2.2 Extenstions documentation in the install-dir\docs\api directory.

FIGURE 19-4 Non-Protected Properties


The System API also activates the volume monitoring mechanism whenSystem.promptMasterVolume is called, as shown in FIGURE 19-5.

FIGURE 19-5 Master Volume



APPENDIX A

Application Demonstrations

This appendix describes the application demonstrations that are bundled with theSprint Wireless Toolkit 3.2 (the toolkit).

A.1 OverviewThe toolkit includes demonstration applications that highlight some of thetechnologies and APIs that are supported by the emulator. The goal of thesedemonstrations is to give you a glimpse of the API features of the emulator and theenhancements throughout the toolkit.

TABLE A-1 lists all the demonstration applications that are included in this release.

Most demonstration applications are simple to run. Section A.2, “GeneralInstructions” on page A-4 contains instructions for running most demonstrations.Demonstrations that have additional documentation are linked in TABLE A-1. If thereis no link, the demonstration is simple (or has its own instructions) and the generalinstructions are sufficient.

The source code for every demonstration application is available in the toolkit\appsdirectory. Subdirectories contain projects, and each project has a src directory thatcontains Java programming language source code. For example, if the toolkit isinstalled in C:\SPRINT_WTK_32, the source code for the SMS sender MIDlet(example.sms.SMSSend) in WMADemo is contained in C:\SPRINT_WTK_32\apps\WMADemo\src\example\sms\SMSSend.java.

A-1

TABLE A-1 Application Demonstrations

Demonstration APIs DescriptionSpecialInstructions

AdvancedMultimediaSupplements JSR 234 AdvancedMultimediaSupplements

Shows 3D audio, reverberation, imageprocessing, and camera control.

A.3

Audiodemo MMAPI 1.1 Demonstrates audio capabilities,including mixing and playing audiowith an animation.

BluetoothDemo JSR 82 Bluetooth Demonstrates device discovery anddata exchange using Bluetooth.

A.4

CHAPIDemo JSR 211 CHAPI A content viewer which also makesuses of MediaHandler.

A.5

CityGuide JSR 179 LocationAPI

Shows a city map that displayslandmarks based on the currentlocation.

A.6

DebugApp Demonstrates how to write or readdata to and from a COMM console ordevice.

A.7

Demo3D JSR 184 Mobile 3DGraphics

Contains MIDlets that demonstratehow to use 3D graphics, bothimmediate mode and retained mode.

A.8

Demos MIDP 2.0 Includes various examples: animation,color, networking, finance, and others.

A.9

FPDemo CLDC 1.1 Simple floating point calculator.

Games MIDP 2.0 Includes TilePuzzle, WormGame, andPushPuzzle.

GoSIP JSR 180 SIP Demonstrates setting up a chat usingSIP and a SIP server.

A.10

Hello World A simple Hello World MIDlet.

i18nDemo JSR 238 MobileInternationalizationAPI

Includes string sorting, numberformatting, and a phrase translator.

A.11

JBricks JSR 229 PaymentAPI

A game that uses the Payment API forbuying extra lives or levels.

A.12

JSR172Demo Web services Demonstrates how to use the JSR 172API to connect to a web service from aMIDlet.

A.13

A-2 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

KeyEventDemo When a key is pressed, displays thecorresponding event.

A.14

LX260-Test-S05 Demonstrates portrait and landscapedisplay for LX260.

A.15

MobileMediaAPI MMAPI 1.1 Demonstrates MMAPI features,including tone sequences, MIDIplayback, sampled audio playback,and video.

A.16

MP4Player Sprint Demonstrates that MP4 files can beplayed on an external screen for Sprint2.0 extensions.

A.17

MugletDemo Sprint Demonstrates MIDlet capabilities forSprint 1.0 extension.

A.18

MVMDemoBackgroundNoPause Sprint Demonstrates Multitasking VMsettings.

A.19

MVMDemoLaunchBackground Sprint Demonstrates Multitasking VMsettings.

A.19

MVMDemoPowerOn Sprint Demonstrates Multitasking VMsettings.

A.19

NetworkDemo MIDP 2.0 Shows how to use datagrams andserial connections.

A.20

ObexDemo JSR 82 OBEX Demonstrates transferring data usingOBEX over IrDA.

A.21

PDAPDemo JSR 75 PIM andFileConnection

Shows how to manipulate contacts,calendar items, and to-do items.Demonstrates accessing local files.

A.22

Photoalbum MIDP 2.0 Demonstrates a variety of imageformats.

Razr2Demo Demonstrates RAZR2 touch sensitivebutton support.

A.23

RecordStoreDemo MIDP 1.0 and 2.0 Demonstrates RecordStore, as definedin the MIDP 1.0 and 2.0 APIs.

A.24

SATSADemos JSR 177 SATSA Demonstrates communication with asmart card and other features ofSATSA.

A.25

SATSAJCRMIDemo JSR 177 SATSA Shows how to use SATSA-JCRMI. A.26

TABLE A-1 Application Demonstrations (Continued)


Appendix A Application Demonstrations A-3

A.2 General InstructionsMost of the demonstration applications can be run then launched with no specialpreparation. Some demonstrations, however, require changes to the toolkitpreferences or settings. This section describes the general procedure.

The first step is to run the toolkit. Go to the Microsoft Windows Start menu andchoose Start > Programs > Sprint Wireless Toolkit 3.2 - Powered by Java Technology> KToolbar. The KToolbar window appears:

SIPDemo JSR 180 SIP Uses SIP to communicate between twodevices.

A.27

SprintDemo Sprint Includes External Canvas demo,SystemStates demo, and Media demo.

A.28

SVGContactList JSR 226 SVG API Demonstrates a contact list displayedwith different skins.

A.29

SVGDemo JSR 226 SVG API Shows different techniques forrendering SVG

A.30

UIDemo MIDP 2.0 Showcases the breadth of MIDP 2.0'suser interface capabilities

A.31

VirtualKeypadDemo Java virtual keypad for the SamsungUpStage device

A.32

WMADemo WMA 2.0 Shows how to send and receive SMSand MMS messages

A.33

TABLE A-1 Application Demonstrations (Continued)



FIGURE A-1 KToolbar

Click the Open Project button to open a demonstration application. A list of all theavailable applications appears.


FIGURE A-2 Opening a Demonstration Application Project

Select a project and click the Open Project button in the dialog. Once the applicationis open, press the Run button.

The device emulator window opens with the demo application running. If there is amenu of MIDlets, use the navigation arrows to choose an item, then choose SELECT.As the demonstration progresses you might need to press one of the soft keys belowthe screen on the left or right side. You use soft keys to launch an application, opena menu, exit, or perform some other action.


Some demonstrations require specific setup and instructions. For example, if anexample uses web services and you are behind a firewall, you must configure theemulator’s proxy server settings or the demo fails. Choose Edit > Preferences fromthe KToolbar menu, then select Network Configuration. Check Use proxy server. Fillin the proxy server address field and the port number.

Read each demonstration description for more operating instructions.

Sometimes a menu has numbered items. To choose an item number, type it on yourkeyboard or click the number on the emulator keypad.

Some demonstrations require other setup and instructions. Check the full list to seeif there are specific instructions for a demonstration.

A.3 Advanced Multimedia SupplementsThis MIDlet suite demonstrates the power of JSR 234 Advanced MultimediaSupplements (AMMS) with two MIDlets: Image Effects, and Moving Helicopter.

Image Effects - Shows standard image processing operations. Choose an effect fromthe menu. The processed image is shown following the source image as shown inFIGURE A-3. Note that some items, Set Transforms, for example, can perform severaloperations. Click the Done soft button to apply the effects you have chosen.

FIGURE A-3 Original and Reduced Image with Border Added

Moving Helicopter - Simulates a helicopter flying around a stationary observer (thered dot is the helicopter and the blue dot is the observer). Use headphones for bestresults. From the soft menu, you can control the following effects:


1. Volume.

2. Location Settings. The screen width determines how far the helicopter can rangeand the flight altitude affects the level of sound from the helicopter.

3. Spectator Orientation. A radio button list describes the position of the observer. Ifyou have fallen on your right side, you should only hear through your left ear,while the opposite is true if you fall on your left side. For the other options thesound difference is subtle.

4. Distance Attenuation setting. For the minimum attenuation distance, a highnumber makes the volume louder overall as the helicopter advances and retreats.For the factor determining the speed of the sound attenuation, a high numbercauses the sound to fade more quickly. The maximum attenuation distance is thelimit of the observer’s ability to distinguish sound. If “Mute beyond MaximumDistance“ is checked, the observer hears nothing when the helicopter is out ofrange. For example, if the screen width is 30 meters, and the maximumattenuation distance is 12 meters, the sound will disappear as the helicopter nearsthe edge of the screen.

Options 1, 2 and 4 use interactive gauges like those shown in FIGURE A-4. To changea setting, navigate left or right to highlight a + or - control.

With the + or - highlighted, press select to perform the action. The number of bars inthe gauge increases or decreases, and the values change.

If you can’t see all the settings, navigate down to scroll the screen.

FIGURE A-4 Helicopter Demo Controllers


A.4 Bluetooth DemoThis application contains MIDlets that demonstrate the use of JSR 82’s BluetoothAPI.

The project BluetoothDemo shows how images can be transferred between devicesusing Bluetooth. You must run two instances of the emulator to see how thisdemonstration works.

In the first emulator, launch Bluetooth Demo, then choose Server. The emulator asksyou if you want to allow a Bluetooth connection. Choose Yes. The server starts anddisplays a list of images. At the beginning, none of the images are available on theBluetooth network. To make images available, select them and from the menuchoose Publish image (or type or click 1). The icon color changes from purple togreen, indicating it is published.

FIGURE A-5 Running the Bluetooth Demo Server

On the second emulator, launch Bluetooth Demo, then select Client. The MIDlet tellsyou it’s ready to search for images. Click the Find soft button. The MIDlet finds theother emulator and get a list of images from it. Select one from the list and chooseLoad. The emulator asks if you want to allow the connection. Choose Yes.

■ If you are running the demonstration in a trusted protection domain, the image istransferred using simulated Bluetooth and is shown on the client emulator.

■ If you are not running in a trusted protection domain, the first emulator (theserver) displays a prompt asking if you want to authorize the connection from theclient. Choose Yes. The image is displayed in the client emulator.


FIGURE A-6 Image Transferred Using Simulated Bluetooth

A.5 CHAPIDemoCHAPIDemo is a content browser. It maintains a list of favorites and enables you toselect and view various kinds of content.

This demonstration uses the content handler registry, so you cannot see all of itsfeatures when you use the Run button. Instead, use Project > Run via OTA to installthe application into the emulator. If you don’t know how to do this, read about it inSection 2.3.2, “Install” on page 2-10.

After you install CHAPIDemo, it appears in the application list as Text Viewer. It isa MIDlet that is a content handler for plain text. Select Text Viewer and chooseLaunch from the soft button menu. A list of favorite links appears.


FIGURE A-7 Viewing Favorite Links in CHAPIDemo

Use the navigation keys to highlight CHAPIDemo then press SELECT on theemulator. The application asks if it is OK to use airtime. Press the Yes soft button. Alist of various types of content appears (FIGURE A-8).

FIGURE A-8 Content List

Try selecting one of the PNG files first. Use the arrows to highlight the link, thenpress SELECT to view the file. Using CHAPI, the ImageViewer MIDlet is launchedand displays the content.


FIGURE A-9 Viewing a PNG Image

The other types of content require another content handler MIDlet suite,MediaHandler. To install this suite from CHAPIDemo, select thehttp:handlers/MediaHandler.jad link (from the list shown in FIGURE A-8). TheAMS is invoked and leads you through the installation.

After the MIDlet suite is installed, you can view the other types of content listed inText Viewer. For example, select http:video/test-mpeg.mpg to see a series ofimages including the one shown in FIGURE A-10.

FIGURE A-10 Viewing an MPEG Movie Using MediaHandler

To view the content handler settings for the TextViewer and ImageViewer MIDlets,click Settings in KToolbar, then click the Content Handlers icon. You might also wishto examine the MediaHandler project.


A.6 CityGuideCityGuide shows how you can use the Location API. It shows your current positionsuperimposed on a city map. As you move around the city, interesting landmarksare highlighted and identified.

Because location prompts occur frequently, it is best to run this demonstration intrusted or maximum mode. In Ktoolbar, select Edit > Preferences, then selectSecurity. Choose maximum for the Security domain.

Open and run the CityGuide project. In the emulator, launch the CityGuide MIDlet.Click Next to view the map page.

FIGURE A-11 Your Location in the City

Choose MIDlet > External events from the emulator window menu. On the locationtab (see FIGURE A-11), click the browse button and select the file toolkit\apps\CityGuide\citywalk.xml.


FIGURE A-12 Adjusting the Emulator’s Simulated Location


The player buttons at the bottom of the window are now active. Press the green playbutton (right-pointing triangle) to run the script.

The display shows four types of landmarks: restaurants, museums, shops, andtheaters. Open the soft menu and choose the Settings command to adjust thelandmark display. Use the navigation keys to highlight a category, then use SELECTto check or uncheck an item.

When you are near a landmark (shown highlighted on the map), open the soft menuand choose the Detail command to see more information. See Chapter 14 for moredetails on location scripts.

A.7 DebugAppDebugApps demonstrates how to transmit the System.out and System.errstreams from a MIDlet running on a real device to the toolkit running on a PC. Forthis example we use two PCs (instead of a PC and a device). We call them PC1 andPC2.

■ PC1 is running the toolkit and the emulator.

■ PC2 represents the real device running the MIDlet. This demo document featuresscreen shots showing the toolkit’s COMM terminal, but there is no requirement toinstall the toolkit on PC2. All that is required is a console, such as HyperTerm.

1. Use a serial cable to connect two PCs on the same COM port.

For example, run a serial cable between COM1 on PC1 and COM1 on PC2.

2. On PC2, configure the console for this demo.

The demo uses the following fixed parameter values, so set your consolepreferences to match:

3. On PC1, open the DebugApp demo.

4. Select the port that is connected to PC2 and press the Connect Button.

baudrate 115200

parity none

stopbits 1

databits 8

flow control hardware


When the Connect button is pressed the message “Type text below usingcomputer keyboard“ is sent to the console on PC2. The MIDlet waits for aninput stream.

On PC2, the message arrives in the console window.

5. On PC2, type the character A into the Input field and press the Send button.


6. On PC1 check the emulator to see the incoming message from the console.

A.8 Demo3DThis application contains three MIDlets that show off the emulator’s support of JSR184, the Mobile 3D Graphics API.

A.8.1 Life3DLife3D implements the popular Game of Life in three dimensions. Live cells arerepresented by cubes. Each cell has 26 possible neighbors (including diagonals). Foreach step of the animation, cells with fewer than four neighbors die of loneliness,while cells with more than five neighbors die of overcrowding. An empty cell withexactly four neighbors becomes a new live cell.

The view of the playing board rotates slowly so you can view the board from allangles.


FIGURE A-13 Game of Life in Three Dimensions

The keypad buttons in TABLE A-2 provide control over the game.

The source code for this example is particularly well documented. Take a look attoolkit\apps\Demo3D\src\com\superscape\m3g\wtksamples\life3d\Life3D.java.

A.8.2 PogoRooPogoRoo shows a kangaroo bouncing up and down on a pogo stick. To steer thekangaroo, use the arrow keys. Push up to go forward, down to go backward, and leftand right to change direction. You might need to hold down the key to see an effect.

TABLE A-2 Controls for Life3D

Button Description

0 Pause the animation.

1 Resume the animation at its default speed.

2 Speed up the animation.

3 Slow down the animation.

4 Choose the previous preset configuration from an arbitrary list. The name of theconfiguration is shown at the top of the screen.

5 Choose the next preset configuration from the list.

* Generate a random configuration and animate until it stabilizes or dies. If it dies,generate a new random configuration.


FIGURE A-14 Bouncing Kangaroo

A.8.3 retainedmode

The retainedmode MIDlet plays a scene file that shows a tireless skateboarder inan endless loop.


FIGURE A-15 Tireless Skateboarder

A.9 DemosThis demo contains several MIDlets that highlight different MIDP features.

A.9.1 ColorsThis application displays a large horizontal rectangle that runs the width of thescreen. Below, ten small vertical rectangles span the screen. Finally, three horizontalcolor bars indicate values for blue, green, and red (RGB). Values are expressed asdecimal (0-255) or hexadecimal (00-ff) based on the first menu selection.

■ To select a vertical bar to change, use the up navigation arrow to move to thecolor bars. Use the right navigation arrow to highlight a color bar. The largerectangle becomes the color of the selected bar.

■ Use the up or down selection arrows to choose the value to change (red, green, orblue). Use the left or right arrow keys to increase or decrease the selected value.The second menu item allows you to jump in increments of 4 (Fine) or 32 (coarse).

■ You can change the color on any o93r all of the vertical bars.

A.9.2 PropertiesThis MIDlet displays property values. For example, see FIGURE A-16:


FIGURE A-16 System Properties

A.9.3 HttpThis test application uses an HTTP connection to request a web page. The request isissued with HTTP protocol GET or POST methods. If the HEAD method is used, thehead properties are read from the request.

Preparing to Run the Demo

Before beginning, examine your settings as follows.

■ Go to Preferences > Security. Set the policy to JTWI and the domain to maximum.

■ In Preferences > Network Configuration, the HTTP version must be 1.1.

■ If you are behind a firewall, go to Preferences > Network Configuration andspecify your proxy server information.

■ If you are running antivirus software, you might need to create a rule that allowsthis MIDlet to allow connections to and from a specific web site.

Running the Demo

Launch the Http MIDlet. By default the MIDlet attempts to contacthttp://www.yahoo.com. To test, choose the Menu soft key and choose 1, 2, or 3 totest the selected URL.

Http Test returns the information it is able to obtain. If the information fills thescreen use the down arrow to scroll to the end. The amount of information dependson the type of request and on the amount of META information the page provides. Toprovide body information or content, the page must declare CONTENT-LENGTH asdescribed in RFC 2616.


http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3



http://www.yahoo.com

Using Menu Options

Use the Menu soft key for the following actions.

■ Choose 1 to GET information from the selected page.

■ Choose 2 to obtain the POST information from the selected page.

■ Choose 3 to display the HEAD attributes for the page.

■ Choose 4 to bring up the current list of web pages. You can chose a new page oradd your own page to the list. To specify a new URL, choose the Menu soft keyand choose 4. The screen displays http://. Type in the rest of the URL, makingsure to end with a slash (/). For example http://www.internetnews.com/.Press the OK soft button. The Http Test screen shows your new URL and promptsfor an action.

A.9.4 FontTestletThis MIDlet shows the various fonts available: Proportional, Regular, Regular Italic,Bold Plain, and Bold Italic. Choose 1 or 2 from the menu to toggle between thesystem font (sans serif) and the monospace font.

A.9.5 StockLike the Http demonstration, This sample uses an HTTP connection to obtaininformation. Use the same preparation steps as Section A.9.3, “Http” on page A-21.

Run the Demos project and launch the Stock MIDlet.

By default, the screen displays an empty ticker bar at the top. Below the ticker, themenu list shows four applications: Stock Tracker, What If? Alerts, and Settings. Youmust add stock symbols before you can use the first three applications.

A.9.5.1 Working with Settings

To use the applications features, you must supply some stock symbols for theapplication to act upon.

Add Stock Symbols to the Ticker

To add a stock symbol to the ticker, use the navigation arrows to select Settings.

Select Add Stock.





http://www.internetnews.com/

The display prompts you to enter a stock symbol. Type SUNW and select the Donesoft key. The stock you added and its current value is now displayed in the ticker.Add a few more stock symbols, such as IBM and HPQ.

Change the Update Interval

By default the update interval is 15 minutes. Select Updates to change the interval.Use the navigation arrows to select one of Continuous, 15 minutes, 30 minutes,1 hour, or 3 hours. Select the Done soft key.

Remove a Stock

Select Remove a Stock. You see a list of the stocks you have added. Use thenavigation keys to select one or more stocks to remove. Choose the Done soft key.

A.9.5.2 Stock Tracker

Stock Tracker displays a list of the stocks you added and their current values. Stocktracker display additional information about the selected stock, for example, the lasttrade and the high and low values.

Choose a stock and press SELECT.

A.9.5.3 What If?

What If? is an application that asks for the original purchase price and the number ofshares you own. It calculates your profit or loss based on the current price.

Select a stock symbol.

Enter the purchase price and the number of shares, then press Calc.

A.9.5.4 Alerts

This application sends you a notification when the price changes to a value youspecify.

From the main menu, select Alerts.

Select Add.

Choose a Stock. The screen prompts, Alert me when a stock reaches. Enteran integer.


The alert is placed on the Current Alerts list. To remove an alert, press Remove andselect the alert. Choose the Done soft key.

When the value is reached you hear a ring and receive a message. For example,Symbol has reached your price point of $value and is currently trading at$current_value. Once the alert is triggered it disappears from the Current Alerts list.

A.9.6 TicketsThis demonstrates how an online ticket auction application might behave. The homescreen displays a ticket ticker across the top. The Choose a Band field displaysAlanis Morrisette by default.

To select a band, highlight the band name and press SELECT. Use the down arrow tohighlight a different band, moby, for example, then press SELECT. The availableauction appears.

To make a bid, select the Menu soft key and choose 2. Use the arrow keys to movefrom field to field. Fill out each field. Select the Next soft key. The application asksyou to confirm your bid. Use the arrow keys to highlight Submit then press SELECT.You receive a Confirmation number. Click Bands to return to the welcome page.

To set an alert, select the Menu soft key and choose 3. Use the navigation arrows tomove to the field and type in a value higher than the current bid. Select the Save softkey. You are returned to the welcome page. You can trigger the alert by making a bidthat exceeds your alert value. Your settings determine how often the applicationchecks for changes, so the alert may not sound for a few minutes.

To add a band, select the Menu soft key and choose 4. Type in a band name or acomma-separated list of names. Choose the Save soft key. After confirmation you arereturned to the welcome page. The added band(s) are displayed in the Choose aBand drop down. This is only a demonstration. To fully describe the band you mustedit the file:

toolkit\apps\Demos\src\example\auction\NewTicketAuction.java

To remove a band, select the Menu soft key and choose 5. Navigate to a band thenchoose SELECT to mark the check box. You can select multiple bands. Choose theSave soft key.

To display the current settings for ticker display, updates, alert volume, and date,select the Menu soft key and choose 6. If desired, use the arrow keys and the selectkey to change these values. Choose the Save soft key.


A.9.7 ManyBallsThis MIDlet starts with one ball traveling the screen. Use the up and down arrows toaccelerate or decelerate the ball speed (fps). Use the right or left arrows to increaseor decrease the number of balls.

A.10 GoSIPGoSIP is a chat application that uses SIP to set up communications using a SIP proxyserver and registrar.

Begin by running the SIP server. Choose File > Utilities from the KToolbar menu.Select Start SIP Server and press Launch. The SIP proxy server window appears.Click Start to run the server. With the server you can confirm a successfulregistration attempt.


FIGURE A-17 SIP Proxy and Registrar

Next, run two instances of the emulator with the GoSIP application.

In the first emulator, launch Sippy A. You are prompted for the proxy host. Enteryour local machine name or IP address and choose Next, then Register.

In the SIP server window, SIP messages from the emulator appear. Sippy A appearsin the list of registered users. The emulator suggests you invite your friend Sippy Bto talk. Don’t do it yet.


In the second emulator, launch Sippy B. Just as before, enter the address of the SIPproxy, choose Next, then Register. The Sippy B user appears in the SIP serverwindow.

In the first emulator (Sippy A), choose Invite.

The second emulator (Sippy B) indicates that it’s ringing and displays an IP address.Choose Answer to start the chat. Both emulators now show a Talking screen. Youcan send messages back and forth using the Send command.

When you are finished, choose Bye to end the chat.

A.11 i18nDemoThis MIDlet suite shows off the JSR 238 Mobile Internationalization API. TheMIDlets String Comparator and Formatter show how to sort strings and displaynumbers appropriately for different locales. The third MIDlet, MicroLexicon, is asmall phrase translator that comes in handy if you need to ask for a beer in Prague,Herzliya, Beijing, Milan, or several other locations.

Note – The default fonts for the Sprint Wireless Toolkit do not support Chinese andJapanese. To use these languages, follow these steps before running this demo:

1. Install a True Type font that supports Chinese or Japanese.2. Modify toolkit\devices\skin-directory\skin.properties to specify that font.

To run a MIDlet, use SELECT to highlight the MIDlet, then use the lower rightbutton to Launch the MIDLet.

The String Comparator MIDlet demonstrates how strings (city names) are sorteddifferently depending on locale. Launch the MIDlet. Use the lower right button toview the menu. Click or Type 2 to select Sort - default, and the list is sortedalphabetically. Click or Type 3 to select Sort - slovak. It’s easy to see the difference inthe cities that begin with the letter Z, with and without the mark on top. Click Exitto return to the list of MIDlets.

The second MIDlet, Formatter, simply displays times and numbers formatted fordifferent locales. Click next to view all four screens. Click Exit to return to the list ofMIDlets.

The final MIDlet, MicroLexicon, translates phrases from one language to anotherlanguage. To select the target language from the list, use the navigation arrows tohighlight Choose Language. Click SELECT to view the language drop down. Use thenavigation arrows to choose a language (see FIGURE A-15) and then click SELECT.


FIGURE A-18 Choosing the Target Language

MicroLexicon displays a list of phrases. Highlight one and press the SELECT buttonon the emulator. You see the flag of the target language and the translated phrase.

To change the source language, choose Edit > Preferences from the KToolbar menu.Click the i18n tab and enter a valid locale string. The next time you run the emulatorand MicroLexicon, the instruction text appears in the given locale, if it is supported.One example that works is cs-CZ.

MicroLexicon is powered by MIDlet resources. To understand how you can use thetoolkit to localize an application, choose Project > i18n Resources Manager from theKToolbar menu. All the resources, both text and images, used by MicroLexicon,appear. You can edit the resources and run MicroLexicon again to see what happens.You don’t need to build the application again because the resources are loaded atruntime.


FIGURE A-19 Internationalization Resources Manager

The resources themselves are stored in toolkit\apps\i18nDemo\res\global.

A.12 JBricksJBricks is a game that demonstrates the use of the JSR 229 Payment API. The gameitself resembles Breakout or Arkanoid. In JBricks, you can buy another life or a newgame level. Behind the scenes, the Payment API handles the details.


To use the payment features of JBricks, use Project > Run via OTA to install JBricksinto the emulator. If you don’t know how to do this, read about it in Section 2.3.2,“Install” on page 2-10.

To see how JBricks uses the Payment API, choose either Buy Life or Buy Levelfrom the game’s main menu. Next, choose whether you want to buy a single life orthree lives for a reduced price. The next screen gives you a choice of payment types.

FIGURE A-20 Choosing a Payment Type

Use the navigation arrows to select the line starting with Pay by. Click the SELECTbutton to see the possible credit card adaptors in a drop down menu. Use thenavigation arrows to select the VISA adaptor, then click SELECT. Click Yes on thelower right to proceed.

Next, you are able to enter credit card information. Use any valid VISA number (forexample, 4111411141114111) and a valid expiration date.


FIGURE A-21 Providing Payment Information

To view the transactions for the current instance of the emulator, choose MIDlet >External Events and click the Payment Transactions tab. Transactions for this specificinstance of the emulator appear.


FIGURE A-22 Viewing Transactions

In addition, you can view all transactions passing through the toolkit’s paymentsystem. Choose File > Utilities, then select Payment Console. A transaction in theconsole looks something like the following:


A.13 JSR172DemoJSR172Demo shows how to access a web service from a MIDlet. The web service isalready running on an Internet server. If you are behind a firewall, you mustconfigure the emulator’s proxy server settings. Choose Edit > Preferences from theKToolbar menu, then select Network Configuration. Fill in the proxy server addressfile and the port number. Build and run the example.

JSR172Demo contains a single MIDlet named Server Script. Launch it and follow theprompts. You can browse through simulated news headlines, all of which areretrieved from the web service.

A.14 KeyEventDemoThis application contains a MIDlet that describes key events. The recognized eventsare Pressed, Repeated, and Released. For every action performed on a key, the screendisplays the corresponding event. For example, when you press the 1 key, the screendisplays 1 pressed.

PSP Console running, using phone number +5555555555.PSP Server running at https://localhost:-1Received Payment Request from 127.0.0.1 Credit card issued by: VISA Credit Card type: 0 Credit Card Number: 4111111111111111 Credit Card Holder: Jonathan Knudsen Feature ID: 3_lives Credit Card Verification Number (CCV): 123 Payload: nullResponse to 127.0.0.1HTTP/1.1 200 OKContent-Length: 0Pay-Response: SUCCESSFULPay-Timestamp: 1156282954734


A.15 LX260-Test-S05This LX260 device has a full QWERTY keyboard that slides out from the side. Thedisplay must switch from portrait mode to landscape mode and back when thedevice is rotated. The rotation affects forms, lists, scrolling, and word-wrap.

This demonstration shows two features:

■ Ability to switch between full screen and regular screen on the canvas. Theregular screen shows a title bar at the top and a soft key bar at the bottom. In fullscreen mode the title bar is gone and items on the soft key bar occupy theminimum space.

■ Ability to switch the display from canvas to a form.

1. Open the LX260-Test-S05 project.

2. Select the MIDP 2.0 Power Vision platform. On the Devices tab, select theLX260.

3. Click Run.

The demo launches in the portrait view. The screen text indicates the form factorvalue is Open and the usable portion of the screen is 176x180.

■ From the menu select 1 ToggleFullScrn.

Note the screen height has changed from 180 to 220 and observe theappearance of the soft keys.

■ Select Frm/Cnvs.

You see the form and a text string that wraps in the portrait view.

FIGURE A-23 summarizes these screens.


FIGURE A-23 Screen Variations in the Portrait View (Form Factor Open)

4. In the emulator select MIDlet > External events. On the Non-ProtectedProperties tab, locate Form Factor and click the Closed radio button.

The display switches to the landscape view. FIGURE A-24 shows the demo screensas they appear in landscape view. Note the changed screen dimensions and lineendings.

FIGURE A-24 Screen Variations in the Landscape View (Form Factor Closed)


A.16 MobileMediaAPIThe MobileMediaAPI application contains four MIDlets that showcase the toolkit’smultimedia capabilities. This section describes the MIDlets and includes additionalinformation about using multimedia from your applications.

A.16.1 Simple TonesThe Simple Tones example demonstrates how to use interactive synthetic tones.Select an example, then click Play on the lower right.

■ Short Single Tone and Long Single Tone use Manager.playTone() to play toneswith different pitch.

■ Short MIDI event plays a chord on the interactive MIDI device (locator"device://midi"). The shortMidiEvent() method of MIDIControl is usedto trigger the notes of the chord.

■ To run the MMAPI Drummer demo, click or type number keys (0-9). Eachnumber plays a different sound.

A.16.2 Simple PlayerThe Simple Player application demonstrates the range of audio and videocapabilities of the emulator. It includes sample files in a variety of formats and canplay files from the emulator's persistent storage or from HTTP URLs.

The player portion uses a generic javax.microedition.media.Player interface.The player displays duration, media time, and controls for running the media file. Ifmetadata is available in a file, the player enables you to view the information, suchas author and title. In the case of MIDI files, if karaoke text is present in the file, itdisplays on the screen during play. Graphical user interface controls can be viewedon the display screen if applicable. You can access these controls by selecting one ofthe media samples in Simple Player, then pressing the Menu button to view andselect the desired command.

Select Simple Player then click Launch. The demo includes the following mediasamples:

■ Bong plays a short WAV file. You can adjust certain playback features, asdescribed later in this document. The display shows the duration of the sound inminutes:seconds:tenths of a second, for example 00:17:5. This audio sample is aresource file in the MIDlet suite JAR file.


■ MIDI Scale plays a sample musical scale. The display shows the title of theselected music file, the duration of the song, the elapsed time during playback,and the current tempo in beats per minute (bpm). This MIDI file is stored in theMIDlet suite JAR file.

■ Simple Ring Tone plays a short sequence of Beethoven's Fifth Symphony. Thedisplay shows the title of the selected music file, the duration of the song, theelapsed time in seconds and tenths of a second during playback, and the currenttempo in beats per minute (bpm). This ringtone file (.jts format) is stored in theMIDlet suite JAR file.

■ WAV Music plays a brief audio file. The display shows the title of the audio file,the duration of the audio the elapsed time during playback, and the playback ratein percent. This WAV file is retrieved from an HTTP server.

■ MIDI Scale plays a MIDI file that is retrieved from an HTTP server.

■ The Animated GIF example shows an animated GIF that counts from 1 to 5. Thefile is stored in the MIDlet suite JAR file.

■ Audio Capture from a default device lets you capture audio from a microphoneor connected device. The sound is captured and played back on the speaker. Toavoid feedback, use a headset.

■ Video Capture Simulation simulates viewing input video such as might bepossible on a device equipped with a camera.

■ MPEG1 Video [http]. Plays an MPEG video found athttp://java.sun.com/products/java-media/mma/media/test-mpeg.mpg.

■ [enter URL] allows you to play back media files from arbitrary HTTP servers.Type a valid URL (for example, http://java.sun.com/products/java-media/mma/media/test-wav.mpg) at the insertion point and click OK to play afile. If you want to open an HTTP directory from which to select media, be sure toadd a slash to the end of the URL.

In addition, Simple Player parses ring tones in Ringing Tones text transfer language(RTTTL). See http://www.convertyourtone.com/rtttl.html for informationon RTTTL.


http://www.convertyourtone.com/rtttl.html

http://www.convertyourtone.com/rtttl.html

The Simple Player includes a common set of commands that control media playback.The commands are available from the Simple Player menu, and some haveassociated keypad buttons. The following table describes these commands.

TABLE A-3 Simple Player Commands

Command Key Description

Mute/Unmute 0 Turns off sound but the file continues to play. This commandtoggles to Unmute.

Volume * and # Increases or decreases loudness.

META Data Displays information provided by the media file such ascopyright information, title, and track list.

Stop in 5seconds

Pauses the audio play in five seconds when set during playback.

Rate 4 and 6 Alters the rate of speed of playback.

Tempo Increases or decreases the tempo of the tone sequence or MIDIfile.

Pitch up anddown

Lowers or raises the notes in a MIDI file.

Start/StopRecording

Records the audio playback. A file is created containing therecorded audio in the directory in which the emulator isrunning. If you do not specify a filename, a file calledrecording.wav is created. This command toggles to StopRecording.

Step Frame 7 and 9 Jumps forward or backward one frame at a time in a video file.

Play/Stop 2 andSelect

Starts or stops the media.

Loop Mode Plays back the audio file immediately after completion of play.Running Loopmode once plays the audio file once. Pressing asecond time plays the file three times. Pressing a third timeplays the file repeatedly. Pressing a fourth time returns to singleplay.

Skip 1 and 3 Skips forward or backward five percent of the duration of themedia file. The sound track syncs to the video.

Rewind Returns to the start time of the audio playback.

Stop andRewind

5 Stops playback and rewinds to the start time.

Quick Help Displays a list of commands and keypad buttons.


The commands may or may not be available depending on the media type thatSimple Player is playing. In addition, some commands can be invoked using thekeypad buttons. The following table describes the availability of commands, theirkeypad equivalents, and the relevant class from MMAPI.

Note that a short list of commands and the corresponding keypad buttons isavailable in the Simple Player application itself. Just choose the Quick Helpcommand from the menu.Video

The Video application illustrates how the emulator is capable of playing animatedGIF files and capturing video. On a real device with a camera, video capture can beused to show the user what the camera sees.

Animated GIFs and video capture can be implemented using either a Form Item ora Canvas. The Video demonstration includes all the possibilities. Animated GIF -Form [jar] shows an animated GIF as a Form Item. The form also includes someinformation about the playback, including the current time. Choose the Snapshotcommand to take a snapshot of the running animation. The snapshot is placed in theform following the animated GIF.

■ Animated GIF - Canvas [jar] shows an animated GIF in a Canvas. A simpleindicator shows the progress through the animation. Choose Snapshot to get astill image of the current appearance. The snapshot is shown briefly, then thedisplay goes back to the animation.

■ Video Capture - Form simulates capturing video from a camera or other sourceand showing it as an Item in a Form. Choose the Snapshot command to take asnapshot of the captured video. The snapshot is placed in the form following thevideo capture.

■ Video Capture - Canvas simulates capturing video from a camera or other sourceand showing it in a Canvas. Choose Snapshot to get a still image of the currentappearance. The snapshot is shown briefly, then the display goes back to thevideo capture.

■ MPEG1 Video - Form, MPEG1 Video - Canvas

The MPEG1 applications obtain MPEGs from the web, so if you are behind afirewall, you must configure the emulator’s proxy server settings.

Choose Edit > Preferences from the KToolbar menu, then select NetworkConfiguration. Check Use proxy server. Fill in the proxy server address field andthe port number. For this demo, select HTTP/1.0.

When you play the demo, expect to wait a few seconds while the toolkit obtainsthe data. The MPEG1 demos have the same behavior as Video Capture - Formand Video Capture - Canvas, respectively.


A.16.3 Pausing Audio TestThis MIDlet exists to demonstrate how the toolkit warns you if a paused MIDlet hasnot stopped its running Players. After you launch the MIDlet, choose the Playcommand to start playing some audio. The screen displays a status, which is either“Well-behaved” or “Not Well-Behaved.”

Choose MIDlet > Pause from the emulator window’s menu. As expected, the MIDletis paused and no message is displayed on the console. Choose MIDlet > Resumefrom the emulator window’s menu.

A.16.4 Attributes for MobileMediaAPIThe MobileMediaAPI applications have the following attributes that you canmodify in the project settings dialog box User Defined tab:

A.17 MP4Player DemoThis section demonstrates the ability to play MP4 files on the external screen.

1. On the main MIDlet (the open phone) screen, press the soft key below Launch.Wait a few seconds while the player initializes.

2. The midlet displays instructions on how to play and pause the MP4 file.

3. Click the Invoke soft key to start playing the movie. You can Pause (2),Forward (3), or Rewind (1) the movie according to the instructions. SeeFIGURE A-25.

TABLE A-4 Descriptions of MMAPI-specific MIDlet attributes

Attribute Description

PlayerTitle-n Name of the nth media title to be played back by the Simple PlayerMIDlet.

PlayerURL-n Location of the nth media title, PlayerTitle-n, to be played backby the Simple Player MIDlet.

VideoTest-n The name of the nth media title to be played back by the Videoapplication.

VideoTest-URLn Location of the nth media title, VideoTest-n, to be played backby the Video application.


FIGURE A-25 MP4 Demo Playing

While the demo is running you can play the movie on the External Canvas. Followthese steps:

1. Select MIDlet > External Events. In the External Event Generator, select theSprint System States tab.

2. Change the Form Factor property from Open to Closed. The display istransferred to the External Canvas as shown in FIGURE A-26.

To play, pause, play, forward or rewind the movie, use the external buttons onthe device.


FIGURE A-26 MP4 Demo Playing on External Canvas


A.18 Muglet DemoThis section demonstrates the Muglet capabilities defined in the Sprint API.

Note – This demo must be run via OTA.

The Demo contains 3 MIDlets:

■ MugletDemo: the manager MIDlet.

■ AudioMIDlet: knows how to play an audio file (uses Sprint media API).

■ ViewerMIDlet: knows how to display images.

1. In the tool bar, click Open Project.

2. Choose MugletDemo from the project list and click the Open Project button.

3. Click the Run via OTA button.

4. On the main MIDlet (the open phone) screen, press the soft key correspondingto Apps. You see the Applications screen.

5. Click the soft key beneath Launch. You see Install Application on the screen.

a. Click the soft key beneath Menu. Press 2 to launch the installation.

b. The application suggests a local website. Click the Menu soft key. Press 1 toaccept the site.

c. The application displays a JAD file. Click the Install soft key. The JAD filedownloads, then it is verified. The application asks you to confirm theinstallation. click the Install soft key. Continue through any warnings.

6. The application asks if you want to launch the MugletDemo.jad. Click the OKsoft key. The three midlets are displayed on the screen (FIGURE A-27).


FIGURE A-27 Launched Muglet Demo, MIDlets Displayed

7. Click the Launch soft key to run the selected JAD. Click the Launch soft key tolaunch the selected MugletDemo. Muglet options are displayed (FIGURE A-28).

FIGURE A-28 MugletDemo Options

8. Click the Launch soft key to play the selected item (bubbles.mp3).

9. To play a different selection, click Back to return to the Options screen. Usearrow keys or the phone’s navigation key to move up and down the list.

Click the Launch soft key to play the selection.


A.19 Multitasking VM DemoThis procedure uses demo projects to highlight Multitasking VM (MVM) features.

Before beginning, add some MP3 or MP4 files to the database for the MultitaskingVM device you are using. For example:install-dir\appdb\DeviceName\filesystem\memorycard.

The Multitasking VM demos have settings that determine how they will interactwith other Multitasking VM applications, as summarized in TABLE A-5.

1. Open the MVMDemoBackgroundNoPause project and click Run via OTA.

2. Choose Install Application and upload the demo. Follow the prompts until theinstallation is complete.

3. Choose the Exit soft key or click the X in the window border to close theemulator window.

4. Repeat steps 1 through 3 for MVMDemoLaunchBackground, andMVMDemoPowerOn.

Three MVM demos are now loaded in the emulator.

5. Open the MP4Player project.

a. Click the Settings button.

b. Select the User Defined icon and change the MIDlet-Heap-Size to 111111.

c. Click the Package button.

d. Click Sign to sign the MIDlet.

e. Click Run via OTA.

MVMDemoPowerOn launches immediately. This happens becauseMIDlet-Launch-Power-On is set to yes.

TABLE A-5 MVM Demo Settings

Demo User-Defined Settings Value

MP4Player MIDlet-Heap-Size 555555

MVMDemoBackgroundNoPause MIDlet-Background-No-Pause yes

MVMDemoPowerOn MIDlet-Launch-Power-On yes

MVMDemoLaunchBackground MIDlet-Launch-Background yes


6. Press the End key, and choose Send to Background.

As shown in FIGURE A-29, MVMDemoPowerOn has a green check showing it isrunning in the background.

FIGURE A-29 Application Manager

7. Select MVMDemoPowerOn. Go to the soft menu and remove this application.

8. Select Install Application to install the player.

When you invoke the player you see this message: The application hasunexpectedly quite because it ran out of memory. Click Done.

9. In the AMS, select the MP4Player and Remove it. Close the emulator.

10. In KToolbar, reset the MIDlet-Heap-Size to 555555, package and sign theapplication, and Run via OTA.

a. Install the MP4Player application.

b. Select MP4Player and launch the application. Select Invoke to play.

The MP4 player runs.

c. Click End. Select Exit Application.

You are returned to the AMS. Note, there’s no green check because you exitedrather than sending the player to the background.

11. Launch MVMDemoLaunchBackground.

A green check signifies the application is running. You don’t see anything elsebecause MIDlet-Launch-Background is set to yes. This attribute is typically usedfor service MIDlets.

12. Launch MVMDemoBackgroundNoPause.

Wait for the /memorycard folder to appear. Select the folder.

13. Browse to the Music folder and select an MP3 file.


14. Press the End key and choose Go to the Application Manager.

You return to the application manager while the file you launched in Step 13continues to play in the background. A green check appears by the application.

15. In the Application Manager, launch the MP4Player demo. Press the Invoke key.

The MP4Player plays in the foreground, replacing the MP3 file.

16. Close the emulator to end this demo.

A.20 Network DemoThis demo has two MIDlets: Socket Demo and Datagram Demo. Each demo requiresyou to run two emulator instances so that you can emulate the server and clientrelationship.

A.20.1 Socket DemoRun two instances of the emulator. One acts as the socket server, and the other as thesocket client.

In the first emulator, launch the application, then select the Server peer. ChooseStart. The emulator explains that the demo wants to send and receive data over thenetwork and asks, “Is it OK to use network?” Choose Yes. The Socket Serverdisplays a screen that indicates it is waiting for a connection.

In the second emulator, launch the application, select the Client peer, then chooseStart. The emulator explains that the demo wants to send and receive data over thenetwork and asks, “Is it OK to use network?” Choose Yes. The Socket Client displaysa screen that indicates it is connected to the server. Use the down navigation arrowto highlight the Send box. Type a message in the Send box, then choose the Send softkey.

For example, in the client, type Hello Server In the Send box (see FIGURE A-30).Choose the Send soft key. The emulator activates a blue light during thetransmission.


FIGURE A-30 Sending a Message from the Socket Client

On the emulator running the Socket Server, the Status reads: Message received -Hello Server. You can use the down arrow to move to the Send box and type areply. For example, Hello Client, I heard you. Select Send. See FIGURE A-31.

FIGURE A-31 Server Shows Message Received and Message to Send.

Back in the Socket Client, the status shows the message received from the server. TheSend box contains the previous message you sent.

A.20.2 Datagram DemoThis demo is similar to Socket Demo.


Run two instances of the emulator. One acts as the datagram server, and the other asthe datagram client.

In the first emulator, launch Datagram Demo, then select the Server peer. ChooseStart. The emulator explains that the demo wants to send and receive data over thenetwork and asks, “Is it OK to use network?“ Choose Yes. Initially, the DatagramServer status is Waiting for connection, and the Send box is empty.

In the second emulator, launch Datagram Demo, select the Client peer, then chooseStart. The emulator explains that the demo wants to send and receive data over thenetwork and asks, “Is it OK to use network?“ Choose Yes. The Datagram Clientstatus is: Connected to server. Use the down navigation arrow to highlight theSend box. Type a message in the Send box, then choose the Send soft key. Forexample, type Hello datagram server.

On the emulator running the Datagram Server, the Status displays: Messagereceived - Hello datagram server. You can use the down arrow to move tothe Send box and type a reply to the client.

In the Datagram Client, the status field displays the message received from theserver. The Send box contains the last message you sent.

A.21 ObexDemoThis application shows how to transfer image files between emulator instances usingthe OBEX API. This demonstration shows the use of OBEX over a simulated infraredconnection.

Run two instances of the emulator. One listens for incoming connections, while theother attempts to send an image. In the first emulator, launch the application thenchoose Obex Demo, then Receive Image. The emulator explains that an OBEXconnection allows other devices to talk to yours and asks, “Is it OK to make theconnection?“ Choose Yes. The listener emulator displays a screen that indicates it iswaiting for incoming connections.

In the second emulator (the sender), launch Obex Demo, then choose Send Image.You see a list of images. Select one and choose Send. The emulator explains thedemo wants to make an outgoing client connection, and asks if it is OK. Choose Yes.The Send Image utility uploads the image.

In the listening emulator, the utility displays information about the incoming imageand asks “Would you like to receive it?“ See FIGURE A-32.


FIGURE A-32 Listener Prompting to Accept a Connection

Choose Yes. The image you selected is transferred over the simulated infrared linkand displayed on the first emulator. See FIGURE A-33.

FIGURE A-33 Successfully Transferred Image

A.22 PDAPDemoPDAPDemo shows how to use the PIM and FileConnection APIs that are part ofthe JSR 75 specification.


A.22.1 Browsing FilesPDAPDemo shows how to use the PIM and FileConnection APIs that are part of theJSR 75 specification.

A.22.2 Browsing FilesTo run the file browser, you must give the MIDlet appropriate securityauthorization. The easiest way to do this is to choose Edit > Preferences... from theKToolbar menu. Click the Security tab. Change the Security domain to maximumand press OK.

Now open and run the PDAPDemo project. Launch the FileBrowser MIDlet. Yousee a directory listing. You can browse through the available directories and files. Bydefault there is one directory, memorycard.

FIGURE A-34 Browsing Files

Select a directory and press the select button to enter it. The memorycard directorycontains a single file, file.txt, and an empty directory, photos.


FIGURE A-35 Contents of the memorycard Directory

Using the commands in the demonstration, you can view the file or see itsproperties. Try selecting the file and choosing Properties or View from the menu.

FIGURE A-36 Viewing File Properties and Contents

The actual files are located in toolkit\appdb\skin\filesystem, where skin is theemulator skin you are using. You can add files and root directories as you wish andthey are visible to the JSR 75 File API. See Chapter 11 for more information.


A.22.3 The PIM APIThe JSR75 PIM APIs example demonstrates how to access personal information,like contact lists, calendars, and to-do lists. After you launch the example, choose atype of list from the main menu.

In this example application, each type of list works the same way and each list typecontains a single list. For example, if you choose Contact Lists, there is a singlecontact list called Contacts. Event Lists contains a single list called Events, and To-Do Lists contains a single list called To do.

FIGURE A-37 Choosing a List Type

Once you've selected a list type and chosen the specific list, you'll see all the items inthe list. If this is the first time you've run the example, the list is probably empty.


FIGURE A-38 An Empty Contact List

To add an item, choose New from the menu. The application prompts you for aFormatted Name for the item. You can add more data fields to this item using AddField in the menu. You'll see a list of field names. Pick one, then enter the value forthe new field.

FIGURE A-39 Adding Contact Fields

To save the list item, choose Commit from the menu.


FIGURE A-40 Saving an Item

You can return to the list by choosing the Back command. You'll see the item you justcreated in the list.

The items that you create are stored in standard vCard or vCalendar format in thetoolkit\appdb\skin\pim directory. See Chapter 11 for more information.

The PIM API allows for exporting contact, calender, and to-do items in a standardformat. The exact format depends on the list type. When you are viewing an item inany list, the menu contains a command for viewing the exported item.

For example, when you are viewing a contact list item, the menu contains ShowvCard. When you choose this command, the exported item is shown on the screen.Calendar items and to-do items both get exported as vCalendar.

A.23 Razr2Demo1. Open the RAZR2 Project.

2. Select the MIDP 2.0 Power Vision platform. On the Devices tab, select theMotorolaRAZR2 device.

3. Click Run via OTA.

4. Install and launch the demo.

In the emulator, the demo instructs you to close the form factor.


5. Select MIDlet > External events. On the Non-Protected Properties tab, findForm Factor and select the Close radio button.

A player launches on the external screen as shown in FIGURE A-41.

FIGURE A-41 RAZR2 External Screen

Click > to play a clip. As you click buttons, the action is displayed in the title area.

A.24 RecordStoreDemoThis application contains a MIDlet that demonstrates the use of RecordStore, asdefined in the MIDP 1.0 and MIDP 2.0 APIs. The demo enables you to create newRecordStore objects. A RecordStore object can contain records.

Open the Record Store project and launch the application. The Record Stores screenshows a list of Record Stores. Initially the screen is empty. To add a Record Store,click Add new on the lower left. All you need to do is specify a record name.


FIGURE A-42 Initial Screen

As shown in FIGURE A-43, you are prompted to enter the name of the new recordstore. After entering the name, click the Done soft button. You can enter multipleRecord Store names.

FIGURE A-43 Adding New Record Store

The Record Stores listing now shows the name of the record store you created (inthis case User1). To view its properties, select the record store name, open the Menu,and select 2, Properties. As shown in FIGURE A-44, the Properties screen shows theRecord store properties.


FIGURE A-44 View Record Store Properties

Note that the store has zero records. Press the Back soft key to return to the list ofRecords.

You can also change a record’s access modes. There are two modes, accesspermission, and write permission. By default any MIDlet has both entry access andwrite permission. You can limit the access so that only the creator MIDlets haveaccess, as shown in FIGURE A-45.

FIGURE A-45 MIDlet Access

Once you have created a record store you can add records to it. Select the recordstore, open the menu, and select 1, Open. FIGURE A-46 shows the open record storeUser1. Click the Add record soft key.


FIGURE A-46 Add Record Screen

You are prompted to add a record. You can add multiple records to the store. Forexample, in FIGURE A-47 we added the user’s service start date, and service levelagreement (SLA), and the host server.


FIGURE A-47 Record Listing for User1 Record Store

The Record screen menu enables you to edit or delete an existing record, or view itsproperties. Option 4, Back returns you to the Record Store listing.

FIGURE A-48 Record Screen with Soft Menu Expanded

Note that records you enter are displayed in reverse order. You can display theproperties for a record. In this example we select Server22, the last entry. To view its


properties, select Menu, and choose 3, Properties. The properties are as shown inFIGURE A-49. Click Cancel to return to the add Record screen.

FIGURE A-49 Properties for Server22 Record

In the Record screen, select User1, and select Option 2, Properties. Figure shows theRecord properties. Note that there are now three records, as compared toFIGURE A-44.


FIGURE A-50 Properties of Populated Record Store

A.25 SATSADemosSATSADemos includes demonstrations of SATSA, the Security and Trust ServicesAPIs. Most of the demonstrations show how to communicate with a smart card. Theemulator can communicate with a simulated smart card using a socket protocol. Thesmart card simulator, cref, is included with the toolkit. See Chapter 15 for details.

The following sections contain instructions for each menu choice for this demo. Foreach demo, be sure to do the following before launching the emulator:

■ Run the instance(s) of cref from the command line.

■ Be sure to set the set the security domain to maximum.

A.25.1 APDUMIDletThis MIDlet demonstrates communication with a smart card using ApplicationProtocol Data Units (APDUs), small packets of data. APDUMIDlet expects to findtwo simulated smart cards. You can run the smart card simulator using cref, whichis part of the Java Card Development Kit.

The Mohair application includes pre-built memory images that you can use withcref. The memory images contain Java Card applications with which Mohairinteracts. The memory images are in the root directory of the Mohair project.


Start up two instances of cref like this, one for each simulated card slot (assumingthe current directory is the toolkit root directory):

start bin\cref -p 9025 -i apps\SATSADemos\demo2.eeprom


Note that the port numbers (9025 and 9026 in this example) must match the portnumbers you specified in the SATSA preferences, described in Chapter 15. Also,make sure you use the correct path to demo2.eeprom.

Once you have the two smart card simulators running, you can run APDUMIDlet.

A.25.2 SATMIDletSATMIDlet demonstrates smart card communication with a slight variation onAPDU communication.

To set up the simulated smart card, use cref, very much like you did forAPDUMIDlet. This time you don’t have to specify a port number, and the memoryimage is different:

start bin\cref -i apps\SATSADemos\sat.eeprom

When the smart card simulator is running, you can run SATMIDlet to communicatewith card applications.

A.25.3 CryptoMIDletCryptoMIDlet demonstrates the general cryptographic features of SATSA. It doesnot interact with a smart card in any way.

A.25.4 MohairMIDletMohairMIDlet has two functions. The first, Find slots, displays all the availablecard slots. Each slot has a number followed by ‘C’ or ‘H’ indicating whether the slotis cold-swappable or hot-swappable. After viewing the slots select Back to return tothe first screen.

The second part of MohairMIDlet, SATSA-PKI Sign test, uses a smart card togenerate a digital signature. As with the earlier demonstrations, you need to runcref with the right memory image to prepare for the connection fromMohairMIDlet. Type the following in the installation directory:


start bin\cref -i apps\SATSADemos\sat.eeprom

In the emulator, highlight SATSA-PKI Sign test and choose SELECT. The followingconfirmation message appears:

This certificate will be used: MohairAuth

Select the OK soft key.

For PIN 1, type: 1234

Select the OK soft key. The following confirmation message appears:

This string will be signed: JSR 177 Approved

Select the OK soft key. The following confirmation message appears:

This certificate will be used: MohairAuth

Select the OK soft key.

For non repudiation key 1 PIN, type: 2345

A.26 SATSAJCRMIDemoThis application contains a single MIDlet, JCRMIMIDlet, which shows how tocommunicate with a card application using Java Card RMI, a card-friendly remoteobject protocol. As with some of the MIDlets in SATSADemos, you need to start upcref with an appropriate memory image:


Now run JCRMIMIDlet to see how your application can communicate with adistributed object on the card.

A.27 SIPDemoThis application is a very simple example of using SIP to communicate directlybetween two devices. Usually devices use SIP with a proxy server to set up directcommunications of some kind. For a more complete example involving a proxy, takea look at GoSip.


To see how SIPDemo works, run two instances of the emulator. In the first, chooseReceive message. You can use the default port, 5070, and choose Receive. The firstemulator is now listening for incoming messages.

In the second emulator, choose Send message. Fill in values for the recipient, portnumber, subject, and message, or accept the defaults, and choose Send. Yourmessage is displayed in the first emulator. The first emulator’s response is displayedin the second emulator.

A.28 SprintDemoThe Sprint demo demonstrates several Sprint API capabilities.

A.28.1 External Canvas DemoThis demo demonstrates how to use the external canvas by changing the FormFactor property.

1. Open and run the SprintDemo project.

2. In the MIDlet, choose the Launch soft key.

The application gives instructions on running the demo.

3. Click the Continue soft key.

4. In the emulator, select MIDlet > External Event

5. On the Sprint System States tab, go to the Non-Protected properties tab andchange the FormFactor property from Open to Close.

6. The display changes from the primary to the secondary screen.


FIGURE A-51 Demo in Main Screen and External Screen

A.28.2 SystemStates DemoThis demo demonstrates the Sprint System API options.

1. Open and run the SprintDemo.

2. Select the SystemStates demo.

3. Click the Launch soft key.

The application displays three options, each of them demonstrating a differentaspect of the System API.

4. Use the Launch soft key to select an option.

5. Select a property and use the Launch soft key to display it.


The options are as follows:

■ System Events option: Presents the values the MIDlet retrieves by calling thegetSystemState method.

FIGURE A-52 System Events Options

■ System Properties option: Presents a list of properties. When you choose one ofthe properties on the list, the getSystemState method is called to show theproperty's value on the screen.

FIGURE A-53 System Properties


■ System Protected Properties option: Presents a list of protected properties. Whenyou choose one of the properties on the list, the getProtectedPropertymethod is called to show the property's value on screen.

FIGURE A-54 System Protected Properties

A.28.3 Media DemoThe media demo demonstrates the Sprint media API.

1. Open and run the SprintDemo project.

2. Use the phones navigation keys or your keyboard arrow keys to select theMedia option. Click the Launch soft key.

3. Choose the Media option. The application displays two options. Use theLaunch soft key run the demo:

■ Player option – Demonstrates the options to Play, Stop, Pause, and Resume amedia file. Use Play to start the clip. If you select stop, select play to startfrom the beginning. If you select pause, select resume to start from the pointyou pressed pause.

■ Vibrate option – Simulates handset vibration.


A.29 SVGContactListThis application uses different skins to display the same contact list information anda news banner. The skins have different colors and fonts.

Select SVGContactlist(skin 1) or SVGContactlist(skin 2), then click Launch.

Use the up and down arrows to navigate the list of contacts. The highlighted nameis marked with a special character (a > or a dot) and is displayed in a larger font.

FIGURE A-55 Contact List Shown with Skin 2

Press the select button to see more information for the highlighted name.


FIGURE A-56 Contact List Details

Press select again to return to the contact list.

A.30 SVGDemoThis suite contains MIDlets that demonstrate different ways of using the JSR 226Scalable 2D Vector Graphics API for J2ME. This API provides ways to loadmanipulate, render, and play SVG content.

The Scalable Vector Graphics (SVG) 1.1 specification defines a language fordescribing two-dimensional graphics in XML. The full specification is available athttp://www.w3.org/TR/SVG11/.

SVG Tiny (SVGT) is a subset of SVG that is appropriate for small devices like mobilephones. See http://www.w3.org/TR/SVGMobile/. SVG Tiny is a compact yetpowerful XML format for describing rich, interactive, and animated 2D content.Graphical elements can be logically grouped and identified by the SVG markup.


http://www.w3.org/TR/SVG11/

http://www.w3.org/TR/SVGMobile/

http://www.w3.org/TR/SVGMobile/

http://www.w3.org/TR/SVG11/

A.30.1 SVG BrowserThe SVGBrowser MIDlet displays SVG files residing in the phone file system. Beforerunning this demo, place an SVG file in the directory workdir\appdb\DefaultColorPhone\filesystem\root1.

Launch the demo. The application displays the contents of root1. Select your SVGfile and choose the Open soft key.

A.30.2 Render SVG ImageLoads an SVG image from a file and renders it. Looking at the demo code you cansee that the image is sized on the fly to exactly fit the display area. The output isclear and sharp.

A.30.3 Play SVG AnimationThis application plays an SVG animation depicting a Halloween greeting card. Press8 to play, 5 to start, and 0 to stop. If you press 8, pressing 5 resumes the animation.If you press 0, pressing 5 starts the animation from the beginning.

The SVG file contains a description of how the various image elements evolve overtime to provide this short animation.

In the following code sample, the JSR 226 javax.microedition.m2g.SVGImageclass is used to load the SVG resource. Then, thejavax.microedition.m2g.SVGAnimator class can take all the complexity ofSVG animations and provides a java.awt.Component orjavax.swing.JComponent which plays the animation. The SVGAnimator classprovides methods to play, pause and stop the animation.

import javax.microedition.m2g.ScalableGraphics;import javax.microedition.m2g.SVGImage;

...String svgURI = ...;SVGImage svgImage = (SVGImage) SVGImage.createImage(svgURI, null);SVGAnimator svgAnimator = SVGAnimator.createAnimator(svgImage);

// If running a JSE applet, the target component is a JComponent.JComponent svgAnimationComponent = (JComponent)svgAnimator.getTargetComponent();...


A.30.4 Create SVG Image From ScratchThis demo builds an image using API calls. It creates an empty SVGImage,populates it with a graphical content, and then displays that content.

A.30.5 Bouncing BallsBouncing Balls plays an SVG animation. Press 8 to play, 5 to start, and 0 to stop. Ifyou press 8, pressing 5 resumes the animation. If you press 0, pressing 5 starts theanimation from the beginning.

A.30.6 Optimized MenuIn this demo, selected icons have a yellow border. As you move to a new icon, itbecomes selected and the previous icon flips to the unselected state. If you navigateoff the icon grid, selection loops around. That is, if the last icon in a row is selected,moving right selects the first icon in the same row.

This demo illustrates the flexibility that combining UI markup and Java offers: a richset of functionality (graphics, animations, high-end 2D rendering) and flexibility ingraphic manipulation, pre-rendering or playing.

In this example, a graphic artist delivered an SVG animation defining the transitionstate for the menu icons, from the unselected state to the selected state. The programrenders each icon's animation sequence separately into off-screen buffers (for fasterrendering later on), using the JSR 226 API.

With buffering, the MIDlet is able to adapt to the device display resolution (becausethe graphics are defined in SVG format) and still retain the speed of bitmaprendering. In addition, the MIDlet is still leveraging the SVG animation capabilities.

svgAnimator.play();...svgAnimator.pause();...svgAnimator.stop();


The task of defining the look of the menu items and their animation effect (the job ofthe graphic artist and designer) is cleanly separated from the task of displaying themenu and starting actions based on menu selection (the job of the developer). Thetwo can vary independently as long as both the artist and the developer observe theSVG document structure conventions.

A.30.7 Picture DecoratorIn this demo you use the phone keys to add decorations to a photograph. The keyvalues are:

This demo provides 16 pictures for you to decorate.

Use the 2 and 6 keys to page forward and back through the photos.

To decorate, press # to display the picker. Use the arrow keys to highlight a graphicobject. The highlighted object is enlarged. Press SELECT to choose the currentgraphic or press the arrow keys to highlight a different graphic. Press SELECT againto add the graphic to the photo. When the decoration is added you see a red + on thegraphic. This means it is selected and can be moved, resized, and manipulated.

1 key shrink

2 key next picture

3 key grow

4 key help

5 key horizontal flip

6 ley vertical flip

7 key rotate counter-clockwise

8 key previous picture

9 key rotate clockwise

# display picker options


FIGURE A-57 Decorated Picture with Quotation Selected

■ Use the navigation arrows to move the graphic.

■ Use 1 to shrink the graphic, and 3 to enlarge the graphic.

■ Use 5 or 6 to flip, and 7 or 9 to rotate.

When you are satisfied with the position, press SELECT. Note that a green triangleappears. This is a cursor. Use the navigation keys to move the green triangle aroundthe picture. When the cursor is over an object it is highlighted with a red box. PressSELECT. The red + indicates the object is selected.

FIGURE A-58 Highlighted Mustache

To remove a decoration (a property), select an object, then click the Menu soft key.Press 2 to remove a property.


A.30.8 Location-Based ServiceThe Itinerary demo uses locations to create an itinerary.

Launch the application. A splash screen (also used as the help) appears. Press 4 atany time to retrieve this help screen.

The initial map view plots your itinerary (a walk through San Francisco) in red dots.The bay (in blue) is on the right of your screen.

Press 1 to start following the itinerary. The application zooms in on your location onthe map. Turn-by-turn directions appear in white boxes on the horizontal axis.

While the itinerary is running, press 7 to rotate the map counter-clockwise. Note, themap rotates and the text now appears on the vertical axis. Press 7 again to restore thedefault orientation.


FIGURE A-59 Zoomed View of Location-Based Service

A.31 UIDemoThis demo provides many examples of UI elements you can use in yourapplications. The demo names explain their purpose.

Most have some interactive capability (navigate and select) and some allow input.Interaction is similar across demos. You can choose items from lists or input data.

ChoiceGroup, List: The ChoiceGroup, List, and TextBox demos show the threechoice group types: Exclusive (radio buttons), Multiple (check boxes) and Pop-Up (adrop list).

■ For Exclusive and Multiple, navigate to highlight an object, and use the selectcapability to pick an option.

■ For pop-ups, highlight the popup and select to open it. Use navigation keys tomove up and down the list. Use Select to choose an item. The Alert and DateFielddemos use pop-ups.


Input: The CustomItem and TextField, and TextBox demos showcase different inputtypes. Text boxes and fields can be set to accept five types of input (not all elementsuse all types). These categories act as filters.

■ Qwerty: Any character on the keyboard.

■ 123: Any numeral

■ ABC: Any letter

■ Predict: Predicts next character based on prior input

■ Symbols. Any symbol

For example, if 123 is assigned to a field and you type abc, nothing will be enteredin the field. As shown in FIGURE A-60, Text Fields can display a tip (in this case“Qwerty“) to prompt the user for acceptable input.

FIGURE A-60 Text Field Demo With Hint

A.32 VirtualKeypadDemoThis demo was created for the Samsung Upstage phone. The virtual keypad allowsthe user to enter text by choosing characters from a list using the media playerinterface (instead of flipping the phone over and using the keypad). The virtualkeypad uses the same key assignments as the conventional keypad.

In KToolbar, open the VirtualKeypadDemo project and choose the MIDP 2.0 MVMplatform. Go to the Device tab, and choose the Upstage phone.


Run the demo. VirtualKeypadDemo lets you enter one string, andVirtualKeypadDeluxe accepts four strings, as shown in FIGURE A-61.

FIGURE A-61 VirtualKeypadDeluxe Spanish and English Entries

Select a text string and choose Edit from the soft menu. The Enter Text screendisplays the selection options. The demo uses the media player controls as describedin TABLE A-6.

The Menu soft key offers two options: (1) Done and (2) Language. Your languageselection determines the characters displayed for each key group.

Choose characters using the actions in TABLE A-6 and choose Done from the menuwhen you are finished.

TABLE A-6 Media Player Controls for Virtual Keypad

Key Action

Menu Move up the list

<< Cursor left

> Select/Tap

>> Cursor right

Back Delete previous character

Tap the area below > to move down the list

End Return to launch menu without saving


FIGURE A-62 Enter Text Screen with Spanish Option

A.33 WMADemoThis application shows how to send and receive SMS messages. The Sprint WirelessToolkit 3.2 offers a flexible emulation environment to support messaging. Messagescan be exchanged between emulator instances and can be generated or receivedusing the WMA console utility.

Because this example makes use of the push registry you must use the Run via OTAfeature to install the application into the emulator in a process that mirrors howapplications are installed on real devices. If you don’t know how to do this, readabout it in Chapter 2.

Use the WMA console to send the emulator a message as follows.

Choose File > Utilities... and select WMA Console.

In the WMA console window, click the Send SMS... button. Choose the number inthe SMS message window, then fill in a port number of 50000. Type in a text messageand click Send.


FIGURE A-63 Sending a Text Message

The emulator notifies you that it has received a message.


FIGURE A-64 The Push Registry Asks for Confirmation

Choose Yes. The SMSReceive MIDlet is launched and immediately displays theincoming SMS message.

FIGURE A-65 An Incoming Text Message

You can also use the WMA console to send and receive MMS messages. SeeChapter 8 for more information.

If you are attempting to send text messages to WMADemo using the WMA console,make sure to specify the port number as 50000. For MMS messages, useexample.mms.MMSDemo as the application ID.


For example, to send an MMS message from the WMA console to the emulator,make sure that WMADemo has been installed using Run via OTA as described above.Leave the emulator running.

In the WMA console, click Send MMS... to pop up the MMS composition window.Fill in a message subject, the application ID example.mms.MMSDemo, and thetelephone number of the running emulator.

FIGURE A-66 Addressing an MMS Message

Next, click the Parts tab. The WMA console allow you to select files from your harddisk that you wish to send as parts of the MMS message. Click Add to add a file tothe message. Use the file browser to find the file you want to send and click OK.


FIGURE A-67 Adding Parts to an MMS Message

Click Send to send the message.

The emulator asks if it can launch WMADemo. Click Yes. The image and itsinformation are displayed.

FIGURE A-68 WMADemo Receives the Image



APPENDIX B

Command Line Reference

This appendix describes how to operate the Sprint Wireless Toolkit 3.2 (the toolkit)from the command line and details the steps required to build and run anapplication. It also describes the toolkit certificate manager utility, calledMEKeyTool, and the MIDlet signing utility, called JAD Tool (Java ApplicationDescriptor Tool).

B.1 PrerequisitesBefore building and running an application from the command line, verify that youhave a version no earlier than 1.5 of the J2SE SDK. Run the jar.exe command (makesure the command is in your PATH) and then run java -version at the commandline to verify that the version of the J2SE SDK that is actually being used is 1.5.

For more examples, see the files build.bat and run.bat in the bin directories of thedemonstration applications. You can find these files under thetoolkit\apps\demo\bin directory where toolkit is the installation directory of thetoolkit and demo is the name of one of the demo applications.

B.2 The Development CycleFor a full description of developing MIDP applications, see Chapter 2. This sectiondescribes how to accomplish each of the steps in the development cycle from thecommand line.

B-1

B.2.1 BuildUsing KToolbar, building a project is a single step. Behind the scenes, however, thereare actually two steps. First, Java source files are compiled into Java class files. Next,the class files are preverified, which means they are prepared for the CLDC KVM.

Use the javac compiler from the J2SE SDK to compile Java source files. You can usethe existing toolkit project directory structure. You must use the -bootclasspathoption to tell the compiler to use the MIDP APIs, and the -d option to tell thecompiler where to put the compiled class files.

The following example shows how you could compile a MIDP 2.0 application,taking source files from the src directory and placing the class files in the tmpclassesdirectory. Newlines have been added for clarity.

javac

-bootclasspath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar

-d tmpclasses

src\*.java

If you want to use the optional APIs that are supported by the toolkit, add their JARfiles to the -bootclasspath option.

For more information on javac, consult the J2SE documentation.

The next step is to preverify the class files. In the bin directory of the toolkit lives ahandy utility called preverify. The syntax for the preverify command is as follows:

preverify options files|directories

Some of the options are as follows:

-classpath classpath

Specify the directories or JAR files (given as a semicolon-delimited list) fromwhich classes are loaded.

-d output-directory

Specify the directory into which the preverifier should output classes. Thisdirectory must exist before preverifying. If this option is not used, the preverifierplaces the classes in a directory called output.

Following the example for compiling, use the following command to verify thecompiled class files. As before, newlines have been added for clarity.

preverify

-classpath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar

B-2 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

-d classes

tmpclasses

As a result of this command, preverified class files are placed in the classes directory.If your application uses WMA, MMAPI, or other versions of CLDC or MIDP, be sureto include the relevant .jar files in the classpath.

B.2.2 PackageTo package a MIDlet suite, you must create a manifest file, an application JAR, andfinally, a MIDlet suite descriptor.

Create a manifest file containing the appropriate attributes as specified in the MIDPspecification. You can use any text editor to create the manifest file. A manifestmight have the following contents, for example:

MIDlet-1: My MIDlet, MyMIDlet.png, MyMIDlet

MIDlet-Name: MyMIDlet

MIDlet-Vendor: My Organization

MIDlet-Version: 1.0

MicroEdition-Configuration: CLDC-1.0

MicroEdition-Profile: MIDP-2.0

Create a JAR file containing the manifest as well as the suite’s class and resourcefiles. To create the JAR file, use the jar tool that comes with the J2SE SDK. The syntaxis as follows:

jar cfm file manifest -C class_directory . -C resource_directory .

The arguments are as follows:

file: The JAR file to create.

manifest: The manifest file for the MIDlets.

class_directory: The directory containing the application’s classes.

resource_directory: The directory containing the application’s resources.

For example, to create a JAR file named MyApp.jar whose classes are in the classesdirectory and resources are in the res directory, use the following command:

jar cfm MyApp.jar MANIFEST.MF -C classes . -C res .

Appendix B Command Line Reference B-3

Create a JAD file containing the appropriate attributes as specified in the MIDPspecification. You can use any text editor to create the JAD file. This file must havethe extension .jad.

Note – You need to set the MIDlet-Jar-Size entry to the size of the JAR file created inthe previous step.

For example, a JAD file might have the following contents:

MIDlet-Name: MyMIDlet

MIDlet-Vendor: My Organization

MIDlet-Version: 1.0

MIDlet-Jar-URL: MyApp.jar

MIDlet-Jar-Size: 24601

B.2.3 RunYou can run the emulator from the command line. The toolkit’s bin directorycontains the command emulator. The syntax for the emulator command is asfollows:

emulator options

The general options are:

-help: Display a list of valid options.

-version: Display version information about the emulator.

-Xquery: Print emulator skin information on the standard output stream and exitimmediately. The information includes the skin name, screen size, and othercapabilities.

Options that pertain to running MIDlet suites are:

-Xdevice:skin_name: Run an application on the emulator using the given skinname. For a list of skin names, see Chapter 4, “Using the Emulator.”

-Xdescriptor:jad_file: Run an application locally using the given JAD file.

-classpath classpath: Specify the classpath for libraries required to run theapplication. Use this option when running an application locally.

-D runtime_property: Set the HTTP and HTTPS proxy servers. Valid propertiesinclude:

com.sun.midp.io.http.proxy=proxy host:proxy-port


-Xjam:command=application: Run an application remotely using the ApplicationManagement Software (AMS) to run using OTA provisioning. If no application isspecified with the argument, the graphical AMS is run.

install=jad_file_url|force|list|storageNames

Install the application with the specified JAD file onto a device.

run=storage_name| storage_number

Run a previously installed application. The application is specified by itsvalid storage name or storage number.

remove=storage_name|storage_number|all

Remove a previously installed application. The application is specified by itsvalid storage name or storage number. Specifying all, all previouslyinstalled applications are removed.

transient=jad_file_url

Install, run, and remove the application with the specified JAD file.Specifying transient causes the application to be installed and run and thenremoved three times.

B.2.4 DebuggingYou can use the following options with the emulator for debugging and tracing.

-Xverbose:trace_options

Display trace output, as specified by a list of comma-separated options:

class : trace class loading

gc : trace garbage collection

all : use all tracing options

-Xdebug

Enable runtime debugging. The -Xrunjdwp option must also be used.

-Xrunjdwp:debug_settings

Start a JDWP debug session, as specified by a list of comma-separated debugsettings. The -Xdebug option must also be used. Valid debug settings include:

transport=transport_mechanism

The transport mechanism used to communicate with the debugger. The onlytransport mechanism supported is dt_socket.

address=host:port

The transport address for the debugger connection. You can omit providing ahost. If host is omitted, localhost is assumed to be the host machine.


server=y|n

Start the debug agent as a server. The debugger must connect to the portspecified. The possible values are y and n. Currently, only y is supported (theemulator must act as a server).

B.3 Launching Toolkit GUI ComponentsThe components of the toolkit can all be launched from the command line. Eachcomponent is in the toolkit’s bin directory.

B.4 Setting Emulator PreferencesYou can change the emulator preferences from the command line by using the-Xprefs option for the emulator command. The format is as follows:

-Xprefs:filename

The filename you provide should be the full path name of a property file whosevalues override the values in the preferences dialog box. The property file cancontain the following properties:

TABLE B-1 Toolkit component commands

Command Description

DefaultDevice Pops up a dialog that allows you to choose the default emulator skin

ktoolbar Launches KToolbar

prefs Launches the toolkit preferences

utils Launches the toolkit utilities window


TABLE B-2 Emulator Preferences Properties List

Property Name Property Description and Legal Values

http.version Network Configuration > HTTP VersionValue: HTTP/1.1 | HTTP/1.0

http.proxyHost Network Configuration > HTTP AddressValue: hostname

http.proxyPort Network Configuration > HTTP PortValue: integer

https.proxyHost Network Configuration > HTTPS AddressValue: hostname

https.proxyPort Network Configuration > HTTPS PortValue: integer

netspeed.bitpersecond Performance > bits/sec combo boxValue: integer

netspeed.enableSpeedEmulation Performance>EnablenetworkthroughputemulationValue: true | false

screen.graphicsLatency Performance > Graphics primitives latencyValue: integer

screen.refresh.mode Performance > Display refresh (radiobutton)Value: default | immediate | periodic

screen.refresh.rate Performance > Display refresh (slider)Value: integer

vmspeed.bytecodespermilli Performance > Enable VM speed emulation(check box)Value: integer

vmspeed.enableEmulation Performance > Enable VM speed emulation(slider)Value: true | false

storage.root Storage > Storage root directoryValue: String (relative path to appdb)

storage.size Storage > Storage sizeValue: integer

mm.control.capture MMedia > Audio CaptureValue: true | false


B.5 Using Security FeaturesThe full spectrum of the toolkit’s security features are also available from thecommand line. You can adjust the emulator’s default protection domain, sign MIDletsuites, and manage certificates.

mm.control.midi MMedia > MIDI tonesValue: true | false

mm.control.mixing MMedia > Audio MixingValue: true | false

mm.control.record MMedia > Audio RecordValue: true | false

mm.control.volume Value: true | false

mm.format.midi MMedia > MIDI formatValue: true | false

mm.format.video MMedia > Video formatValue: true | false

mm.format.wav MMedia > WAV Audio formatValue: true | false

wma.client.phoneNumber WMA > Phone Number of Next EmulatorValue: integer

wma.server.firstAssignedPhoneNumber WMA > First Assigned Phone NumberValue: integer

wma.server.percentFragmentLoss WMA > % Random Message Fragment LossValue: integer

wma.server.deliveryDelayMS WMA > Message Fragment Delivery Delay(ms)Value: integer

TABLE B-2 Emulator Preferences Properties List (Continued)

Property Name Property Description and Legal Values


B.5.1 Changing the Emulator’s Default ProtectionDomainTo adjust the emulator’s default protection domain, use the following option withthe emulator command:

-Xdomain domain_type

Assigns a security domain to the MIDlet suite. Domain types include untrusted,trusted, minimum, and maximum.

B.5.2 Signing MIDlet SuitesJadTool is a command-line interface for signing MIDlet suites using public keycryptography according to the MIDP 2.0 specification. Signing a MIDlet suite is theprocess of adding the signer certificates and the digital signature of the JAR file to aJAD file.

JadTool only uses certificates and keys from J2SE keystores. J2SE provides keytool,the command-line tool to manage J2SE keystores.

JadTool is packaged in a JAR file. To run it, open a command prompt, change thecurrent directory to toolkit\bin, and enter the following command:

java -jar JADTool.jar command

The commands are as follows:

-help

Print the usage instructions for JADTool.

-addcert -keystore keystore -alias alias -storepass password[-certnum number] [-chainnum number] -inputjad input_jadfile-outputjad output_jadfile

Add the certificate of the key pair from the given keystore to the JAD file.

-addjarsig -jarfile jarfile -keystore keystore -alias alias -storepasspassword -keypass password -inputjad input_jadfile -outputjad output_jadfile

Add the digital signature of the given JAR file to the specified JAD file. Thedefault value for -jarfile is the MIDlet-Jar-URL property in the JAD file.

-showcert [([-certnum number] [-chainnum number]) |-all[-encoding encoding] -inputjad filename

Display the list of certificates in the given JAD file.

The default value for:

-encoding is UTF-8


-jarfile is the MIDlet-Jar-URL property in the JAD

-keystore is %HOMEPATH%\.keystore

-certnum is 1-chainnum is 1

B.5.3 Managing CertificatesMEKeyTool manages the public keys of certificate authorities (CAs), making itfunctionally similar to the keytool utility that comes with the J2SE SDK. The keyscan be used to facilitate secure HTTP communication over SSL (HTTPS).

Before using MEKeyTool, you must first have access to a Java CryptographyExtension (JCE) keystore. You can create one using the J2SE keytool utility. Seehttp://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.htmlfor more information.

To run MEKeyTool, open a command prompt, change the current directory totoolkit\bin, and enter the following command:

mekeytool.exe command

The commands are as follows:

-help

Print the usage instructions for MEKeyTool.

-import -alias alias -keystore JCEkeystore -storepass storepass-domain domain_name

Import a public key into the ME keystore from the given JCE keystore usingthe given JCE keystore password. The default ME keystore is toolkit\appdb\_main.ks and the default JCE keystore is user.home\.keystore.

-list

List the keys in the ME keystore, including the owner and validity period foreach. The ME keystore is toolkit\appdb\_main.ks.

-delete (-owner owner|-number key_number)

Delete a key from the given ME keystore with the given owner. The MEkeystore is toolkit\appdb\_main.ks.

Note – The toolkit contains an ME keystore called _main.ks, which is located in theappdb subdirectory. This keystore includes all the certificates that exist in the defaultJ2SE keystore, which comes with the J2SE SDK installation.


http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html

APPENDIX C

Localization

This appendix describes setting the language displayed in the Sprint Wireless Toolkit3.2 and the localization setting of the emulation environment.

C.1 Locale SettingA locale is a geographic or political region or community that shares the samelanguage, customs, or cultural conventions. In software, a locale is represented by acollection of files, data, and code, which contains the information necessary to adaptsoftware to a specific location.

Some software uses a locale to tailor information for users, such as:

■ Messages displayed to the user

■ Fonts used or other writing-specific information

By default, all KToolbar strings, that is, the entire User Interface (UI), are displayedin the language of the supported platform’s locale.

For example, Japanese characters can be displayed in KToolbar running on aJapanese Microsoft Windows machine, provided that the correct localized SprintWireless Toolkit 3.2 is downloaded and installed.

You can set the wtk.locale property to have the KToolbar displayed in a specifiedlocale’s language. For example, you can have the toolkit running on a Japanesemachine but still have the KToolbar display shown in English by setting the localeproperty to en-US, and making sure that the proper supplement has beendownloaded and installed over the Sprint Wireless Toolkit 3.2. The wtk.localeproperty should be placed in the toolkit\wtklib\platform\ktools.propertiesfile, where platform is the name of the underlying platform (Windows or Linux, forexample).

C-1

C.2 Emulated LocaleA device’s locale is contained in the system property microedition.locale. Youcan change the emulator’s locale by choosing Edit > Preferences from the KToolbarmenu, then selecting i18n. Choose a locale from the combo box or type it in directly.

For information on microedition.locale, consult the MIDP specification.

C.3 Character EncodingsThe CLDC system property, microedition.encoding, defines the defaultcharacter encoding name of the MIDP environment. In the Sprint Wireless Toolkit 3.2emulator, this property is set according to the underlying window system you areusing. The property’s value is set to the default encoding for the Java SE platformrunning on the same window system. For example, in an English window system,the encoding setting is as follows:

microedition.encoding=ISO8859_1

You can override the default value by adding the microedition.encodingproperty to the toolkit\wtklib\platform\ktools.properties file. For example, ifyou want to use UTF-8 as the default setting on Microsoft Windows, you can set theproperty in the toolkit\wtklib\Windows\ktools.properties file as follows:

microedition.encoding=UTF-8

For more information on character encoding, see the CLDC specification.

Note – All the Java SE platform encoders are available in the emulatedenvironment. See the Sprint Wireless Toolkit 3.2 Basic Customization Guide forinformation on how to limit the list of available encoders for a specific device.

Java Technology Compiler Encoding Setting

The javac.encoding property determines the encoding used by the javac compilerto compile your source files. The property’s value is set to the default encoding forthe Java SE platform running on the same window system.

C-2 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

You can override the default value by adding the javac.encoding property to thetoolkit\wtklib\platform\ktools.properties file, where platform is the name ofthe underlying platform, like Windows or Linux. For example, if you are running inan English system but find you need to compile a Japanese resource bundle, you canspecify a Japanese character set, such as:

javac.encoding=EUCJIS

C.4 Font Support in the Default EmulatorThe default fonts that are used in the emulated environment are set according to theunderlying window system locale. By default, the MIDP environment fonts aremapped to the default Java SE platform Java technology fonts. These fonts usuallysupport all the characters that are required by the current window’s locale.

You can override these fonts to support other characters that are not supported bythe default fonts. See the Sprint Wireless Toolkit 3.2 Basic Customization Guide forinformation on how to configure them.

Appendix C Localization C-3

C-4 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

Index

Aaccess control, 15-3advanced configuration options, 3-12application descriptor, 2-9Application Management Software (AMS), 2-10applications directory, setting, 3-12applications, running remotely, 2-20attributes, 3-3

BBCC, 12-3Bluetooth preferences, 12-1Bluetooth simulation, 12-1building source code, 2-6

Ccall graph, 5-4capture, 9-2certificate importing, 7-15certificate management, 7-13certificate manager utility, B-1certificates, 7-3character encodings, C-2-classpath option, B-2COMM default connection parameters, 6-10COMM Terminal, 6-10command line operations, B-1command path, B-1

Ddebugging, 2-17

from command line, B-5with NetBeans IDE, 2-17

debugging options, B-5demonstrations, A-1

source code, 1-2deploying on a web server, 2-20descriptor, 2-9

attributes, 3-3Developer certificate database, 7-3development cycle

full, 2-8simple, 2-4

Eemulator, 4-1

card slots, 15-2default font support, C-3keyboard shortcuts, 4-3language support, C-1locale, 18-1location, 14-1performance, 4-8phone number, 8-1preferences, 4-6running solo, 4-12skins, 4-1

emulator command, B-4encoding, javac, 3-12external canvas, 6-1, 19-1

Index-1

FFileConnection API, 11-1

managing roots, 11-2font support, C-3

GGCD file, 7-6

Hheap size, 4-7-help option, B-4

Iidentified_third_party protection domain, 7-4-import command, B-10

JJAD, 2-9

attributes, 3-3creating, 2-9MIME type, 2-20

JAD attributes, 6-8JAR

creating, 2-9MIME type, 2-20

Java Card simulator, 15-2Java Cryptography Extension (JCE) keystore, B-10javac.encoding property, C-2JSR 75, 11-1JSR 82, 12-1JSR 135, 9-1JSR 172, 13-1JSR 177, 15-1JSR 179, 14-1JSR 180, 16-1JSR 184, 10-2JSR 185, 7-3JSR 205, 8-1JSR 226, 10-1JSR 229, 17-1JSR 234, A-7JSR 238, 18-1JSR 75, 11-1JTWI protection domains, 7-4

Kkey management, 7-8key pair, creating, 7-10keytool utility, B-10KToolbar

advanced configuration options, 3-12application directory, 3-12starting, 1-1, 2-1

ktools.properties, 3-12, C-1

Llandmarks, 14-3libraries, 3-8locale, 18-1, 18-3location, 14-1

landmarks, 14-3provider, 14-3

LX260, A-34

MM3G, 10-2managing certificates from command line, B-10manifest file, creating, B-3manufacturer protection domain, 7-4maximum protection domain, 7-4media capture, 9-2media formats, 9-1memory monitor, 5-5messages, sorting, 5-11messaging, network simulation, 8-2method profiling, 5-1microedition.encoding property, C-2MIDlets

in projects, 3-5signing, 7-12

MIME types, 2-20minimum protection domain, 7-4MMAPI, 9-1Mobile 3D Graphics, 10-2Mobile 3D Graphics API, 10-1Mobile Media API (MMAPI), 9-1

capture, 9-2formats and protocols, 9-1

muglet, 19-4

Index-2 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

MVM, 4-10MVM attributes, 6-8

Nnetwork monitor, 5-9

filtering, 5-11sorting, 5-11sorting messages, 5-11

OOBEX

demo, A-49preferences, 12-1

obfuscation, 2-15installing ProGuard, 2-16installing RetroGuard, 2-16

Open With, 2-6open with, 2-5, 4-15optional APIs, 1-4

Ppackaging

example from command line, B-3packaging from command line, B-3pause, 4-10pausing and resuming, 4-10payment

API, 17-1attributes, 17-4console, 17-7preferences, 17-4settings, 17-1transactions, 17-5

performance, 4-8permissions, 7-1persistent storage, 4-7Personal Information Management (PIM) API, 11-1phone number, setting in emulator, 8-1PIM AP, 11-3preverifying, 2-7

example from command line, B-2profiler, 5-1

call graph, 5-3, 5-4projects, 2-1, 3-1

attributes, 3-3building, 2-6

creating, 2-2deploying on real devices, 2-12libraries, 3-8MIDlets, 3-5opening in IDE, 2-13packaging, 2-9push registry, 3-7running, 2-7selecting APIs, 3-1source code, 2-3

protection domainJTWI, 7-4

protection domains, 7-1proxy servers, 4-6push registry, 3-7

Rremotely-deployed applications, 2-20resource, add, 4-16resume, 4-10revision control, 3-13Revision Control System (RCS), 3-13RevisionControl property, 3-13run options, B-4Run via OTA, 2-10, 7-3running, from command line, B-4

SSATSA, 15-1secondary screen, 6-1, 19-1signed MIDlet suites, 7-1signing MIDlet suites, 7-5SIP, 16-1SMS binary message, sending, 8-5SMS text message, sending, 8-4source code

location, 2-3source file, add, 4-16Sprint certificate database, 7-3supported APIs, 1-4

Ttarget platform, 3-3Tracing, 5-12tracing options, B-5

Index-3

trusted protection domain, 7-4

Uunidentified_third_party protection domain, 7-4untrusted protection domain, 7-4

Vversion control, 3-13-version option, B-4

WWireless Messaging API (WMA), 8-1Wireless Toolkit

certificate manager utility, B-1running from command line, B-1

Wireless Toolkit, setting locale, C-1WMA console, 8-3

receiving messages, 8-8wtk.locale property, C-1

X-Xdebug option, B-5-Xquery option, B-5-Xrunjdwp option, B-5-Xverbose option, B-5

Index-4 Sprint Wireless Toolkit 3.2 User’s Guide • December 2007

Date post:	07-Sep-2014
Category:	Documents
Upload:	dilshan-perera
View:	154 times
Download:	8 times