Sun Microsystems J2ME User manual

Sun Microsystems, Inc.
4150 Network Circle
Santa Clara, California 95054
U.S.A.
1-800-555-9SUN or 1-650-960-1300
User’s Guide
J2ME Wireless Toolkit
2.2
October 2004

Please
Recycle
Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.
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.
This distribution may include materials developed by third parties.
Sun, Sun Microsystems, the Sun logo, Java, J2ME 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 and the PostScript logo are trademarks or registered trademarks
of Adobe Systems, Incorporated.
Products covered by and information contained in this service manual are controlled by U.S. Export Control laws and may be subject
to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end
users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities
identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is
strictly prohibited.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE
LEGALLY INVALID.
Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés.
Cette distribution peut comprendre des composants développés par des tierces parties.
Sun, Sun Microsystems, le logoSun, Java, J2ME 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. et le logo PostScript sont des marques de fabrique ou
des marques déposées de Adobe Systems, Incorporated.
Les produits qui font l'objet de ce manuel d'entretien et les informations qu'il contient sont regis par la legislation americaine en
matiere de controle des exportations et peuvent etre soumis au droit d'autres pays dans le domaine des exportations et importations.
Les utilisations finales, ou utilisateurs finaux, pour des armes nucleaires, des missiles, des armes biologiques et chimiques ou du
nucleaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou reexportations vers des pays sous
embargo des Etats-Unis, ou vers des entites figurant sur les listes d'exclusion d'exportation americaines, y compris, mais de maniere
non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une facon directe ou indirecte, aux exportations
des produits ou des services qui sont regi par la legislation americaine en matiere de controle des exportations et la liste de
ressortissants specifiquement designes, sont rigoureusement interdites.
LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES
EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y
COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE
UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.

Contents iii
Contents
Preface ix
1. Introduction 1
1.1 Quick Start 1
1.2 The Tools in the Toolkit 2
1.3 Toolkit Features 3
1.4 Supported Technology 3
2. Developing MIDlet Suites 5
2.1 About Projects 5
2.2 The Simple Development Cycle 7
2.2.1 Edit Source Code 7
2.2.2 Build 8
2.2.3 Run 9
2.3 The Full Development Cycle 11
2.3.1 Package 11
2.3.2 Install 12
2.3.3 Run 14
2.4 Using an Obfuscator 15
2.5 Using a Debugger 17
2.6 Deploying Applications on a Web Server 17
3. Working With Projects 19

iv J2ME Wireless Toolkit User’s Guide • October 2004
3.1 Selecting APIs 19
3.2 Changing MIDlet Suite Attributes 21
3.3 Manipulating MIDlets 23
3.4 Using the Push Registry 24
3.5 Project Directory Structure 25
3.6 Using Third-Party Libraries 25
3.6.1 Third-Party Libraries for One Project 26
3.6.2 Third-Party Libraries for All Projects 26
3.7 Configuring KToolbar 26
3.7.1 Setting the Application Directory 27
3.7.2 Setting the javac Encoding Property 27
3.7.3 Working with Revision Control Systems 27
4. Using the Emulator 29
4.1 Emulator Skins 29
4.2 Using the Emulator 30
4.3 Setting Emulator Preferences 32
4.3.1 Network Proxies 32
4.3.2 Heap Size 33
4.3.3 Storage and Cleaning 33
4.3.4 Adjusting Emulator Performance 34
4.4 Pausing and Resuming 35
4.5 Running the Emulator Solo 36
4.6 Using Third Party Emulators 36
5. Monitoring Applications 39
5.1 Using the Profiler 39
5.1.1 The Call Graph 41
5.1.2 Execution Time and Number of Calls 41
5.1.3 Saving and Loading Profiler Information 41
5.2 Using the Memory Monitor 42
5.2.1 Saving and Loading Memory Monitor Information 44
5.3 Using the Network Monitor 44

