Page 1

Quick Guide Sprint Wireless Toolkit 3.2 Powered by Java Technology

PART NO. QG32 December 2007


Copyright © 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, Jini, Solaris, J2SE, Java SE, J2ME, Java ME, Netbeans, java, the Duke logo and the Java Coffee Cup logo 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 or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

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 ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plus des brevets américains listés à l'adresse http://www.sun.com/patents et un ou les brevets supplémentaires ou les applications de brevet en attente aux Etats - Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence. Cette distribution peut comprendre des composants développés par des tierces parties. Sun, Sun Microsystems, le logo Sun, Java, Jini, Solaris, J2SE, Java SE, J2ME, Java ME, Netbeans, java, le logo Duke et le logo Java Coffee Cup sont des 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 vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires,des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportation amé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 directe ou 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 et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.


Contents

Preface 1.

2.

vii

Introduction

1–1

1.1

Quick Start

1–1

1.2

The Tools in the Toolkit

1.3

Toolkit Features

1.4

Supported Technology

1–2

1–3

Developing MIDlet Suites

1–4 2–1

2.1

About Projects

2.2

The Simple Development Cycle 2.2.1

2–1

Source Code Open With

2.3

2.4

2.2.2

Build

2.2.3

Run

2–4

2–5 2–5

2–6 2–7

The Full Development Cycle 2.3.1

Package

2.3.2

Install

2.3.3

Run

2–8

2–9 2–10

2–12

Opening a Project in the Sprint IDE

2–13

iii


3.

2.5

Creating a Project from a MIDlet Suite

2.6

Using an Obfuscator

2.7

Using a Debugger

2.8

Deploying Applications on a Web Server

4.

2–17 2–20

3–1

3.1

Permissions

3.2

Setting Security Preferences

3–1 3–3

3.2.1

MSA Protection Domains

3.2.2

Java for the Wireless Toolkit Industry Protection Domains

3.3

Signing a MIDlet Suite

3.4

Signing a GCD File

3.5

Managing Keys

3–4

3–5

3–6

3–8

3.5.1

Creating and Using Keystores

3.5.2

Creating a New Key Pair

3.5.3

Getting Real Keys

3.5.4

Removing a Key Pair

Managing Certificates

3–8

3–10

3–12 3–13

3–13

3.6.1

Enabling and Disabling Certificates

3.6.2

Importing Certificates

3–15

3.6.3

Removing Certificates

3–15

New in This Release 4.1

iv

2–15

Security and MIDlet Signing

3.6

2–14

New Features

3–14

4–1 4–1

4.1.1

Multitasking VM

4–1

4.1.2

Sprint Multitasking VM JAD Attributes

4.1.3

MIDP 2.0 Multitasking VM Platform

4.1.4

GCD File Creator

4–2

4.1.5

COMM Terminal

4–2

Sprint WirelessToolkit 3.2 Quick Guide • December 2007

4–1

4–2

3–4


4.1.6

Keystore Password Encryption

4.1.7

Qualcomm GPS-ONE API Support

4.1.8

Sprint 2.2 Extensions

4.1.9

Security

4–2

4–3

4–3

4.2

New JSRs in this Release

4.3

Additional Sprint Features

4.4

4–2

4–3 4–3

4.3.1

New Look and Feel

4–4

4.3.2

Open With

4.3.3

New Skins and Skin Specifications

4–4 4–5

4.3.3.1

New Skins

4–5

4.3.3.2

Device Skin Performance Properties

4.3.3.3

Device Specifications

4–5

4.3.4

Signing Window Changes

4.3.5

Integrity Check for Project Settings

4.3.6

Sprint JAD and Multitasking VM Attributes

4.3.7

Opening Projects in the Sprint IDE

New Demos

4–5

4–6 4–6 4–8

4–11

4–11

4.4.1

DebugApp

4–12

4.4.2

GoSIP

4.4.3

i18nDemo

4.4.4

JBricks

4.4.5

KeyEventDemo

4–22

4.4.6

LX260-Test-S05

4–22

4.4.7

Multitasking VM Demo

4.4.8

ObexDemo

4–26

4.4.9

Razr2Demo

4–27

4.4.10

RecordStoreDemo

4.4.11

SIPDemo

4–14 4–16

4–18

4–24

4–28

4–33

Contents

v


4.4.12

SVGContactList

4.4.13

SVGDemo

4.4.14 Index

vi

4–34

4–35

4.4.13.1

SVG Browser

4.4.13.2

Render SVG Image

4.4.13.3

Play SVG Animation

4.4.13.4

Create SVG Image From Scratch

4.4.13.5

Bouncing Balls

4.4.13.6

Optimized Menu

4–37

4.4.13.7

Picture Decorator

4–38

VirtualKeypadDemo

Index–1

Sprint WirelessToolkit 3.2 Quick Guide • December 2007

4–36

4–40

4–36 4–36

4–37

4–37


Preface This document describes how to work with the Sprint Wireless Toolkit 3.2 Powered by Java Technology (the toolkit). It focuses on features new in this release and on Sprint features not available in the Sun Java Wireless Toolkit.

Who Should Use This Book This guide is intended for developers creating Mobile Information Device Profile (MIDP) applications with the toolkit. You should already understand how to use the Mobile Information Device Profile (MIDP) 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 a quick start with MIDP programming, read Learning Path: Getting Started with MIDP 2.0: http://developers.sun.com/techtopics/mobility/learn/midp/midp20/

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

Preface

vii


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

TABLE P-1

viii

Related Documentation

Topic

Title

Release Notes

Sprint Wireless Toolkit 3.2 Powered by Java Technology 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

Sprint WirelessToolkit 3.2 Quick Guide • December 2007


How This Book Is Organized This guide contains the following chapters: Chapter 1 introduces the Sprint Wireless Toolkit 3.2 Powered by Java Technology and the development features it provides. Chapter 2 describes the development processes for creating and running MIDlets. Chapter 3 describes security features. Chapter 4 summarizes the new features available in this release.

Typographic Conventions TABLE P-2

Typographic Conventions

Typeface

Meaning

Examples

AaBbCc123

The names of commands, files, and directories; on-screen computer output

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

AaBbCc123

What you type, when contrasted with on-screen computer output

% su Password:

AaBbCc123

Book titles, new words or terms, words to be emphasized

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

Command-line variable; replace with a real name or value

To delete a file, type rm filename.

Variable file names and directories.

In the book, toolkit always refers to the toolkit installation directory.

{AaBbCc.dir}

Preface

ix


Accessing Sun Documentation Online The following sites provide technical documentation related to Java technology. http://developer.sun.com/ http://java.sun.com/docs/

We Welcome Your Comments We are interested in improving our documentation and welcome your comments and suggestions. You can email your comments to us at: Sprint-WTK-Feedback-External@Sun.Com

x

Sprint WirelessToolkit 3.2 Quick Guide • December 2007


CHAPTER

1

Introduction This book describes how to use Sprint Wireless Toolkit 3.2 Powered by Java Technology (the toolkit). The toolkit is a set of tools that makes it possible to create applications for mobile phones and other wireless devices. Although it is based on the Mobile Information Device Profile (MIDP) 2.1, the toolkit also supports many optional packages, making it a widely capable development toolkit.

1.1

Quick Start If you’d like to get started right away, try the demonstration applications that are included 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.1 You 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 instead of 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 button at the bottom of the window. The demonstration application opens. Press the Run button. The emulator pops up running the application. Most demonstrations are self-explanatory, but some have additional instructions. See Appendix A in the User’s Guide for additional details. All the source code for the demonstration applications is available in the toolkit\apps directory. Each demonstration has its own project directory. Inside the project directory, the source files are in the src directory. For example, the source code for the games demonstration is in toolkit\apps\games\src directory.

