J2ME in a nutshell

www.it-ebooks.info 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 www.it-ebooks.info Table of Contents Preface Contents of This Book Related Books J2ME Programming Resources Online Examples Online Conventions Used in This Book Request for Comments Acknowledgments 1 5 6 I: Introduction to the Java Micro Edition Platform API Introduction 1.1 What Is the J2ME Platform? 1.2 J2ME Specifications 1.3 J2ME and Other Java Platforms 9 14 14 The Connected Limited Device Configuration 2.1 The CLDC Java Virtual Machine 2.2 The CLDC Class Libraries 2.3 KVM Debugging 2.4 Advanced KVM Topics 16 16 24 32 37 The Mobile Information Device Profile and MIDlets 3.1 MIDP Overview 3.2 The MIDP Java Platform 3.3 MIDlets and MIDlet Suites 3.4 MIDlet Execution Environment and Lifecycle 3.5 Developing MIDlets 3.6 Delivery and Installation of MIDlets 47 47 51 51 57 62 76 MIDlet User Interfaces 4.1 User Interface Overview 4.2 The High-Level User Interface API 84 84 88 The Low-Level MIDlet User Interface API 5.1 The Canvas Class 5.2 Painting and the Graphics Class 5.3 Graphics Attributes 5.4 Drawing Lines and Arcs 5.5 Translating the Graphics Origin 5.6 A Simple Animation MIDlet 5.7 The Graphics Clip 5.8 Rendering Text 5.9 Images 5.10 Event Handling 5.11 Multithreading and the User Interface 139 139 143 144 147 153 155 158 161 166 171 176 Wireless Java: Networking and Persistent Storage 6.1 A Networking Architecture for Small Devices 6.2 Sockets 6.3 Datagrams 6.4 HTTP Connections 6.5 Persistent Storage 179 179 183 187 192 207 www.it-ebooks.info The Connected Device Configuration and Its Profiles 227 7.1 The CDC 227 J2ME Command-Line Tools 8.1 cvm: The Connected Device Configuration Virtual Machine 8.2 kdp: The KVM Debug Proxy 8.3 kvm: The Kilobyte Virtual Machine 8.4 midp: The MID Profile Execution Environment 8.5 emulator: The J2ME Wireless Toolkit Emulator 8.6 preverify: The KVM Class Preverifier 8.7 MakeMIDPApp: JAD to PRC Conversion Tool 8.8 chMEKeyTool: Public Key Certificate Management Tool 239 239 244 246 250 254 258 261 264 J2ME Programming Environments 9.1 The J2ME Wireless Toolkit 9.2 MIDP for PalmOS 9.3 J2ME and Forte For Java 9.4 Other Integrated Development Environments 267 267 281 291 296 II: API Quick Reference 298 10 J2ME Packages and Classes 10.1 J2ME Packages 10.2 J2SE Packages Not Present in J2ME 10.3 J2ME Package Contents 308 308 309 310 11 java.io Package java.io ByteArrayInputStream ByteArrayOutputStream DataInput DataInputStream DataOutput DataOutputStream EOFException InputStream InputStreamReader InterruptedIOException IOException OutputStream OutputStreamWriter PrintStream Reader UnsupportedEncodingException UTFDataFormatException Writer 325 325 325 327 327 328 329 330 331 332 333 334 334 335 336 337 338 339 339 339 12 java.lang Package java.lang ArithmeticException ArrayIndexOutOfBoundsException ArrayStoreException Boolean Byte Character Class ClassCastException ClassNotFoundException 341 341 342 343 343 343 344 345 346 347 347 www.it-ebooks.info Error Exception IllegalAccessException IllegalArgumentException IllegalMonitorStateException IllegalStateException IllegalThreadStateException IndexOutOfBoundsException InstantiationException Integer InterruptedException Long Math NegativeArraySizeException NullPointerException NumberFormatException Object OutOfMemoryError Runnable Runtime RuntimeException SecurityException Short String StringBuffer StringIndexOutOfBoundsException System Thread Throwable VirtualMachineError 348 348 349 349 350 350 351 351 352 352 353 354 355 355 356 356 356 358 358 359 359 360 360 361 363 365 366 367 368 369 13 java.util Package java.util Calendar Date EmptyStackException Enumeration Hashtable NoSuchElementException Random Stack Timer TimerTask TimeZone Vector 370 370 371 373 374 374 375 376 376 377 378 379 379 380 14 javax.microedition.io Package javax.microedition.io Connection ConnectionNotFoundException Connector ContentConnection Datagram DatagramConnection HttpConnection InputConnection OutputConnection StreamConnection 383 383 384 385 385 387 388 389 391 393 394 394 www.it-ebooks.info StreamConnectionNotifier 395 15 javax.microedition.lcdui Package javax.microedition.lcdui Alert AlertType Canvas Choice ChoiceGroup Command CommandListener DateField Display Displayable Font Form Gauge Graphics Image ImageItem Item ItemStateListener List Screen StringItem TextBox TextField Ticker 396 396 398 399 400 402 404 405 407 407 408 409 410 412 413 414 417 418 419 420 421 422 423 424 424 427 16 javax.microedition.midlet Package javax.microedition.midlet MIDlet MIDletStateChangeException 428 428 428 430 17 javax.microedition.rms Package javax.microedition.rms InvalidRecordIDException RecordComparator RecordEnumeration RecordFilter RecordListener RecordStore RecordStoreException RecordStoreFullException RecordStoreNotFoundException RecordStoreNotOpenException 432 432 432 433 434 436 437 438 441 441 442 442 Class, Method, and Field Index A B C D E F G H I J 443 443 445 447 451 455 458 460 471 477 483 www.it-ebooks.info K L M N O P R S T U V W Y 483 485 487 490 492 494 497 502 512 515 516 516 518 Colophon 519 www.it-ebooks.info J2ME in a Nutshell Preface This book is a desktop quick reference for the Java 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 Standard Edition (J2SE) platform Java Enterprise in a Nutshell does the same for the APIs in the Java 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 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 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 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 www.it-ebooks.info J2ME in a Nutshell that a typical mobile device would provide to allow the user to download, install, manage, and remove MIDlets Chapter 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 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 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 This chapter looks at the Connected Device Configuration (CDC) and its profiles, which are designed for use on devices that have more than 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 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 www.it-ebooks.info J2ME in a Nutshell Chapter 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 www.it-ebooks.info J2ME in a Nutshell setConstraints(): TextBox, TextField setCurrent(): Display setData(): Datagram setDate(): DateField setElementAt(): Vector setError(): PrintStream setFont(): Graphics setGrayScale(): Graphics setImage(): Alert, ImageItem 505 www.it-ebooks.info J2ME in a Nutshell setInputMode(): DateField setItemStateListener(): Form setLabel(): ChoiceGroup, DateField, Gauge, ImageItem, Item, StringItem, TextField setLayout(): ImageItem setLength(): Datagram, StringBuffer setMaxSize(): TextBox, TextField setMaxValue(): Gauge setPriority(): Thread setRecord(): RecordStore 506 www.it-ebooks.info J2ME in a Nutshell setRequestMethod(): HttpConnection setRequestProperty(): HttpConnection setSeed(): Random setSelectedFlags(): Choice, ChoiceGroup, List setSelectedGloss(): Choice, ChoiceGroup, List setSize(): Vector setString(): Alert, TextBox, TextField, Ticker setStrokeStyle(): Graphics setText(): StringItem 507 www.it-ebooks.info J2ME in a Nutshell setTicker(): Screen setTime(): Calendar, Date setTimeInMillis(): Calendar setTimeout(): Alert setTimeZone(): Calendar setTitle(): Screen setType(): Alert setValue(): Gauge Short: java.lang 508 www.it-ebooks.info J2ME in a Nutshell shortValue(): Integer, Short showNotify(): Canvas size(): ByteArrayOutputStream, Choice, ChoiceGroup, Form, Hashtable, List, TextBox, TextField, Vector SIZE_LARGE: Font SIZE_MEDIUM: Font SIZE_SMALL: Font skip(): ByteArrayInputStream, DataInputStream, InputStream, InputStreamReader, Reader skipBytes(): DataInput, DataInputStream 509 www.it-ebooks.info J2ME in a Nutshell sleep(): Thread SOLID: Graphics Stack: java.util start(): Thread startApp(): MIDlet startsWith(): String STOP: Command StreamConnection: javax.microedition.io StreamConnectionNotifier: javax.microedition.io 510 www.it-ebooks.info J2ME in a Nutshell String: java.lang StringBuffer: java.lang StringGlossOutOfBoundsException: java.lang StringItem: javax.microedition.lcdui stringWidth(): Font STYLE_BOLD: Font STYLE_ITALIC: Font STYLE_PLAIN: Font STYLE_UNDERLINED: Font 511 www.it-ebooks.info J2ME in a Nutshell substring(): String substringWidth(): Font SUNDAY: Calendar System: java.lang T TextBox: javax.microedition.lcdui TextField: javax.microedition.lcdui Thread: java.lang Throwable: java.lang 512 www.it-ebooks.info J2ME in a Nutshell THURSDAY: Calendar Ticker: javax.microedition.lcdui TIME: DateField Timer: java.util TimerTask: java.util TimeZone: java.util toBinaryString(): Integer toByteArray(): ByteArrayOutputStream toCharArray(): String 513 www.it-ebooks.info J2ME in a Nutshell toHexString(): Integer toLowerCase(): Character, String toOctalString(): Integer TOP: Graphics toString(): Boolean, Byte, ByteArrayOutputStream, Character, Class, Hashtable, Integer, Long, Object, Short, String, StringBuffer, Thread, Throwable, Vector totalMemory(): Runtime toUpperCase(): Character, String translate(): Graphics 514 www.it-ebooks.info J2ME in a Nutshell trim(): String trimToSize(): Vector TUESDAY: Calendar U UnsupportedEncodingException: java.io UP: Canvas URL: TextField useDaylightTime(): TimeZone UTFDataFormatException: java.io 515 www.it-ebooks.info J2ME in a Nutshell V valueOf(): Integer, String VCENTER: Graphics Vector: java.util VirtualMachineError: java.lang W wait(): Object WARNING: AlertType WEDNESDAY: Calendar WRITE: Connector 516 www.it-ebooks.info J2ME in a Nutshell write(): ByteArrayOutputStream, DataOutput, OutputStreamWriter, PrintStream, Writer DataOutputStream, OutputStream, writeBoolean(): DataOutput, DataOutputStream writeByte(): DataOutput, DataOutputStream writeChar(): DataOutput, DataOutputStream writeChars(): DataOutput, DataOutputStream writeInt(): DataOutput, DataOutputStream writeLong(): DataOutput, DataOutputStream Writer: java.io 517 www.it-ebooks.info J2ME in a Nutshell writeShort(): DataOutput, DataOutputStream writeUTF(): DataOutput, DataOutputStream Y YEAR: Calendar yield(): Thread 518 www.it-ebooks.info J2ME in a Nutshell Colophon Our look is the result of reader comments, our own experimentation, and feedback from distribution channels Distinctive covers complement our distinctive approach to technical topics, breathing personality and life into potentially dry subjects The animal on the cover of J2ME in a Nutshell is a galago Galagos are prosimian primates, "pre-monkeys" that existed before monkeys, apes, and humans evolved These small (10-35 cm long, not including their tail, which ranges from 20 to nearly 50 cm long), nocturnal animals live in Africa, spending much of their time in trees and eating mostly bugs, fruit, and the occasional small bird Their big ears, featured prominently on the cover, can be bent almost completely back, either one at a time or both together, something the galagos apparently like to quite frequently Leanne Soylemez was the production editor and copyeditor for J2ME in a Nutshell Mary Anne Weeks Mayo was the proofreader, and Matt Hutchinson and Jane Ellin provided quality control John Bickelhaupt wrote the index Ellie Volckhausen designed the cover of this book, based on a series design by Edie Freedman The cover image is from Animal Creation Emma Colby produced the cover layout with QuarkXPress 4.1 using Adobe's ITC Garamond font Melanie Wang and David Futato designed the interior layout based on a series design by Nancy Priest Neil Walls cleaned up the original FrameMaker files for Part I The print version of Part II was generated from XML using a basic macro set developed by Steve Talbott from the GNU troff -gs macros and adapted to the book design by Lenny Muellner; Norm Walsh wrote the Perl filter that translates XML source into those macros The text and heading fonts are ITC Garamond Light and Garamond Book The illustrations that appear in the book were produced by Robert Romano and Jessamyn Read using Macromedia FreeHand and Adobe Photoshop This colophon was written by Leanne Soylemez 519 www.it-ebooks.info ... 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... 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... briefly summarize these alternative platforms and compare them to J2ME 14 www.it-ebooks.info J2ME in a Nutshell 1.3.1 JavaCard JavaCard is a platform aimed at smart card technology Smart cards are the