J2ME in a nutshell: a desktop quick reference

526 Pages·2002·5.741 MB·English

by  Kim Topley

J2ME in a Nutshell

Kim Topley
Publisher: O'Reilly
Edition March 2002
ISBN: 0-596-00253-X, 478 pages

J2ME in a Nutshell provides a solid, no-nonsense reference to the 'alphabet soup' of micro
edition programming, covering the CLDC, CDC, KVM and MIDP APIs. The book also
includes tutorials for the CLDC, KVM, MIDP and MIDlets, MIDlet user interfaces,
networking and storage, and advice on programming small handhelds. Combined with
O'Reilly's classic quick reference to all the core micro-edition APIs, this is the one book that
will take you from curiosity to code with no frustrating frills in between.
Table of Contents
Preface ..................................................... 1
Contents of This Book .......................................... 1
Related Books ................................................ 3
J2ME Programming Resources Online ................................ 4
Examples Online .............................................. 5
Conventions Used in This Book .................................... 5
Request for Comments .......................................... 6
Acknowledgments ............................................. 6

I: Introduction to the Java 2 Micro Edition Platform API .................. 8

1. Introduction ................................................ 9
1.1 What Is the J2ME Platform? .................................... 9
1.2 J2ME Specifications ......................................... 14
1.3 J2ME and Other Java Platforms .................................. 14

2. The Connected Limited Device Configuration ........................ 16
2.1 The CLDC Java Virtual Machine ................................. 16
2.2 The CLDC Class Libraries ..................................... 24
2.3 KVM Debugging ........................................... 32
2.4 Advanced KVM Topics ....................................... 37

3. The Mobile Information Device Profile and MIDlets .................... 47
3.1 MIDP Overview ............................................ 47
3.2 The MIDP Java Platform ...................................... 51
3.3 MIDlets and MIDlet Suites ..................................... 51
3.4 MIDlet Execution Environment and Lifecycle ........................ 57
3.5 Developing MIDlets ......................................... 62
3.6 Delivery and Installation of MIDlets .............................. 76

4. MIDlet User Interfaces ........................................ 84
4.1 User Interface Overview ...................................... 84
4.2 The High-Level User Interface API ............................... 88

5. The Low-Level MIDlet User Interface API ........................... 139
5.1 The Canvas Class ........................................... 139
5.2 Painting and the Graphics Class .................................. 143
5.3 Graphics Attributes .......................................... 144
5.4 Drawing Lines and Arcs ....................................... 147
5.5 Translating the Graphics Origin .................................. 153
5.6 A Simple Animation MIDlet .................................... 155
5.7 The Graphics Clip ........................................... 158
5.8 Rendering Text ............................................ 161
5.9 Images .................................................. 166
5.10 Event Handling ........................................... 171
5.11 Multithreading and the User Interface ............................. 176

6. Wireless Java: Networking and Persistent Storage ..................... 179
6.1 A Networking Architecture for Small Devices ........................ 179
6.2 Sockets .................................................. 183
6.3 Datagrams ................................................ 187
6.4 HTTP Connections .......................................... 192
6.5 Persistent Storage ........................................... 207
7. The Connected Device Configuration and Its Profiles ................... 227
7.1 The CDC ................................................ 227

8. J2ME Command-Line Tools ..................................... 239
8.1 cvm: The Connected Device Configuration Virtual Machine ............... 239
8.2 kdp: The KVM Debug Proxy ................................... 244
8.3 kvm: The Kilobyte Virtual Machine ............................... 246
8.4 midp: The MID Profile Execution Environment ....................... 250
8.5 emulator: The J2ME Wireless Toolkit Emulator ....................... 254
8.6 preverify: The KVM Class Preverifier ............................. 258
8.7 MakeMIDPApp: JAD to PRC Conversion Tool ....................... 261
8.8 chMEKeyTool: Public Key Certificate Management Tool ................ 264