1.2

The Tools in the Toolkit The toolkit has three main components:

1-2

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

The emulator is a simulated mobile phone. It is useful for testing MIDP applications.

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


A collection of utilities provides other useful functionality, including a text messaging console and cryptographic utilities.

KToolbar is the center of the toolkit. You can use it to build applications, launch the emulator, and start the utilities. Alternately, the emulator and utilities can be run by themselves, which is useful in many situations. If you want to demonstrate MIDP applications, 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 Features The toolkit supports the creation of MIDP applications with the following main features: ■

Building and packaging: You write the source code and the toolkit takes care of the 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 or install it using a process that resembles application installation on a real device. A memory monitor, network monitor, and method profiler are provided to analyze the operation of your MIDlets.

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

Chapter 1

Introduction

1-3


1.4

Supported Technology The toolkit supports many standard Application Programming Interfaces (APIs) defined through the Java Community Process (JCP). TABLE 1-1 shows the APIs and includes links to the specifications. TABLE 1-1

1-4

Supported JCP APIs in the Sprint Wireless Toolkit 3.2

JSR API

Name URL

JSR 75 PIM and File

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

JSR 82 Bluetooth and OBEX

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

JSR 118 MIDP 2.1

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

JSR 120 WMA 1.1

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

JSR 135 MMAPI 1.1

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

JSR 139 CLDC 1.1

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

JSR 172 Web Services

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

JSR 177 SATSA

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

JSR 179 Location

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

JSR 180 SIP

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

JSR 184 3D Graphics

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

JSR 185 JTWI 1.0

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

JSR 205 WMA 2.0

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

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


TABLE 1-1

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

JSR API

Name URL

JSR 211 CHAPI

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

JSR 226 SVG

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

JSR 229 PAPI

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

JSR 234 AMMS

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

JSR 238 MIA

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

JSR 248 MSA

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

Chapter 1

Introduction

1-5


1-6

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


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 works through the development process. When creating MIDlet suite applications you are likely to follow one of two basic development 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 allows for more comprehensive and realistic testing. Toward the end of the chapter, read about how to use the toolkit with advanced development tools like an obfuscator and a debugger. A final section briefly describes how to configure a web server to serve MIDP applications.

2.1

About Projects In the toolkit, MIDlet suites are organized into projects, where the end result of one project is one MIDlet suite. A project contains all of the files that are used to build a MIDlet 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 an existing project. In this chapter you work with a very simple example project. As you read about each 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.1 You see the KToolbar window. 1. Depending on how Microsoft Windows is configured, you might need to choose Start > All Programs instead of Start > Programs.

2-1


FIGURE 2-1

The KToolbar Window

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

2-2

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 2-2

Creating a New Project

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

Chapter 2

Developing MIDlet Suites

2-3


FIGURE 2-3

2.2

File Locations in the Console

The Simple Development Cycle The 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 that are 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 and edit them again. If you find a bug when you are testing your application in the emulator, edit the source files to fix the bug. Now that you understand the simple development cycle at a high level, the rest of this section illustrates how you can accomplish each step using the toolkit.it

2-4

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


2.2.1

Source Code You can use the text editor of your choice to create and edit source code files. (If you don’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 file TinyMIDlet.java. It should be saved in the source directory of your project, which is toolkit\apps\Tiny\src\TinyMIDlet.java where toolkit is the installation directory of the toolkit. The file contains a very simple MIDlet: 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(); } }

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 Open With... as shown in FIGURE 2-4.

Chapter 2

Developing MIDlet Suites

2-5


FIGURE 2-4

Open a File with an External Application

The Open With menu options are as follows:

2.2.2

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

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

Build The 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 source file in the right place, the toolkit finds it and compiles it. Compilation errors are displayed in the KToolbar console. If you have errors, go back and edit the source code to fix them. Once you’ve eliminated your errors, the KToolbar console tells you the project was successfully built.

2-6

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 2-5

Messages about Building

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

2.2.3

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

Chapter 2

Developing MIDlet Suites

2-7


FIGURE 2-6

2.3

TinyMIDlet in Action

The Full Development Cycle The 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 class files 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 install the 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 development cycle. Editing source code is the same as always. The Build step is now incorporated in packaging. The full development cycle includes two new steps, packaging and installing. Finally, running an installed application is different in important ways from running an application in the simple development cycle.

2-8

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


2.3.1

Package The toolkit automates the task of packaging a MIDlet suite. The end result of packaging is two files, a MIDlet descriptor and a MIDlet suite JAR. The descriptor is a small text file that contains information about the MIDlet suite. The JAR contains the class files and resources that make up the MIDlet suite. Devices can use the descriptor to learn about the application before downloading the entire JAR, an important 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, as shown in FIGURE 2-7. The MIDlet suite descriptor and JAR are generated and placed in 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 shrink the size of the MIDlet suite JAR, a technique that is described later in this chapter. In addition, the toolkit provides tools to allow you to cryptographically sign MIDlet suites. See Chapter 3 for more information.

Chapter 2

Developing MIDlet Suites

2-9


2.3.2

Install To properly test a MIDlet suite, you should install it into the toolkit’s emulator or a real device. When you press the Run button in KToolbar, the MIDlet suite is not installed into the emulator. Instead, the emulator runs the MIDlet classes directly. The emulator also has the capability of installing applications into its memory in a process that resembles how applications are transmitted and installed on real devices. 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 Management Software (AMS). The emulator’s AMS is an example of the type of software that real devices must have to manage MIDlet suites. FIGURE 2-8

Emulator AMS Welcome Screen

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

2-10

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 2-9

URL Prompt

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

Confirming the Installation

Choose Install again. You might see a security confirmation message. Press Continue. You are asked if you want to launch Tiny.jad. Click the OK soft button and you see the MIDlet’s welcome message. Select Exit and you are returned to the Applications screen. Tiny is now listed as an installed application.

Chapter 2

Developing MIDlet Suites

2-11


FIGURE 2-11

The Application Menu

Run via OTA is an extremely useful mechanism that makes it easy to install your MIDlet suite on the toolkit emulator. Some features must be tested using this technique, 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. How this happens depends heavily on the device you are using. There are two likely possibilities:

2.3.3

You can deploy the application on a web server, then transmit the application from server to device using the Over the Air (OTA) protocol described in the MIDP 2.0 specification. This is most likely the same mechanism that users encounter 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 web server, and although it won’t give you any insights into the process of installing your application on the device via OTA, it allows you to see how your application performs on the device.

Run Once the application is installed, choose the application from the list and choose Launch from the menu.

2-12

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


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 IDE Projects created with the Sprint Wireless Toolkit 3.2 can also be opened in the Sprint IDE. 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 a project from your toolkit installation. For example, choose a project from: C:\SPRINT_WTK_32\apps, as shown in FIGURE 2-13.

Chapter 2

Developing MIDlet Suites

2-13


FIGURE 2-13

2.5

Sprint IDE Open Project Window

Creating a Project from a MIDlet Suite You can also create a toolkit project from a MIDlet suite archive (.jar file) and descriptor (.jad file). This is useful for running MIDlet suites from KToolbar even when you don’t have the source code available. You can use the toolkit to easily manipulate the attributes in the descriptor, or you can run the project and use the toolkit’s monitoring tools to scrutinize its behavior. To create a project based on a MIDlet suite choose File > Create project from JAD/JAR. Navigate to the descriptor you wish to use and click Open. Note that the descriptor and the JAR should be in the same directory.

2-14

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 2-14