Contents v
5.3.1 Filtering Messages 45
5.3.2 Sorting Messages 46
5.3.3 Saving and Loading Network Monitor Information 46
5.3.4 Clearing the Message Tree 47
6. Security and MIDlet Signing 49
6.1 Permissions 49
6.2 Protection Domains 50
6.3 Signing a MIDlet Suite 51
6.4 Managing Keys 52
6.4.1 Creating a New Key Pair 52
6.4.2 Getting Real Keys 53
6.4.3 Importing an Existing Key Pair 54
6.4.4 Removing a Key Pair 54
6.5 Managing Certificates 54
6.5.1 Importing Certificates 55
6.5.2 Removing Certificates 56
7. Using the Wireless Messaging API 57
7.1 Setting Emulator Phone Numbers 57
7.2 Simulating an Unreliable Network 58
7.3 Sending Messages With the WMA Console 59
7.3.1 Sending a Text SMS Message 59
7.3.2 Sending a Binary SMS Message 60
7.3.3 Sending Text or Binary CBS Messages 61
7.3.4 Sending MMS Messages 62
7.4 Receiving Messages in the WMA Console 63
7.5 Using the Network Monitor with WMA 64
8. Using the Mobile Media API 65
8.1 Supported Formats and Protocols 65
8.2 Using MediaControlSkin 66
8.3 Media Capture 66

vi J2ME Wireless Toolkit User’s Guide • October 2004
8.4 Well-Behaved MIDlets 66
9. Working With Mobile 3D Graphics 67
9.1 JSR 184 Overview 67
9.2 Immediate Mode 67
9.3 Retained Mode 68
9.4 Trading Quality for Speed 68
9.5 Creating Mobile 3D Graphics Content 69
10. Using the PIM and FileConnection APIs 71
10.1 The FileConnection API 71
10.2 The PIM API 72
11. Using the Bluetooth and OBEX APIs 73
11.1 Bluetooth Simulation Environment 73
11.2 OBEX Over Infrared 73
11.3 Setting OBEX and Bluetooth Preferences 74
11.3.1 OBEX Preferences 74
11.3.2 Bluetooth Discovery Timeout 75
11.3.3 Bluetooth System Properties 75
11.3.4 Bluetooth BCC Properties 75
12. Using Web Services 77
A. Application Demonstrations 79
A.1 Overview 79
A.2 General Instructions 81
A.3 BluetoothDemo 82
A.4 Demo3D 83
A.4.1 Life3D 83
A.4.2 PogoRoo 84
A.4.3 retainedmode 85
A.5 JSR172Demo 86
A.6 mmademo 86

Contents vii
A.6.1 Simple Tones 87
A.6.2 Simple Player 87
A.6.3 PausingAudioTest 89
A.6.4 Video 89
A.6.5 Attributes for mmademo 90
A.7 ObexDemo 90
A.8 PDAPDemo 92
A.8.1 Browsing Files 92
A.8.2 The PIM API 94
A.9 WMADemo 97
B. Command Line Reference 103
B.1 Prerequisites 103
B.2 The Development Cycle 103
B.2.1 Build 103
B.2.2 Package 104
B.2.3 Run 106
B.2.4 Debugging 107
B.3 Launching Toolkit GUI Components 108
B.4 Setting Emulator Preferences 108
B.5 Using Security Features 110
B.5.1 Changing the Emulator’s Default Protection Domain 110
B.5.2 Signing MIDlet Suites 111
B.5.3 Managing Certificates 112
B.6 Using the Stub Generator 113
B.6.1 Options 113
B.6.1.1 Example 114
C. Internationalization 115
C.1 Locale Setting 115
C.2 Emulated Locale 116
C.3 Character Encodings 116
C.3.1 Java Compiler Encoding Setting 117

viii J2ME Wireless Toolkit User’s Guide • October 2004
C.4 Font Support in the Default Emulator 117
Index 119