9. J2ME Programming Environments ................................ 267
9.1 The J2ME Wireless Toolkit .................................... 267
9.2 MIDP for PalmOS .......................................... 281
9.3 J2ME and Forte For Java ...................................... 291
9.4 Other Integrated Development Environments ......................... 296

II: API Quick Reference ......................................... 298

10. J2ME Packages and Classes .................................... 308
10.1 J2ME Packages ........................................... 308
10.2 J2SE Packages Not Present in J2ME .............................. 309
10.3 J2ME Package Contents ...................................... 310

11. java.io ................................................... 325
Package java.io ............................................... 325
ByteArrayInputStream .......................................... 325
ByteArrayOutputStream ......................................... 327
DataInput ................................................... 327
DataInputStream .............................................. 328
DataOutput .................................................. 329
DataOutputStream ............................................. 330
EOFException ............................................... 331
InputStream ................................................. 332
InputStreamReader ............................................ 333
InterruptedIOException ......................................... 334
IOException ................................................. 334
OutputStream ................................................ 335
OutputStreamWriter ............................................ 336
PrintStream ................................................. 337
Reader ..................................................... 338
UnsupportedEncodingException .................................... 339
UTFDataFormatException ....................................... 339
Writer ..................................................... 339

12. java.lang .................................................. 341
Package java.lang ............................................. 341
ArithmeticException ........................................... 342
ArrayIndexOutOfBoundsException .................................. 343
ArrayStoreException ........................................... 343
Boolean .................................................... 343
Byte ...................................................... 344
Character ................................................... 345
Class ...................................................... 346
ClassCastException ............................................ 347
ClassNotFoundException ........................................ 347
Error ...................................................... 348
Exception ................................................... 348
IllegalAccessException .......................................... 349
IllegalArgumentException ........................................ 349
IllegalMonitorStateException ...................................... 350
IllegalStateException ........................................... 350
IllegalThreadStateException ...................................... 351
IndexOutOfBoundsException ..................................... 351
InstantiationException .......................................... 352
Integer ..................................................... 352
InterruptedException ........................................... 353
Long ...................................................... 354
Math ...................................................... 355
NegativeArraySizeException ...................................... 355
NullPointerException ........................................... 356
NumberFormatException ........................................ 356
Object ..................................................... 356
OutOfMemoryError ............................................ 358
Runnable ................................................... 358
Runtime .................................................... 359
RuntimeException ............................................. 359
SecurityException ............................................. 360
Short ...................................................... 360
String ..................................................... 361
StringBuffer ................................................. 363
StringIndexOutOfBoundsException ................................. 365
System .................................................... 366
Thread ..................................................... 367
Throwable .................................................. 368
VirtualMachineError ........................................... 369

13. java.util .................................................. 370
Package java.util .............................................. 370
Calendar ................................................... 371
Date ...................................................... 373
EmptyStackException .......................................... 374
Enumeration ................................................. 374
Hashtable ................................................... 375
NoSuchElementException ........................................ 376
Random .................................................... 376
Stack ...................................................... 377
Timer ..................................................... 378
TimerTask .................................................. 379
TimeZone .................................................. 379
Vector ..................................................... 380

14. javax.microedition.io ......................................... 383
Package javax.microedition.io ..................................... 383
Connection .................................................. 384
ConnectionNotFoundException .................................... 385
Connector .................................................. 385
ContentConnection ............................................ 387
Datagram ................................................... 388
DatagramConnection ........................................... 389
HttpConnection ............................................... 391
InputConnection .............................................. 393
OutputConnection ............................................. 394
StreamConnection ............................................. 394
StreamConnectionNotifier ........................................ 395

15. javax.microedition.lcdui ....................................... 396
Package javax.microedition.lcdui ................................... 396
Alert ...................................................... 398
AlertType .................................................. 399
Canvas .................................................... 400
Choice ..................................................... 402
ChoiceGroup ................................................ 404
Command .................................................. 405
CommandListener ............................................. 407
DateField ................................................... 407
Display .................................................... 408
Displayable ................................................. 409
Font ...................................................... 410
Form ...................................................... 412
Gauge ..................................................... 413
Graphics ................................................... 414
Image ..................................................... 417
ImageItem .................................................. 418
Item ...................................................... 419
ItemStateListener ............................................. 420
List ....................................................... 421
Screen ..................................................... 422
StringItem .................................................. 423
TextBox .................................................... 424
TextField ................................................... 424
Ticker ..................................................... 427