2.6

Creating a New Project from JAD and JAR Files

Using an Obfuscator An obfuscator is a tool that reduces the size of class files. MIDlet suites need to be compact, both to minimize download times and to comply with sometimes stringent limits on JAR size imposed by manufacturers or carriers. Using an obfuscator is one way (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. Although the toolkit doesn’t come with an obfuscator, it is already configured to use the ProGuard obfuscator. All you need to do is download ProGuard and put it in a place where the toolkit can find it. ProGuard is published under the terms of the GNU General Public License (GPL). If you are comfortable with the terms of the license, you can download and use ProGuard free of charge.

Chapter 2

Developing MIDlet Suites

2-15


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 ProGuard installation to the bin directory of your toolkit installation. Once ProGuard is installed, you can use it by choosing Project > Package > Create Obfuscated 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 tell ProGuard 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 need to 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 and restart 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/retroguardmain.html. 2. Download the latest version. 3. Extract the retroguard.jar file from downloaded zip file to the bin directory of your toolkit installation. 4. Edit toolkit\wtklib\platform\ktools.properties so that it uses the RetroGuard 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.properties file as follows: obfuscator.runner.class.name: com.sun.kvem.ktools.RunPro obfuscator.runner.classpath: wtklib\\ktools.zip 2-16

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


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

2.7

Using a Debugger A variation on running your application is running it with a debugger. A debugger allows you to monitor the running application more closely, set breakpoints, and examine variables. You must supply your own debugger. You can use the jdb debugger from J2SE™ or another debugger of your choice. If you want to use a debugger, you are likely to use an Integrated Development Environment (IDE) that is aware of the toolkit. For example the NetBeans Mobility pack. See http://www.netbeans.org/products/mobility/. Information about using jdb 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 the emulator. Click Debug. The port number can be any legal port between 1024 and 65546. When you click Debug, 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. For more 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 IDE These instructions assume you have the NetBeans Mobility Pack and the Sprint Wireless Toolkit installed. ■

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

Chapter 2

Developing MIDlet Suites

2-17


add this platform, click Add Platform and use the wizard to add a Java ME MIDP Platform Emulator of that name and specify the path to your Sprint Wireless Toolkit 3.2 installation. â–

You might need to customize your firewall settings or disable your firewall to ensure 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 number between 1024 and 65536.

2-18

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 2-16

Ktoolbar Remote Debugging Port

b. Click Debug. The emulator runs. Before it launches you see the following benign messages in 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 select Attach 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 the same port number that you specified in Step 3. Click OK. The connection is made. In the NetBeans IDE debugger console you see the following message: Attaching to 127.0.0.1:5000 User program running When the connection succeeds the MIDlet is started in the emulator.

Chapter 2

Developing MIDlet Suites

2-19


FIGURE 2-18

Attach Window

6. Launch the application (in this case TextFieldDemo). The application stops at the breakpoint. In NetBeans, the breakpoint is now colored green.

2.8

Deploying Applications on a Web Server The MIDP 2.0 specification includes the Over The Air User Initiated Provisioning Specification, 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 JAD file’s MIDlet-Jar-URL property to the URL of the JAR file. The URL should be an absolute 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 the text/vnd.sun.j2me.app-descriptor MIME type.

For MIDlet suite JARs, map the .jar extension to the application/javaarchive MIME type.

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

2-20

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


The emulator implements the device behavior during OTA provisioning. You can use the emulator to test and demonstrate the full provisioning process of MIDlet suites 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 OTA option. To launch the emulator’s AMS, you have two options: ■

In the Microsoft Windows start menu, choose Start > Programs > Sprint Wireless Toolkit 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 very similar to the Run via OTA option described earlier in this chapter, except you must enter the URL of your own server to install your application.

Chapter 2

Developing MIDlet Suites

2-21


2-22

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


CHAPTER

3

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 to protected functions. The MIDP 2.0 specification also includes a recommended practice for using public key cryptography to verify and authenticate MIDlet suites. For definitive information, consult the MIDP 2.0 specification. For an overview of MIDlet signing using the J2ME Wireless Toolkit, read this article: Understanding MIDP 2.0's Security Architecture http://developers.sun.com/techtopics/mobility/midp/articles/pe rmissions/ 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/se curity1/ This chapter describes support for protection domains, permissions, and MIDlet signing in the Sprint Wireless Toolkit 3.2 (the toolkit).

3.1

Permissions MIDlets must have permission to perform sensitive operations, like connecting to the network. Permissions have specific names, and MIDlet suites can indicate their need for certain kinds of permissions through attributes in the MIDlet suite descriptor.

3-1


In the toolkit, you can add these permission attributes to a project by clicking on the Settings... button. Select the Permissions icon. The MIDlet-Permissions box shows permissions which the MIDlet must possess, while the MIDlet-Permissions-Opt box contains permissions that are optional. FIGURE 3-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.

3-2

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


3.2

Setting Security Preferences The 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 Architecture or MSA). The protection domains are further described in Section 3.2.1, “MSA Protection Domains” on page 3-4 and Section 3.2.2, “Java for the Wireless Toolkit Industry Protection Domains” on page 3-4. To choose the security policy you want the emulator to use, select Edit > Preferences and select Security in the Category list. From the Security Policy combo box, choose either MSA or JTWI. Select one of the available security policies, and select a certificates database. See FIGURE 3-2. The Sprint database is appropriate for Sprint devices. It contains the Sprint certificate and the Verisign root certificate used to authenticate the Sprint certificate. The Developer database can contain certificates used for applications that run on platforms other than Sprint. JDK certificates and TCK certificates fall in this category.

FIGURE 3-2

Security Preferences

When you use Run via OTA. your packaged MIDlet suite is installed directly into the emulator and it is placed in a protection domain at installation time. The emulator uses public key cryptography to determine the protection domain of installed MIDlet suites. If the MIDlet suite is not signed, it is placed in the default protection domain. The default is different for MSA and JTWI, as explained in Sections 3.2.1 and 3.2.2. If the MIDlet is signed, it is placed in the protection domain that is associated with the root certificate of the signing key’s certificate chain. For example, suppose Respectable Software, a hypothetical company, wants to distribute a cryptographically signed MIDlet suite. Respectable Software buys a signing key pair from Super-Trustee, a hypothetical certificate authority. Using the signing key, Respectable Software signs the MIDlet suite and distributes their certificate with the MIDlet suite. When the MIDlet suite is installed on the emulator

Chapter 3

Security and MIDlet Signing

3-3


or on a device, the implementation verifies Respectable’s certificate using its own copy of Super-Trustee’s root certificate. Then it uses Respectable’s certificate to verify the signature on the MIDlet suite. Assuming everything checks out, the device or emulator installs the MIDlet suite into the protection domain that is associated with Super-Trustee’s root certificate, most likely identified_third_party. The toolkit provides tools to sign MIDlet suites, manage keys, and manage root certificates.

3.2.1

MSA Protection Domains The toolkit supports five protection domains for MSA: ■

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

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

identified_third_party - Intended for MIDlets whose origins were determined using cryptographic certificates. Permissions are not granted automatically, but the user is prompted less often than for the unidentified_third_party domain.

unidentified_third_party - Provides a high level of security for applications whose origins and authenticity cannot be determined. The user is prompted frequently 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 code runs in the unidentified_third_party protection domain by default.

3.2.2

Java for the Wireless Toolkit Industry Protection Domains The Sun Java Wireless Toolkit includes the following protection domains:

3-4

untrusted - Provides a high level of security for applications whose origins and authenticity cannot be determined. The user is prompted frequently when the application 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 to trusted.).

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


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