Preface ix
Preface
This document describes how to work with the J2ME Wireless Toolkit.
Who Should Use This Book
This guide is intended for developers creating Mobile Information Device Profile
(MIDP) applications with the J2ME Wireless 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 book is not a tutorial in MIDP programming, nor is it a tutorial in
programming any of the additional APIs that are supported by the toolkit. 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:

xJ2ME Wireless Toolkit User’s Guide • October 2004
http://developers.sun.com/techtopics/mobility/
How This Book Is Organized
This guide contains the following chapters and appendixes:
Chapter 1 introduces the J2ME Wireless Toolkit and the development features it
provides.
Chapter 2 describes the development processes for creating and running
MIDlets.
Chapter 3 explains how to work with projects in KToolbar. You’ll learn how to
adjust project properties, manipulate MIDlets, work with the push registry, and
understand the project directory structure.
Chapter 4 describes the emulator and explains how to adjust its options and take
advantage of its many features.
Chapter 5 shows how you can examine the performance of your application
using the method profiler, memory monitor, and network monitor.
Chapter 6 describes how to sign MIDlet suites and manage keys and certificates.
Topic Title
Customizing the J2ME Wireless Toolkit J2ME Wireless Toolkit Basic Customization Guide
Release Notes J2ME Wireless Toolkit Release Notes
MIDP 1.0 - JSR 37 Mobile Information Device Profile for the J2ME™
Platform
MIDP 2.0 - JSR 118 Mobile Information Device Profile 2.0
CLDC 1.0 - JSR 30 J2ME Connected Limited Device Configuration
CLDC 1.1 - JSR 139 J2ME Connected Limited Device Configuration
WMA 2.0 - JSR 205 Wireless Messaging API (WMA)
MMAPI - JSR 135 Mobile Media API
JTWI - JSR 185 Java Technology for the Wireless Industry
J2ME Web Services JSR 172 J2ME Web Services Specification
PDAP Optional Packages - JSR 75 PDA Optional Packages for the J2ME Platform
Bluetooth and OBEX - JSR 82 Java APIs for Bluetooth
Mobile 3D Graphics - JSR 184 Mobile 3D Graphics API for J2ME

Preface xi
Chapter 7 details support for running and testing wireless messaging
applications.
Chapter 8 explains how the J2ME Wireless Toolkit supports the Mobile Media
API.
Chapter 9 contains information about developing 3D graphics content.
Chapter 10 describes how the toolkit implements access to local files and
personal information like contacts and calendar appointments.
Chapter 11 covers the toolkit’s Bluetooth and OBEX simulation environment.
Chapter 12 shows how to use the web services stub generator.
Chapter 12 shows how to use the web services stub generator.
Appendix A describes the application demonstrations that are included in the
J2ME Wireless Toolkit.
Appendix B explains how to use the functionality of the J2ME Wireless Toolkit
from the command line.
Appendix C describes internationalization features in the J2ME Wireless Toolkit.

xii J2ME Wireless Toolkit User’s Guide • October 2004
Typographic Conventions
Accessing 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:
[email protected]
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
Command-line variable; replace
with a real name or value
Read Chapter 6 in the User’s Guide.
These are called class options.
You must be superuser to do this.
To delete a file, type rm filename.
{AaBbCc.dir} Variable file names and
directories.
In the book, {toolkit} always refers to
the installation directory of the J2ME
Wireless Toolkit.

1
CHAPTER 1
Introduction
This book describes how to use the J2ME Wireless Toolkit.
The J2ME Wireless 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.0, the J2ME Wireless Toolkit also
supports a handful of 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 J2ME Wireless Toolkit.
To run the demonstrations, start KToolbar. On Windows you’ll do this by choosing
Start > Programs > J2ME Wireless Toolkit 2.2 > KToolbar.1You’ll see a window
like this:
1. Depending on how Windows is configured, you might need to choose Start > All Programs instead of Start
> Programs.