16. javax.microedition.midlet ...................................... 428
Package javax.microedition.midlet .................................. 428
MIDlet .................................................... 428
MIDletStateChangeException ..................................... 430

17. javax.microedition.rms ........................................ 432
Package javax.microedition.rms .................................... 432
InvalidRecordIDException ....................................... 432
RecordComparator ............................................. 433
RecordEnumeration ............................................ 434
RecordFilter ................................................. 436
RecordListener ............................................... 437
RecordStore ................................................. 438
RecordStoreException .......................................... 441
RecordStoreFullException ........................................ 441
RecordStoreNotFoundException ................................... 442
RecordStoreNotOpenException .................................... 442

Class, Method, and Field Index .................................... 443
A ........................................................ 443
B ........................................................ 445
C ........................................................ 447
D ........................................................ 451
E ........................................................ 455
F ........................................................ 458
G ........................................................ 460
H ........................................................ 471
I ......................................................... 477
J ......................................................... 483
K ........................................................ 483
L ........................................................ 485
M ........................................................ 487
N ........................................................ 490
O ........................................................ 492
P ........................................................ 494
R ........................................................ 497
S ........................................................ 502
T ........................................................ 512
U ........................................................ 515
V ........................................................ 516
W ........................................................ 516
Y ........................................................ 518