3.3

Signing a MIDlet Suite To sign a MIDlet suite, you must package it first. See Section 2.3.1, “Package” on page 2-9. Select the packaged MIDlet, then choose Project > Sign or click the Sign button. The Sign Application window appears (FIGURE 3-3).

FIGURE 3-3

The Sign Application Window

Select the keystore you want to use from the Alias List and click the Sign Application ... button. The Sprint keystore will work in most cases. If you chose the Developer database, as described in Section 3.2, “Setting Security Preferences” on page 3-3, you should choose a keystore from the TCK or JDK.

Chapter 3

Security and MIDlet Signing

3-5


3.4

Signing a GCD File You can use the toolkit to sign a General Content Descriptor (GCD) file. A GCD file might look like this: Content-Name: My Content Name Content-Size: 2135 Content-Type: image/jpeg Content-URL: my_image.jpg Content-Vendor: my_vendor Content-Version: 1.0

1. In the main window click the Sign button. The Sign Application window appears (see FIGURE 3-3). 2. Select Action > Sign Application. The Select JAD or GCD File window opens (FIGURE 3-4). Choose a GCD file and click the Sign Application button. FIGURE 3-4

3-6

Choose a GCD File

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


The Security Tool window notifies you that the file is signed. Click OK. Suppose you specify the following GCD file, test.gcd: Content-Type: audio/wav Content-Name: test-wav Content-Version: Content-Vendor: Sun Content-URL: http://java.sun.com/products/java-media/mma/media/test-wav.wav Content-Size: 217

The signed file might look like this: Content-Type: audio/wav Content-Name: test-wav Content-Version: Content-Vendor: Sun Content-URL: http://java.sun.com/products/java-media/mma/media/test-wav.wav Content-Size: 217 Content-Certificate-1-1: MIIE8DCCA9igAwIBAgIQR/meD3uDWU1ghEQEBxudSzANBgkqhkiG9w0BAQUFADCBtDELMAkGA1UEBhMCVVMxFzAVBg NVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJt cyBvZiB1c2UgYXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNDEuMCwGA1UEAxMlVmVyaVNpZ24gQ2 xhc3MgMyBDb2RlIFNpZ25pbmcgMjAwNCBDQTAeFw0wNjEwMzEwMDAwMDBaFw0wOTEwMzAyMzU5NTlaMIGzMQswCQYD VQQGEwJVUzEPMA0GA1UECBMGS2Fuc2FzMRYwFAYDVQQHEw1PdmVybGFuZCBQYXJrMQ8wDQYDVQQKFAZTcHJpbnQxMT AvBgNVBAsTKERpZ2l0YWwgSUQgQ2xhc3MgMyAtIEphdmEgT2JqZWN0IFNpZ25pbmcxJjAkBgNVBAsUHUFwcGxpY2F0 aW9uIERldmVsb3BlciBQcm9ncmFtMQ8wDQYDVQQDFAZTcHJpbnQwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAK m4Fe21dKk8Duj/qllZQZWgUOcVHJYqzHTXyj1Ar2Xq6T7zImJFURsocM6a/+ZplUbRxG8rTm7cgM+PferIRfsQlLPd jrIRhv8DJNOXfBAexq0lcuU03f6m/0NrlDigt0zG47iBIMqkw4IRIazaIB4knpHzkOHGhZOvtJCYrZtLAgMBAAGjgg F/MIIBezAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIHgDBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vQ1NDMy0yMDA0 LWNybC52ZXJpc2lnbi5jb20vQ1NDMy0yMDA0LmNybDBEBgNVHSAEPTA7MDkGC2CGSAGG+EUBBxcDMCowKAYIKwYBBQ UHAgEWHGh0dHBzOi8vd3d3LnZlcmlzaWduLmNvbS9ycGEwEwYDVR0lBAwwCgYIKwYBBQUHAwMwdQYIKwYBBQUHAQEE aTBnMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC52ZXJpc2lnbi5jb20wPwYIKwYBBQUHMAKGM2h0dHA6Ly9DU0MzLT IwMDQtYWlhLnZlcmlzaWduLmNvbS9DU0MzLTIwMDQtYWlhLmNlcjAfBgNVHSMEGDAWgBQI9VHo+/49PWQ2fGjPW3io 37nFNzARBglghkgBhvhCAQEEBAMCBBAwFgYKKwYBBAGCNwIBGwQIMAYBAQABAf8wDQYJKoZIhvcNAQEFBQADggEBAD jcMgcgK0gGfRSzbaGGpHk6/6t3Ko2LqV5XtrVY78xTnbtiq8JvPuwny9fwKcGBt31V4Rd/cvmwyL8BNlcGX8b7DTmw vm3wbRLpe0qXPCnLG88xsRNLlvIUDX/TyfAIXrU0y/O0n8nXnWej1509M+sXW4ogNPXadZ4xrqbqiBdgw1G8NR9JAe 2gqmmSEVWjZvm1ao34mqD/J4J/1fAsfCJXsmiRef3OawvtVMvGiBg2jOtZcgMv3m641/8T0qsASCW9CLnvBvIjiqJa XkqC1JXZRbGBo2mJwXGOu1fhH7naU+JJAPOGUhn3GwpvR1sy5GwND13A6L3xGaNl8qIAIZs= Content-RSA-SHA1: WGIfzY2kcQdKHXFQ/TYFhnTO8ZhemdUt07VY6AaExIRb6o06LlFOsx7/77jncIFa1851+UDXq/2Iu/8vtb36BCgaID cyW/4r0URGibQajow5+8ToosOrwJPYcsp2/ujlt7hftLCN4dw5B1/v4YGwvp7rExltxnwDfCJEMQSIfZg=

Chapter 3

Security and MIDlet Signing

3-7


3.5

Managing Keys The MIDlet signing widow can also be used to manage keys and keystores.

3.5.1

Creating and Using Keystores A keystore file can contain one or more keys. By default the toolkit uses the keystore file 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 new keystore or another keystore you want to change. You can add keys to the keystore by creating a new key pair as described in Section 3.5.2, “Creating a New Key Pair” on page 3-10. Alternatively, you can click Import Key Pair to copy a key pair from another keystore to the current keystore. You are prompted to choose the keystore that contains the key pair you want to import.

3-8

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 3-5

Import Key Pair

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

Chapter 3

Security and MIDlet Signing

3-9


FIGURE 3-6

Importing a Key Pair

As shown in FIGURE 3-6, each key pair in the keystore is identified by an alias displayed in the Alias List on the left. The toolkit prompts you to choose a protection domain, as explain in sections 3.2.1 and 3.2.2.

3.5.2

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

3-10

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 3-7

Creating a New Key Pair

After you click Create, the toolkit prompts you to choose a protection domain, as explained in See Sections 3.2.1 and 3.2.2. FIGURE 3-8

Choosing a Protection Domain for a New KeyStore

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

Chapter 3

Security and MIDlet Signing

3-11


The connection between the key pair you just created and a protection domain is established 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 new key:

3.5.3

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 key pair.

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

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

Getting Real Keys The ability to create a key pair and sign a MIDlet within the toolkit environment is for testing purposes only. When you run your application on an actual device, you must 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 Key Pair... in the MIDlet signing window, as described above. 2. Generate a Certificate Signing Request (CSR). Press Generate CSR... in the signing window. To change the location of the CSR file, enter a new path or press Browse... and choose a new file location. Press Create to write the CSR file. After the CSR is written, you see a message that indicates success. 3. Send the CSR to a certificate authority (CA). The CA requires more information from you to verify your identity. You also need to pay the CA for the certificate they generate for you. 4. Once the CA has verified your identity and taken your money, you receive a certificate from the CA that certifies your public key. 5. Import the certificate into the toolkit by pressing Import Certificate... in the MIDlet signing window. You can now use your own private key to sign MIDlet suites. The toolkit takes care of the details of placing the signature and your certificate into the MIDlet suite.