2J2ME Wireless Toolkit User’s Guide • October 2004
FIGURE 1 The KToolbar window
Next, click on the Open Project... button to open a demonstration application.
You'll see a list of all the available applications. Pick one of them and click on the
Open Project button in the dialog.
Once the application is open, all you need to do is press the Run button. The
emulator will pop up running the example application.
Most demonstrations are self-explanatory, but some have additional instructions.
See Appendix A, “Application Demonstrations,” 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 J2ME Wireless Toolkit has three main components:
■KToolbar automates many of the tasks involved in creating MIDP applications.
■The emulator is a simulated mobile phone. It is useful for testing MIDP
applications.
■A collection of utilities provides other useful functionality, including a text
messaging console and cryptographic utilities.

Chapter 1 Introduction 3
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 J2ME Wireless 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.
1.4 Supported Technology
The J2ME Wireless Toolkit supports many standard Application Programming
Interfaces (APIs) defined through the Java Community Process (JCP). TABLE 1
shows the APIs and includes links to the specifications.
TABLE 1 Supported JCP APIs in the J2ME Wireless Toolkit
JSR
API Name URL
JSR 139
CLDC 1.1
Connected Limited Device Configuration
http://jcp.org/en/jsr/detail?id=139
JSR 118
MIDP 2.0
Mobile Information Device Profile
http://jcp.org/en/jsr/detail?id=118
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

4J2ME Wireless Toolkit User’s Guide • October 2004
JSR 135
MMAPI 1.1
Mobile Media API
http://jcp.org/en/jsr/detail?id=135
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 172 J2ME Web Services Specification
http://jcp.org/en/jsr/detail?id=172
JSR 184
3D Graphics
Mobile 3D Graphics API for J2ME
http://jcp.org/en/jsr/detail?id=184
TABLE 1 Supported JCP APIs in the J2ME Wireless Toolkit
JSR
API Name URL

5
CHAPTER 2
Developing MIDlet Suites
This chapter describes how you can use the J2ME Wireless Toolkit to create
applications. It begins with a description of toolkit projects, then works through the
development process.
There are two basic development cycles you are likely to follow in creating MIDlet
suite applications. The first is quicker and simpler; you will probably 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 you’ll read about how to use the J2ME Wireless
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 J2ME Wireless 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
will be used to build a MIDlet suite, including Java source files, resource files, and
the MIDlet descriptor.
The J2ME Wireless Toolkit works on one project at a time. You can create a new
project or open an existing project.
In this chapter you will 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 Windows, choose Start > Programs
> J2ME Wireless Toolkit 2.2 > KToolbar.2You’ll see the KToolbar window.
2. Depending on how Windows is configured, you might need to choose Start > All Programs instead of Start
> Programs.

6J2ME Wireless Toolkit User’s Guide • October 2004
FIGURE 2 The KToolbar window
Click on New Project... The toolkit will ask you for the name of the project and the
name of the MIDlet class you will write. Fill in the names and click Create Project.
FIGURE 3 Creating a new project
The project options automatically pop up, allowing you to set up the build
environment for the project. The default options are fine for this example; just click
on OK to dismiss the window. In the KToolbar console, you’ll see some messages
telling you exactly where to store the source code and resource files for this project.

Chapter 2 Developing MIDlet Suites 7
FIGURE 4 File locations in the console
2.2 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
will be used by your application.
2. Build. The J2ME Wireless 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 J2ME Wireless
Toolkit.
2.2.1 Edit Source Code
Editing source code is the only step in which the J2ME Wireless Toolkit is no help
at all. You will need to use the text editor of your choice to create and edit source
code files.

8J2ME Wireless Toolkit User’s Guide • October 2004
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 will be {toolkit}\apps\Tiny\src\TinyMIDlet.java where {toolkit} is the
installation directory of the toolkit. The contents of the file are 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.
2.2.2 Build
The next step is to build your source code. The toolkit makes this part very easy.
In the KToolbar window, click on the Build button. Assuming you saved your
source file in the right place, the toolkit will find it and compile 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.