Colophon .................................................... 519
J2ME in a Nutshell
Preface
This book is a desktop quick reference for the Java 2 Micro Edition (J2ME ). It is
intended for Java programmers writing applications for devices with limited memory
resources and processor power, such as cell phones, Personal Data Assistants (PDAs), and
set-top boxes. The first part of this book provides a fast-paced introduction to the two
different configurations that make up the J2ME platform -- the Connected Limited Device
Configuration (CLDC) and the Connected Device Configuration (CDC), along with
the profiles that are based on them, such as the Mobile Information Device Profile (MIDP),
which provides the APIs for programming cell phones and similar devices. These chapters are
followed by a quick-reference section that details each class of the CLDC and MIDP APIs,
along with tables that show which Java packages and classes are available in each
configuration and profile.
This book is intended to be used in conjunction with the best-selling Java in a Nutshell, by
David Flanagan, and Java Enterprise in a Nutshell, by Jim Farley, David Flanagan, and
William Crawford (both published by O'Reilly). Java in a Nutshell introduces the Java
programming language itself and provides an API quick reference for the core packages and
classes of the Java 2 Standard Edition (J2SE) platform. Java Enterprise in a Nutshell does
the same for the APIs in the Java 2 Enterprise Edition (J2EE). The CDC and its profiles are
actually large subsets of the J2SE API, and, therefore, this book does not replicate their API
quick reference material, which you can find in Java in a Nutshell and, in the case of the RMI
profile, in Java Enterprise in a Nutshell.
Contents of This Book
The first nine chapters of this book describe the J2ME platform, the command-line tools that
are provided with Sun's J2ME reference implementations, and some of the visual
development environments that you can use when writing J2ME applications:
Chapter 1
This chapter introduces the J2ME platform and the concepts of configuration and
profile, and it compares J2ME to a number of other Java platforms for small devices.
Chapter 2
This chapter covers the Connected Limited Device Configuration (CLDC), which is
the basic building block for the J2ME profiles for wireless devices and PDAs. It
begins by outlining the differences between CLDC and the core libraries of the J2SE
platform. Then it takes a close look at KVM, the small-footprint virtual machine that
is used in Sun's reference implementation of CLDC.
Chapter 3
This chapter introduces MIDlets, the wireless Java equivalent of applets. MIDlets are
part of the Mobile Information Device Profile (MIDP), which is the subject of this
and the following three chapters. This chapter looks at the lifecycle of a MIDlet
and illustrates it with a simple example. It concludes with a discussion of the facilities
1
J2ME in a Nutshell
that a typical mobile device would provide to allow the user to download, install,
manage, and remove MIDlets.
Chapter 4
The devices that MIDlets run on range from cell phones with a small two-color
display and room for only a few lines of text to PDAs with larger, multicolor screens.
In order to isolate MIDlets from the specifics of the devices on which they are
running, MIDP includes a high-level API that provides simple input and output
controls and the ability to combine these controls to create form-like screens. This
chapter takes a detailed look at the high-level API and provides sample MIDlets that
can be run on cell phones or PDAs.
Chapter 5
This chapter looks at an alternative user interface API that provides lower-level access
to a mobile device's screen and input devices. This chapter looks at the details of this
API and shows how to avoid writing code that may not be portable between devices
with different user interface capabilities.
Chapter 6
Networking is a key feature of a mobile device. The first part of this chapter looks at
the Generic Connection Framework (GCF), which provides the basis for access to
various networking APIs, including optional protocols (such as sockets and
datagrams) and HTTP, which all MIDP implementations are required to support. A
simple example that involves fetching information from a web site is used to illustrate
the use of HTTP on a mobile device and shows how to avoid problems that arise when
working in an environment with limited memory. The second part of this chapter
looks at the facilities available for storing information on a mobile device and
illustrates them by extending the HTTP example to include persistence of information
retrieved from the web site.
Chapter 7
This chapter looks at the Connected Device Configuration (CDC) and its profiles,
which are designed for use on devices that have more than 2 MB of memory to devote
to the Java platform. It begins by looking at Sun's reference implementation of CDC
and the CVM, the virtual machine for CDC devices, then briefly covers the content of
the CDC-based profiles that are currently defined.
Chapter 8
This chapter contains reference material for the command-line tools that are provided
with the CLDC and CDC reference implementations and the MIDP for the PalmOS
product.

2
J2ME in a Nutshell
Chapter 9
This chapter covers the J2ME wireless toolkit, a development environment provided
by Sun that allows you to create and test MIDlets using a cell-phone emulator that can
be customized to resemble a number of different cell phones and PalmOS-based
handhelds. It also looks at how to use the wireless toolkit in conjunction with Sun's
Forte for Java IDE to create a complete development environment, and it investigates
a number of alternative third-party products that provide similar functionality.
These first nine chapters provide a tutorial introduction to J2ME, with particular emphasis on
wireless devices, which are currently the most popular application of J2ME technology.
The core of this book, however, is the API quick reference, Chapter 10 through Class,
Method, and Field Index, which is a succinct but detailed API reference formatted for
optimum ease of use. Please be sure to read "How To Use This Quick Reference," which
appears at the beginning of the reference section; it explains how to get the most out of this
section.
Related Books
O'Reilly & Associates, Inc., publishes an entire series of books on Java programming. These
books include Java in a Nutshell and Java Enterprise in a Nutshell, which, as mentioned
earlier, are companions to this book.
You can find a complete list of Java books from O'Reilly at http://java.oreilly.com/. Books
that are of particular interest to J2ME programmers include:
Java in a Nutshell, by David Flanagan
A Java language tutorial and complete API reference for the core Java classes. This
book is of particular interest if you intend to work with the CDC-based profiles, since
the APIs very closely match those of J2SE.
Java Enterprise in a Nutshell, by Jim Farley and William Crawford, with David
Flanagan
A tutorial and API reference for Java's enterprise APIs, including Remote Method
Invocation (RMI). This book will be of interest to you if you intend to use the RMI
profile.
Java Network Programming, by Elliotte Rusty Harold
A book that describes the J2SE networking APIs.
Java I/O, by Elliotte Rusty Harold
A book that describes the input/output architecture of the Java platform, a proper
understanding of which is essential if you intend to use the networking and persistent
storage features of MIDP.

3