3-12

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


3.5.4

Removing a Key Pair To remove a key pair from the MIDlet signing window, select its alias and choose Action > Delete Selection.

3.6

Managing Certificates You’ve already heard about the emulator’s list of root certificates. In this section, you learn how you can manage this list using the toolkit. Real devices have similar lists of root certificates, although they cannot usually be modified 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 is present on the device. Otherwise, the device is unable to verify your application. While you’re developing your application, the toolkit’s certificate management utility provides a convenient way to manipulate the emulator’s list of root certificates for testing purposes. Choose File > Utilities... from the KToolbar menu. Select Manage Certificates and press Launch to open up the certificate manager window.

Chapter 3

Security and MIDlet Signing

3-13


FIGURE 3-9

The Certificate Manager

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

3.6.1

Enabling and Disabling Certificates Certificates can be enabled or disabled. This is handy if you want to make certificates temporarily unavailable without removing them from the keystore. To enable or disable a certificate, select it in the list and press Enable/Disable Certificate. The toolkit asks you to confirm the action. Choose Yes to proceed.

3-14

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


3.6.2

Importing Certificates You 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 certificate manager window. After you locate the certificate file, choose which protection domain is associated with the certificate. To import a certificate from a Java SE keystore, choose Action > Import J2SE Certificate from the menu in the certificate manager window. First, choose a protection domain for the certificate. Then select the keystore file and enter the keystore password. Finally, select the alias for the certificate you wish to import.

3.6.3

Removing Certificates To remove a certificate from the list, select the certificate and choose Action > Delete Selection.

Chapter 3

Security and MIDlet Signing

3-15


3-16

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


CHAPTER

4

New in This Release

4.1

New Features This section lists new features in Version 3.2.

4.1.1

Multitasking VM This release is based on the Sun's CLDC-HI feature-rich, high-performance, multitasking, cutting-edge, state-of-the-art, deployment-ready virtual machine implementation for mobile handsets. The Multitasking Java VM (MVM) provides the ability to emulate execution of multiple applications that run simultaneously. Each application is instantly available. To see Multitasking VM in action, go to installdir/docs/MVMTutorialMovie and run the .html file.

4.1.2

Sprint Multitasking VM JAD Attributes The following Sprint Multitasking VM JAD attributes are supported. To add attributes to a JAD file, edit the project's settings in the User Defined tab. For a full description of these attributes, see Chapter 6 in the User’s Guide. ■

MIDlet-Background-No-Pause

MIDlet-Launch-Background

MIDlet-Launch-Power-On

4-1


4.1.3

MIDlet-Heap-Size

MIDlet-Background-No-Pause

MIDP 2.0 Multitasking VM Platform This new MIDP 2.0 Multitasking VM platform supports Multitasking VM devices.

4.1.4

GCD File Creator The GCD File Creator is a utility that helps you create a General Content Descriptor (GCD) file. It is a plain text file that describes a download for a mobile device.

4.1.5

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

4.1.6

Keystore Password Encryption A keystore's password and certificate password are now encrypted before they are stored in a project's properties file.

4.1.7

Qualcomm GPS-ONE API Support The MIDP 2.0 Power Vision platform provides optional support for Qualcomm's GPS-ONE API. This API contains Qualcomm Java Application Extensions (QJAE) to determine the current position of a mobile station. MIDP 2.0 Power Vision supports the use of the GPS-ONE API to build a MIDlet. GPS-ONE is not supported at runtime.

4-2

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


4.1.8

Sprint 2.2 Extensions The Sprint 2.2 extensions are now available in the emulator. Select MIDlet > External Events. Select the Sprint System States tab, and click 2.2 Version and select the Nonprotected Properties tab. The 2.2 extensions are at the bottom of the panel.

4.1.9

Network Extensions: WIMAX, WIFI, DOrA, DOrB, ACTIVESYNC, and INTERNATIONAL ROAMING

Bluetooth: ON, OFF, N/A

Hpptt: ON, OFF, N/A

Fmtransmitter: ON, OFF, N/A

Ddtm: ACTIVE, NOT ACTIVE, N/A

Bluetooth key pressed: LEFT, RIGHT, PLAY/PAUSE, VOLUME UP, VOLUME DOWN

Bluetooth key repeated: LEFT, RIGHT, PLAY/PAUSE, VOLUME UP, VOLUME DOWN

Bluetooth key released: LEFT, RIGHT, PLAY/PAUSE, VOLUME UP, VOLUME DOWN

Security This release supports both JTWI and MSA security mechanisms. In addition, the toolkit can now mimic the Sprint devices certificate database such that the database includes the Sprint certificate only.

4.2

New JSRs in this Release This release supports all the JSRs supported in version 3.1 with the addition of JSR 248, the Mobile Service Architecture (MSA). In some cases changes support has been extended to include Multitasking VM.

4.3

Additional Sprint Features This section summarizes the features that are new in Sprint Wireless Toolkit 3.2 .

Chapter 4

New in This Release

4-3


4.3.1

New Look and Feel The look and feel has been enhanced in several ways.

4.3.2

Increased highlighting capability in windows and tabs.

New window icons and button icons in many windows.

Main window has new buttons so you no longer have to choose some actions from the Project menu.

The Welcome tab has a new look and more convenient links. ■

While connected to the internet What's New displays an RSS feed for Sprint Developers and displays the Release note when offline.

New links to Qcelp and the Multitasking VM tutorial movie.

Signing window has new buttons so you no longer have to choose some actions from the Actions menu.

Updated Device tab.

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

Open a File with an External Application

The Open With menu options are as follows:

4-4

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


4.3.3

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

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

New Skins and Skin Specifications The toolkit supports skins from Sprint MIDP 1.0 Vision, Sprint MIDP 2.0 Vision, Sprint Power Vision, and the new MIDP 2.0 Multitasking VM platform.

4.3.3.1

New Skins The following new device skins have been added:

4.3.3.2

MotoRAZR2 - includes support for the external touch screen mechanism

Motorola_ic902

Sanyo 6600

Sanyo 6650

Sanyo 7050 - includes support of the Multitasking VM

Sanyo 8500

LG 160

LG LX260 - includes rotation support for the landscape and portrait screen mode

LG 570 - includes support of the Multitasking VM

Samsung Upstage - includes support for the Player/Phone flip mechanism, and the Multitasking VM

Device Skin Performance Properties To make emulated device skins more like a real device, skins now have properties for Java heap size and total storage size. To see device properties, right-click on the device icon in the Devices tab.

4.3.3.3

Device Specifications To view the specification for a given emulator skin, go to the Devices tab, right-click a device, and select Device’s spec... from the context menu.

Chapter 4

New in This Release

4-5


4.3.4

Signing Window Changes When you have a project open, you can press the Sign button to open the Sign Application window (FIGURE 3-3). The Sign Application window has two new buttons, New Keystore, and Open Keystore. Section 3.5.1, “Creating and Using Keystores” on page 3-8 explains how to use these features.

4.3.5

Integrity Check for Project Settings To change an attribute, from the Settings window, select the Required, Optional, or User Defined icon on the left, as shown in FIGURE 4-2. Click the cell next to the attribute key you wish to change. While you are editing one of the values on the Required or Optional panes, the OK button is disabled during the editing process. When you're done editing and you leave the field (for example, you type Tab to move to another field), the toolkit performs a validation. If the value you edited is invalid, you receive an error message. See FIGURE 4-3.

4-6

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-2

Editing a Project Setting

Chapter 4

New in This Release

4-7


FIGURE 4-3

4.3.6

Error Message for Incorrect Value

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

4-8

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-4

Adding Sprint JAD Attributes

Note that the attribute names are in violation of the MIDP specification because they start with “MIDlet“. Consequently, you see the following dialog every time you add one of these attributes: FIGURE 4-5

Benign Warning for JAD Attributes

Click Yes to continue and the attribute will be added properly.

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

Chapter 4

New in This Release

4-9


.

JAD Attributes

TABLE 4-1 JAD Attribute

Description

Length Validity Criteria

MIDlet-Launch-Background

If the value is “yes” (case insensitive); when the MIDlet is launched, it must be launched to the background (not visible on UI). The splash screen MUST NOT be displayed.

3

• If the parameters are not valid (or not present) according to the description, the attribute MUST be ignored and not assigned on device power on. • If the midlet is not signed (e.g. MIDletJAR-RSA-SHA1 present and valid), then this attribute MUST be ignored. • Multitasking VM ONLY (ignore attribute for single instance VM).

MIDlet-Launch-Power-On

If the value is “yes” (case insensitive), then the application MUST be launched when the device is powered on.

3

• If the parameters are not valid (or not present) according to the description, the attribute MUST be ignored and not assigned on device power on. • If the midlet is not signed (e.g. MIDletJAR-RSA-SHA1 present and valid), then this attribute MUST be ignored. • Multitasking VM ONLY (ignore attribute for single instance VM).

MIDlet-Heap-Size

Heap memory required by the MIDlet in order to execute. This value is considered a maximum value 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 a single applications, then a 901 Insufficient Memory – Heap is returned. • Multitasking VM ONLY (ignore attribute for single instance VM).

3

• If the parameters are not valid according to the description (or not present), the AMS MUST ignore the attribute and allow application to exit. • Multitasking VM ONLY (ignore attribute for single instance VM).

MIDlet-Background-No-Pause When an application is sent to the background, pauseApp is called. Adding this attribute with the value “yes” overwrites this functionality and keeps the application running in the background.

4-10

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


4.3.7

Opening Projects in the Sprint IDE The Sprint Mobility IDE supports Sprint Wireless Toolkit 3.2 by default. It is not necessary to import the project into the IDE. It can open toolkit projects directly. Run the Sprint IDE and select File > Open Project. To choose a Sprint Wireless Toolkit 3.2 project, browse to your toolkit installation directory, go into the apps directory and select a project. FIGURE 4-6 shows a demonstration being opened as the Main Project. FIGURE 4-6

4.4

Opening a Toolkit Project from the Sprint Mobility IDE

New Demos The demos in this section are new in version 3.2.

Chapter 4

New in This Release

4-11


4.4.1

DebugApp DebugApp demonstrates how to transmit the System.out and System.err streams from a MIDlet running on a real device to the the toolkit running on a PC. For this example we use two PCs (instead of a PC and a device). We call them PC1 and PC2. ■

PC1 is running the toolkit and the emulator.

PC2 represents the real device running the MIDlet. This demo document features screenshots showing the toolkit’s COMM terminal, but there is no requirement to install the toolkit on PC2. All you really need for this demonstration 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 console preferences to match: baudrate

11520

parity

none

stopbits

1 or 2 (1.5 is not supported)

databits

8

flow control

hardware

3. On PC1, open the DebugApp demo. 4. Select the port that is connected to PC2 and press the Connect Button.

4-12

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


When the Connect button is pressed the message “Type text below using computer keyboard“ is sent to the console on PC2. The MIDlet waits for an input 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.

Chapter 4

New in This Release

4-13


6. On PC1 check the emulator to see the incoming message from the console.

4.4.2

GoSIP GoSIP is a chat application that uses SIP to set up communications using a SIP proxy server 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 successful registration attempt.

4-14

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-7

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. Enter your local machine name or IP address and choose Next, then Register. In the SIP server window, SIP messages from the emulator appear. Sippy A appears in the list of registered users. The emulator suggests you invite your friend Sippy B to talk. Don’t do it yet.

Chapter 4

New in This Release

4-15


In the second emulator, launch Sippy B. Just as before, enter the address of the SIP proxy, choose Next, then Register. The Sippy B user appears in the SIP server window. 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. You can send messages back and forth using the Send command. When you are finished, choose Bye to end the chat.

4.4.3

i18nDemo This MIDlet suite shows off the JSR 238 Mobile Internationalization API. The MIDlets String Comparator and Formatter show how to sort strings and display numbers appropriately for different locales. The third MIDlet, MicroLexicon, is a small 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 and Japanese. 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 right button to Launch the MIDLet. The String Comparator MIDlet demonstrates how strings (city names) are sorted differently depending on locale. Launch the MIDlet. Use the lower right button to view the menu. Click or Type 2 to select Sort - default, and the list is sorted alphabetically. Click or Type 3 to select Sort - slovak. It’s easy to see the difference in the cities that begin with the letter Z, with and without the mark on top. Click Exit to return to the list of MIDlets. The second MIDlet, Formatter, simply displays times and numbers formatted for different locales. Click next to view all four screens. Click Exit to return to the list of MIDlets. The final MIDlet, MicroLexicon, translates phrases from one language to another language. To select the target language from the list, use the navigation arrows to highlight Choose Language. Click SELECT to view the language drop down. Use the navigation arrows to choose a language (see FIGURE 4-8) and then click SELECT.

4-16

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-8

Choosing the Target Language

MicroLexicon displays a list of phrases. Highlight one and press the SELECT button on 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 emulator and 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 the toolkit to localize an application, choose Project > i18n Resources Manager from the KToolbar 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 at runtime.

Chapter 4

New in This Release

4-17


FIGURE 4-9

Internationalization Resources Manager

The resources themselves are stored in toolkit\apps\i18nDemo\res\global.

4.4.4

JBricks JBricks is a game that demonstrates the use of the JSR 229 Payment API. The game itself resembles Breakout or Arkanoid. In JBricks, you can buy another life or a new game level. Behind the scenes, the Payment API handles the details. To use the payment features of JBricks, use Project > Run via OTA to install JBricks into the emulator.

4-18

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


To see how JBricks uses the Payment API, choose either Buy Life or Buy Level from the game’s main menu. Next, choose whether you want to buy a single life or three lives for a reduced price. The next screen gives you a choice of payment types. FIGURE 4-10

Choosing a Payment Type

Use the navigation arrows to select the line starting with Pay by. Click the SELECT button to see the possible credit card adaptors in a drop down menu. Use the navigation arrows to select the VISA adaptor, then click SELECT. Click Update, then click Yes on the lower right to proceed. Next, you will be able to enter credit card information. Use any valid VISA number (for example, 4111411141114111) and a valid expiration date.

Chapter 4

New in This Release

4-19


FIGURE 4-11

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 specific instance of the emulator appear.

4-20

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-12

Viewing Transactions

In addition, you can view all transactions passing through the toolkit’s payment system. Choose File > Utilities from the KToolbar menu, then select Payment Console. A transaction in the console looks something like the following:

Chapter 4

New in This Release

4-21


PSP Console running, using phone number +5555555555. PSP Server running at https://localhost:-1 Received 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: null Response to 127.0.0.1 HTTP/1.1 200 OK Content-Length: 0 Pay-Response: SUCCESSFUL Pay-Timestamp: 1156282954734

4.4.5

KeyEventDemo This application contains a MIDlet that describes key events. The recognized events are Pressed, Repeated, and Released. For every action performed on a key, the screen displays the corresponding event. For example, when you press the 1 key, the screen displays 1 pressed.

4.4.6

LX260-Test-S05 This LX260 device has a full QWERTY keyboard that slides out from the side. The display must switch from portrait mode to landscape mode and back when the device 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. The regular screen shows a title bar at the top and a soft key bar at the bottom. In full screen mode the title bar is gone and items on the soft key bar occupy the minimum 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 the LX260.

4-22

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


3. Click Run. The demo launches in the portrait view. The screen text indicates the form factor value 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 the appearance of the soft keys.

â–

Select Frm/Cnvs. You see the form and a text string that wraps in the portrait view.

FIGURE 4-13 summarizes these screens. FIGURE 4-13

Screen Variations in the Portrait View (Form Factor Open)

4. In the emulator select MIDlet > External events. On the Non-Protected Properties tab, locate Form Factor and click the Closed radio button. The display switches to the landscape view. FIGURE 4-14 shows the demo screens as they appear in landscape view. Note the changed screen dimensions and line endings.

Chapter 4

New in This Release

4-23


FIGURE 4-14

4.4.7

Screen Variations in the Landscape View (Form Factor Closed)

Multitasking VM Demo This procedure uses demo projects to highlight Multitasking VM (MVM) features. Before beginning, add some MP3 or MP4 files to the database for the Multitasking VM device you are using. For example: install-dir\appdb\DeviceName\filesystem\memorycard. The Multitasking VM demos have settings that determine how they will interact with other Multitasking VM applications, as summarized in TABLE 4-2. TABLE 4-2

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

1. Open the MVMDemoBackgroundNoPause project and click Run via OTA. 2. Choose Install Application and upload the demo. Follow the prompts until the installation is complete. 3. Choose the Exit soft key or click the X in the window border to close the emulator window. 4. Repeat steps 1 through 3 for MVMDemoLaunchBackground, and MVMDemoPowerOn. Three MVM demos are now loaded in the emulator.

4-24

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


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 because MIDlet-Launch-Power-On is set to yes. 6. Press the End key, and choose Send to Background. As shown in FIGURE 4-15, MVMDemoPowerOn has a green check showing it is running in the background. FIGURE 4-15

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 has unexpectedly 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 the application, and Run via OTA. a. Install the MP4Player application. b. Select MP4Player and launch the application. Select Invoke to play. The MP4 player runs.

Chapter 4

New in This Release

4-25


c. Click End. Select Exit Application. You are returned to the AMS. Note, there’s no green check because you exited rather than sending the player to the background. 11. Launch MVMDemoLaunchBackground. A green check signifies the application is running. You don’t see anything else because MIDlet-Launch-Background is set to yes. This attribute is typically used for 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 13 continues 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.

4.4.8

ObexDemo This application shows how to transfer image files between emulator instances using the OBEX API. This demonstration shows the use of OBEX over a simulated infrared connection. Run two instances of the emulator. One listens for incoming connections, while the other attempts to send an image. In the first emulator, launch the application then choose Obex Demo, then Receive Image. The emulator explains that an OBEX connection allows other devices to talk to yours and asks, “Is it OK to make the connection?“ Choose Yes. The listener emulator displays a screen that indicates it is waiting 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 the demo 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 image and asks “Would you like to receive it?“ See FIGURE 4-16.

4-26

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-16

Listener Prompting to Accept a Connection

Choose Yes. The image you selected is transferred over the simulated infrared link and displayed on the first emulator. See FIGURE 4-17. FIGURE 4-17

4.4.9

Successfully Transferred Image

Razr2Demo 1. Open the RAZR2 Project. 2. Select the MIDP 2.0 Power Vision platform. On the Devices tab, select the MotorolaRAZR2 device.

Chapter 4

New in This Release

4-27


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, find Form Factor and select the Close radio button. A player launches on the external screen as shown in FIGURE 4-18. FIGURE 4-18

RAZR2 External Screen

Click > to play a clip. As you click buttons, the action is displayed in the title area.

4.4.10

RecordStoreDemo This application contains a MIDlet that demonstrates the use of RecordStore, as defined in the MIDP 1.0 and MIDP 2.0 APIs. The demo enables you to create new RecordStore objects. A RecordStore object can contain records. Open the Record Store project and launch the application. The Record Stores screen shows a list of Record Stores. Initially the screen will be empty. To add a Record Store, click Add new on the lower left. All you need to do is specify a record name.

4-28

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-19

Initial Screen

As shown in FIGURE 4-20, you are prompted to enter the name of the new record store. After entering the name, click the Done soft button. You can enter multiple Record Store names. FIGURE 4-20

Adding New Record Store

The Record Stores listing now shows the name of the record store you created (in this case User1). To view its properties, select the record store name, open the Menu, and select 2, Properties. As shown in FIGURE 4-21, the Properties screen shows the Record store properties.

Chapter 4

New in This Release

4-29


FIGURE 4-21

View Record Store Properties

Note that the store has zero records. Press the Back soft key to return to the list of Records. You can also change a record’s access modes. There are two modes, access permission, and write permission. By default any MIDlet has both entry access and write permission. You can limit the access so that only the creator MIDlets have access, as shown in FIGURE 4-22. FIGURE 4-22

Choose MIDlet Access Mode

Once you have created a record store you can add records to it. Select the record store, open the menu, and select 1, Open. FIGURE 4-23 shows the open record store User1. Click the Add record soft key.

4-30

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-23

Add Record Screen

You are prompted to add a record. You can add multiple records to the store. For example, in FIGURE 4-24 we added the user’s service start date, and service level agreement (SLA), and the host server.

Chapter 4

New in This Release

4-31


FIGURE 4-24

Record Listing for User1 Record Store

The Record screen menu enables you to edit or delete an existing record, or view its properties. Option 4, Back returns you to the Record Store listing. FIGURE 4-25

Record Screen with soft Menu Expanded

Note that records you enter are displayed in reverse order. You can display the properties 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 in FIGURE 4-26. Click Cancel to return to the add Record screen.

4-32

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-26

Properties for Server22 Record

In the Record screen, select User1, and select Option 2, Properties. Figure shows the Record properties. Note that there are now three records, as compared to FIGURE 4-21. FIGURE 4-27

4.4.11

Properties of Populated Record Store

SIPDemo This application is a very simple example of using SIP to communicate directly between two devices. Usually devices will use SIP with a proxy server to set up direct communications of some kind. For a more complete example involving a proxy, take a look at GoSip.

Chapter 4

New in This Release

4-33


To see how SIPDemo works, run two instances of the emulator. In the first, choose Receive message. You can use the default port, 5070, and choose Receive. The first emulator is now listening for incoming messages. In the second emulator, choose Send message. Fill in values for the recipient, port number, subject, and message, or accept the defaults, and choose Send. Your message will be displayed in the first emulator. The first emulator’s response is displayed in the second emulator.

4.4.12

SVGContactList This application uses different skins to display the same contact list information and a 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 name is marked with a special character (a > or a dot) and is displayed in a larger font. FIGURE 4-28

Contact List Shown with Skin 2

Press the select button to see more information for the highlighted name.

4-34

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-29

Contact List Details

Press select again to return to the contact list.

4.4.13

SVGDemo This suite contains MIDlets that demonstrate different ways of using the JSR 226 Scalable 2D Vector Graphics API for J2ME. This API provides ways to load manipulate, render, and play SVG content. The Scalable Vector Graphics (SVG) 1.1 specification defines a language for describing two-dimensional graphics in XML. The full specification is available at http://www.w3.org/TR/SVG11/. SVG Tiny (SVGT) is a subset of SVG that is appropriate for small devices like mobile phones. See http://www.w3.org/TR/SVGMobile/. SVG Tiny is a compact yet powerful XML format for describing rich, interactive, and animated 2D content. Graphical elements can be logically grouped and identified by the SVG markup.

Chapter 4

New in This Release

4-35


4.4.13.1

SVG Browser The SVGBrowser MIDlet displays SVG files residing in the phone file system. Before running 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 SVG file and choose the Open soft key.

4.4.13.2

Render SVG Image Loads an SVG image from a file and renders it. Looking at the demo code you can see that the image is sized on the fly to exactly fit the display area. The output is clear and sharp.

4.4.13.3

Play SVG Animation This application plays an SVG animation depicting a Halloween greeting card. Press 8 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 over time to provide this short animation. In the following code sample, the JSR 226 javax.microedition.m2g.SVGImage class is used to load the SVG resource. Then, the javax.microedition.m2g.SVGAnimator class can take all the complexity of SVG animations and provides a java.awt.Component or javax.swing.JComponent which plays the animation. The SVGAnimator class provides 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(); ... svgAnimator.play();

4-36

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


... svgAnimator.pause(); ...

svgAnimator.stop();

4.4.13.4

Create SVG Image From Scratch This demo builds an image using API calls. It creates an empty SVGImage, populates it with a graphical content, and then displays that content.

4.4.13.5

Bouncing Balls Bouncing Balls plays an SVG animation. Press 8 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.

4.4.13.6

Optimized Menu In this demo, selected icons have a yellow border. As you move to a new icon, it becomes selected and the previous icon flips to the unselected state. If you navigate off 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 rich set of functionality (graphics, animations, high-end 2D rendering) and flexibility in graphic manipulation, pre-rendering or playing. In this example, a graphic artist delivered an SVG animation defining the transition state for the menu icons, from the unselected state to the selected state. The program renders each icon's animation sequence separately into off-screen buffers (for faster rendering later on), using the JSR 226 API. With buffering, the MIDlet is able to adapt to the device display resolution (because the graphics are defined in SVG format) and still retain the speed of bitmap rendering. In addition, the MIDlet is still leveraging the SVG animation capabilities. The task of defining the look of the menu items and their animation effect (the job of the graphic artist and designer) is cleanly separated from the task of displaying the menu and starting actions based on menu selection (the job of the developer). The two can vary independently as long as both the artist and the developer observe the SVG document structure conventions.

Chapter 4

New in This Release

4-37


4.4.13.7

Picture Decorator In this demo you use the phone keys to add decorations to a photograph. The key values are: 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

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 graphic object. The highlighted object is enlarged. Press SELECT to choose the current graphic or press the arrow keys to highlight a different graphic. Press SELECT again to add the graphic to the photo. When the decoration is added you see a red + on the graphic. This means it is selected and can be moved, resized, and manipulated.

4-38

Sprint Wireless Toolkit 3.2 Quick Guide • December 2007


FIGURE 4-30

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 triangle appears. This is a cursor. Use the navigation keys to move the green triangle around the picture. When the cursor is over an object it is highlighted with a red box. Press SELECT. The red + indicates the object is selected. FIGURE 4-31

Highlighted Mustache

To remove a decoration (a property), select an object, then click the Menu soft key. Press 2 to remove a property.

Chapter 4

New in This Release

4-39


4.4.14

VirtualKeypadDemo This demo was created for the Samsung Upstage phone. The virtual keypad allows the user to enter text by choosing characters from a list using the media player interface (instead of flipping the phone over and using the keypad). The virtual keypad uses the same key assignments as the conventional keypad. In KToolbar, open the VirtualKeypadDemo project and choose the MIDP 2.0 Multitasking VM platform. Go to the Device tab, and choose the Upstage phone. Run the demo. VirtualKeypadDemo lets you enter one string, and VirtualKeypadDeluxe accepts four strings, as shown in FIGURE 4-32. FIGURE 4-32

VirtualKeypadDeluxe Spanish and English Entries

Select a text string and choose Edit from the soft menu. The Enter Text screen displays the selection options. The demo uses the media player controls as described in TABLE 4-3. TABLE 4-3

4-40

Media Player Controls for Virtual Keypad

Key

Action

Menu

Move up the list

<<

Cursor left

>

Select/Tap

>>

Cursor right

Sprint Wireless Toolkit 3.2 Quick Guide â&#x20AC;˘ December 2007


Media Player Controls for Virtual Keypad

TABLE 4-3 Key

Action

Back

Delete previous character Tap the area below > to move down the list

End

Return to launch menu without saving

The Menu soft key offers two options: (1) Done and (2) Language. Your language selection determines the characters displayed for each key group. Choose characters using the actions in TABLE 4-3 and choose Done from the menu when you are finished. FIGURE 4-33

Enter Text Screen with Spanish Option

Chapter 4

New in This Release

4-41


4-42

Sprint Wireless Toolkit 3.2 Quick Guide â&#x20AC;˘ December 2007


Index

Numerics

G

18nDemo, 4-16

GCD, 4-2 GCD file, 3-6 GCD file creator, 4-2 GoSIP, 4-14

A application descriptor, 2-9 Application Management Software (AMS), 2-10 applications, running remotely, 2-20

B

I i18nDemo, 4-16 identified_third_party protection domain, 3-4

building source code, 2-6

J C certificate importing, 3-15 certificate management, 3-13 certificates, 3-3 COMM terminal, 4-2

D DebugApp, 4-12 debugging, 2-17 with NetBeans IDE, 2-17 demonstrations source code, 1-2 deploying on a web server, 2-20 descriptor, 2-9 Developer certificate database, 3-3 development cycle full, 2-8 simple, 2-4

JAD, 2-9 creating, 2-9 MIME type, 2-20 JAR creating, 2-9 MIME type, 2-20 JBricks, 4-18 JSR 185, 3-3 JTWI protection domains, 3-4

K key management, 3-8 key pair, creating, 3-10 KeyEventDemo, 4-22 KToolbar starting, 1-1, 2-1

L LX260, 4-22

Index-1


M manufacturer protection domain, 3-4 maximum protection domain, 3-4 MIDlets signing, 3-12 MIME types, 2-20 minimum protection domain, 3-4 Multitasking VM, 4-1 MVM, 4-1

signing window, 4-6 SIP, 4-33 skins, 4-5 source code location, 2-3 Sprint certificate database, 3-3 Sprint IDE, 4-11 supported APIs, 1-4

T trusted protection domain, 3-4

O OBEX demo, 4-26 obfuscation, 2-15 installing ProGuard, 2-16 installing RetroGuard, 2-16 Open With, 2-6 open with, 2-5, 4-4 optional APIs, 1-4

U unidentified_third_party protection domain, 3-4 untrusted protection domain, 3-4

P payment API, 4-18 permissions, 3-1 preverifying, 2-7 projects, 2-1 building, 2-6 creating, 2-2 deploying on real devices, 2-12 opening in IDE, 2-13 packaging, 2-9 running, 2-7 source code, 2-3 protection domain JTWI, 3-4 protection domains, 3-1

R RecordStoreDemo, 4-28 remotely-deployed applications, 2-20 Run via OTA, 2-10, 3-3

S settings, integrity check, 4-6 signed MIDlet suites, 3-1 signing MIDlet suites, 3-5

Index-2

Sprint Wireless Toolkit 3.2 Quick Guide â&#x20AC;˘ December 2007

sfdsdfg  

sadfljsfglsdg

Read more
Read more
Similar to
Popular now
Just for you