Java 2 Micro Edition: Professional Developer's Guide

BusinessCulinaryArchitecture ComputerGeneral Interest ChildrenLife SciencesBiography AccountingFinanceMathematics Histor...

Author: Eric Giguere

80 downloads 1643 Views 2MB Size Report

This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Report copyright / DMCA form

DOWNLOAD PDF

BusinessCulinaryArchitecture ComputerGeneral Interest ChildrenLife SciencesBiography AccountingFinanceMathematics HistorySelf-ImprovementHealth EngineeringGraphic Design A p p l i e d S c i e n c e s Psychology Interior DesignBiologyChemistry

WILEYe BOOK WILEY JOSSEY-BASS PFEIFFER J.K.LASSER CAPSTONE WILEY-LISS WILEY-VCH WILEY-INTERSCIENCE

67957_Wiley_Giguere_FM

10/17/2000 4:44 PM

Page

i

Professional Developer’s Guide

Java 2 

Micro Edition Eric Giguère

Wiley Computer Publishing

John Wiley & Sons, Inc. N EW YOR K • CH ICH ESTER • WEI N H EI M • B R ISBAN E • SI NGAPOR E • TORONTO


10/17/2000 4:44 PM

Page

ii

Publisher: Robert Ipsen Editor: Carol Long Managing Editor: John Atkins Associate New Media Editor: Brian Snapp Text Design & Composition: D&G Limited, LLC

Designations used by companies to distinguish their products are often claimed as trademarks. In all instances where John Wiley & Sons, Inc., is aware of a claim, the product names appear in initial capital or ALL CAPITAL LETTERS. Readers, however, should contact the appropriate companies for more complete information regarding trademarks and registration.

This book is printed on acid-free paper.

Copyright © 2000 by Eric Giguere. All rights reserved. Published by John Wiley & Sons, Inc. Published simultaneously in Canada.

No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except as permitted under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 750-4744. Requests to the Publisher for permission should be addressed to the Permissions Department, John Wiley & Sons, Inc., 605 Third Avenue, New York, NY 10158-0012, (212) 850-6011, fax (212) 850-6008, E-Mail: PERMREQ @ WILEY.COM.

This publication is designed to provide accurate and authoritative information in regard to the subject matter covered. It is sold with the understanding that the publisher is not engaged in professional services. If professional advice or other expert assistance is required, the services of a competent professional person should be sought.

Library of Congress Cataloging-in-Publication Data: ISBN: 0-471-39065-8 Printed in the United States of America.

10 9 8 7 6 5 4 3 2 1


10/17/2000 4:44 PM

Page

iii

Professional Developer’s Guide Series Other titles in the series: Advanced Palm Programming by Steve Mann and Ray Rischpater, ISBN 0-471-39087-9 WAP Servlets by John L. Cook, III, ISBN: 0-471-39307-X


10/17/2000 4:44 PM

Page

iv


10/17/2000 4:44 PM

Page

v

To Lisa, Victoria, Dino, and Taffy, with all my love.


10/17/2000 4:44 PM

Page

vi


10/17/2000 4:44 PM

Page

vii

Contents

Preface Introduction

Part One: Chapter 1:

Chapter 2:

xv xvii

Java and Small Devices

1

It Really Is a Small World After All

3

Small Computing Devices Memory and Storage Capacity Processor Power Input/Output Methods Input Methods Output Methods Form Factor Networking Putting It All Together Chapter Summary

4 5 7 8 8 12 13 13 15 15

Java: Fat and Slow?

17

The Architecture of Java Overview

18 18

vii


viii

10/17/2000 4:44 PM

Page

viii

C O N T E N TS

Chapter 3:

The Execution Engine The Virtual Machine The Garbage Collector The Class Loader The Class Verifier The Native Code Interface Runtime Libraries The Evolution of Java Java 1.02: Client Programming Applets Applications Java 1.1: Server Programming Just-in-Time Compiling Object Serialization RMI Database Connectivity JavaBeans Servlets Browsers and the Java Plug-In JRE Java 2: Enterprise Programming New Names and New Beginnings One Version, Three Editions Java 2 Standard Edition (J2SE) Java 2 Enterprise Edition (J2EE) Java 2 Micro Edition (J2ME) What Is Next for Java 2? The Devolution of Java Chapter Summary

19 20 29 31 33 33 34 35 36 36 38 39 39 40 41 41 42 42 43 44 44 45 45 46 47 47 47 48 49

Programming Strategies for Small Devices

51

If in Doubt, Do Not Use Java Move Computation to the Server Simplify the Application Build Smaller Applications Use Less Memory at Run Time Use Scalar Types Do Not Depend on the Garbage Collector Help the Garbage Collector Use Lazy Instantiation Release Resources Early

51 52 53 54 56 56 57 57 58 59


10/17/2000 4:44 PM

Page

ix

CO NTE NTS

Part Two: Chapter 4:

Chapter 5:

ix

Reuse Objects Avoid Exceptions Code with Performance in Mind Use Local Variables Avoid String Concatenation Use Threads, but Avoid Synchronization Separate the Model An Introduction to MVC Why Separate the Model? How to Build a Model The Tic-Tac-Toe Example Chapter Summary

59 61 62 62 63 64 65 65 66 66 68 73

Java 2 Micro Edition (J2ME) Specifications

75

Java 2 Micro Edition (J2ME)

77

Introducing the Micro Edition A New Virtual Machine New and Changed Classes Configurations and Profiles The KVM The Spotless System Early KVM Controversy The KVM Today Related Technologies Chapter Summary

78 78 79 79 81 82 83 84 86 87

Configurations

89

Overview The Purpose of a Configuration Connected Device Families Dynamic Application Delivery Identifying a Configuration The CLDC CLDC Quick Summary Detailed Requirements Language Support Virtual Machine Support Sandbox Security Inherited Classes CLDC-Specific Classes: Generic Connections

89 90 90 91 91 91 92 94 94 95 96 97 98


x

10/17/2000 4:44 PM

Page

x

C O N T E N TS

The CDC CDC Quick Summary Comparison to the CLDC Chapter Summary

101 101 103 104

Profiles

105

Overview The Purpose of a Profile How Profiles Are Used Identifying a Profile MIDP Mobile Information Devices MIDP Quick Summary MIDlets and MIDlet Suites What Defines a MIDlet? What Defines a MIDlet Suite? The Manifest Application Descriptors Application Lifecycle User Interface Classes The MIDP UI APIs and Abstract Windowing Toolkit (AWT) Screens and Events Drawing and Repainting Threading Issues Other MIDP Classes The Record Management System HTTP Connections Timer Notifications Other Profiles The PDA Profile The Foundation Profile The Personal Profile The RMI Profile Chapter Summary

106 106 106 107 107 108 109 109 110 111 111 113 114 115 115 116 119 120 120 120 123 124 125 125 125 126 126 126

Part Three: Java 2 Micro Edition (J2ME) Implementations

127

Chapter 6:

Chapter 7:

The Connected Limited Device Configuration (CLDC) Reference Implementation

129

Overview Installation Running the Samples

129 130 131


10/17/2000 4:44 PM

Page

xi

CO NTE NTS

Chapter 8:

xi

Compiling, Preparing, and Running Classes The Hello World Application The Hello World Spotlet Memory Usage The JAM Debugging Internet Resources Chapter Summary

134 136 137 139 139 141 142 142

Java for Palm Connected Organizers

143

Using the CLDC with Palm Devices A Palm Primer A User’s Perspective A Developer’s Perspective The Palm OS Emulator Installing the Palm CLDC Running the Samples KVMutil Revisiting the Hello World Application Additional MakePalmApp Options Additional APIs The User Interface The Spotlet Model Input Events Drawing Controls Databases Understanding Palm Databases Using Databases in Java Network Connectivity The Connector Class HTTP Connections The Tic-Tac-Toe Example Usage How It Works The Automatic Player Third-Party Tools and Extensions kAWT Color KVM JBuilder Handheld Express Jbed MicroEdition (CLDC) Chapter Summary

143 144 144 145 149 150 151 152 153 155 157 158 158 158 160 161 163 163 164 165 165 167 167 168 168 171 172 172 172 173 173 175


xii

10/17/2000 4:44 PM

Page

xii

C O N T E N TS

Chapter 9:

Chapter 10:

Chapter 11:

The Mobile Information Device Profile (MIDP) Early Access Release

177

Overview Installation Using the Cellular Phone Simulator Running the Simulator Web Server Setup Example Invocations Running the Samples Compiling and Preparing Classes The HelloMIDlet Application The Tic-Tac-Toe Example Chapter Summary

177 178 179 180 180 181 182 183 184 187 191

Java for Motorola Devices

193

The Motorola J2ME SDK Installing the SDK Using the SDK Using the Emulator Running the Samples Compiling and Preparing Classes The Tic-Tac-Toe Example Chapter Summary

194 194 194 195 196 198 198 200

Java for BlackBerry Wireless Handhelds

201

A BlackBerry Primer A User’s Perspective A Developer’s Perspective The BlackBerry JDE Installing the JDE Starting the IDE Using the IDE Running and Debugging Code Using the Simulator Running the Samples RIM’s J2ME Implementation Overview A First Application A Better Application Building Applications by Hand The Application Model Application Entry Event Dispatching

201 202 203 203 203 204 204 206 208 211 213 213 213 216 218 219 219 220


10/17/2000 4:44 PM

Page

xiii

C O N T E N TS

Chapter 12:

Chapter 13:

Appendix A:

xiii

Screens and Graphics User-Interface Components Network Communication Miscellaneous Classes The Tic-Tac-Toe Example The TicTacToe Class The TicTacToeUI Class Chapter Summary

220 221 221 222 222 223 223 225

Waba: An Alternative to Java

227

What Is Waba? The Waba VM The Waba Run Time The Bridge Classes Using Waba Installation Running the Samples Compiling and Running Classes The HelloWorld Application Debugging The Waba Foundation Classes Overview The Application Model The User Interface Input/Output (I/O) The Tic-Tac-Toe Example Chapter Summary

227 228 228 229 230 230 231 233 235 235 235 235 235 236 236 237 239

Final Thoughts

241

Alternatives to J2ME Conclusion

241 242

Tic-Tac-Toe Source Code

243

What’s on the CD-ROM?

287

Index

289


10/17/2000 4:44 PM

Page

xiv


10/17/2000 4:44 PM

Page

xv

Preface

W

riting a book about software is a frustrating task, because you know that by the time the book makes it into print, something about the software will have changed. This is especially true when writing about Java technology, because it evolves at Internet speeds. Rather than just listing things, I have tried to explain them. How do I use them? Where do I get them? What can I ignore? Where can I get more information about them? How do they relate to each other and to other things? The primary purpose of this book, then, is to explain what Java 2 Micro Edition (J2ME) is and how you can use it—or not use it because it does not meet your needs or expectations. When you get to the end, you will be ready to start programming small computing devices in Java. You will understand how configurations and profiles work and what the KVM is and is not. You will know where to go in order to get the tools and reference implementations that you need, and you will know how to use them (which is not always obvious). And you will know where to get updates on everything discussed here: the book’s Web site at www.ericgiguere.com/microjava. xv


xvi

10/17/2000 4:44 PM

Page

xvi

P R E FA C E

Before I close this preface, I would like to make a few acknowledgements. As usual, I would like to thank my editor at John Wiley & Sons, Carol Long, for putting up with a busy part-time author who tends to push the envelope when it comes to deadlines. And I would like to thank all of the other good people at Wiley as well as my agent, Carole McClendon. Jose Lacal at Motorola and David Yach at Research In Motion also receive my thanks for allowing me to include their software on the CD-ROM. My employer, iAnywhere Solutions, a new subsidiary of Sybase, also deserves recognition for providing a wonderful work environment and a chance to explore and use new technologies while providing real solutions for our customers and for allowing me to write this kind of book. And finally, to my wife Lisa, whom I love dearly, and my baby daughter Victoria, whose birth immediately followed the “birth” of my first book, for providing a warm and fun home environment and reminding me that there is more to life than programming—no matter how much you enjoy it. Eric Giguère Waterloo, Ontario October 2000


10/17/2000 4:44 PM

Page

xvii

Introduction

T

his book introduces you to Java programming for hand-held and embedded systems, devices such as personal digital assistants (PDAs), cellular telephones, and so-called intelligent appliances. The focus is on the Java 2 Micro Edition (J2ME), a new Java platform from Sun Microsystems that is geared specifically toward devices that have limited memory and/or processor power (which we refer to simply as small computing devices). J2ME is still a developing platform, however, so we also will look at other options when appropriate. By reading this book, you will learn to apply your Java programming skills to an ever-increasing number of small computing devices.

Why Java? As a software developer, you choose the programming language that helps you get the job done as effectively and efficiently as possible. For desktop- and server-based applications, many developers now choose to program in Java because of the features that it offers: xvii


xviii

10/17/2000 4:44 PM

Page

xviii

I NTRO D U CTI O N

Object-orientation. Apart from a few primitive types, everything in Java is an object. This situation forces you to decompose your application into classes and interfaces from the start, imposing a certain structure on your code. We are not saying that you cannot write bad code in an object-oriented system, but this system does require you to think a bit about what you are doing (which is the first step toward writing good code). Automatic garbage collection. Java frees you from having to track who is using a specific piece of memory and when it is available for reuse by another part of the application. If nobody is referring to an object, the system automatically reclaims that object. Without garbage collection, you have to resort to schemes such as referencecounting (like the auto_ptr type in C++ or the AddRef and Release methods in COM) in order to ensure that an object is truly unreferenced. These schemes require careful cooperation of all users of the object, or else memory leaks or heap corruptions inevitably result. (That said, garbage collection is not a solution to all memory woes—as we will see in Chapter 3, one of your jobs as a programmer is to help the garbage collector do its job.) Exception handling. Exceptions are notifications that something has gone wrong—something that might or might not be fixable—and that execution must stop until the notification is handled. Java includes support for throwing and catching exceptions. Portability. Java promises that you can run the same program on any platform (write once, run anywhere) with a conforming Java interpreter and run-time library. Developers can reuse their skills and knowledge in order to target a wider audience than would otherwise be possible. Multithreading. Java is thread-aware and includes built-in support for thread creation, synchronization, and notification. Care is still required to make code thread-safe, but the framework that the language provides makes it easier and more portable than using the operating system’s threading capabilities (if any). Similarity to C++. Java is as close to C++ as any other programming language not based on C, which makes it easier to transfer programming skills. These features also appeal to developers who work on smaller devices. Garbage collection, for example, avoids memory leaks, which can be


10/17/2000 4:44 PM

Page

xix

I NTR O D U CTI O N

xix

disastrous in an embedded system. Some would argue that these features are even more important on these devices because they add a robustness to programs that is only achieved with careful and disciplined programming in languages such as C or C++. There is a reluctance, however, to adopt Java as a programming platform because of its perceived shortcomings: Java is fat. The original Java platform, what is now called the Java 2 Standard Edition (J2SE), has grown steadily in size since it was first released. To reduce the installation footprint, the part required to run Java programs (as opposed to the part required to compile them) was split into a separate Java Runtime Environment (JRE) containing the Java interpreter, run-time classes, and associated support files. Even by itself, however, the JRE portion of J2SE is large—about 26MB on the Windows platform at this writing—and it grows as more and more classes are added to the core Java run time. The JRE is simply too large for many devices, considering that a typical Palm-connected organizer has between 2MB and 8MB of total memory. Add to that the memory that is required to load and run a Java program, and you will see why Java has been slow to make inroads as a viable programming platform on these devices. You can also make the argument that certain features of the language itself— its object orientation, exception handling, and symbolic run-time method resolution—lead to larger programs. Java is slow. Java is an interpreted language, executing more slowly by one or more orders of magnitude than comparable native code. To make matters worse, a slower processor is often used in small computing devices in order to extend battery life, because slower processors use less power. Java performance is acceptable on desktop and server systems not just because they use faster processors, but also because of the run-time conversion of Java bytecodes to native code by using technologies such as HotSpot and just-in-time compilation (technologies that are not feasible on smaller systems). Portability is unnecessary. The promise of write once, run anywhere appeals to developers who are writing applications that need to run on different systems, but if you are writing code for a specific embedded system or hand-held device, portability can be more of a hindrance than a help. If you cannot access the unique features of your device with the Java platform, then Java is useless. As well,


xx

10/17/2000 4:44 PM

Page

xx

I NTRO D U CTI O N

portability is often never completely achieved in any case because of bugs in the Java interpreter and in the run-time classes (write once, debug everywhere as the joke goes). As small computing devices evolve, they will undoubtedly include more memory and faster processors—making standard Java a viable programming language on these platforms. If you have 16MB of memory available on your PDA, however, you would probably rather have most of that memory available to store addresses, images, sound recordings, and other data (as opposed to using half of it just to run your programs). The end user does not care if a program is written in Java or C; instead, his or her only concern is that the application works well and makes efficient use of the device’s limited resources. From this viewpoint, Java would seem to fail. The irony is that Oak, the early form of the Java language, was specifically designed as an embedded programming language for consumer devices. (For some interesting reading about Oak and the Green Project at Sun Microsystems, refer to the Web site http://java.sun.com/ people/jag/green/index.html). As such, there is nothing inherent in the design of the language that limits it to usage on high-powered devices; rather, it is all a matter of implementation. The recent surge in popularity of hand-held devices is pushing Java to return to its roots as a programming language for small devices. This situation is happening in a number of ways, ranging from the simple (like writing tools in order to compact Java code) to the complex (such as reimplementing the Java interpreter). The question remains, “Is Java usable on small computing devices?” The answer is yes, at least with J2ME. When Sun Microsystems announced J2ME at the JavaOne Conference in 1999, the major significance of the announcement was that it demonstrated a will to make Java work well on smaller platforms. It might take a while to get there, but Java is on its way to acceptance as an alternative to C or C++ for all platforms.

What to Expect from This Book You will obtain two things from this book: a general understanding of what makes Java programming on small devices different, and specific instructions to get you started. You will still have to download and read


10/17/2000 4:44 PM

Page

xxi

I NTR O D U CTI O N

xx

the various specifications for yourself, but the book will provide you with valuable guidance to the material.

Who Should Read This Book? This book is written for software developers. We assume that you have a moderate level of Java programming experience. You do not need any background in hand-held or embedded systems, however, because the concepts that you need to understand are introduced as we go along. It helps, however, to have access to some device—real or simulated—that you can use for experimentation and to better understand the user experience. If you do not own a device, do not worry—we will show you how to get one or two simulators.

Chapter Summaries This book has 13 chapters, grouped into three parts. The chapters are best read in sequence.

Part One: Java and Small Devices Chapter 1, “It Really Is a Small World After All,” defines what small computing devices are all about. Chapter 2, “Java: Fat and Slow?” looks at the architecture of Java and its evolution so that we can better understand the need for somethidng like J2ME. Chapter 3, “Programming Strategies for Small Devices,” discusses design and coding strategies that you can use in order to write Java programs that work on small devices.

Part Two: J2ME Specifications Chapter 4, “Java 2 Micro Edition (J2ME),” introduces the Micro Edition and explains how it fits into the bigger Java picture. This chapter traces the development of one of its key components, a new virtual machine called the KVM.


xxii

10/17/2000 4:44 PM

Page

xxii

I NTRO D U CTI O N

Chapter 5, “Configurations,” describes the two initial J2ME configurations: the Connected Device Configuration (CDC) and the Connected, Limited Device Configuration (CLDC). Configurations define basic Java language and run-time library support. Chapter 6, “Profiles,” describes the first J2ME profile: the Mobile Information Device Profile (MIDP). This chapter also briefly describes other profiles that are currently in development. Profiles build on top of configurations by adding classes to support specific types of applications or uses of devices.

Part Three: J2ME Implementations Chapter 7, “The Connected Limited Device Configuration (CLDC) Reference Implementation,” shows you how to use the reference implementation of the CLDC on your desktop computer. Chapter 8, “Java for Palm Connected Organizers,” shows you how to use the Palm operating system (OS) port of the CLDC reference implementation. This chapter includes a short discussion of the unique architecture of Palm devices and how to use and obtain the Palm OS Emulator so that you can try out the port even if you do not own a Palm device yourself. Chapter 9, “The Mobile Information Device Profile (MIDP) Early Access Release,” shows you how to use the Early Access release of the MIDP reference implementation. This release includes a cellular phone simulator that lets you try your MIDP applications in a different environment than Palm. Chapter 10, “Java for Motorola Devices,” describes Motorola’s implementation of the MIDP, the first complete MIDP implementation from a non-Sun party. A beta version of the Motorola J2ME SDK, complete with emulators for various Motorola cellular telephones, is available on the CD-ROM accompanying this book. Chapter 11, “Java for BlackBerry Wireless Handhelds,” describes the BlackBerry Java Development Environment—another non-Sun implementation of J2ME. An early-access version of the BlackBerry JDE is available on the CD-ROM accompanying this book.


10/17/2000 4:44 PM

Page

xxiii

I NTR O D U CTI O N

xxiii

Chapter 12, “Waba: An Alternative to Java,” explores a similar but different take on making Java work on small computing devices. Chapter 13, “Final Thoughts,” concludes our exploration with a few thoughts about the future of J2ME.

Appendices Appendix A, “Tic-Tac-Toe Source Code,” lists the source code for the tic-tac-toe game developed in this book.

The Web Site and CD-ROM The accompanying CD-ROM includes the samples as well as some of the software and reference material that we refer to in this book, including the Motorola J2ME SDK and the Research In Motion Java Development Environment. Refer to the index.html file at the root of the CD for all of the details. You can also refer to the book’s Web site at www.ericgiguere.com/microjava for updates, corrections, and more material.


10/17/2000 4:44 PM

Page

xxiv

67957_Wiley_Giguere_CH01x

10/17/2000 4:49 PM

Page 1

ONE

PA R T

Java and Small Devices


10/17/2000 4:49 PM

Page 2


10/17/2000 4:49 PM

Page 3

CHAPTER

1


T

hese days, it seems that smaller is becoming just as important as faster—at least, when it comes to computing. Whether it is something as extreme as nanotechnology or as commonplace as internet appliances, there is an increasing desire to embed computing technology in all facets of the human experience. The popularity of personal digital assistants (PDAs), cellular telephones, and other hand-held devices is just the first wave of this surge. Today’s small computing devices are comparable in power to the computers of five years ago. Most will always lag behind what is considered adequate for a desktop computer, however, due to space and powerconsumption considerations. The challenge is to adapt programs that work well on the fastest processors and that use memory indiscriminately so that they also work on these smaller devices. In this chapter, we discuss small computing devices to see what makes them different from desktop and server computers. This knowledge prepares us for the next chapter, where we will explore how Java works and why it needs to change in order to work with these devices.We will then conclude this part of the book with a discussion of programming strategies for small devices.

3


4

10/17/2000 4:49 PM

Page 4

CHAPTER 1

Small Computing Devices First, we should define a small computing device, which is simply a computing device that has limited processor speed and/or available memory when compared to a desktop or server computer. A typical small computing device is a PDA, such as a Palm V, but the category also covers devices that do not have a conventional user interface. Some devices, for example, are meant to be embedded inside other systems—with no explicit human interaction. These devices are also of interest to us, although we will be dealing mostly with interactive devices throughout this book (because they are more general and more readily available). Admittedly, the line separating a small computing device from the capabilities of a full-fledged desktop or server computer is rather blurry as thinner notebook computers, Web pads, and other devices come onto the market. In general, however, you can use the following rule of thumb to separate the two camps. If you never worry about the speed of your application (if it is acceptable without any extra work on your part) or about the amount of memory that it requires (within normal limits), you are not working with a small computing device. We can now examine the characteristics that separate small computing devices from their more powerful siblings.

Speed Is Always Important No matter what platform you are programming for, the speed of your application is always important. What your goal is, however, is acceptable performance—not the best possible performance. Achieving the best possible performance is usually a lower-priority task than fixing bugs or otherwise improving the application. In many cases, the difference between acceptable and best possible simply is not worth the effort that it requires. The challenge with small computing devices is achieving acceptable performance, not surpassing it.


10/17/2000 4:49 PM

Page 5


5

Memory and Storage Capacity Memory capacity is an important measuring stick, and at first glance, a small computing device might not seem that limited. You will find that it is not unusual, for example, for a modern PDA to have 4MB, 8MB, or more of memory. While this amount is less than the 64MB or 128MB that you will get in a typical desktop system, it is not a debilitating amount. Programs can fit comfortably in the 0MB–to–4MB range, regardless of the platform. Focusing on memory capacity is rather deceiving, however, because what we need to focus on is total storage capacity (which is a much more important number). Total storage capacity is the sum of a device’s online and offline storage capacity. Online storage capacity is simply another term for memory capacity—the amount of memory available to store runtime application data (stack, threading information, and heap), system data, built-in applications, and the operating system. Online storage is characterized by instant availability and might or might not be persistent. Offline storage capacity, on the other hand, is the capacity of secondary, persistent storage modules such as hard disks or memory sticks. Offline storage is usually slower to access and is not normally available for storing runtime application data. Compare the memory capacity of a desktop computer with 64MB of random access memory (RAM) and a Palm Vx with 8MB of RAM, as illustrated in Figure 1.1. The difference is not that pronounced. Now compare the total storage capacity of the two devices. Say that the desktop computer includes a 10GB hard drive for offline storage. Figure 1.2 demonstrates the difference between the two quite dramatically: the desktop computer’s capacity is roughly 10GB (we can effectively ignore the 64MB of RAM for this calculation), and the Palm Vx’s still stands at 8MB. The desktop computer has almost infinite storage capacity when compared to the basic Palm Vx. Total storage capacity is not always a distinguishing feature, however. Consider the IBM Microdrive, for example—a 340MB storage device that can be plugged into any device that supports the CompactFlash Type II expansion slot. In other words, you can use it with PDAs such as the Hewlett-Packard Jornada 430se or the Psion Series 7. While


Page 6

CHAPTER 1

72

Memory Capacity (MB)

64 56 48 40 32 24 16 8 Desktop computer

PalmVx

Figure 1.1 Memory capacity compared.

10 9

Total Storage Capacity (GB)

6

10/17/2000 4:49 PM

8 7 6 5 4 3 2 1 Desktop computer

PalmVx

Figure 1.2 Total storage capacity compared.


10/17/2000 4:49 PM

Page 7


7

10GB is still an order of magnitude larger than 340MB, the latter is itself significantly more than 8MB. Sony’s Memory Stick is another device that provides offline storage for small devices. These and other storage devices will continue to narrow the gap in total storage capacity.

Processor Power Unless they are embedded in some other system, small computing devices are typically designed as self-contained units without a dedicated electrical power connection. In other words, they are batteryoperated. One of the primary design goals of a battery-operated system is to conserve battery power. The longer that a device can function without replacing or recharging its batteries, the more useful the device is. Notebook computers will only run for a few hours on a single battery, so it is not unusual to bring a second battery along in case the first battery runs out of power. One of Palm, Inc.’s greatest selling features for its line of hand-held organizers is their capability to run for weeks on two AAA batteries or on internal rechargeable batteries. To conserve battery power, then, manufacturers of small devices use central processing units (CPUs) that are optimized for low-power scenarios. These processors are slower than normal CPUs and are often based on older chip models. A processor running at a clock speed of 20 megahertz (MHz) is not unusually slow for such devices. Of course, 20MHz is quite slower than the 600MHz or higher clock speeds that you will find in today’s desktop computers. Even embedded systems without the same electrical power constraints as portable systems will use slower, older chip models (if only for cost and availability advantages). Cost and availability are also factors when designing portable devices, of course—especially when mass production of the devices is anticipated. In general, then, a small computing device runs applications more slowly than a desktop computer. Any compute-bound application written for these devices has to take this slower processor speed into account. Later in Part One, we will discuss some strategies for dealing with this problem.


8

10/17/2000 4:49 PM

Page 8

CHAPTER 1

Input/Output Methods Small computing devices are more likely to have alternate input/output (I/O) methods than desktop computers. For portable devices, the form factor—which we discuss in the next section—often determines what I/O methods are acceptable. Size constraints make the regular I/O methods of a desktop computer (full-size keyboard, monitor, and mouse) impractical or impossible. In an embedded system, of course, I/O methods are more constrained. There might be no visible user interface, for example, and all input might come from sensors (as opposed to human interaction).

Input Methods The touch-sensitive screen, perhaps the most common input method for PDAs, also doubles as an output method (a monochrome or color screen). Combining the two saves space, which is an important consideration. Touch-sensitive screens are most often used in conjunction with some kind of writing or stroking device (usually referred to as a pen or stylus) and on-board character-recognition software. The Palm V organizer shown in Figure 1.3 is dominated by its large, touch-sensitive screen. If an application requires a lot of text input—as

Figure 1.3 The Palm V Connected Organizer.


10/17/2000 4:49 PM

Page 9


9

opposed to selecting items and clicking buttons—then the touch-sensitive screen (or more precisely, the character-recognition software) can actually be a hindrance. Character recognition is also imprecise and requires a certain amount of processing power in order to be effective. A conventional keyboard is the most accurate and fastest way for most users to enter text data. On most small computing devices, a full-size keyboard is out of the question. Instead, most devices that have keyboards reduce both the number and the size of the keys. When the keyboard becomes too small for touch typing, it is common to see users holding a device in both hands and using their thumbs to press the keys. That is why such small keyboards are often referred to as twohanded keyboards. You will find it surprising what you can pack into a small space. Consider the RIM 950 (also known as the BlackBerry) Wireless Handheld, shown in Figure 1.4, with its optimized QWERTY keyboard.Notice how the keyboard is larger than the screen, which stresses the fact that the device is as much about sending mail as it is about reading it. For those who want a larger display, RIM also offers the 957 Wireless Handheld, shown in Figure 1.5. Unlike the 950, the 957 is more of a direct competitor to the Palm series of organizers. Sometimes keyboards are add-ons. Palm offers a collapsible keyboard for its devices, shown in Figure 1.6, and this keyboard is large enough

Figure 1.4 The RIM 950 (BlackBerry) Wireless Handheld.


10

10/17/2000 4:49 PM

Page 10

CHAPTER 1

Figure 1.5 The RIM 957 Wireless Handheld.

Figure 1.6 The Palm portable keyboard.

to be used by touch-typists. The disadvantage is that it increases the total weight and bulk of the device and requires a flat surface for correct operation (it is not really suitable for hand-held operation).


10/17/2000 4:49 PM

Page 11


11

An alternative to a keyboard is a keypad, which is used primarily for entering numeric data. Cellular phones are the primary devices that use keypads, as shown in Figure 1.7. What is interesting is that you can also use a numeric keypad to enter alphabetic characters. You perform this action by assigning multiple characters to each key and letting the user cycle through them by pressing a key several times. This process is tedious, but it is workable for limited text entry. A more sophisticated input method is voice recognition. The capability to recognize spoken commands is becoming possible in small devices. Cellular phones such as the Ericsson T18s support voice-activated dialing. Full voice recognition requires a lot of processing power and is still far from perfect, but it is perhaps the most promising input method for small devices that cannot support full keyboards (and even perhaps for those that can). Voice recognition is mostly a server-side capability at this stage, however.

Figure 1.7 A cellular phone keypad.


12

10/17/2000 4:49 PM

Page 12

CHAPTER 1

Anyone who has played video games will recognize the joystick and trackball input methods. Both specify two-dimensional movement. A similar input method is a roller wheel, which is a dial that you can move clockwise or counter-clockwise in order to simulate one-dimensional movement. The RIM devices in Figures 1.4 and 1.5 include a roller wheel (which is referred to as a thumbwheel because it is rotated via the thumb) as well as the small keyboard. And, of course, there are push buttons and other kinds of buttons. Buttons are found on most devices. The Palm V, for example, has four buttons below its screen. On the RIM devices, the thumbwheel doubles as a push button. Specialized input methods, such as barcode readers, are also available with some devices.

Output Methods The most common output method is obviously the display screen. Just like a desktop computer, small devices often support some kind of display screen. The screen can be quite small and is capable of displaying only three or four lines of text. Even the larger devices cannot display that many lines of text. For hand-held devices, 20 lines is considered an upper limit for text that is still readable without a user having to hold the device up to his or her face. Size issues aside, there can be other restrictions on what is available when compared to a typical desktop system. There might be restrictions on the type and number of fonts that are available. Bitmapped graphics might not be available. Even something as basic as color support cannot be taken for granted, because many devices such as cellular phones and even PDAs have no color support at all. In a few years, however, monochrome devices are more likely to be an exception than the norm in most device categories. Apart from the screen, indicator lights can also be used to communicate with the user. Individual lights can provide a visual indication of hardware events such as network activity and power usage or software events such as message availability. These lights are often programmable and can be controlled by an application. If a speaker is included, a device can use simple audio signals such as rings and beeps. More sophisticated devices can play back messages and music or synthesize voices.


10/17/2000 4:49 PM

Page 13


13

Output methods do not have to involve the senses of sight or sound. A cellular phone’s vibrating battery, for example, provides a physical indication about an incoming call. Many devices support infrared ports, not only enabling them to communicate with other devices, but also (with the right programming) enabling them to control electronic devices such as televisions and stereo systems.

Form Factor The form factor of a device refers to its physical size, shape, and weight. The intended use of the device places absolute limits on these values, but in general, a smaller form factor is better. The form factor for a hand-held device such as the Palm V requires it to fit comfortably in one hand, freeing the other hand to use the stylus on the touch-sensitive screen. RIM’s wireless hand-held devices are designed to fit in a belt holster so that you can carry it with you at all times, much like you would a pager. The form factor greatly influences the choice of I/O methods and hardware. In particular, the type, size, and location of the device’s batteries are constrained by the form factor. The Palm V was capable of achieving a thinner profile and lighter weight, for example, only by moving away from AAA batteries (as found in earlier models such as the Palm III) to integrated rechargeable batteries. Advanced features such as wireless data communication (discussed next) can make it even harder to down-size a device’s form factor. For embedded systems, form factor is still important. The smaller the device, the easier it is to integrate the device into the larger system. Hopefully, it is also less expensive, because the cost of each component is important when building embedded systems.

Networking Given the limitations that we have discussed so far, it is almost a given that any portable device will have some form of built-in networking capability. Not only does networking enable the device to access external data, but more importantly, it enables the device to offload data and computation to another more powerful device. Networking also


14

10/17/2000 4:49 PM

Page 14

CHAPTER 1

enables devices to share data—a process often referred to as data synchronization. Data synchronization is particularly important with portable devices, because it avoids the errors and difficulties with manually keeping shared data up-to-date. But even embedded systems can benefit from data synchronization in order to keep communication costs and overhead down by using a local data cache. You can broadly classify portable devices into two groups, based on the type of network connection that they support. The first group includes devices without a permanent network connection, which we can refer to as occasionally connected devices. Most hand-held devices support serial communication with a desktop computer, for example, through the use of a cradle (or a simple cable) that is permanently connected to the computer. You place the device in its cradle to do its networking (primarily data synchronization). The second group includes devices with a permanent network connection, which we refer to as alwaysavailable devices. If portable, these devices use some form of wireless communication (either infrared or radio-based) to exchange data with other devices or computers. Of course, some devices fall into both groups. Most handhelds, for example, support infrared communication as well as serial communication.

Always Available versus Always Connected The counterpart to an occasionally connected device is referred to as an alwaysconnected device, but we use the terminology always-available instead. The reason is because always-available implies that the networking capability is there but is not necessarily in use. This reminder shows you that you are dealing with portable devices in which power conservation is extremely important.

In general, the throughput of an occasionally connected device will exceed that of an always-available device. Basic serial communication is not fast (in the 19Kbps to 33Kbps range). Newer cradles that support the Universal Serial Bus (USB) standard can achieve faster speeds. Wireless radio communication is currently in the 4Kbps to 19Kbps range, although these limits are expanding. But none of these communication methods are currently as fast as the typical Ethernet connection that you will find on a desktop computer, although new


10/17/2000 4:49 PM

Page 15


15

technologies such as Bluetooth will narrow the gap. Even if the communication method supports higher speeds, the device itself will always be a limiting factor because it can only process so much information at a time with its slower CPU. Throughput limitations aside, there can also be cost limitations associated with network communication. This situation is particularly true with wireless communications that use public data networks, such as Mobitex or ARDIS, where charges are based in part on the amount of data sent. There is also the cost of including the networking hardware itself in the device and keeping power consumption at acceptable levels.

Putting It All Together Individually, the characteristics that we just discussed do not necessarily distinguish a small computing device from a desktop or notebook computer. When they are used together is when the differences between the two platforms become apparent. As a developer, you will have to adapt your programming strategies to deal with these differences, which is what we will discuss in Chapter 3.

Chapter Summary In this chapter, we looked at what differentiates a small computing device from a regular desktop computer and what kind of limitations those characteristics place on our applications. In the next chapter, we will look at how Java works and why a new edition is necessary for smaller devices.


10/17/2000 4:49 PM

Page 16


10/17/2000 4:50 PM

Page 17

CHAPTER

2

Java: Fat and Slow?

A

sk Java zealots if Java is slow, and watch them bristle with annoyance. “Of course not,” they will say. “Performance is perfectly adequate with just-in-time compilers and is even better with the new HotSpot technology.” Ask them if Java is fat, and you will receive a similar response: “The Java runtime is a bit large, but that’s only because it provides so many useful APIs. You’d get that kind of size with any system.” And you know, they are not wrong, either. On server and desktop platforms, Java does work. In particular, Java has made huge inroads as a server-side programming language, due primarily to the advantages that we discussed in the introduction. As for performance issues, remember that in a server environment, installing more or faster CPUs or more memory or even spreading the load across several machines can often tackle these issues.

17


18

10/17/2000 4:50 PM

Page 18

CHAPTER 2

Still, there is a perception among developers that Java is fat and slow, but its convenience outweighs its performance issues. This perception is a concern to us, however, because we are interested in writing Java programs that run on small computing devices. Unlike server or even desktop platforms, we cannot just throw more hardware at smalldevice performance problems. In this chapter, we look at why Java is fat and slow and how those characteristics affect our desire to run Java programs on small devices. First, we examine the architecture of Java. Then, we follow its evolution from a language for writing platform-independent client applications and finally to its current role as a language for server and enterprise programming.

The Architecture of Java We start by looking at how Java works. The basic architecture has not changed since Java was first released, although there has been considerable effort to improve parts of it. If you are already familiar with the architecture, feel free to skip to the next section—although you might find a refresher course useful.

Overview The code that runs a Java program is referred to generally as a Java runtime environment (JRE). A JRE is a combination of native (compiled for a specific machine architecture) and Java code that is targeted for a particular operating system. JREs are embedded in other applications, such as Web browsers, or are available directly from a shell prompt or desktop user interface. A JRE is generally packaged as a set of shared libraries (the native code) and archives (the Java code). There are alternative packagings, however. Parts of a JRE can be incorporated directly into hardware, creating the so-called Java chips. Or, alternatively, Java programs—or parts of programs—can be compiled directly into native code, eliminating sections of a conventional JRE. In all cases, however, the semantics of Java code execution must be preserved, so we will discuss things from the viewpoint of a conventional JRE.


10/17/2000 4:50 PM

Page 19

Java: Fat and Slow?

19

Sun’s Runtime Environment As we discuss the architecture of Java, we will use the term JRE in a generic sense. More specifically, however, JRE refers to Sun’s runtime environment, which is a downloadable, self-contained package that is meant for distribution with Java applications to be installed on machines that do not already have the capability to run Java programs. We will discuss that JRE later in this chapter.

Packaging issues aside, a JRE consists of two major components: an execution engine and a pair of runtime libraries.

The Execution Engine The execution engine is the core of the JRE and is responsible for loading and running Java programs. The requirements for the execution engine are contained in The Java Virtual Machine Specification (JVMS), the official reference with which all implementations must conform in order to qualify as a JRE. The execution engine itself is split into several components: a virtual machine, a garbage collector, a class verifier, a class loader, and a native code interface.

Compilation versus Execution There are two important documents that tool implementers—the programmers who write compilers, debuggers, runtime environments, and other applications that other programmers use—refer to when dealing with Java. The first is the JVMS. The second is The Java Language Specification (JLS). The JLS describes the syntax and semantics of the Java programming language, while the JVMS describes how to run Java programs. In general terms, the JLS is about compiling Java, while the JVMS is about executing Java. We will see that you can also use the JVMS to run programs that are written in other languages.

The Java virtual machine (often referred to as the VM or JVM) is the most visible part of the execution engine. In fact, the two are usually considered synonymous. For our discussions in this section, we will treat them as separate entities, but in the remainder of this chapter


20

10/17/2000 4:50 PM

Page 20

CHAPTER 2

(starting with our look at the evolution of Java) and in the chapters that follow, we will use the terms VM and JVM to refer to the complete execution engine. The various pieces that we discuss here are so closely tied together that for all intents and purposes, we can treat them as a single entity. The Virtual Machine The heart of the execution engine is the virtual machine. In computer science, a virtual machine is an abstract, idealized computer with its own instruction set. Virtual machines are implemented in software and are used for teaching and portability purposes—in any situation where it is useful to hide the messy details of an actual, physical architecture. Programs that are coded for a virtual machine can be run on any architecture simply by porting the virtual machine—which is, after all, just another application—to the new architecture. This system is the basis of Java’s portability, along with the classfile format and the core runtime libraries.

Portability Is More Than a VM Using a VM does not guarantee complete portability, however. True portability (usually referred to as binary portability) is achieved when the file format used to store the program is itself portable and the runtime libraries that the program depends on are present on each target architecture. Java’s write once, run anywhere portability is based on those three components: the VM, the classfile format, and the standard runtime libraries.

Bytecodes

The instruction set for the JVM is described in the JVMS. The instructions are commonly referred to as bytecodes, because many of them are a single byte in length. There are Java bytecodes for common operations such as reading or writing memory, adding or subtracting numbers, and branching—operations that any machine architecture supports. There are also bytecodes for implementing certain features that are specific to the Java language itself, such as the instanceof keyword. The JVM is built around the Java type model, so it understands the scalar types and object references that the language uses.


10/17/2000 4:50 PM

Page 21

Java: Fat and Slow?

21

You can use a JVM to run programs that are written in other languages, but only if those languages can be compiled into Java bytecodes (the tight linkage between the VM and the Java language can make that difficult). For an example of a non-Java language that can run on a JVM, refer to IBM’s NetREXX, which is available from http://www2.hursley. ibm.com/netrexx. A JVM is a stack-based machine that uses no registers, except for a program counter to track the instruction that is currently executing. Most bytecodes manipulate the stack in some way, using it as a place to retrieve input and to store results. For example, consider the following Java code: int a = 5; int b = 3; int c; c = a + b;

One possible translation into bytecode would be as follows: bipush 5 istore 0 bipush 3 istore 1 iload 0 iload 1 iadd istore 2

// // // // // // // //

push single-byte value 5 on stack as int pop int value and store in first local variable push single-byte value 3 on stack as int pop int value and store in second local variable load int from first local variable and push on stack do the same for second local variable pop top two ints from stack, add, and push result pop int value and store in third local variable

Using a stack makes it easy to implement the virtual machine on any architecture, because there is no dependence on specialized registers. It does increase the size of the compiled code, however, because of the necessity to push and pop values onto and from the stack. Consider this hypothetical example obtained by adding two registers, A and B, to the virtual machine: // hypothetical only! load_A 5 store_A 0 load_B 3 store_B 1 add_A_B store_A 2

// // // // // //

load value 5 into register A store register A into first local variable load value 3 into register B store register B into second local variable add A and B, storing result back in A store register A into third local variable


22

10/17/2000 4:50 PM

Page 22

CHAPTER 2

This imaginary example is 11 bytes long (each bytecode takes a single byte, and each of the operands takes another byte), while the previous example is 15 bytes long. This difference is not huge, but for larger programs, it could make a noticeable difference in size. To alleviate this concern, the Java instruction set includes a number of short forms for commonly performed operations. A better compilation of the Java code would, in fact, be as follows: iconst_5 istore_0 iconst_3 istore_1 iload_0 iload_1 iadd istore_2

// // // // // // // //

push constant value 5 on stack as int pop int value and store in first local variable push constant value 3 on stack as int pop int value and store in second local variable load int from first local variable and push on stack do the same for the second local variable pop top two ints from stack, add, and push result on stack pop int value and store in third local variable

Instructions such as iload that take two bytes (one byte for the instruction and one for the operand) are replaced with equivalent one-byte instructions where the operand value is implicit (hard-coded into the instruction itself). Thus, iload becomes iload_, where n is a value from 0 to 3 (in other words, there are four separate iload variants in addition to the general form iload : iload_0, iload_1, iload_2, and iload_3). By using these implicit instructions, the compiler can produce code that is 8 bytes long—a definite improvement over the 15-byte example that used the general (explicit) instruction forms.

Favor Implicit Instructions One way to reduce the size of your compiled Java code is to favor the use of implicit instruction forms wherever possible. For example, if you can limit a method to four or fewer local variables, then the compiler can take full advantage of the implicit forms of instructions (such as aload, iload, fload, astore, istore, fstore, and so on). Limit yourself to three local variables on non-static methods, however, because the this reference (the object whose method is being invoked) is always stored as the first local variable (index 0).


10/17/2000 4:50 PM

Page 23

Java: Fat and Slow?

23

Disassembling Java Bytecode

Seeing how Java code translates into bytecode is simple when you use the javap tool that comes with Sun’s Java Development Kit (JDK). We will talk more about the JDK later in this chapter. Simply ensure that the class you wish to disassemble is in the classpath, and invoke javap with the –c option. For example, try disassembling the code for java. lang.Object: javap -c java.lang.Object

The output will look like the code shown in Figure 2.1, which we have abridged for readability by removing the wait methods. Notice how the methods implemented by the class are listed and followed by the code for each method. Native methods are not listed, of course, because there is no Java code associated with them. All of this information is extracted directly from the compiled class file—obviously a verbose format.

// Abridged output of javap -c java.lang.Object Compiled from Object.java public class java.lang.Object { static {}; public java.lang.Object(); protected native java.lang.Object clone() throws java.lang.CloneNotSupportedException; public boolean equals(java.lang.Object); protected void finalize() throws java.lang.Throwable; public final native java.lang.Class getClass(); public native int hashCode(); public final native void notify(); public final native void notifyAll(); public java.lang.String toString(); // removed the three variants of wait() } Method static {} 0 invokestatic #21 <Method void registerNatives()> 3 return (continues)

Figure 2.1 Sample output for javap.


24

10/17/2000 4:50 PM

Page 24

CHAPTER 2

Method java.lang.Object() 0 return Method boolean equals(java.lang.Object) 0 aload_0 1 aload_1 2 if_acmpeq 9 5 iconst_0 6 goto 10 9 iconst_1 10 ireturn Method void finalize() 0 return Method java.lang.String toString() 0 new #13 3 dup 4 aload_0 5 invokevirtual #18 <Method java.lang.Class getClass()> 8 invokevirtual #19 <Method java.lang.String getName()> 11 invokestatic #24 <Method java.lang.String valueOf(java.lang.Object)> 14 invokespecial #16 <Method java.lang.StringBuffer(java.lang.String)> 17 ldc #3 <String “@”> 19 invokevirtual #17 <Method java.lang.StringBuffer append(java.lang.String)> 22 aload_0 23 invokevirtual #20 <Method int hashCode()> 26 invokestatic #22 <Method java.lang.String toHexString(int)> 29 invokevirtual #17 <Method java.lang.StringBuffer append(java.lang.String)> 32 invokevirtual #23 <Method java.lang.String toString()> 35 areturn

Figure 2.1 (Concluded.)

Java class files

A virtual machine written according to the specifications in the JVMS must accept its input in a format referred to as the classfile format. The classfile format is a portable binary format that describes the bytecode, strings, and other attributes of a single Java class. Each class file does not have to correspond to a single physical file, although that was a


10/17/2000 4:50 PM

Page 25

Java: Fat and Slow?

25

common scenario in the early days of Java. Nowadays, it is more common to package multiple class files into a single, compressed Java Archive (JAR) file for a variety of reasons. To the VM, however, the class files are still separate entities and are always treated individually. Portability is a key feature of the classfile format. You can take a class file compiled on a particular architecture and move it to another machine without worrying about differences in byte order or character encodings. The JVMS takes care of these and other potential road blocks. For example, strings are stored in UTF-8 format, which is a multi-byte encoding of Unicode, while individual data values that are larger than a single byte are always stored in big-endian (high bytes first) format. Class files are not compact because they store a lot of symbolic information: the name of the class, the names (including the parameter and return types) of methods, field names, the names of other classes and methods referenced by the class, and so on. Some of this information is optional and can be stripped out (debugging information, for example). But most of it is necessary because Java uses symbolic name resolution at run time in order to find classes, methods, and fields. Consider, for example, a simple class with no fields or methods apart from the automatically generated constructor: public class EmptyClass { }

The compiled class file is about 200 bytes long (with no debugging information included), but if you disassemble it with javap, you will find the following: Compiled from EmptyClass.java public class EmptyClass extends java.lang.Object { public EmptyClass(); } Method EmptyClass() 0 aload_0 1 invokespecial #3 <Method java.lang.Object()> 4 return

The bytecode for this class is exactly five bytes long. The rest of the file stores the strings for this class—the names of the class and its superclass, the name of its single method (constructor)—and other


26

10/17/2000 4:50 PM

Page 26

CHAPTER 2

information. If EmptyClass were an interface instead of a class, the class file would be a bit smaller, but there would still be overhead. You should note that Java class files are standalone entities. There is no sharing of data between class files. In particular, this mean that the same strings—whether they are string literals, method names, or class names—are repeated across different files. This repetition and the fact that class files contain so many strings is one reason why they compress so well when packaged together in JAR files. Are Java VMs Slow?

JVMs are usually implemented as interpreters, which run programs by reading and executing the bytecodes one instruction at a time. This procedure is not a requirement; rather, it is merely the simplest implementation. According to the second edition of The Java Virtual Machine Specification, So long as the class file format can be read and the semantics of its code is maintained, the implementor may implement these semantics in any way. What is “under the hood” is the implementor’s business, as long as the correct external interface is carefully maintained.

In other words, VM implementors are free to do as they choose as long as they preserve program behavior. The most common alternative implementation is to convert Java bytecodes directly to native instructions, for example. We will discuss that concept more when we explore the evolution of Java. People often make claims that Java is slow and blame this characteristic on its interpreted nature. By themselves, however, interpreters are not necessarily slow. A computer’s CPU is itself an interpreter, after all. Java’s slowness derives from other factors that are characteristics of the language itself, especially when compared to C or C++: Lack of pointers. The VM carefully controls all memory access. Objects are referred to by references, not by pointers, which enables the VM to ensure that the object is valid whenever it is involved in an operation. A reference is typically (but not necessarily) a handle to the actual object—an entry in a table of object pointers or a pointer to a pointer. This kind of implementation gives the garbage collector the flexibility to move objects around in memory in order to satisfy


10/17/2000 4:50 PM

Page 27

Java: Fat and Slow?

27

memory requests, but it also adds an extra level of indirection whenever an object is accessed. Runtime checks. Java bytecodes perform a number of runtime checks in order to catch errors as quickly as possible and to prevent memory corruption. If an object reference is required, for example, a NullPointerException is thrown if the reference is null. Array indices are checked to make sure that they are within the bounds of the array; otherwise, an ArrayIndexOutOfBoundsException is thrown. Casts are checked in order to ensure that the object being casted extends or implements the required class or interface. A language such as C/C++ performs little runtime checking. Security checks. Security checks are runtime checks that deserve special mention because of the important part that they play in ensuring that a program is valid. Many of these are performed by the verifier, which we will discuss shortly, and this process slows program startup. The runtime libraries also perform various checks, which slow program execution. Synchronization primitives. Java was designed to support multiple threads of execution (whether or not the underlying operating system itself does), and the VM instruction set includes instructions such as monitorenter and monitorexit that directly support the synchronization semantics of the language. Any programmer who has worked with semaphores knows that acquiring a lock on a semaphore takes time and that too much synchronization will have a measurable effect on the program’s execution. For this reason, operating systems such as Windows offer faster synchronization primitives (critical sections or functions) to perform simple atomic operations—anything to cut down the time it takes to acquire and release synchronization locks. Java’s synchronization facilities have always been particularly slow, and this concern is something that Sun has only recently addressed. Symbolic name resolution. As previously mentioned, a Java class file stores the names of each method in the class and each method called. The names are resolved at run time when the class is loaded and verified. Looking up methods by name instead of by position is how Java avoids the fragile base-class problem that is inherent in languages such as C++, where almost any change to a base class requires


28

10/17/2000 4:50 PM

Page 28

CHAPTER 2

recompilation of every class that uses that class. This process does add overhead, however, by increasing the size of a class file and lengthening the time required to load a class in preparation for execution. Non-static methods are also implicitly virtual (or invoked via indirect lookup), which is a difference from C++ (where methods must be explicitly marked as virtual). Slow array initialization. There are no instructions for initializing complete arrays in the Java VM. Instead, compilers must generate a series of bytecodes that initialize the array element by element. Consider, for example, the following array declaration: int[] array = new int[]{ 10, 20, 30, 40, 50 };

The code to initialize the array elements looks as follows: iconst_0

// index 0

bipush 10 iastore iconst_1 bipush 20 iastore iconst_2 bipush 30 iastore iconst_3 bipush 40 iastore iconst_4 bipush 50 iastore

// // // // // //

value 10 store index 1 value 20 store etc. etc.

For large arrays, this process generates a significant amount of code— not only bloating the size of the compiled class file, but also slowing program execution because of the extra code that must execute. The other components of the execution engine—the garbage collector, the class loader, the class verifier, and the native code interface—also play a part in slowing Java down, as we will see shortly. But removing or altering any of the factors that we have just discussed, or any of the components that we are about to discuss, would be counter-productive in most cases and would change important features of the Java language. You can only make careful and specific changes.


10/17/2000 4:50 PM

Page 29

Java: Fat and Slow?

29

Array Initialization and java.lang.Character Array initialization affects every Java program, even if the program does not declare any arrays. Why? The answer is because java.lang.Character defines a number of arrays for determining whether characters are letters or digits, upper-case or lower-case characters, and so on, and java.lang.Character is referenced (usually indirectly) by every program. In Java 1.02, these arrays were initialized in the usual way, but it was not a huge penalty—because at that point, java.lang.Character dealt almost exclusively with the ANSI subset of Unicode (the first 256 characters). With Java 1.1 came better support for program internationalization, and to avoid excessive bloating due to array initialization, the required values were encoded in strings (by using the \u Unicode escape where necessary), and those strings were then used to manually initialize the arrays.

The Garbage Collector A key feature of Java is its lack of explicit memory-deallocation primitives. All objects are allocated from the runtime heap by using the new keyword, but there is no keyword for deallocating objects. Instead, the garbage collector is responsible for searching through the runtime heap and reclaiming unused memory. This procedure can be done in several ways, but the most common method is to use a mark-and-sweep algorithm—marking objects as reachable or unreachable by following references from other objects (starting with objects that are static to a class or stored in a thread’s stack) and sweeping away all of the unreachable objects. As you might imagine, there are tradeoffs to using garbage collection instead of explicit object deallocation. The main advantages are as follows: Objects are not deallocated prematurely. Unless there is a bug in the garbage collector (and this situation has been known to happen, but for the most part, they are conservative when marking objects as unreachable), an object that is in active use is never deallocated. There is no need to add reference-counting semantics to objects, for example, as is usually done with C++, nor is it necessary to agree on


30

10/17/2000 4:50 PM

Page 30

CHAPTER 2

whom should deallocate an object when that object is passed between two or more methods. Objects are deallocated automatically. If an object serves no useful purpose, it is discarded without the programmer’s intervention. Here are the disadvantages: Garbage collection takes time. At various points throughout a program’s execution, the VM spends some time performing garbage collection. The garbage collection can occur on a regular basis by using a background thread, or it might only occur when the heap runs low on free space. Garbage collection can occur at inopportune times when using a mark-and-sweep-type algorithm, causing the program to pause for no apparent reason. Algorithms that work incrementally can avoid these pauses by spreading the work more evenly as the program runs, but that still slows execution. No control over object allocation and deallocation. Languages such as C++ give the programmer complete flexibility in arranging how objects are allocated and deallocated. Different heaps can be used for different objects, for example, or objects can be allocated directly on the program stack. Java provides a single heap for all allocations and does not permit allocations from the stack. Objects may never be freed. Garbage collection can occur infrequently or not at all. There are no rules. Even when garbage collection does occur, some objects that are no longer needed by the program might not be freed, because active objects hold references to them. The garbage collector cannot do anything about these so-called dangling references.

Avoiding Dangling References The easiest way to avoid dangling references is to explicitly set references to null whenever the referenced objects are no longer needed. Or, if you are using a full J2VM, consider using weak references—a way of marking active but not critical objects for possible deallocation by the garbage collector.

Pros and cons aside, there is little that a programmer can do to influence the garbage collector. Apart from avoiding dangling references


10/17/2000 4:50 PM

Page 31

Java: Fat and Slow?

31

and hinting as to when garbage collection should occur (by using System.gc), the only real concrete influence that the programmer has is over the number of allocations. Allocate objects less often—and allocate smaller objects—in order to reduce garbage collection frequency. In particular, avoid garbage collector thrashing, which means continuously allocating small objects (such as event objects). Reuse existing objects whenever possible, and refer to the programming strategies discussed in the next chapter. The Class Loader A virtual machine needs a way to locate the classes that it needs. This task belongs to the class loader. The class loader is perhaps the simplest part of the execution engine, but it has an important part to play. Its job is to find a class and load it into memory for use by the virtual machine. There are two kinds of class loaders. The system class loader is the basic class loader supplied by the execution engine. This loader always loads the core runtime classes (such as those in the java.lang package) and usually loads the application classes, unless the application supplies its own class loader. In most implementations, the system class loader loads individual class files from a file system or from an archive file (such as a JAR or ZIP file), but it could just as easily load them from read-only memory (ROM), extract them from an executable image, or pull them across a network—whatever is appropriate for a particular execution engine. Non-system class loaders are referred to as user class loaders. A user class loader is a Java class that extends java.lang.ClassLoader in order to provide an application-specific method of locating class files. Web browsers, for example, install a class loader that obtains class files via a Hypertext Transport Protocol (HT TP) request back to a Web server. User class loaders are more limited than the system class loader, because all they do is locate and load class files. Validating the class, converting it to the VM’s internal format, and creating a Class object are tasks delegated to the system class loader. Class loaders maintain a cache of loaded classes to avoid the overhead of reloading classes whenever they are referenced. This measure also


32

10/17/2000 4:50 PM

Page 32

CHAPTER 2

ensures that class initialization—initializing static fields and executing static initialization blocks—only occurs once. In general, then, a Class object cannot be garbage collected until the class loader that loaded it is itself garbage collected. This concern is not normally an issue, except when loading classes dynamically in order to group classes into namespaces. Unlike languages such as C++, Java does not formally define what a namespace is—although it supports them indirectly through the use of class loaders. A namespace is the set of classes loaded by a specific instance of a class loader. Classes in different namespaces are disjoint: in other words, the same class loaded by two different class loaders is considered to be two different classes. Alternatively, two different classes with the same name can be loaded by two different class loaders with no fear of conflict. This capability is useful as a way to run updated versions of classes without having to restart the virtual machine. Servlets, for example, are often loaded by Web servers in this way, enabling the programmer to replace the class files for a servlet without having to restart the server. To ensure that namespaces work as expected, once a class loader loads a class, any class it references is then loaded by using the same class loader. In theory, all of the classes that an application uses—including the core classes in the java.lang package—could be reloaded for each instance of a class loader. In practice, however, this situation does not occur, because one of the first things that a class loader does is delegate the loading of a class to a parent class loader. Prior to Java 2, the parent class loader was always the system class loader. Java 2 introduced true parent-child relationships between class loaders. In either case, the class loader always asks the parent loader to load the requested class first, loading the class itself only if the parent cannot find it. For this reason, a Web browser will not download classes that are loaded locally by the VM’s system class loader (such as classes in the java.lang package). Namespaces have an important limitation. Classes in two different namespaces cannot invoke methods on each other. This condition would seem to make inter-namespace communication impossible, but class-loader delegation works around this limitation. If two classes are loaded by different class loaders but share a base class or interface in common—and the loading of that base class or interface is delegated to


10/17/2000 4:50 PM

Page 33

Java: Fat and Slow?

33

a shared parent class loader—then the two classes can communicate by invoking the methods of the base class or interface. For example, if class A implements java.lang.Runnable, which is almost always loaded by the system class loader, then an object of class B in another namespace can invoke the run method of an object of class A by first casting that object to Runnable. The Class Verifier After a class is loaded (but before it is used), the class is processed by the class verifier. The verifier is an important part of the Java security infrastructure and ensures that any loaded classes are well-formed, that the bytecodes are all legal, that enough stack is allocated for each path throughout the code, that the bytecodes respect Java’s typing rules, and so on. Without the verifier, a malicious programmer could write bytecode that would compromise the system—a dangerous proposition if you allow unknown classes to be downloaded across a network. Verification is really just one step of a process referred to by the JVMS as linking. The other steps are preparation and resolution. Preparation creates the static fields of a class and initializes them to default values and can also perform other processing in order to prepare the class for execution. Resolution validates symbolic names, ensuring for example that the methods or fields that a class refers to actually exist. Linking is an apt name for the three steps, because they are akin to the linking process in languages such as C or C++—except that they occur at run time instead of in a separate, pre-execution step. As you might imagine, the linking process—verification in particular— adds overhead to the execution of a Java program. Extra time is required whenever a class is loaded, and on a slower processor, this situation can significantly lengthen the startup time of a program. The Native Code Interface The final component of the execution engine is not really a component; rather, it is a bridge from Java to the underlying operating system. Any method declared as native is implemented in a language other that Java—typically C—and the native code interface defines how the VM


34

10/17/2000 4:50 PM

Page 34

CHAPTER 2

calls that native code whenever the native method is invoked. The native code interface also defines how native code calls back into the execution engine in order to set and get field values, create new objects, invoke methods, and perform other operations. In Java 1.02, the native code interface was simple and non-portable. Java 1.1 introduced the Java Native Interface (JNI), a portable interface that made it easier to move native code from one machine to another. The portability comes at a price, however, because JNI is slower than its predecessor. When Sun Microsystems sued Microsoft for not completely implementing the Java 1.1 specification, one of the claims was that Microsoft did not include support for JNI in its implementation, preferring instead to use its own interface called Raw Native Interface (RNI). Microsoft, in turn, claimed that RNI was significantly faster than JNI. For the end user, however, it meant that on Windows native code libraries, JNI could not be used with Microsoft’s VM (while RNI-based code could not be used with Sun’s VM). This, of course, contradicted Java’s message of write once, run anywhere.

Runtime Libraries Like C or C++, the Java programming language depends on a library of runtime code to interface with the system and to provide useful routines for common programming tasks. The language itself is thus kept fairly small with few keywords. Writing portable Java programs, however, depends on having a standard set of runtime classes that can be ported to different platforms along with the virtual machine. There are really two runtime libraries that accompany a virtual machine: one is a set of Java classes and the second is the native code required to completely implement those classes. Only the Java classes are visible to the programmer, of course, because the native code is called by invoking native methods on those classes. Unless the execution engine is written entirely in Java, however, there is no way to avoid using the native runtime library, because key parts of the Java runtime library require the cooperation of the virtual machine. Creating threads is a concrete example. Whether an operating system thread is created or whether the VM simulates threads with its own context switching, the VM needs to know that a new thread is being started so that it can


10/17/2000 4:50 PM

Page 35

Java: Fat and Slow?

35

allocate a new runtime stack and perform other important housekeeping chores. The border between the Java and native runtime libraries is blurry. Some things, such as thread creation or writing to the file system, can only be done by the native library. Other tasks, such as copying elements from one array to another, could be done with Java or with native code but are done natively for performance reasons. The programmer does not need to know if a method is native or non-native. The only real way to tell is by looking for the native keyword in the Java runtime library’s source code. The core of the Java runtime library is the java.lang package. A number of its classes are directly referred to by the Java virtual machine: ■■

Object as the root of all class and interface hierarchies

■■

Class for defining information about a class

■■

ClassLoader for loading classes

■■

String for storing string constants

■■

Throwable for declaring and throwing exception information

The VM usually initializes these and other core classes upon startup. Many of the core classes are intertwined, so calling or using one class automatically causes one or more different classes to be loaded and initialized.

The Evolution of Java Although the architecture of Java has not changed much since its initial release, both the language and the runtime environment have evolved over time. Inner classes were introduced. The runtime libraries increased in size and complexity. Performance issues were (and are still) being addressed. In this part of the chapter, we follow Java’s evolution from its initial public release as Java 1.02 to its present-day Java 2 incarnations. Each major release of Java—1.02, 1.1, and 1.2 (renamed Java 2)—focused on a different kind of programming.


36

10/17/2000 4:50 PM

Page 36

CHAPTER 2

Java 1.02: Client Programming Java’s first public release was version 1.02. This release is often referred to as JDK 1.02, where JDK stands for Java Development Kit. At that time, a separate JRE did not exist. To install the JVM and the associated runtime libraries, you had to install the complete JDK (including the Java compiler and other development tools). Or, you had to run Java applications in a Web browser. Either way, Java was associated with client programming—programs that interacted with a user. Applets Embedding a virtual machine in a Web browser is what first brought Java to prominence. Downloading a program across the Internet and running it in a secure environment promised to usher in a new era of zero-install, on-demand application deployment. A new term, applet, was even coined to refer to these programs—which were in theory smaller than stand-alone Java applications.

Building the Java Sandbox The Java sandbox is a combination of different features, all of which work together in order to ensure that applets do not perform risky operations. The first line of defense is the class loader, which ensures that an applet’s classes are only loaded from a single host. The class loader also ensures that different applets run in different namespaces. The second line of defense is the class verifier, which ensures that the downloaded code is well formed. The final defense is the security manager, which is a subclass of java.lang.SecurityManager that the browser installs and that the core runtime classes use to decide whether an applet has the necessary permissions in order to perform certain operations. These operations could include loading native code libraries, installing new class loaders, reading or writing to the file system, and so on. The security manager is not easily extended, however, and is not as fine-grained as some would like. Therefore, in Java 2, a new security mechanism was introduced that supercedes the security manager. The same concepts still apply, however, but now there is more flexibility.


10/17/2000 4:50 PM

Page 37

Java: Fat and Slow?

37

In many ways, Java is an ideal language for applet programming. Not only does it offer binary portability (the capability to download and run class files on any client with a JVM), but it also makes it easy to build a sandbox in which to run classes distributed by untrusted third parties. The sandbox metaphor refers to the walls that a browser erects in order to prevent malicious applets from damaging the system, in the same way that a child playing in a sandbox is contained and is kept out of trouble. With Java 1.02, applets are always untrusted and are always run in a sandbox. Despite the original excitement, serious attempts at applet programming were discouraging. There were several reasons for this discouragement: Long download times. A large applet took a long time to download, especially over the 28K or 56K Internet links that were common in the early days of Java programming. This concern is less of an issue now that more and more high-speed Internet connection options are available, but the problem is still noticeable. What is worse, the downloading was done by using the HTTP protocol, which meant opening a new connection to the web server for each class to be downloaded. Inflexible and limited user interface components. Java 1.02 defined a portable user interface tool kit called the Abstract Windowing Toolkit (AWT), which used components from the underlying native user interface. Those components were by necessity limited to the capabilities that were common across the different operating-system platforms, however. This lowest-common-denominator approach is inflexible. Initially, AWT did not even provide control over basic elements such as tab order. The event model was also hardwired and hard to extend. Restrictive security model. Applets were restricted by the sandbox model. An applet could not store any information on the local machine, for example. The only way around this situation was to turn applet security off and give applets unfettered access to the machine, which of course was undesirable. Of these, the long download time was the most problematic, because users were extremely impatient and found the waits frustrating. The waits could be reduced a bit by archiving the required files into an uncompressed (compression was not supported until Java 1.1) ZIP file,


38

10/17/2000 4:50 PM

Page 38

CHAPTER 2

which the browser then fetched by using a single HTTP command. The most successful applets were either small or partitioned into discrete pieces that were dynamically loaded as needed, with a small splash screen at the beginning that asked the user to be patient while the applet finished loading. Another problem was that not all Web browsers were Java-enabled, meaning that if you included Java applets on your Web site, you were limiting the potential audience. This problem is less of an issue now, but at the time, the browser market was much more fragmented. Even among Java-enabled browsers, however, there were enough differences—and bugs—between implementations to make the promise of write once, run anywhere seem a bit of a joke. Applications If applets were not a success, what about using Java to write standalone applications—programs that are run in a conventional manner— without a Web browser? As a general-purpose programming language, Java has much to offer. We discussed some of its features in the introduction—features such as layout managers, garbage collection, and built-in threading support. An application is not subject to applet security restrictions or encumbered by a lengthy download time. So, on the surface, Java should have succeeded early on as a general-purpose application language (despite the drawbacks that caused Java applets to fail as a programming model). Despite the advantages that are inherent in Java, there were three important and outweighing disadvantages that affected its use for general application programming. First, the Java 1.02 user interface components were limited and inflexible, making it hard to build applications with the rich functionality of native applications. Second, execution speed was also a concern. Java applications were slower and larger (for the reasons we discussed earlier in this chapter) than their native equivalents. And finally, you had to install a JDK on each machine in order to even run the applications—perhaps the biggest drawback of all because of size and licensing issues. Most programming languages never recover from these kinds of problems. Java, however, gained a real following in the programming com-


10/17/2000 4:50 PM

Page 39

Java: Fat and Slow?

39

munity, which saw it as an alternative to C++. Java also had a lot of marketing and development muscle behind it. So, instead of abandoning the language, Sun put out a new version of the language and started to de-emphasize its use as a language for client programming.

Java 1.1: Server Programming Java 1.1 was much more of a change than the version number implied. Java 1.1 was more like a 2.0 than a 1.x release. Among the important changes were the introduction of inner classes, a new event model for user interface components, lightweight user interface components, internationalization, class reflection, object serialization, remotemethod invocation (RMI), and others. (If you are curious, most of the changes are listed and explained on Sun’s Web site at http://java.sun. com/products/jdk/1.1/docs/relnotes/features.html). Some changes were separate from but dependent on Java 1.1,such as the Swing set of user interface components and the JavaBeans component model. Java 1.1 also brought the Java Database Connectivity (JDBC) database interfaces into the core runtime library. Although several of the changes had significance from a client-programming point of view, many of them were more important for server programming— programs that ran on a server machine with no direct user interaction, or the parts of a client program that communicated with the server. Let’s briefly examine the major changes, especially ones that are applicable to server programming. Just-in-Time Compiling Of particular importance to Java 1.1 was the introduction of just-in-time compiling. A just-in-time (JIT) compiler converts bytecode to native code as a Java program runs. The compiler does not convert the entire program at once; instead, it works piece by piece and converts only the code that is about to be executed. Consider, for example, a simple code fragment: int j = 0; for( int i = 0; i < 10000; ++i ){ j += i * 2; }


40

10/17/2000 4:50 PM

Page 40

CHAPTER 2

Calling this fragment 1,000 times took about 2,000 milliseconds using JDK 1.1 but without JIT. Enabling the JIT reduced the execution time to about 60 milliseconds. (These numbers are meant to be representative only, not formal benchmarks.) For CPU-bound code, a JIT makes a significant difference. The biggest drawback, of course, is that extra time is required to compile the code before it is first executed. For this reason, a JIT can actually slow down the execution of code that is called only once or twice.

Disabling the JIT Disabling the JIT in Java 1.1 is quite simple. Just use the –nojit option when using the java command. Doing this allows you to see complete stack traces when an uncaught exception is thrown. There is no equivalent option in Java 2, however. In order to disable the JIT, you have two choices: use the –Djava. compiler= option (in other words, set java.compiler to the empty string) when invoking the java interpreter, or rename or delete the runtime environment’s JIT module. To perform the latter action, look for a shared library or dynamic link library (DLL) with a jit in its name. In Windows, for example, the JIT is a DLL called symcjit.dll.

Although Sun included a JIT with Java 1.1, it also announced that it was working on a more effective and ambitious acceleration technology called HotSpot. HotSpot was not released until after Java 2 was out, however, so we will defer our discussion of it until then. Object Serialization Objects in Java 1.1 can save their internal state to a stream in a process that we refer to as serialization. Not all objects are serializable, and not all the internals of the object are saved. The class gets to choose how its state should be saved. Once saved, a new object can later be recreated or deserialized directly from the serialization data. Unlike some persistence models, serialization is quite robust. Changes can be made to a class without losing the capability to recreate an object saved by using the old version of the class.


10/17/2000 4:50 PM

Page 41

Java: Fat and Slow?

41

Serialization enables you to store Java objects for later reuse, such as in a database. This function also enables you to pass objects by value across a network connection. RMI One of Java’s great strengths is that its core runtime library includes classes for network communication. Java 1.1 extended this functionality with the concept of RMI, enabling a client Java application to invoke methods on an object running in a remote server. The client uses a proxy object to represent the real, remote object. Because the proxy and remote objects implement the same interface, the application calls methods on the proxy as if it were directly calling methods on the remote object. The client only requires a few changes in order to use RMI to obtain proxy instances and to handle network errors. Most of the work is done on the server, and even then it is not that hard. The RMI infrastructure hides all of the messy details. RMI does not pretend to be an interoperable protocol; rather, it is strictly for Java-to-Java distributed programming. A Java VM is required on both ends, and object serialization is used to pass parameters. Database Connectivity In Java 1.1, the JDBC classes and interfaces became part of the core Java run time. Databases play an important role in many applications, and JDBC provides a standard and vendor-independent way to communicate with database servers via a JDBC driver. JDBC actually predates Java 1.1 but was defined after 1.02 was already out and did not come as part of the JDK, therefore requiring a separate download and installation. Because it was not part of the core runtime library, none of the 1.02-only Web browsers supported it, requiring the JDBC classes themselves to be downloaded with any applet that used them. As Java started being used extensively for server programming, work began to update the JDBC standard to include features such as connection pooling and shared transactions in preparation for the next major release of Java.


42

10/17/2000 4:50 PM

Page 42

CHAPTER 2

Browser Support for JDBC Prior to 1.1 The JDBC classes and interfaces are defined as part of the java.sql package, but browsers that support only Java 1.02 do not have them installed. Normally, this situation would not be a problem. The classes would be downloaded into the browser with the rest of the applet, but browsers will not (for security reasons) download classes in the java package or in any of its subpackages. The only way around this restriction is to rename the package and recompile the JDBC source files in order to produce a new set of identical but downloadable classes. Sun recommended that vendors should use the jdbc.sql package, and that is what most of them did. Once the newer browsers supporting Java 1.1 (and thus, the java.sql package) overtook the older browsers, the problem largely went away. For a while, though, vendors were supporting two versions of their JDBC drivers: one for use with Java 1.02, and one for Java 1.1 or later.

JavaBeans Java 1.1 defined a new component model called JavaBeans for sharing and reusing objects. A JavaBean component (usually referred to simply as a bean) is a self-describing Java class that exposes attributes such as properties (with accessor methods), operations as methods, and notifications as events. Beans are meant to be plugged into a development environment such as PowerJ, JBuilder, or Visual Café, which then asks the bean for a description of its features (through a process called introspection) and enables the user to manipulate the bean visually through development aids such as property lists. The JavaBeans specification is really directed at client development because it does not deal with server-side issues such as component reuse and transaction participation. This realm was left to the next version of Java and the Enterprise JavaBeans specification. Servlets As Web applications—server-based applications that generate Hypertext Markup Language (HTML) pages as a user interface—gained in popularity, it became necessary for Sun to define a Web server extension mechanism in Java as an alternative to languages such as Perl or


10/17/2000 4:50 PM

Page 43

Java: Fat and Slow?

43

PHP3 or to interfaces such as ISAPI or NSAPI. The solution that Sun came up with was the servlet programming interface. Servlets are not part of the core Java run time but are instead considered a standard extension to Java. The servlet classes are part of the javax.servlet package. Support for servlets was at first limited to Sun’s own Web server, which could easily support them because it was itself written in Java. Other Web servers had to first embed a Java VM in order to run servlets or else delegate the running to a separate server. The latter option is the most common way to run servlets within a non-JavaWeb server. Browsers and the Java Plug-In The virtual machine and runtime classes used by a Web browser are tightly coupled to the browser. Upgrading a 1.02-only Web browser to support Java 1.1 was not just a matter of copying some new files into the browser’s installation directory; rather, it required support from the vendor of the browser. New browser versions were released in order to support Java 1.1. Unfortunately for applet developers, users were in no hurry to install the newer browsers. Corporations were particularly reticent to upgrade company-wide installations without extensive testing or without a compelling reason. The applet developer had to choose between developing a 1.1-only applet and requiring users to upgrade their browsers or else stay with Java 1.02 and its limitations. To make matters worse, Netscape upgraded its browser in two steps: the first step added all of the core Java 1.1 classes except the new user interface classes, which were released in a later upgrade. The partial support for Java 1.1 was confusing to users. Microsoft’s browser had some differences, as well. In particular, Internet Explorer did not include support for JNI, preferring instead Microsoft’s own native interface. This issue and others led Sun Microsystems to sue Microsoft for not living up to the terms of its Java licensing agreements. Because of these problems, Sun developed and released the Java Plugin, a complete Java 1.1 runtime environment that could be installed as a Web browser extension. The user can easily install the Plug-in and can upgrade it at any time with bug fixes or new features without affecting


44

10/17/2000 4:50 PM

Page 44

CHAPTER 2

the browser. Sun can release a new version of the Plug-in whenever it releases a new version of Java. From the developer’s point of view, the Plug-in is a mixed blessing. By requiring its use, developers ensure that their applets will run in a known and stable environment. The Plug-in is not available for all platforms and browsers, however, and it also requires changes to be made to the way in which the applets are embedded in an HTML page. JRE As we already discussed, the Java 1.02 runtime environment was only available as part of the larger JDK. With Java 1.1, Sun separated the runtime and development pieces of the JDK and offered the runtime environment in a separate download called (not surprisingly) the JRE. Besides being smaller than the JDK—about 3MB on Windows compared to the 20MB plus of the JDK—the JRE is also freely distributable, which enables developers to include it as part of their applications (instead of licensing the complete JDK from Sun or forcing the end user to obtain and install the JDK or JRE separately from the application). Once installed, the JRE also registers itself with the operating system, enabling other applications to discover its existence and to not have to install a second JRE (although that is still an option if an application requires a specific version of the runtime environment).

Java 2: Enterprise Programming Unlike the transition from Java 1.02 to Java 1.1, the changes between Java 1.1 and Java 1.2 were not as radical. We are not saying that the changes were not significant, however. The introduction of the collections classes, a new finer-grained security model, a new version of JDBC, and a new VM implementation are just a few. Developers did not have to rewrite their code so much as learn about a large number of new application programming interfaces (APIs). Many of these new APIs were focused on enterprise programming—programming for corporate environments where applications interacted with other non-Java programs and had special requirements related to high availability and scalability. And along the way, the Java platform was renamed and split into multiple editions.


10/17/2000 4:50 PM

Page 45

Java: Fat and Slow?

45

New Names and New Beginnings The collection of Java-related technologies from Sun was always referred to as the Java platform or just Java. Developers would refer to a Java platform by using the version number of its JDK. At times, it was not clear whether the term Java 1.x referred to the version of the Java programming language, the version of the virtual machine, or the version of the JDK. To clarify the situation and also to generate some excitement for its new release of the Java platform, Sun renamed the platform the Java 2 Platform. The JDK became the Java 2 Software Development Kit (SDK). The version number of the SDK—which many developers still refer to as the JDK (a term that we will continue to use throughout this book)—still followed the old numbering system, however. The first SDK was version 1.2, not version 2.0. The 2 in Java 2 does not really refer to a specific version; rather, it refers to a new marketing mechanism for Java technology. But the renaming did not stop there. One Version, Three Editions The sheer number of programming interfaces available in the Java 2 Platform is almost embarrassing. Many of these APIs were (and are) being defined by a new process directly involving interested parties external to Sun—a process referred to as the Java Community Process. This process was developed partly in response to criticisms that Sun was not capable of defining new interfaces quickly or objectively enough in order to satisfy market requirements. Sun realized early on that only a subset of the new classes defined by it or by the Java Community Process could become part of the core runtime environment. For one thing, the set of core classes was large enough already, as we will see in a later section, and some of the new classes would only interest small groups of Java programmers. This realization predates Java 2 and is why Java 1.1 introduced the concept of standard extensions, which was further formalized in Java 2. Another motivation for Sun not to include everything in the core run time was to generate more revenues by charging licensing fees for some of the more advanced features. Apart from charging fees to development


46

10/17/2000 4:50 PM

Page 46

CHAPTER 2

tool vendors and other corporations that wanted to embed Java in their software or hardware in ways that were not covered by the free-ofcharge JRE license, Java was in many ways a loss leader for Sun. Java was available for free to most developers as a way to promote and sell Sun Microsystems products and solutions. Separate licensable packages would enable Sun to recoup more of its investment in Java. For these reasons, Sun split the Java 2 Platform into three editions, referred to as Standard, Enterprise, and Micro. Each edition targets a different set of application developers. Java 2 Standard Edition (J2SE) The Java 2 Standard Edition, or J2SE, targets conventional Java applications. These are client applications running on desktop computers (either in a Web browser or as stand-alone applications) or server applications that do not require advanced APIs or interoperability with other languages or object models. In other words, J2SE is the core of what would have been called Java 1.2 and of any future versions. J2SE does not require any real change on the part of Java developers. Apart from API additions, many of the changes in Java 2 as compared to Java 1.1 are cosmetic: ■■ ■■

Swing is now part of the core run time. The JDK directory structure has been revised to separate the JRE from the rest of the JDK.

■■

A new version of Javadoc generates better API documentation.

■■

Standard extensions have been formalized.

There were many internal changes, however. Various performance enhancements were made, including the development of the HotSpot execution engine. HotSpot is based on technology that Sun acquired with much fanfare in response to criticisms that Java’s performance was extremely poor. Unlike a JIT, which indiscriminately compiles Java code upon first use, HotSpot profiles the code as it runs in order to determine which parts require optimization. The execution engine also includes an improved garbage collector and performs faster thread synchronization. You can read about HotSpot on Sun’s Web site at http://java.sun.com/products/hotspot/. There are currently two versions of HotSpot available, and these are referred to as the HotSpot Client


10/17/2000 4:50 PM

Page 47

Java: Fat and Slow?

47

VM and the HotSpot Server VM. The former is tuned for use on clients (applications start more quickly), while the latter is tuned for serverside use (where applications are likely to run longer and can benefit from more optimization upon startup). Java 2 Enterprise Edition (J2EE) J2EE is a superset of J2SE that is geared specifically to enterprise programming. While J2SE can be used to build server programs, J2EE addresses the needs of corporations that need to write server-based programs that support thousands of clients and that must also interact with legacy (in other words, non-Java) systems. A full description of J2EE is beyond the scope of this book, but in broad terms, J2EE focuses on three elements: Application deployment. J2EE includes the tools to enable you to seamlessly and securely deploy applications to clients. This function includes support for thin-client computing by using Java Server Pages as well as enhancements to the Java Plug-in. Interoperability with legacy systems. J2EE adds support for CORBA/IIOP and extensible markup language (XML). Enhanced component-based development. By using Enterprise JavaBeans, developers can write scalable, transaction-aware components for use in application servers. For more information, consult any of the many books about J2EE or go straight to the J2EE homepage at http://java.sun.com/j2ee/. Java 2 Micro Edition (J2ME) Finally, there is J2ME. This application is, of course, the focus of this book. We will defer all discussion of J2ME until Chapter 4, except to say that J2SE is simply too large for many small devices. J2ME slims it down by removing or rewriting key parts of the core runtime environment. What Is Next for Java 2? Many parts of the Java 2 platform are quite mature, and many are just developing. J2ME, for example, is still new, as is the Enterprise Edition.


48

10/17/2000 4:50 PM

Page 48

CHAPTER 2

Both of them will be the focus of new development. New APIs for the Standard Edition are continually being developed through the Java Community Process, however, and you can expect to see occasional enhancements to J2SE—especially those that carry through to the other two editions. We do not foresee any radical changes in the immediate future.

The Devolution of Java Although Java has evolved greatly in its transition from Java 1.02 to the Java 2 platform, in some sense it has also devolved from its roots as a language for programming consumer appliances. Consider, for example, the size of the Java runtime libraries. In JDK 1.02, the classes. zip file was 1.3MB in size (uncompressed) and contained just fewer than 600 classes. (All numbers are from Sun’s implementations for the Windows operating system.) The same file in JDK 1.1.7 is 8.34MB in size and contains more than 1,600 classes. (To be fair, though, the JRE 1.1 has a smaller set of classes because it excludes internationalization classes. But the JDK does include them all.) For JDK 1.2.2, the Standard Edition rt.jar file (the equivalent of classes.zip) is 9.7MB in size and contains more than 4,300 classes. Even without worrying about the rest of the execution engine, we can see that J2SE is simply too large for most small computing devices. The obvious solution is to start cutting components from the runtime environment. But what do you cut, and what do you leave in? Do you cut at the class level or at the method level? Can you reduce the interdependencies between the core classes? How do you deal with differences in basic capabilities? Some devices have file systems and others do not, so do you leave java.io.File in or take it out? Can you perform any of these actions and still have the program run in a normal Java environment (such as J2SE or J2EE)? We will answer these questions and more in Chapter 4, which introduces J2ME.


10/17/2000 4:50 PM

Page 49

Java: Fat and Slow?

49

Chapter Summary In this chapter, we took a close look at the architecture of Java and its evolution from a client-oriented programming language to a platform that is capable of running enterprise applications. But before we discuss J2ME, let’s take some time to discuss some useful programming strategies for small devices.


10/17/2000 4:50 PM

Page 50


10/17/2000 4:50 PM

Page 51

CHAPTER

3


T

he limitations that are inherent in small devices require you to change the way in which you code your applications. Before we move on to discussing specific Java implementations that are aimed at small devices, let’s take some time to develop some general programming strategies for small devices.

If in Doubt, Do Not Use Java The first strategy to consider is simple, if perhaps a bit heretical. You should avoid using Java until you are sure that it meets your application requirements—not only in features, but in performance. This statement might seem obvious, but becoming blinded by all of the hype that accompanies Java and the enthusiasm that it generates is easy. A programmer who codes in Java on desktop or server systems is understandably reluctant to abandon Java when moving to smaller devices, but this reluctance is detrimental to the project.

51


52

10/17/2000 4:50 PM

Page 52

CHAPTER 3

The reality is that Java on small devices is still an immature technology with a lot of room to improve and evolve, as we will see later in this book when we discuss the individual specifications and implementations associated with the Java 2 Micro Edition (J2ME). Possibly, the Micro Edition meets your needs today, or perhaps it does not. There may also be new licensing issues to deal with if you need to include a Java runtime environment with your application. If you absolutely want to use Java, start with a simple, non-critical project. Writing your mission-critical software in Java is not the way to experiment with a device’s Java support. You should instead bite the bullet and write your software by using C/C++. We are not saying that Java is not a viable programming language. Rather, the technology is so new that not all devices will support it— and device limitations on central processing unit (CPU) speed and memory capacity might not make it possible to write Java applications that run (or run with acceptable performance) within those limits. For example, the initial beta releases of the KVM—which is a small Java interpreter that we will discuss later—is a key part of the Micro Edition and could not deal with programs larger than 64K when running on Palm devices. This situation made it difficult to write serious applications that could run in that environment.

Move Computation to the Server Once you have decided to take the plunge with Java, the next strategy is almost as simple: avoid running computationally intensive tasks on the device. Instead, let a server computer run them for you. The alternative is to tie up the device (potentially even making its user interface unresponsive) for several seconds or minutes—delays that your users will find unacceptable. In many ways, this process is similar to deploying a thin-client Web application where most of the logic is in the Web server, leaving the Web browser to handle the user interface. Finding the right balance between what to do with the device and what to do on the server is tricky and depends on both the application and the device’s connectivity. Obviously, a device that has a wireless radio can connect to a server more often than a device that has only cradlebased communication. But the cradle-based communication is faster


10/17/2000 4:50 PM

Page 53


53

and essentially free, while wireless communication can be slow and expensive. Therefore, even if you can connect to the server on an asneeded basis, it might be time-prohibitive or cost-prohibitive to download large amounts of data. Letting the server do some of the work does not have to be complicated. Even simple things that are done on the server can make a big difference in your application’s responsiveness. For example, rather than downloading data from the server and sorting it on the device, let the server sort it for you. The download time will not improve, but you will save the time that your application spent sorting the data after the download. Later, after changes have been made to the data, the application can resort the data—and you will benefit because the data will be in near-sorted condition already. Of course, in many cases you have no choice but to partition the application between the device and a server. Often, there is just too much data to put on the device itself, or else the data is too sensitive to leave on an unsecured machine.

Simplify the Application After moving as much as you can to the server, the next step is to simplify the application. This step is best done during application design, of course, and as usual, some work and prototyping ahead of the actual coding will save you time and work later. The most obvious simplification for your application is to remove unnecessary features. Consider each feature of your application carefully. Is this feature really needed, or could users get by without it? Removing code is the simplest way to reduce the size of an application. If you need a feature only occasionally, consider moving it and similar features into a second, auxiliary application. Users can then remove the auxiliary application if they do not need those features. Internationalized programs are often large because of all of their resources—text strings, bitmaps, and other locale-sensitive data— which are required to support various national, linguistic, and cultural scenarios. For desktop programming, it is common to ship a single version of the application that can handle the different locales transparently.


54

10/17/2000 4:50 PM

Page 54

CHAPTER 3

Performing this task in Java is quite easy because of its support for resource bundles, formatters, and other locale-sensitive classes. The resources are often located and loaded dynamically, based on the current locale. As an optimization, the application installer often installs the files for a single locale, because this procedure cuts down on the disk space that the application requires. While a desktop system’s total storage capacity is large, it is not infinite. To save space, then, you will want to use a similar strategy and build separate versions of your application for each locale, instead of relying on automatic locale detection and adaptation. After removing unnecessary features, the next step is to reuse the user interface wherever possible. A large portion of an interactive application is spent dealing with the user interface. Look for opportunities to reuse parts of the user interface whenever possible. Not only does this reuse make the application smaller, but it makes it easier for the user to learn the application. Finally, try to provide a single-action path for each feature. Use simple, consistent, and unique ways to invoke particular features. This approach is less confusing for your users, and there is less code for you to write. Also, this approach forces you to look carefully at your overall user-interface design. You should always group the commonly used features so that they are quickly accessible by users with as few button/ key presses or pen strokes as possible. Do not forget, though, that you will have different kinds of users. As you simplify your application, be sure to leave in the shortcuts and features that your power users will appreciate. If you think that this advice seems contradictory, you are right. Everything is a delicate balancing act. You cannot remove everything from your application, after all. It is really just a matter of fine-tuning its features for smaller devices.

Build Smaller Applications Another step that you can take is building smaller applications. A smaller application takes up less memory on the device and requires less time to install. This type of application will usually require a shorter startup time as well, especially with a language such as Java


10/17/2000 4:50 PM

Page 55


55

where a significant part of the startup time is spent verifying and otherwise preparing the individual classes that an application requires. Smaller applications are also cheaper to install if you happen to be downloading it onto the device via a wireless network. For installation purposes, you want to package your Java applications as compressed Java Archive (JAR) files whenever possible. This technique is the most obvious way to build a smaller application, but it does increase the load time for the application because of the time that is required to decompress the individual class files. You might have no choice, however. A JAR file might be the only packaging that is acceptable to the runtime environment. (If startup time is an issue, try building an uncompressed JAR file and determine whether that helps. It might be worth the extra cost in terms of memory footprint and installation/ download time.) To further reduce the size of your application, consider using a tool called an obfuscator. An obfuscator makes the code and the symbolic information in your class files harder to read by converting identifiers to short, undistinguished character sequences and by performing other tricks that still result in a legal class file. A side effect of the obfuscation is a reduction in the size of the final class file. Most obfuscators will also remove unnecessary and unused methods and classes, which of course leads to further savings in class-file size. You will find some freely available obfuscators on the book’s companion Web site.

Remove the Public Members As a rule, obfuscators will not remove public members (fields or methods) of a class, because other classes might call those members. If you think about it, the only members that are safe to remove are private members. If you are building a complete application that safely stands by itself, however, you can usually tell the obfuscator to consider the classes that your application uses to be a closed set of classes. You can also tell it to treat any public, package, or protected members as if no one outside the closed set will refer to them. This technique enables the obfuscator to remove more code than it would normally be capable of removing. Still, your best bet is to make as many members as you can private. The fewer public members you have, the easier it is to optimize the code.


56

10/17/2000 4:50 PM

Page 56

CHAPTER 3

Of course, reducing the number of classes that your application uses is really the simplest way to reduce its memory footprint. Remember that every class or interface that you create generates a separate class file, including nested, inner, or (especially) anonymous classes.

Use Less Memory at Run Time As we have discussed, the runtime memory capacity of a small computing device can be quite limited. Sometimes these limits are not obvious, however. For example, the Palm operating system (OS) defines two kinds of memory: dynamic and storage. Dynamic memory stores the application’s runtime data—in particular, its stack and its runtime memory heap. Storage memory is write-protected, persistent memory. The amount of dynamic memory available to an application varies from 32K to 256K, and the remainder of the device’s RAM is storage memory. Even if a device has 8MB of RAM, the 256K limit on dynamic memory is important. If more memory is required, the application must use storage memory, which is slower to access due to the write protection. What follows are some simple tips and examples of how to reduce the amount of runtime memory that your Java applications use.

Use Scalar Types Each object that you use must be allocated from the runtime memory heap. There is no way to declare objects that are allocated on the stack. The object’s constructor runs as part of that allocation process. Therefore, each object that you allocate impacts your application’s performance as well as the amount of memory that it requires. To reduce the number of objects that are allocated, consider using scalar types—the non-object types such as int and boolean—in place of objects whenever possible. Consider the methods of java.awt.Component as an example. These methods define two variants of the setSize method: public void setSize( int width, int height ); public void setSize( Dimension size );


10/17/2000 4:50 PM

Page 57


57

The first variant takes only scalar types, while the second one requires you to allocate a Dimension object. When you call the first variant, you generate a bit more code—but you avoid an object allocation. Besides, the second variant is defined as follows: public void setSize( Dimension size ){ setSize( size.width, size.height ); }

Although a call to the second variant is a bit cheaper in terms of bytecode generation, you end up executing more code in addition to incurring the object-allocation expense.

Do Not Depend on the Garbage Collector As we saw in the previous chapter, the garbage collector is an important part of the execution engine. Without it, Java programmers would have to explicitly free allocated objects, which adds complexity to programs and requires the use of object-management schemes such as reference counting. The garbage collector frees you from having to worry about who is using an object and about determining if the memory can be reclaimed by the system. Although a garbage collector is handy, it does not excuse you entirely from the memory-management process. If you allocate too many objects too quickly, the garbage collector might have trouble keeping up and collecting unreferenced objects. Your application might pause at inopportune times as the garbage collector works to catch up. Also, as the peak memory usage increases, the execution engine will grab more and more memory from the system in order to allocate objects. When the garbage collector finally catches up, that memory is rarely (if ever) returned to the system, even if most of it is not required by the application anymore. This memory is now effectively unavailable for use by other applications.

Help the Garbage Collector Be sure to help the garbage collector do its work by setting object references to null whenever you are finished with them. For example,


58

10/17/2000 4:50 PM

Page 58

CHAPTER 3

you might define a deinitialize method for a class in order to explicitly clear out its members: public class MyClass { private Object someObject; public MyClass( Object obj ){ someObject = obj; } public void deinitialize(){ someObject = null; } }

By clearing out object references, you make it easier for the garbage collector to find and reclaim unreferenced objects. This technique is simple and does not add too much code to your classes. Another way to help the garbage collector is to use weak references, which premiered in Java 2. Weak references are instances of special system classes that reference objects that you would like to keep active and in memory but that can be garbage collected by the system if necessary in order to free some memory. Weak references are not usually supported on small devices, however, so you should not depend on their presence. Watch out for garbage-collection bugs. Sun’s garbage collector in Java 1.1, for example, prematurely frees singleton objects (objects that are supposed to be created only once and that are stored in a static class member) if the singletons are not referenced from an active thread. The workaround in this case is to start a thread that does nothing except keep a reference to the singleton.

Use Lazy Instantiation Another technique to reduce overall and peak memory usage is to only allocate objects as they are needed. We usually refer to this technique as lazy instantiation. In this approach, you check for a null object reference (remember that Java guarantees that the members of a class are always initialized to a default value, which makes it easy to perform this kind of check):


10/17/2000 4:50 PM

Page 59


59

public class LazyClass { private Vector v; // defaults to null public Vector getVector(){ if( v == null ) v = new Vector(); return v; } }

If you are using multiple threads, however, be sure to use the double check technique described later to ensure that only one object ever gets created.

Release Resources Early Whether you are writing for small devices or for desktop systems, it makes sense to release resources—database connections, network connections, files, and so on—as soon as possible. Do not hang onto them longer than necessary. Not only does this procedure free the resource for use by another application, but it also enables the system to free any memory associated with that resource. In particular, do not depend on finalizers to free resources. Finalizers might never run, and as we will see later, they are not even supported by some Java interpreters. Always provide methods for explicitly freeing the resources, and document their use. If your Java platform does support finalizers, however, it is still a good idea to define finalizers for each resource-using class just to ensure that the resources are really freed (in case the programmer forgot to release them).

Reuse Objects One technique that can pay good dividends is to reuse objects instead of continually allocating and abandoning them. Basically, what you want to do is provide methods to initialize and deinitialize an object and provide a way to cache unused objects. Consider the following class, for example: public class ObjHolder { private Object _value;


60

10/17/2000 4:50 PM

Page 60

CHAPTER 3 public ObjHolder( Object value ) { _value = value; } public Object getValue() { return _value; } }

This class is trivial but is enough of an example for our purposes. First, we modify it by adding initialization and deinitialization methods: private void initialize( Object value ) { _value = value; } private void deinitialize() { _value = null; }

Then, we modify the constructor by making it private and by having it call the initialize method: private ObjHolder( Object value ) { initialize( value ); }

We could also choose to keep the constructor public or simply define a no-argument version that does not call the initialize method. Because we have chosen to make the constructor private, we have to provide a static function to create one for us. This static function will also keep a cache of objects for us, which for simplicity, we will limit to a single object at a time: private static ObjHolder _cache; // single object cache public static synchronized ObjHolder allocate( Object value ) { ObjHolder holder = _cache; if( holder == null ){ holder = new ObjHolder( value ); } else {


10/17/2000 4:50 PM

Page 61


61

holder.initialize( value ); } _cache = null; return holder; }

Also, of course, we will define an equivalent function to place objects back into the cache: public static synchronized void deallocate( ObjHolder holder ) { holder.deinitialize(); if( _cache == null ){ _cache = holder; } }

Objects of this class are now allocated and freed by using this sequence: ObjHolder holder = ObjHolder.allocate( somevalue ); ..... // use it ObjHolder.deallocate( holder ); // free it!

Be careful with the size of your cache. If it is too large, then your class will be holding references to objects whose memory could otherwise be reclaimed. The size of the cache depends on the application, and you might not be able to determine an appropriate size except by running the application and gathering some statistics. If your cache needs to be thread-safe, as in the previous example, you will also pay a time penalty because of the synchronization primitives that you need to use. Therefore, if you can guarantee that a single thread will use the cache, you will be better off and will be able to avoid the synchronization overhead.

Avoid Exceptions Java’s built-in support for exception handling is extremely convenient. Exceptions are sometimes overused, however. In general, you want to reserve exceptions for unusual or unexpected (exceptional) situations.


62

10/17/2000 4:50 PM

Page 62

CHAPTER 3

Errors that are expected to occur in the normal course of running an application should be handled through other means. By avoiding exceptions, you can reduce the size of the class files and also reduce the number of objects that are allocated (because each exception throws an exception object).

Code with Performance in Mind With a small device, performance is critical. Always write your code with performance in mind. Here are a few suggestions to explore. You can also consult any book on good coding practices for more tips, because a lot of these books are independent of any particular programming language. Also, do not forget to use the Java compiler’s optimization options for producing tighter code.

Use Local Variables It is generally slower to access class members than to access local variables. If you are using the same class member over and over, such as within a loop, it might make sense to assign the value to a temporary variable stored on the stack and to use that temporary variable in place of the class member. Again, be careful when dealing with data that is shared by multiple threads. This optimization might not make sense. Using local variables also makes sense when dealing with arrays. Each time an array element is accessed, the Java interpreter performs a bounds check in order to ensure that the array index is valid. If you access the same array element more than once, store it in a local variable and access it from there instead. For example, instead of: Char[] buf = ....; // get an array somehow for( int i = 0; i < buf.length; ++i ){ if( buf[i] >= '0' && buf[i] = '0' && ch 6 ){ size = 3;

endGame(); cellsPerRow = size; numCells = size * size; numTotals = 2 * size + 2; player1Wins = size * PLAYER_1; player2Wins = size * PLAYER_2;


10/17/2000 4:50 PM

Page 71


71

if( cells == null || cells.length < numCells ){ cells = new byte[ numCells ]; } int i; for( i = 0; i < numCells; ++i ){ cells[i] = NO_PLAYER; } if( totals == null || totals.length < numTotals ){ totals = new int[ numTotals ]; } int initial = cellsPerRow * NO_PLAYER; for( i = 0; i < numTotals; ++i ){ totals[i] = initial; } calculateIndices(); gameStarted = true; notifyGameStarted(); }

The actual cell indices are calculated by calculateIndices, and we will leave the details of this process for Appendix A. newGame also defines numCells, player1Wins, and player2Wins and sets gameStarted to true in order to indicate that a game is in progress. Of course, calculateTotals will never be called unless we provide methods to set the value of a cell: public void setCellState( int row, int col, int value ){ setCellState( row * cellsPerRow + col, value ); } public void setCellState( int index, int value ){ if( !gameStarted || index < 0 || index >= numCells ) return; if( cells[index] != NO_PLAYER ) return; cells[index] = (byte) value calculateTotals(); notifyGameUpdated( index, value ); if( isGameOver() ){ endGame(); } }


72

10/17/2000 4:50 PM

Page 72

CHAPTER 3

For convenience, we enable cell values to be set by row and column or by index. Only empty cells can have their values set. After a cell is set, we notify any listeners about the new value and check to see whether the game is over. Listeners implement the TicTacToeModelListener interface, which defines these three methods: void gameStarted( TicTacToeModel model ); void gameUpdated( TicTacToeModel model, int index, int value ); void gameOver( TicTacToeModel model );

The model class itself defines methods for notifying the listeners, as with the notifyGameOver method: private void notifyGameOver(){ Enumeration e = listeners.elements(); while( e.hasMoreElements() ){ ((TicTacToeModelListener) e.nextElement()).notifyGameOver( this ); } }

Also, of course, TicTacToeModel defines an addListener method just as we did previously, except with the additional feature that if a game has already started, the newly registered listener is immediately notified of this fact via the gameStarted method. Finally, the model class defines methods such as isGameOver, getCellState, getWinner, and getWinningCells that listeners and other interested parties can use to determine the status of a game.

Optimizing Event Notification The TicTacToeModel class notifies listeners in a straight-forward fashion by building an enumeration of registered listeners and cycling through that enumeration. This process works well for our situation, because not many events are triggered. If you are dealing with events that are triggered frequently, however, you might want to change the notification code to use something other than an enumeration and to perform other optimizations based on the number of registered listeners. As always, be sure to keep multithreaded programs in mind when performing these optimizations; otherwise, an event that is triggered while another thread is adding itself as a listener could cause an exception (because the set of listeners is in flux).


10/17/2000 4:50 PM

Page 73


73

The complexity of this model might surprise you. Perhaps tic-tac-toe is not quite as simple as you thought. You will see the benefits of the model when we write the actual game in Part 3.

Chapter Summary In this chapter, we looked at some general strategies for small-device programming, which finishes this first part of the book. The next part introduces us to the J2ME and the specifications that define this application.


10/17/2000 4:50 PM

Page 74


10/17/2000 4:50 PM

Page 75

PA R T

Java 2 Micro Edition (J2ME) Specifications

TWO


10/17/2000 4:50 PM

Page 76


10/17/2000 4:50 PM

Page 77

CHAPTER

4

Java 2 Micro Edition (J2ME)

A

t the JavaOne Conference in June 1999, Sun Microsystems announced a new edition of the Java 2 platform: the Java 2 Micro Edition (J2ME). The purpose of the Micro Edition is to enable Java applications to run on the small computing devices that we discussed in the first chapter. Although the J2ME announcement was interesting, what really caused a stir was the preliminary release of a new Java virtual machine (JVM) that could run simple Java programs on Palm devices. The initial frenzy, however, was soon tempered by the need to develop formal specifications for J2ME and to finish the work on the new virtual machine. It would take almost a year for the first production release of J2ME to become a reality, however. In this chapter, we discuss what J2ME is and what it is not. We look closely at one of its key pieces, a new virtual machine optimized for small devices called the KVM. We also look at how other related pieces of Java technology—things such as EmbeddedJava and PersonalJava—fit into the J2ME puzzle.

77


78

10/17/2000 4:50 PM

Page 78

CHAPTER 4

Introducing the Micro Edition Sun Microsystems’ Web site describes J2ME this way: . . . Java 2 Platform, Micro Edition is a highly optimized Java runtime environment targeting a wide range of consumer products, including pagers, cellular phones, screenphones, digital set-top boxes and car navigation systems.

The key phrase from this description is “highly optimized Java runtime environment.” We must emphasize that J2ME does not define a new kind of Java but instead adapts Java for consumer products that incorporate or are based on some kind of small computing device. A Java application written for the Micro Edition will also work with the Standard Edition and even the Enterprise Edition, assuming the APIs it uses are available in each edition. There are constraints, but the architecture of Java never changes. Writing Java code that runs unchanged in all three editions is possible. Cross-edition portability is not normally a requirement, however, because what you are really interested in is cross-device portability. In other words, will the application work correctly on a specific set or family of devices? Let’s look at some of the key features of J2ME and see why the answer to this question is a simple but resounding yes.

A New Virtual Machine The Java 2 Standard Edition (J2SE) platform currently supports two different virtual machines: the so-called classic virtual machine and the newer HotSpot virtual machine. Swapping out the classic virtual machine and replacing it with a HotSpot virtual machine gives J2SE programs an immediate and measurable performance boost without making any other changes to the runtime environment. If a new virtual machine can be designed from the ground up in order to boost performance, why not design a virtual machine to run in a constrained environment? That is exactly what J2ME does with the KVM, which is short for Kuaui VM (an early name). The KVM is a completely new implementation of a Java virtual machine, an implementation optimized for use on small devices. The KVM accepts the same set of bytecodes (with a few minor exceptions) and the same class-file format that the classic virtual machine does. We will discuss the KVM in greater detail shortly.


10/17/2000 4:50 PM

Page 79

Java 2 Micro Edition (J2M E)

79

You should understand that the Micro Edition is more than just the KVM. In fact, the classic virtual machine can still be used with J2ME. Thus, J2ME supports two different virtual machines: ■■

■■

The classic virtual machine for 32-bit architectures and large amounts of memory The KVM for 16-bit or 32-bit architectures with limited amounts of memory

Possibly, future versions of J2ME will support other virtual machines as well.

New and Changed Classes As you might imagine, one of the keys to getting Java to run on a small device is to reduce the size of the runtime classes installed with the runtime environment. The Micro Edition performs this task by removing unnecessary classes to form a new set of core classes. A similar pruning occurs within the classes themselves (unnecessary or duplicate methods are removed). What is left is a true subset of the J2SE runtime classes. Specific implementations of the Micro Edition are also free to ROMize the core classes. In other words, any classes that are provided as part of the basic runtime environment can be stored by using the virtual machine’s internal format instead of the normal class-file format. The virtual machine must still have the capacity to read user-defined classes in the normal class-file format, however. A stripped-down runtime is not particularly useful if there is no way to interact with the user or with other external devices. J2ME also augments the runtime environment by defining new classes that are suitable for smaller devices. Some of these classes replace similar classes in J2SE while others provide new functionality not found in the other editions.

Configurations and Profiles Realizing that the one-size-fits-all principle used with the Standard Edition does not work on small devices, the Micro Edition uses configurations and profiles to customize the Java runtime environment.


80

10/17/2000 4:50 PM

Page 80

CHAPTER 4

A configuration defines the basic J2ME runtime environment as a virtual machine and a set of core classes that run on a family of devices that have similar capabilities. Two configurations are currently defined: the Connected Limited Device Configuration (CLDC) and the Connected Device Configuration (CDC), both of which we will discuss in the next chapter. Each configuration provides a minimal set of features that all devices in the configuration must support. The CDC uses the classic virtual machine while the CLDC uses the KVM (as shown in Figure 4.1). A profile adds domain-specific classes to a particular J2ME configuration. Unlike configurations, which are device-oriented, profiles are more application-oriented. They provide classes that are geared toward specific kinds of applications (or more accurately, specific uses of devices). Examples are user interface classes, persistence mechanisms, messaging infrastructures, and so on. Figure 4.2 shows how profiles and configurations work together in order to provide a complete Java runtime environment. Several profiles have been defined or are in the process of being defined, and we will discuss them in Chapter 6, “Profiles.”

Java application KVM + CLDC APIs

Native APIs

Java application Classic VM + CDC APIs

Native APIs

Native OS

Native OS

Device

Device

Connected, Limited Device Configuration (CLDC)

Connected Device Configuration (CDC)

Figure 4.1 The two J2ME configurations.

Java application Profile Configuration Native OS Device Figure 4.2 Profiles.


10/17/2000 4:50 PM

Page 81


81

Building Blocks As this book was being written, a revision of J2ME was being developed under the Java Community Process that would replace configurations with building blocks. A building block subsets classes from J2SE or J2EE for use with J2ME. Individual profiles would include appropriate building blocks in order to share more functionality with the J2SE runtime classes. The proposal, JSR-68, states that over time, the concept of a configuration will be replaced with building blocks but that profiles will still exist. Because building blocks are not yet part of an approved specification, this book uses the term configuration.

Profiles are the double-edged sword of J2ME. They define important and necessary functionalities, but they also limit your application’s portability to the other editions of Java or even to other profiles. Such restrictions are not unexpected or unreasonable, however, because the need to run a single application on all possible platforms is quite rare. Some would argue that it is not even possible to do right. What J2ME enables you do to, however, is use Java for all of the pieces of your application—from the database server (more and more databases support Java directly as a programming language) through the middle tier and down to the smaller devices. Although no Java developer really wants another set of application programming interfaces (APIs) to learn (it is hard enough keeping track of all of the new classes that are added to the Standard Edition), profiles keep the developer using a familiar language and familiar development tools. This is a key feature of all three editions of Java.

The KVM Many perceive the KVM to be the heart of the Micro Edition. Strictly speaking, of course, this situation is not the case. The KVM is one of two virtual machines provided by Sun Microsystems for use with J2ME. Also, while most implementations of J2ME will use or port the Sun virtual machines, vendors are also free to implement their own virtual machines as long as they adhere to the J2ME specifications and pass Sun’s compatibility tests. RIM’s BlackBerry system, which we discuss in


82

10/17/2000 4:50 PM

Page 82

CHAPTER 4

Chapter 11 (“Java for BlackBerry Wireless Handhelds”), uses its own implementation, for example. If the KVM is not the heart of J2ME, however, it is certainly an important part of it. As mentioned, when Sun first announced J2ME at the JavaOne Conference, an early version of the KVM was made available to attendees (preloaded on a Palm V that they could buy as a show special). The KVM soon found its way onto the Internet, causing considerable excitement in both the Palm and Java development communities. Finally, there was a way to run Java on a mainstream personal digital assistant (PDA) with promises of more device support to come. It makes sense, then, for us to spend some time looking at the KVM before exploring J2ME configurations or profiles in any detail. The Spotless System Development of the KVM started a number of months before the JavaOne Conference. In fact, the KVM originated as a project in Sun Laboratories, the research arm of Sun Microsystems. This progenitor of the KVM was known as the Spotless project, and its goal was to write a fully functional Java runtime environment—the Spotless System—for the Palm series of connected organizers. Complete details about the Spotless System are found in a Sun Labs technical report published in February 1999, which is available online at www.sun.com/research/spotless. We will summarize the main points here, but we encourage you to read the full report if the history of the KVM interests you. The primary motivation for the development of the Spotless System was to create a small but complete Java execution engine that was suitable for use on small devices. The emphasis was on size, not speed, and on the portability of the execution engine source code. The Spotless System was not the first attempt at getting Java to run on small devices. Sun had three formal initiatives already: Java Card, EmbeddedJava, and PersonalJava—that addressed the problem. We will briefly summarize these initiatives later in this chapter, so for now, all we need to know is that the Spotless team found them all unsuitable for a number of reasons. Thus, they developed a new runtime environment. As we saw in the previous chapter, writing a Java virtual machine is not difficult, nor is the resulting virtual machine particularly large. As both


10/17/2000 4:50 PM

Page 83


83

we and the Spotless team discovered, the size of the Java runtime environment derives mostly from its runtime libraries. The Spotless team conducted extensive and detailed analyses of the Java 1.1 core run time and concluded that it would be simpler to build a new, smaller set of classes from scratch rather than trying to adapt the existing library. The reasons are simple. There are too many classes and too many interdependencies between classes. Untwining the classes and reworking their innards is more complex than writing new classes based on the runtime library specification. By starting from scratch, then, the Spotless team was able to carefully choose which classes to include in its own run time and even which methods to include. The team also chose to merge certain classes and to eliminate various subclasses, all in order to reduce the total number of classes and their cumulative effect on the runtime size. This latter decision would prove to be particularly controversial, as we will see shortly. The result was a complete runtime environment that could run in the constrained setting of a Palm device (and in theory, other similar environments). At some point, a decision was made to transform the research project into the product that we now know as the KVM. The Spotless project still continues as a separate research initiative, but it and the KVM are evolving along different paths. Early KVM Controversy The first public release of the KVM was at the 1999 JavaOne Conference. After the initial excitement subsided, those who took a close look at the KVM and tried to port their Java programs to it soon ran across a number of important road blocks. The most obvious limitation was program size. The static size of a program—basically, the sum of the class files—was limited to 64K. Runtime memory constraints were even more onerous. On a typical Palm device that was available at the time, there was about 20K of runtime memory available to an application after the virtual machine started. These limitations were not inherent to the KVM but were mostly due to the segmented memory architecture of Palm OS, which we will describe in more detail in Chapter 8, “Java for Palm Connected Organizers.” These restrictions have relaxed since then, but runtime memory constraints are still limiting when compared to a typical desktop computer.


84

10/17/2000 4:50 PM

Page 84

CHAPTER 4

A second road block was the decision not to implement the AWT. AWT is a set of APIs that Java programs use in order to generate Graphical User Interfaces (GUIs). Even Swing-based user interfaces eventually use AWT, so AWT is extremely important for client programs. They felt, however, that AWT was simply too large to work well in the restricted environment of the KVM, so the KVM team avoided it altogether. They understood, of course, that some kind of user interface library was necessary, so they implemented their own user interface objects that were simple and Palm-specific. Defining a cross-device user interface was left for later and more formal specifications. In other words, users had to be prepared to rewrite their user interface code whenever a formal specification (in this case, the Mobile Information Device Profile that we will discuss in Chapter 6) was defined and implementations of it were available.

kAWT: AWT for the KVM Early adopters of the KVM were quite disappointed with the limited set of user interface components that it provided and proceeded to build their own set of components called kAWT (modeled after the AWT components with which they were familiar). kAWT is discussed in Chapter 8 and is included on the CD-ROM for this book.

The roadblock that caused the most controversy in the early days, however, was the Spotless team’s decision to move and/or rename methods in the core classes. What it meant was that you could not take the logic sections of a program—the parts not directly involved with the user interface—and run them unchanged on J2SE. This situation somehow seemed more offensive than just dropping methods from those classes, because it broke the promise of Java compatibility. The KVM Today The KVM has been officially released as the reference virtual machine for the first J2ME configuration, which we will discuss in the next chapter. Developers can download the KVM from Sun Microsystems’ Web site (as part of the configuration) and compile it for the Palm, Windows, or Solaris platforms (or port it to any other platform).


10/17/2000 4:50 PM

Page 85


85

Although many changes were made to the KVM, the basic motivation for its existence has not changed: to provide a complete Java runtime environment for small devices. In other words, the KVM is a true Java virtual machine as defined by The Java Virtual Machine Specification (except for some specific, documented deviations that are necessary for proper functioning on small devices): Long integer and floating point datatypes are optional. This makes sense, because operations involving these types often have to be simulated in software on a small device. Floating point operations are especially expensive without a dedicated coprocessor. No object finalization. With no finalization, the garbage collector’s job is made much simpler and less time-consuming. No JNI support. The KVM has a native interface, of course, but this interface is not like JNI, which is more complex because it is a portable interface. In fact, the native methods in the KVM are compiled into the virtual machine and are not user installable. Off-device class verification. Because class verification is an expensive and time-consuming operation, the KVM team came up with a way to move most of the work off the device and onto the desktop or server computer, where the class files are compiled. This step is referred to as preverification. All the device does is run a few simple checks on a preverified class file in order to ensure that it was verified and is still valid. Multidimensional arrays are optional. Few applications use multidimensional arrays, so removing the necessary support saves a bit of space. No user-defined class loaders. The only class loader that is available to applications running on the KVM is the system class loader provided by the KVM itself. Features that are optional are defined in separate modules within the KVM source code. A particular J2ME configuration defines the exact set of features that it expects from a virtual machine, and that determines which of the optional modules will be included when a version of the KVM is compiled for a particular platform. Note that specific use of the KVM is not necessarily required, because the KVM is a reference implementation of a Java virtual machine. Vendors who are shipping a J2ME configuration only need to provide a


86

10/17/2000 4:50 PM

Page 86

CHAPTER 4

virtual machine that meets the requirements of the configuration. Starting with the KVM makes it easier, but there is nothing preventing a vendor from writing his or her own virtual machine from scratch.

Related Technologies If you are not a newcomer to Java, you probably realize that J2ME is not Sun’s first attempt at making Java work on small devices. Java Card, EmbeddedJava, and PersonalJava already existed by the time that KVM made its first public appearance. How do these technologies relate to J2ME? Of the three, PersonalJava is the closest in spirit to J2ME. PersonalJava defines a subset of the core Java APIs (an optimized version of the Java runtime library) that can be combined with a fully-compliant (classic) virtual machine in order to produce a smaller Java runtime environment that is suitable for use on consumer devices. PersonalJava also defines some new APIs—of which the most important is the Truffle Graphical Toolkit, which defines user interfaces with a customizable look-and-feel (such as the Touchable look-and-feel for touch-screen devices). For more information about PersonalJava, refer to http:// java.sun.com/products/personaljava. The biggest difference between PersonalJava and the Micro Edition is that the latter supports a much broader set of devices, mostly by allowing specific changes to the Java virtual machine. As such, PersonalJava is really a subset of J2ME and is in fact being redefined as a J2ME profile, the Personal Profile. We will discuss profiles in Chapter 6. If PersonalJava is being folded into J2ME, what about EmbeddedJava? At first glance, PersonalJava and EmbeddedJava seem similar. In fact, EmbeddedJava seems even more flexible than PersonalJava, because every class, method, and field of the Java runtime library is optional. Unlike PersonalJava or even J2ME, however, EmbeddedJava is specifically meant to be an unexposed, embedded runtime environment. In other words, only the implementer of the embedded system can use and write applications for the EmbeddedJava environment. EmbeddedJava defines a closed system—a black box whose contents and implementation are unknown and inaccessible to third-party developers. EmbeddedJava does not affect and is not affected by the Micro Edition.


10/17/2000 4:50 PM

Page 87


87

For more information about EmbeddedJava, refer to http://java.sun. com/products/embeddedjava. The remaining technology similar to J2ME is Java Card, an architecture for running Java programs on smart cards. A smart card is a set of electronic circuits—some memory with or without a central processing unit (CPU)—packaged as a thin device that looks like a standard credit card. Smart cards are constrained in the amount of data that they can store—too constrained even for the J2ME. To deal with these constraints, a significant number of changes had to be made to Java. Not only does Java Card define its own set of APIs, but a Java Card virtual machine even has a specification separate from The Java Virtual Machine Specification. As you can see, then, J2ME and Java Card have different goals. For more information about Java Card, refer to http:// java.sun.com/products/javacard. To summarize, then, both Java Card and EmbeddedJava can be viewed as complementary technologies to J2ME, while PersonalJava is being folded into J2ME. For a starting point on all of these technologies, refer to the Java Consumer and Embedded Technologies page at http://java. sun.com/products/OV_embeddedProduct.html.

Chapter Summary In this chapter, we introduced J2ME, a new platform for Java programming. We outlined what goes into J2ME and how it compares to existing Java technologies. We also spent a bit of time on the history of the KVM, which is a key part of J2ME. We can now move on to examining J2ME configurations and profiles.


10/17/2000 4:50 PM

Page 88


10/17/2000 4:51 PM

Page 89

CHAPTER

5

Configurations

A

Java 2 Micro Edition (J2ME) configuration defines the minimal requirements to run Java on a family of devices that have similar characteristics. These requirements include the amounts of available memory, the features of the virtual machine, and a set of core classes upon which to write applications. In this chapter, we will discuss the two J2ME configurations: the Connected Limited Device Configuration (CLDC) and the Connected Device Configuration (CDC).

Overview Configurations are defined as part of the Java Community Process (JCP). An expert group is formed that consists of representatives from Sun Microsystems and interested partners and licensees who then work together to write a specification defining the requirements of a particular configuration. The specification is then made available for public review and final approval by the Java community at large. The two configurations that we will discuss here are formally known as JSR-30 (J2ME Connected Limited Device Configuration) and JSR-36 (J2ME Connected Device Configuration). Before looking at either configuration, however, let’s examine the high-level goals and requirements that guided the JCP expert groups. 89


90

10/17/2000 4:51 PM

Page 90

CHAPTER 5

The Purpose of a Configuration A configuration’s primary goal is to define minimum requirements for memory, language support, virtual machine support, and runtime libraries. Also, a configuration does not define any optional components; rather, it is an all-or-nothing proposition. Profiles that are built on top of a configuration can impose additional requirements or restrictions in addition to those defined by the configuration, however.

Connected Device Families Configurations are all about defining common and predictable behaviors and features for a family of devices. The term family is used to refer to devices that have similar characteristics, not devices from the same manufacturer. Applications conforming to a particular configuration are thus guaranteed to be portable across all devices that implement that configuration—as long as the applications restrict themselves to using the set of classes defined by the configuration. Configurations do not provide all of the features that most applications require, however, because important functionalities such as the user interface are left to be defined by profiles (which we will discuss in the next chapter). The two configurations that have been initially defined both target connected devices. A connected device is a device that has network connectivity, whether it is a slow, wireless link or a high-speed fixed link. The connectivity is seen as being critical to the proper use of the device. Note that such a device does not have to be connected to the network at all times, however. The JCP expert groups split the connected devices into two families, each targeted by a different configuration. The first group incorporates the devices that immediately come to mind when thinking about small computing devices: cellular telephones, PDAs, and two-way pagers. As a group, these devices have important memory, power, and networkbandwidth restrictions that directly affect the kind of Java applications that they can support. This family is targeted by the CLDC. The second group includes devices that are not covered by the first group—devices that have fewer restrictions on memory and network bandwidth and that usually have no restrictions on available power. Devices in this


10/17/2000 4:51 PM

Page 91

Configurations

91

family include television set-top boxes (devices that provide some kind of network-based features that are delivered on and through a television) and car entertainment or navigation systems. This family is targeted by the CDC. As is often the case with these kinds of rather arbitrary groupings, the line between the two configurations is somewhat blurry. A particular device, for example, might meet the basic hardware requirements of either the CDC or the CLDC. The device manufacturer (the most likely providers of Java runtime environments are the device manufacturers themselves) must decide which configuration to support.

Dynamic Application Delivery Central to either configuration is the concept of dynamic application delivery—the capability to download and install new or updated applications to a device. Much in the same way that an applet can be downloaded and run by a Web browser, an application can be fetched and run by a connected device. A configuration does not actually define how this procedure is done but provides the framework that makes it possible and encourages implementers to support it. If third-party application development is not something that a device manufacturer wants, EmbeddedJava is probably a better choice for runtime environments.

Identifying a Configuration If you need to know which configuration is being used at run time, use the System.getProperty method to obtain the value of the microedition.configuration property. This value will be a string (such as CLDC-1.0) that consists of the configuration name and a version number.

The CLDC The CLDC is the more interesting of the two configurations, because it is targeted at devices that have extreme limitations when compared to the memory and power requirements of a conventional Java implementation.


92

10/17/2000 4:51 PM

Page 92

CHAPTER 5

Please note that all references to the CLDC in this book are to the CLDC 1.0 specification. For the complete CLDC specification, refer to http://java.sun.com/products/cldc. A reference implementation of the CLDC for the Windows and Solaris platforms is available from the same site. A port for Palm OS is also available, but you must first download and install the Windows/Solaris version. We will discuss these implementations in Part 3, so in this section, we will limit ourselves to discussing the specification itself.

CLDC Quick Summary The CLDC targets devices that have 128K or more of non-volatile memory, 32K or more of volatile memory, limited power (devices are often battery operated, so power conservation is imperative), and a potentially slow-speed network connection. The CLDC defines the following requirements:

Volatile versus Non-Volatile Both the CLDC and CDC specifications refer to non-volatile and volatile memory when defining their target devices. In this context, non-volatile memory is writeprotected and persistent, while volatile memory is non-persistent with no write protection. If the user shuts off the device, the contents of non-volatile memory are preserved while those in volatile memory are lost. In the specifications, nonvolatile memory is used to store the virtual machine and the runtime libraries, while volatile memory is used for runtime memory allocation. In general, a device requires more non-volatile memory than volatile memory in order to hold the class files for one or more Java applications.

Full language support with minor exceptions. Apart from a few differences, the full Java language (as defined in The Java Language Specification) is supported. The exceptions are in the areas of floating point support, finalization, and error handling, and we describe these concepts later in this section. Full virtual machine support with minor exceptions. Apart from a few differences, the CLDC requires a Java virtual machine (as defined by The Java Virtual Machine Specification). We also describe the exceptions later in this section.


10/17/2000 4:51 PM

Page 93

Configurations

93

The security model is the sandbox model. The simple sandbox model described in Chapter 2 (“Java: Fat and Slow?”) that ensures that malicious applets cannot damage a user’s system has been adapted for use with the CLDC. Classes that are not specific to the CLDC are subsets of J2SE 1.3 classes. Each class included in the CLDC that has the same name and package of a class defined by the J2SE specification must be identical to or a subset of the J2SE class. Specifically, any CLDC class that is inherited from J2SE can have fields and methods removed from it, but no public or protected fields or methods can be added to it. As well, the semantics of the class and the remaining methods must be preserved. In other words, you can rewrite the class completely as long as the API is identical or a strict subset and as long as the behavior does not change. Refer to Tables 5.1 and 5.2 for the list of J2SE classes supported by the CLDC. Limited support for internationalization. The CLDC provides basic support for converting Unicode to and from a sequence of bytes by using at least one encoding. Localization issues are not specified by the CLDC, however, because the number of classes required for proper localization is fairly large. Classes that are specific to the CLDC are in the javax. microedition package and its subpackages. In order to ensure upward compatibility with J2SE and J2EE, all classes that are not identical to or subsets of J2SE classes are placed in the javax. microedition package. This functionality makes it easy to separate the CLDC-specific parts of an application from the more generic parts. By using the javax.microedition name instead of java.microedition—defining the package as a Java 2 standard extension—you open the possibility of later porting some of the CLDC-specific classes to J2SE. The CLDC-specific classes define the new Generic Connection framework, which we will describe later. Profiles that are built on top of the CLDC can also add classes to the javax.microedition package. Refer to Table 5.3 for the list of CLDC-specific classes. The CLDC specification uses the KVM (with floating point support disabled but long integers enabled) as its reference virtual machine implementation, but implementers are free to create their own virtual machine if they desire.


94

10/17/2000 4:51 PM

Page 94

CHAPTER 5

In addition to these requirements, the CLDC also defines the acceptable format for distributing applications in a public fashion (as compressed JAR files) and also enables implementers to ROMize (preload or prelink classes, usually storing them in ROM and perhaps storing them in an optimized, internal format) system classes.

Detailed Requirements Let’s take a closer look at the CLDC requirements that we just described. Language Support There are three differences in how the CLDC supports the Java programming language when compared to J2SE. First, Java classes used with the CLDC cannot support floating point numbers at all. In other words, no CLDC application can use any floating point types (double or float) or constants or perform any kind of floating point operation. Among other things, this situation means that the java.lang.Float and java.lang.Double classes are not included in the CLDC run time. Any class in the CLDC run time that is inherited from J2SE has its floating point methods (methods that accept, use, or return floating point types) removed. Second, finalization is not supported because it complicates the garbage-collection process. The CLDC definition of java.lang. Object simply removes the finalize method. If another class defines a finalize method, therefore, it is simply a normal method that will never be called. Finally, runtime errors are handled in an implementation-specific manner. As you know, Java can interrupt the execution of a thread by throwing an object up the call stack by using exception-handling facilities. The objects that can be thrown are all subclasses of java.lang. Throwable and its two immediate subclasses, java.lang.Exception and java.lang.Error. Runtime exceptions—unexpected or infrequent programming or input/output (I/O) problems that are generally recoverable if only to terminate in a graceful fashion—are subclasses of java.lang.Exception. Runtime errors—problems with the virtual machine itself from which the application might not recover—are sub-


10/17/2000 4:51 PM

Page 95

Configurations

95

classes of java.lang.Error. While the CLDC defines a fairly complete set of exception classes, only three error classes are defined: java.lang.Error, java.lang.OutOfMemoryError, and java. lang.VirtualMachineError. Any other kind of error is handled in a manner that is appropriate for the device, which usually would involve terminating the application and/or resetting the device. Virtual Machine Support The differences between the J2SE and CLDC virtual machines are more pronounced than the language support differences. In particular: No floating point support. The virtual machine cannot support floating point types or constants or any bytecodes involving floating point types or operations. No support for the Java Native Interface (JNI). JNI is considered too expensive to implement on a device that the CLDC is targeting. No user-defined class loaders. For security reasons, which we will discuss shortly, an application cannot influence in any way how classes are loaded. The only class loader that can be used is the system class loader provided by the implementation. No reflection. From a programmer’s viewpoint, this statement means that the CLDC does not include any of the classes in the java. lang.reflect package and the associated methods in java. lang.Class. But because it is a restriction on the virtual machine itself, it also eliminates any J2SE feature that depends on reflection— such as object serialization or the debugging (JVMDI) or profiling (JVMPI) interfaces. No thread groups or daemon threads. The virtual machine must support multiple threads of execution, whether by performing its own context switching or by relying on the operating system’s thread support. But it does not support thread groups or daemon threads. No finalization. Again, object finalization is not supported. No weak references. One of the features added to J2SE 1.2 is the capability to mark objects as being potential candidates for garbage collection while still referencing them. These so-called weak references complicate the garbage-collection process and are not supported by the CLDC.


96

10/17/2000 4:51 PM

Page 96

CHAPTER 5

Error handling is implementation-defined. Other than supporting the error classes previously discussed, error handling is appropriate for the device but is otherwise unspecified. An alternate class verifier is specified. As we discussed in Chapter 2, class verification is a computationally intensive process. As it turns out, much of the work of verification can be moved off the device itself and onto the platform where the class file was originally generated, which is typically a desktop computer. This off-device verification process (referred to by the CLDC as preverification) changes some bytecode sequences and inserts special attributes (ignored by conventional virtual machines) into the class files. A CLDC virtual machine uses these attributes to perform some simple checks on the class file in order to guarantee that it has been verified. This ondevice step is much less expensive to perform and requires less memory, making it ideal for the CLDC. You should note, however, that a preverified class file is still a valid Java class file and can be executed by a non-CLDC virtual machine. These differences, of course, mirror the differences between the KVM and the classic virtual machine, because the KVM is the reference virtual machine for the CLDC. Sandbox Security Dynamic application delivery and installation opens a device to attack by malicious applications. J2SE defines a complicated security model in order to ensure the safety and integrity of the system when running applications. This model is too complex and too large for a small device, so the CLDC adopts a sandbox security model that is similar to how Web browsers deal with untrusted applets. Specifically: ■■

■■

■■

■■

All Java class files must be preverified and pass the on-device verification test. Only the device can download and install applications, usually in response to a user request. Individual classes cannot be directly downloaded by an application. Downloaded applications cannot replace any of the configurationspecific, profile-specific, or system-specific classes (such as those in the java or javax.microedition packages). No new native code can be installed or accessed.


10/17/2000 4:51 PM

Page 97

Configurations

97

In particular, notice how the set of native methods is closed. The only native methods that an application can call are the ones that are provided with the implementation. The implementation can provide native methods along with any additional classes that it provides (whether those classes are part of a profile or are device-specific), but the user of the device cannot install any others. Note that profiles are free to place other security restrictions, as we will see in the next chapter with the Mobile Information Device Profile (MIDP). Inherited Classes The classes that the CLDC inherits from J2SE are listed in Table 5.1 (non-exception classes) and Table 5.2 (exception and error classes). These classes are drawn specifically from these packages: java. lang, java.io and java.util. The classes from java.lang are the system classes (such as Object or System), type classes (such as Integer), and exception or error classes. The classes from java.io are the basic stream and reader/writer classes. The remaining classes are the basic utility classes that every Java programmer needs, such as java.util.Vector and java.util.Hashtable. The CLDC expert group had to make some hard choices as to which classes to leave out of the configuration. In some ways, what they ended up with was more precisely a subset of the Java 1.02 core runtime (with a few classes from Java 1.1 thrown in for good measure) than a subset of J2SE 1.3. Notably absent from the CLDC are the following packages: java.lang.applet java.lang.awt java.lang.beans java.lang.math java.lang.net java.lang.rmi java.lang.security java.lang.sql java.lang.text


98

10/17/2000 4:51 PM

Page 98

CHAPTER 5

Some were excluded because of the lack of virtual machine support. The JavaBeans and RMI classes depend on object serialization, for example. Others were excluded primarily for space reasons. Localization and internationalization support in particular are missing—except for the conversion of Unicode characters to and from at least one byte encoding and the capability to determine the locale of the device. Rather than letting the runtime system automatically do a lot of the localization work with resource bundles and date/time/number formatters, application developers are expected to build specific, localized versions of their applications. Table 5.1 Non-Exception Classes Inherited from J2SE 1.3 by the CLDC PACKAGE

CLASSES

java.lang

Boolean, Byte, Character, Class, Integer, Long, Math, Object, Runnable, Runtime, String, StringBuffer, System, Thread, Throwable

java.io

ByteArrayInputStream, ByteArrayOutputStream, DataInput, DataInputStream, DataOutput, DataOutputStream, InputStream, InputStreamReader, OutputStream, OutputStreamWriter, PrintStream, Reader, Writer

java.util

Calendar, Date, Enumeration, Hashtable, Random, Stack, Time, Vector

And of course, any other classes included in J2SE (such as the Swing or CORBA classes) are also excluded from the CLDC. CLDC-Specific Classes: Generic Connections The Standard Edition defines many classes related to I/O and network connectivity. Only a few of these are found in the CLDC. In fact, the CLDC does not have any way to open files or sockets. This situation makes perfect sense, of course, because not all devices support these concepts. And adding the complete java.io and java.net packages would go against the goals of keeping the CLDC small and simple. Still, the CLDC is a configuration for connected devices, which implies that there must be some way to communicate with the external world. So what the expert group did was define a new set of classes for I/O and


10/17/2000 4:51 PM

Page 99

Configurations

99

Table 5.2 Exception and Error Classes Inherited from J2SE 1.3 by the CLDC PACKAGE

CLASSES

java.lang

ArithmeticException, ArrayIndexOutOfBoundsException, ArrayStoreException, ClassCastException, ClassNotFoundException, Error, Exception, IllegalAccessException, IllegalArgumentException, IllegalMonitorStateException, IllegalThreadStateException, IndexOutOfBoundsException, InstantiationException, InterruptedException, OutOfMemoryError, NegativeArraySizeException, NumberFormatException, NullPointerException, RuntimeException, SecurityException, StringIndexOutOfBoundsException, VirtualMachineError

java.io

EOFException, IOException, InterruptedException, UnsupportedEncodingException, UTFDataFormatException

java.util

EmptyStackException, NoSuchElementException

Table 5.3 CLDC-Specific Classes PACKAGE

CLASSES

javax.microedition.io

Connection, ConnectionNotFoundException, Connector, ContentConnection, Datagram, DatagramConnection, InputConnection, OutputConnection, StreamConnection, StreamConnectionNotifier

network communication. These classes are referred to as the Generic Connection framework and are found in the javax.microedition.io package. The classes appear in Table 5.3. The Generic Connection framework is meant to provide the same functionality as the java.io and java.net packages without dependence on specific physical features or capabilities of a device. In fact, the CLDC itself does not provide an implementation for any kind of I/O or network communication, just a framework of Java interfaces and a single factory class. You could say that the Generic Connection framework is a framework for building communication drivers, much the same way that JDBC in J2SE is a framework for building database drivers. The CLDC implementation for a specific device provides communication drivers that are appropriate to that device. Although the drivers


100

10/17/2000 4:51 PM

Page 100

CHAPTER 5

vary from device to device, any implementation details are hidden from the application developer, who only accesses the drivers through the interfaces defined by the framework. The basic idea behind the Generic Connection framework is that all I/O and network communication can be abstracted, and interfaces can be defined for each of those abstractions. Instead of instantiating a specific class of communication object, for example, the developer asks the framework to create a connection by using a particular protocol (whether that protocol is a formal protocol such as HTTP or communication or storage points such as sockets or files). As well, a Universal Resource Indicator (URI) is passed to the framework in order to identify a specific object or target for the protocol. The framework then returns an interface that represents a connection to that object or target. For example, to open an HTTP connection to an object, you would use the following syntax: import javax.microedition.io.Connection; import javax.microedition.io.Connector; import java.io.IOException; try { Connection conn = Connector.open( "http://www.ericgiguere.com" ); .... // do something with the connection } catch( IOException e ){ // couldn’t connect }

To open a direct socket connection, you would just change the string that is passed to the Connector.open method, providing of course the device-supported socket connections. The Connection interface and its six different extensions make it easy to perform communication without having to worry about implementation details. When dealing with wireless networks, for example, this situation is a real boon, because each network is different and the framework enables the application developer to concentrate on writing the application instead of writing (or using different vendors’) network-specific communication routines. The six kinds of connections that are supported are serial input connections (InputConnection), serial output connections (OutputConnection), circuit connections (StreamConnection, which extends InputConnection and OutputConnection), Web server


10/17/2000 4:51 PM

Page 101

Configurations

101

Connection DatagramConnection

InputConnection

OutputConnection

StreamConnectionNotifier

StreamConnection ContentConnection Figure 5.1 The generic connection framework hierarchy.

connections (ContentConnection, which extends StreamConnection), datagram connections (DatagramConnection), and serverside socket connections (StreamConnectionNotifier). The hierarchy is shown in Figure 5.1. Implementers are expected to provide at least one communications driver for the framework—preferably one that supports a higher-level protocol such as HTTP.

The CDC The CDC targets devices that are less limited in terms of power, memory, and network bandwidth than those that are targeted by the CLDC. The CDC is perhaps best described as a stripped-down J2SE to which the CLDC classes were added. Programs written to the CLDC specification will thus also run on the CDC. Please note that as this book was being written, the CDC specification was still in JCP public review—and some of the details are subject to change. For the complete CDC specification, refer to http://java.sun. com/aboutJava/communityprocess. As of this writing, there is no reference implementation yet.

CDC Quick Summary The CDC targets the family of connected devices with 512K or more of non-volatile memory, 256K or more of volatile memory, and no power limitations. The CDC defines the following requirements:


102

10/17/2000 4:51 PM

Page 102

CHAPTER 5

Full language support. The complete Java programming language, as defined in The Java Language Specification, is supported. Full virtual machine support. The CDC requires a complete Java virtual machine as defined by The Java Virtual Machine Specification. All CLDC classes are supported. All of the packages defined by the CLDC are included with the CDC, especially the classes in the javax.microedition package. Refer to Tables 5.1, 5.2, and 5.3 for the list of classes. Other classes are J2SE 1.3 classes. Except for the CLDC classes, the remaining classes in the CDC are classes defined by the J2SE 1.3 specification. A representative sample of these classes is listed in Table 5.4. Refer to the specification for the complete list, which takes several pages. The CDC also requires the virtual machine to support the JNI, Java Virtual Machine Debugging Interface (JVMDI), and Java Virtual Machine Profiling Interface (JVMPI) specifications only if native, debugging, and/or profiling interfaces are included with the virtual machine. Table 5.4 Some of the Additional J2SE Classes Added to the CDC PACKAGE

CLASSES

java.lang

Character.Subset, Character.UnicodeBlock, ClassLoader, Double, Float, Number, Runnable, Void

java.lang.reflect

AccessibleObject, Array, Constructor, Field, Method, Modifier

java.io

BufferedInputStream, BufferedOutputStream, Externalizable, File, FileDescriptor, FileInputStream, FileOutputStream, FilterInputStream, ObjectInputStream, ObjectOutputStream, PushbackInputStream, Serializable

java.net

ContentHandler, DatagramPacket, DatagramSocket, InetAddress, Socket, ServerSocket, URL, URLConnection, URLClassLoader

java.security

AccessControlContext, AccessController, AlgorithmParameters, AlgorithmParametersSpi, CodeSource, KeyFactory, KeyFactorySpi, KeyPair, KeyStore, KeyStoreSpi, Identity, IdentityScope, MessageDigest, MessageDigestSpi, Provider, SecureClassLoader, Signer


10/17/2000 4:51 PM

Page 103

Configurations

103

PACKAGE

CLASSES

java.lang.security.cert

Certificate, Certificate, CertificateRep, CertificateFactory, CertificateFactorySpi, CRL, X509Certificate, X509CRL

java.lang.security.spec

EncodedKeySpec, X509EncodedKeySpec

java.text

ChoiceFormat, DateFormat, DateFormatSymbols, DecimalFormat, DecimalFormatSymbols, FieldPosition, Format, MessageFormat, NumberFormat, SimpleDateFormat

java.text.resources

LocaleData

java.util

AbstractCollection, AbstractList, AbstractMap, AbstractSequentialList, AbstractSet, Arrays, ArrayList, Collections, Dictionary, Enumeration, GregorianCalendar, HashMap, HashSet, Locale, LinkedList, Map, Map.Entry, Properties, WeakHashMap

java.util.jar

Attributes, Attributes.Name, JarInputStream, Manifest

java.util.zip

CRC32, InflatedInputStream, Inflater, ZipInputStream

Comparison to the CLDC From a programming viewpoint, there is little that distinguishes the CDC from the J2SE. Developers should therefore find it a comfortable and familiar programming environment, except perhaps for the lack of user-interface classes (like the CLDC, the CDC leaves user-interface issues to the profiles). The only challenge is to not reference J2SE classes excluded by the CDC. Apart from including more J2SE classes in the core runtime library, what really distinguishes the CDC from the CLDC is the virtual machine. The CDC requires a full and complete virtual machine, while the CLDC deviates a bit (but not much) from The Java Virtual Machine Specification. The KVM, for example, is not a suitable virtual machine for the CDC.


104

10/17/2000 4:51 PM

Page 104

CHAPTER 5

Chapter Summary In this chapter, we described the two J2ME configurations: the CLDC and the CDC. There is actually not that much to say about the CDC, because it is really just a slimmed-down J2SE with a few new classes. The CLDC is different, however, because it requires a new virtual machine and supports a minimal set of classes. We can now proceed with exploring J2ME profiles in the next chapter, after which we will be looking at actual implementations of configurations and profiles.


10/17/2000 4:51 PM

Page 105

CHAPTER

6

Profiles

W

hile configurations provide the foundation for Java programming on small computing devices, they do not by themselves provide enough functionality for most application development. You must augment the configurations with profiles and perhaps even with device-specific classes. User interface classes, for example, are a common example. They are not defined as part of a configuration, because not all devices have a user interface—and there is a great deal of variation even among those devices that do have user interfaces. This chapter discusses the Mobile Information Device Profile (MIDP) and briefly mentions the other profiles that are under development. The profiles discussed here will undoubtedly be complete by the time you read this book, so be sure to check the book’s Web site at www.wiley. com/compbooks/giguere for updated information. Because the profiles are being defined through the Java Community Process (JCP), you can always find any specifications or other information about a particular profile by looking through the list at http://java.sun.com/ aboutJava/communityprocess/search.html.

105


106

10/17/2000 4:51 PM

Page 106

CHAPTER 6

Overview Like configurations, profiles are defined by expert groups as part of the JCP. The profiles currently being defined are formally known as JSR-37 (Mobile Information Device Profile for J2ME), JSR-46 (J2ME Foundation Profile), JSR-62 (J2ME Personal Profile), JSR-66 (J2ME RMI Profile), and JSR-75 (PDA Profile for J2ME). Of these five profiles, only the MIDP has been released as a formal (but not yet final) specification when this book was being written, so it will be the only one that we discuss in any detail. Luckily, the MIDP is one of the two most interesting of the five. Before we start, however, let’s examine the goals and uses of profiles.

The Purpose of a Profile Where a configuration’s primary goal is to define a minimum level of Java support across a family of devices, a profile’s primary goal is to define application programming interfaces (APIs) for devices that have similar uses. For example, the MIDP defines classes for cellular phonetype devices. Also, while a device can support only one configuration, it can support multiple profiles—as long as each of those profiles uses the same configuration as its foundation. Also, a profile can impose additional limitations on the types of devices with which it will work, such as higher minimum values for available memory, the existence of a certain kind of user interface, and so on.

How Profiles Are Used Just as profiles are built on top of configurations, applications are built on top of profiles. The diagram in Figure 6.1 illustrates the architecture. Notice how applications have access to three different sets of APIs: those of the configuration, those of the profile(s), and those that are specific to the device (provided by the implementer of the runtime environment, which is typically the manufacturer of the device). For portability, of course, an application should restrict itself to using only profile and configuration APIs.


10/17/2000 4:51 PM

Page 107

Profiles

107

Java application Profile Configuration

Native APIs

Native OS Device Figure 6.1 How applications use profiles and configurations.

Identifying a Profile To determine which profiles are available at run time, use System. getProperty to obtain the value of the microedition.profiles property. Each profile is listed by using a format such as MIDP-1.0. Multiple profiles can be returned in a single string, with each profile separated from the other by white space.

MIDP Although Sun Microsystems gave the Java community at large access to a version of Java for the Palm connected organizers in summer 1999, there was no formal specification available to define the basic requirements for writing Java programs that ran on the Palm and on similar platforms. Part of that problem was solved with the publication of the Connected Limited Device Configuration (CLDC) that we just discussed in the previous chapter. Palm and similar devices are user-centric, however, and the CLDC does not address user interfaces at all. This issue and others were instead left for definition by a new profile: the Mobile Information Device Profile (MIDP). Motorola is the specification lead for the MIDP, and the MIDP expert group includes all the major vendors of cellular telephones and other small handheld devices. Please note that all references to the MIDP in this book are to the MIDP 0.95 specification, and as such, there could be minor differences between what we discuss here and what is published in the final 1.0


108

10/17/2000 4:51 PM

Page 108

CHAPTER 6

specification. The complete specification for the MIDP is found at http://java.sun.com/products/midp.

Mobile Information Devices What is a mobile information device (MID)? A MID is a small computing device that has the following characteristics: ■■

■■

■■

■■

A monochrome or color display that is at least 96 pixels wide and 54 pixels high A touch screen, keypad (sometimes referred to as a one-handed keyboard), or a conventional keyboard (a two-handed keyboard) A wireless network connection with limited bandwidth. The connection does not have to be continuously available. 128K of non-volatile memory in order to store the MIDP components, 8K of non-volatile memory in order to store persistent data, and 32K of volatile memory for the Java run time.

These are minimum requirements, of course. The targeted systems are cellular telephones, two-way pagers, and PDAs that have wireless connectivity.

Is the Palm a MID? Are Palm devices MIDs? Good question. As of this writing, only the Palm VII supports wireless networking out of the box, although you can buy wireless modems for the other models. The majority of devices in use, however, do not have any wireless network connectivity—although Palm, Inc. has promised that eventually all of its devices will be enabled for wireless communication. You could argue then that only the Palm VII is really a MID. But a Java runtime environment for the Palm VII will also run on any Palm device with the same version of the Palm operating system, which means that Java applications that do not require wireless connectivity will run on all of those devices. So, in reality, most Palm devices can be considered MIDs, whether they have wireless connectivity or not. But when this book was being written, no implementation of the MIDP was yet available for Palm devices. And this is not likely to change, because the PDA Profile being defined is really a better fit for Palm devices and other handheld organizers. The MIDP specification is really aimed at cellular telephones and other devices smaller than a handheld organizer.


10/17/2000 4:51 PM

Page 109

Profiles

109

A MID must also provide a thread or process that will run the Java virtual machine and low-level APIs for capturing user input, drawing on the display, and implementing the other capabilities of the MIDP.

MIDP Quick Summary The MIDP is built on top of the CLDC, adding APIs in the following areas: Defining and controlling applications. Applications written to the MIDP specification are called MIDlets and are similar to applets. Like an applet, a MIDlet defines methods that the system calls in order to start, stop (pause), and destroy the application. Displaying text and graphics and responding to user events. In other words, it provides the necessary classes to build user interfaces. Storing data in simple databases. The MIDP provides a simple, record-based, persistent storage mechanism for saving data inbetween application invocations. Network connectivity via a subset of HTTP. The MIDP defines an HttpConnection class that extends the Generic Connection framework of the CLDC. Timer notifications. Applications can schedule tasks to be executed at various intervals. The MIDP is also careful to note what it does not specify, which includes how applications are downloaded to and installed on the device and what kind of network security is provided (if any). But because application management is such an important issue, Sun Microsystems does provide a sample implementation of just such a manager (as part of the CLDC reference implementation) that others can use as a starting point.

MIDlets and MIDlet Suites As mentioned, applications that only use the APIs defined by the MIDP and CLDC are referred to as MIDlets. MIDlets that need to share code or data are packaged together as MIDlet suites. Although MIDlets and MIDlet suites are discussed near the end of the MIDP specification, it makes more sense to use them as a starting point for our examination of the MIDP.


110

10/17/2000 4:51 PM

Page 110

CHAPTER 6

What Defines a MIDlet? At the simplest level, a MIDlet is a Java class that extends the abstract class javax.microedition.midlet.MIDlet and implements the destroyApp, pauseApp, and startApp methods. These methods are analogous to the start, stop, and destroy methods of the java. applet.Applet class in J2SE. Applets and MIDlets share similar lifecycles. Just like a Web browser calls an applet’s methods to change the applet’s state, the MIDlet application manager calls the MIDlet’s methods to change the MIDlet’s state. Unlike applets, however, MIDlets can also control the state changes to some degree. Here is the basic MIDlet skeleton: import javax.microedition.midlet.*; public class MIDletSkeleton extends MIDlet { public MIDletSkeleton(){ // initialize the MIDlet here } public void startApp() { // the MIDlet is being activated // open databases, prepare the user interface, etc. } public void pauseApp() { // the MIDlet is being paused // release as many resources as possible } public void destroyApp( boolean unconditional ) { // the MIDlet is being destroyed // do a final cleanup here } }

Note how the destroyApp method receives a boolean as its only argument. If this parameter is true, the MIDlet is being unconditionally shut down. If this parameter is false, the MIDlet has the option of refusing to shut down by throwing a MIDletStateChangeException. The class that extends javax.microedition.midlet.MIDlet is referred to as the primary class of the MIDlet, because the MIDlet usually includes other application-defined classes. These classes are all


10/17/2000 4:51 PM

Page 111

Profiles

111

packaged together into a Java Archive (JAR) file along with any resources (images, data, and so on) that the MIDlet requires. The JAR file contains a manifest describing the contents of the file. A manifest is a text file stored as META-INF/MANIFEST in the JAR file. The lines of the manifest are name-value pairs, and if you are not familiar with manifests, you should read about JAR files at http://java.sun.com/products/ jdk1.2/docs/guide/jar/index.html. The name-value pairs define the attributes of the MIDlet, such as the name of the primary class, and the attributes of the MIDlet suite. What Defines a MIDlet Suite? A MIDlet suite is a set of MIDlets that are packaged together into a single JAR file. Entries in the manifest identify the name, version, and creator of the MIDlet suite and describe the minimum profile and configuration versions required. There is also an entry for each individual MIDlet. MIDlet suites are special because MIDlets within the same suite can share the classes and resources contained in the JAR file. MIDlets from different suites cannot interact directly. For example, a MIDlet in one suite cannot read any records from a database created by a MIDlet in a different suite. The MIDP effectively extends the CLDC sandbox security model, building a sandbox around the suite instead of around each MIDlet. The Manifest MIDlet and MIDlet suite manifest attributes are listed in Table 6.1. Here is a sample manifest for a set of arcade games: MIDlet-Name: ClassicGames MIDlet-Version: 1.0.0 MIDlet-Vendor: Old Arcade Games, Inc. MIDlet-Description: A set of arcade classics for your MID. MIDlet-Info-URL: http://www.oagames.com/classicgames MIDlet-Data-Size: 200 MIDlet-1: FrogHighway, /images/FrogHighway.png, com.oagames.FrogHighway MIDlet-2: Millipede, /images/Millipede.png, com.oagames.Millipede MIDlet-3: TableTennis, /images/TableTennis.png, com.oagames.TableTennis MicroEdition-Profile: MIDP-1.0 MicroEdition-Configuration: CLDC-1.0


112

10/17/2000 4:51 PM

Page 112

CHAPTER 6

The MIDlet-Description, MIDlet-Info-URL, and MIDlet-DataSize attributes are optional, but the other attributes are all required. At runtime, a MIDlet can read any of the manifest attributes using the javax.microedition.midlet.MIDlet.getAppProperty method. Table 6.1 MIDlet Manifest Attributes NAME

DESCRIPTION

MicroEdition-Configuration

The name and version of the J2ME profile required to run the MIDlet suite. Use the same format as the microedition.profiles system property, as in MIDP-1.0. Required.

MicroEdition-Profile

The name and version of the J2ME configuration required to run the MIDlet suite. Use the same format as the microedition.configuration system property, as in CLDC-1.0. Required.

MIDlet-

The name, icon, and primary class, separated by commas, of each MIDlet in the suite. If there are three MIDlets in the suite, for example, the manifest has the three attributes: MIDlet-1, MIDlet-2, and MIDlet-3. The name identifies the MIDlet to the user; the icon is the path to an image (in the portable PNG format) in the JAR file; and the class must extend the MIDlet class and have a public constructor with no arguments. Required.

MIDlet-Data-Size

The minimum number of bytes of persistent storage that the MIDlet requires in order to run. Optional. If not specified, the default is zero.

MIDlet-Description

A description of the MIDlet suite. Optional.

MIDlet-Icon

The path of a portable graphics format (PNG) file within the JAR file, used by the application management software to identify the MIDlet suite. Optional.

MIDlet-Info-URL

An URL describing the MIDlet suite in greater detail. Optional.

MIDlet-Name

The name of the MIDlet suite. Required.

MIDlet-Vendor

The vendor of the MIDlet suite. Required.

MIDlet-Version

The version number of the MIDlet suite. Must be in the format XX.YY or XX.YY.ZZ, where XX is the major revision number, YY is the minor revision, and ZZ is the optional micro revision number. If the micro revision number is omitted, it defaults to zero. Required.


10/17/2000 4:51 PM

Page 113

Profiles

113

Application Descriptors The only problem with using a manifest to describe the MIDlets in the suite is that the manifest must be extracted from the JAR file. In other words, this process involves downloading the JAR file to the device, which is a potentially expensive (and lengthy) proposition if you are performing this task via a public wireless data network. Imagine downloading a MIDlet suite only to discover that it requires a higher version of the MIDP and will not even install on your device. To avoid these problems, the MIDP specification defines an optional application descriptor. An application descriptor is a text file that is similar to a manifest, except that it is not packaged in the JAR file. Like the manifest, it consists of a series of attributes that describe a MIDlet suite. The possible attributes are listed in Table 6.2—some of which are shared with the manifest. Of the shared attributes, the MIDlet-Name, MIDlet-Version, andMIDlet-Vendor attributes must have identical values in both the manifest and the application descriptor. If any other shared attributes are different, the ones in the descriptor override those in the manifest. Here is a sample manifest for the same set of arcade games: MIDlet-Name: ClassicGames MIDlet-Version: 1.0.0 MIDlet-Vendor: Old Arcade Games, Inc. MIDlet-Description: A set of arcade classics for your MID. MIDlet-Info-URL: http://www.oagames.com/classicgames MIDlet-Data-Size: 200 MIDlet-Jar-Size: 14398 MIDlet-Jar-URL: http://www.oagames.com/classicgames/oacg.jar

The use of an application descriptor is optional but recommended, because it enables the device to verify various things. Among these functions is verifying whether a newer version of the MIDlet suite is already installed on the device, whether the JAR file is too big for the device, whether it requires too much memory when running, and so on. The device can verify these features without actually having to download the JAR file itself. This function saves both time and money for the user of the device.


114

10/17/2000 4:51 PM

Page 114

CHAPTER 6

Table 6.2 MIDlet Application Descriptor Attributes NAME

DESCRIPTION

MIDlet-Data-Size

The minimum number of bytes of persistent storage that the MIDlet requires to run. Optional. If not specified, the default is zero.

MIDlet-Description

A description of the MIDlet suite. Optional.

MIDlet-Info-URL

An URL that describes the MIDlet suite in greater detail. Optional.

MIDlet-Jar-Size

The size of the MIDlet suite in bytes. Required.

MIDlet-Jar-URL

The URL from which to download the MIDlet suite. Required.

MIDlet-Name

The name of the MIDlet suite. Required.

MIDlet-Vendor

The vendor of the MIDlet suite. Required.

MIDlet-Version

The version number of the MIDlet suite. Must be in the format XX.YY or XX.YY.ZZ, where XX is the major revision number, YY is the minor revision, and ZZ is the optional micro revision number. If the micro revision number is omitted, it defaults to zero. Required.

The MIDlet specification defines a new Multipurpose Internet Mail Extensions (MIME) type for the descriptor, text/vnd.sun.j2me. app-descriptor, as well as a default file extension, jad. This format allows the descriptors to be fetched from a Web server by using HTTP, although the use of that protocol is not a requirement. Application Lifecycle Once an application is installed on a device, it stays there until specifically uninstalled by the user of the device. Installation is a permanent action. The application management software that comes with the device activates the application. The MIDP specification does not define how this software works, but it does define how the software creates and activates a MIDlet. The application manager first creates an instance of the MIDlet by using its no-argument constructor. It then calls the MIDlet’s startApp method to place it in the active state.


10/17/2000 4:51 PM

Page 115

Profiles

115

A MIDlet can be in one of three possible states: active, paused, or destroyed. If the MIDlet is active, it is currently running. If the MIDlet is paused, it has released any resources that it was holding on to (such as a network connection) but is ready to be reactivated. A MIDlet in the destroyed state has permanently shut itself down, released all its resources for good, and is waiting to be garbage collected. State changes occur in response to the user interacting with the application management software. When the MIDlet is activated, its startApp method is called. When it is paused, the pauseApp method is called. When it is destroyed, the destroyApp method is called. If the MIDlet is not ready to be started or destroyed, it can throw a MIDletStateChangeException to defer the state change. The MIDlet can also enter the paused or destroyed states at any time by invoking the notifyPaused or notifyDestroyed methods.

User Interface Classes The most exciting part of the MIDP specification to many programmers are the user interface (UI) classes that it defines. These classes are informally referred to as the MIDP UI APIs and are part of the javax. microedition.lcdui package. All classes referred to in this section are from this package unless otherwise noted. The MIDP UI APIs and Abstract Windowing Toolkit (AWT) The MIDP UI APIs are not based on the AWT. Although AWT forms the basis for the user interface classes defined by J2SE, the MIDP expert group felt that it was not suitable for use on MIDs because the user interaction model on these devices is different. AWT is also quite memoryintensive. It creates many objects (the classes java.awt.Event, java.awt.Point, and java.awt.Dimension are used extensively, for example) that can easily overwhelm the garbage collector on a small device. AWT also requires the existence of a pointing mechanism, something not found on all devices targeted by the MIDP specification. The KVM team used similar reasons for rejecting AWT, but they also had the freedom to build Palm-specific UI classes. Therefore, the classes found in the Palm implementation of the CLDC are not the


116

10/17/2000 4:51 PM

Page 116

CHAPTER 6

same as those defined by the MIDP. (Remember that the CLDC does not define any UI classes, so the reference implementation had to include some way in which to interact with the user until a formal set of classes could be defined. We will discuss these in the next two chapters.) Like AWT, however, the MIDP UI APIs are meant to be cross-platform (at least, to a certain degree). The MIDP UI APIs are composed of two sets of classes: a high-level API and a low-level API. With the high-level API, an application uses task-oriented abstractions to define what the user interface should do (such as present a list of choices to the user) but not specifically how to perform the actions. An application that uses the high-level API exclusively is guaranteed to be portable across MIDP-enabled devices. The low-level API, on the other hand, provides direct access to the display and to any input events. But because different devices have different sizes of displays and different input methods, dependence on these low-level capabilities can limit application portability. When it comes right down to it, the high-level API is really geared toward business-application developers, while the low-level API is meant for game developers. The MIDP implementation can, of course, also add its own devicespecific user interface classes to expose features that are unique to the device. Using these classes will limit application portability, just like the low-level UI API does. Screens and Events A MIDlet uses screens for output purposes. A screen is an object that draws graphics on the device’s display, which is analogous to a window in most user interface systems. Its behavior, however, is different from most windowing systems: only one screen at a time is visible. In J2SE terms, perhaps the best analogy is to think of screens as individual cards in a card layout as defined by java.awt.CardLayout. In this model, an application is basically a deck that switches from card to card in response to user input or other input. There are three kinds of screens from which to choose. The simplest to use are the predefined screens that encapsulate common user interface behaviors. For example, there is a List screen that displays a list of choices to the user. How that list is displayed—by using a listbox, a


10/17/2000 4:51 PM

Page 117

Profiles

117

Table 6.3 Predefined Screens CLASS

DESCRIPTION

Alert

Displays text and images to the user for a specific length of time or until the user dismisses the screen. Limited control over the layout.

List

Displays a list of choices. Each choice is a string and an optional image. How the list is displayed is up to the screen, but the user can navigate through the list of choices as long as necessary. Both single and multiple selection are supported.

TextBox

Displays a screen of titled, editable text with an optional initial value and a maximum number of characters to accept. Simple constraints are defined for entering common values such as URLs, e-mail addresses, phone numbers, numbers, and passwords.

drop-down listbox, a menu, or something else—is up to the implementation. The application is merely notified when the user chooses an item. All predefined screens are subclasses of the abstract class Screen and are summarized in Table 6.3. If the predefined screens are not suitable, individual user interface controls can be grouped together on a screen called a form, although the exact layout of the controls is left up to the screen. A form is defined by the Form class, which is also a subclass of Screen. The items that can be placed on a form are listed in Table 6.4. For complete control over what is drawn on the screen, a canvas screen is used. Using a canvas, which is a subclass of the Canvas class, is an all-or-nothing proposition. You have to do all of the drawing. The Canvas class is the only screen class that does not extend Screen. All screens, however, are subclasses of Displayable. The application uses the Display class to control which screen is current and to obtain some minimal information about the display. Display is a singleton class, which means that there is only one instance of a Display object created per MIDlet. The MIDlet calls Display.getDisplay in order to obtain the object. Input events are also handled by using different abstraction levels. At the highest level, events are handled by defining commands, which are objects that define actions with semantics drawn from a predefined list. For example, the application would display the previous screen in


118

10/17/2000 4:51 PM

Page 118

CHAPTER 6

Table 6.4 Form Items CLASS

DESCRIPTION

ChoiceGroup

Displays a list of choices. Each choice is a string and an optional image. Both single and multiple selection are supported. Single selection is most often represented by radio buttons, and multiple selection is represented by check boxes. But the implementation must decide on the best approach.

DateField

Displays editable date and/or time information

Gauge

Displays a bar graph. Typically used to display progress bars or to let the user choose between a fixed range of values.

ImageItem

Displays a labeled image. The image can specify limited layout information in order to control its placement on the screen.

StringItem

Displays labeled, non-editable text.

TextField

Displays labeled, editable text with an optional initial value and a maximum number of characters to accept. Simple constraints are defined for entering common values such as URLs, e-mail addresses, phone numbers, numbers, and passwords.

response to a back command. How the user invokes the command is out of the application’s control. The device is free to use buttons, menus, or whatever other controls that it wants—regardless of whether they are hardware- or software-based. All the application can do is specify the type and priority of the command and assign it a label. Commands are instances of the Command class. Commands can be attached to any screens (any subclass of Displayable). Lower-level events such as key presses are only available on canvases. The system calls methods on the Canvas class in response to individual events in a way that is reminiscent of the original AWT event model. Instead of using event objects, however, the event parameters—the keycode for key events and the x and y coordinates for pointer events—are passed as simple integers. Keycodes are defined for the basic keys that are common to all MIDs (specifically, the keys on a telephone keypad), but any other keys are device-specific and nonportable. A mapping from keycodes to abstract game events (such as DOWN or FIRE) is also available. The mapping is controlled by the device and can work with keypads or full-function keyboards. As for pointer events, not every device supports pointer-based input, so an application should not depend on their existence; rather, it should check for the capability when started and adapt itself accordingly.


10/17/2000 4:51 PM

Page 119

Profiles

119

Drawing and Repainting The low-level API defines methods for drawing text and graphics on the display and for repainting the display. These capabilities are only available with canvases, because painting is handled automatically for all other screen types. Drawing is done by using a conventional two-dimensional model with the origin of the coordinate system in the upper-left corner. Twenty-fourbit color is supported, although the device might map the colors onto its own less-extensive palette as appropriate. Three font faces are available in three sizes and four styles, although the device might not support them all and will substitute a different font if necessary. The expected methods are available for drawing strings, rectangles, lines, images, and arcs. Drawing can be done directly to the display or to an off-screen memory buffer. These capabilities are all available through the Graphics class. Repainting occurs when the system calls the canvas’ paint method, which must be overridden by subclasses of Canvas. A Graphics object is passed to the paint method with its clipping area set to the union of the areas that need repainting. Here is a simple example of a paint method: protected void paint( Graphics g ){ g.setGrayScale( 255 ); g.fillRect( 0, 0, getWidth(), getHeight() ); g.setGrayScale( 0 ); g.drawLine( 0, 0, getWidth(), getHeight() ); }

Double Buffering In order to perform flicker-free animation, the double buffering drawing technique is often used. In double buffering, you draw not to the display but to a memory buffer, drawing a complete image every time. When you are done drawing to the buffer, you use a single operation to copy the contents of the buffer to the display. Usually, this process is much faster than using individual drawing operations directly on the display and avoids any noticeable flicker. Although the MIDP supports this kind of animation, you might find that the device does not perform the copy quickly enough to avoid the user noticing it. If this situation is the case, your best choice is to draw the individual changes instead of redrawing the entire image. This process is harder with the MIDP, however, because the Graphics class does not even support any methods to perform exclusive OR (XOR) or other bit operations.


120

10/17/2000 4:51 PM

Page 120

CHAPTER 6

Like any modern graphics system, multiple paint requests are coalesced by the system into a single paint request whenever possible, because there is usually a slight delay between a paint request and the time that the painting actually occurs. You can call the serviceRepaints method to force the painting to occur right away. Threading Issues Like the original AWT classes (but unlike the newer Swing classes), the MIDP UI APIs are thread-safe. The methods can be called at any time from any thread. The only potential for deadlock occurs when you use serviceRepaints to force immediate repainting of the display. To avoid the deadlock, do not lock any objects that the paint method will use. To run some code after any pending repaints have been serviced, use the callSerially method of the Display class, passing in a Runnable object. The object’s run method will be invoked soon after the initial call. The run method is always called on the event thread, no matter which thread invoked callSerially.

Other MIDP Classes Apart from the MIDlet and UI classes, the MIDP specification also defines classes for data persistence, networking, and task scheduling. The Record Management System The MIDP defines a set of classes in the javax.microedition.rms package for storing data in a simple database. The classes are referred to as the Record Management System (RMS) because they work on arbitrary records of data, which are read and written by using byte arrays. Remember, there is no object serialization in the CLDC. If you are at all familiar with a conventional record-based database system, such as the Palm OS native database format, you will not find anything surprising here. Records are stored in a record store by the RMS and are represented by the RecordStore class. The contents of a record store persist across different invocations of the MIDlet that created it. The record store can


10/17/2000 4:51 PM

Page 121

Profiles

121

be accessed by other MIDlets, but only if they are members of the same MIDlet suite. The record store is removed whenever the MIDlet suite with which it is associated is removed. No APIs are defined by the RMS or elsewhere in the MIDP to interface with any native databases that the device might support. Any such APIs are left for the implementation to provide as non-portable extensions to the profile. The RMS implementation might actually use a native database to store the records, but the details are never exposed to the developer. A record store has a name that must be unique within the MIDlet suite (different stores in different suites can use the same name) and that can consist of no more than 32 characters. Methods are available for creating, opening, closing, and deleting record stores, as well as listing all of the available record stores. Here is a simple example that uses a few of these methods: import javax.microedition.rms.*; // Cycle through existing record stores try{ String[] stores = RecordStore.listRecordStores(); for( int i = 0; stores != null && i < stores.length; ++i ){ RecordStore s = RecordStore.openRecordStore( stores[i], false ); System.out.println( "Record store " + stores[i] + " has " + s.getNumRecords() + " records." ); s.closeRecordStore(); } } catch( RecordStoreNotFoundException e ){ ..... } catch( RecordStoreFullException e ){ ..... } catch( RecordStoreException e ){ ..... }

Each record in a store is given a unique identifier, the record ID, which is an integer greater than or equal to 1. All operations on an individual record take a record ID as a parameter. The RMS provides the usual operations for creating, reading, writing, and deleting records. Record change notifications are passed to any registered RecordListener objects that are associated with the record store. All operations on


122

10/17/2000 4:51 PM

Page 122

CHAPTER 6

individual records are performed by using byte arrays. The DataInputStream, DataOutputStream, ByteArrayInputStream, and ByteArrayOutputStream classes from the javax.microedition.io package (part of the CLDC) can be used to move data in and out of byte arrays if you would rather not deal with byte values directly: import javax.microedition.rms.*; import java.io.*; // Note that exception handlers are left out for simplicity. RecordStore r = .....; // Get data out of the first record using a datainput stream. byte[] data = r.getRecord( 1 ); DataInputStream in = new DataInputStream( new ByteArrayInputStream( data ) ); boolean bval = in.readBoolean(); String sval = in.readUTF(); // etc. etc. // Store data into the first record using a dataoutput stream. ByteArrayOutputStream bstream = new ByteArrayOutputStream(); DataOutputStream out = new DataOutputStream( bstream ); out.writeBoolean( true ); out.writeUTF( "some string" ); data = bstream.toByteArray(); r.setRecord( 1, data, 0, data.length );

Sorting and searching is done by using the enumerateRecords method, which returns a RecordEnumeration object for traversing through a list of records. You can pass in optional RecordComparator and RecordFilter objects to determine the order and subset of the records that are to be returned. The enumeration can even register its own RecordListener to track any changes that you make to a record store in order to maintain a valid record list (this operation is expensive, however, if you are constantly making changes). Note that the actual record store is never sorted, so two different RecordEnumeration objects can return two different sorts of the same record store without conflict.


10/17/2000 4:51 PM

Page 123

Profiles

123

The RMS classes are thread-safe in the sense that individual operations are guaranteed to be atomic. If two threads call setRecord on the same record, no corruption will occur. But the final contents of the record will be set by the second thread to run. The application must ensure that different threads do not write over each other’s data. HTTP Connections The MIDP specification adds a communication driver for the HTTP protocol to the Generic Connection framework. HTTP is a client-server protocol in which the client makes requests and the server sends back responses. A subset of the HTTP 1.1 protocol is supported—the GET, POST, and HEAD methods—with full header support in both requests and responses. Connections are made by using a Universal Resource Identifier (URI) that starts with the http: prefix, as shown in our discussion of the Generic Connection framework. What is returned is an instance of an HttpConnection—an interface that extends ContentConnection. Note that while HTTP usually runs over a circuit-oriented (TCP/IPbased) network, HTTP does not require such a network. The device is free to simulate such a connection as appropriate for the network that it is using. This situation usually means installing some kind of gateway to act as the bridge from the network to the Internet. The implementation must be completely transparent to a program that is making use of HTTP connections, no matter how it is done. Here is a simple example of using the HTTPConnection class to access a Web page—again, with exception handling removed for simplicity: import javax.microedition.io.*; import java.io.*; HttpConnection conn = (HttpConnection) Connector.open( "http://www.ericgiguere.com" ); InputStream in = conn.openInputStream(); String cache = conn.getHeaderField( "Cache-control" ); int length = conn.getLength(); if( length != -1 ){


124

10/17/2000 4:51 PM

Page 124

CHAPTER 6 // // } else // // }

length is known, could read directly into a byte array if convenient { length is not known, have to read data a byte at a time until the end-of-stream is reached

The only other restriction that the MIDP specification makes is that if the device includes a User-Agent header in its requests, it must contain information about the CLDC and MIDP versions being used. Additionally, the Content-Language header must be supplied in order to identify the locale of the device. You perform this task by calling the setRequestProperty method before opening an input or output stream on the connection: HttpConnection conn = (HttpConnection) Connector.open( "http://www.ericgiguere.com" ); conn.setRequestProperty( "User-Agent", "Profile/MIDP-1.0 Configuration/CLDC-1.0" ); conn.setRequestProperty( "Content-Language", "en-US" ); InputStream in = conn.openInputStream();

A Web server can use the information in these headers in order to prepare its response based on the device’s capabilities and locale. No other protocol is specified as part of the profile, although of course, implementations can provide their own device-specific communication drivers. RIM’s MIDP implementation, for example, provides a driver for directly sending and receiving packets on the wireless network. Timer Notifications The final set of classes defined by the MIDP specification are the two timer classes: java.util.Timer and java.util.TimerTask. These classes are inherited from J2SE 1.3 and are used to schedule tasks for later execution or to notify the application when a timer expires. A Timer object creates a background thread on which it will execute callbacks to objects that implement the TimerTask interface. These callbacks can occur at specific times or at regular intervals. Here is a simple example: class DoSomething extends TimerTask { public void run() {


10/17/2000 4:51 PM

Page 125

Profiles

125

// do something here } } .... // Schedule a task to occur in 10 seconds Timer t = new Timer(); t.schedule( new DoSomething(), 10000 );

Other Profiles At this writing, a number of other J2ME profiles are under development.

The PDA Profile Like the MIDP, the PDA Profile is built on top of the CLDC, but is targeted specifically at personal digital assistants, which have more memory and more sophisticated user interfaces than the low-end devices targeted by the MIDP. The PDA Profile requires that a device have at least 512K of memory (either RAM or a combination of ROM and RAM) available for the Java runtime environment. The profile also requires the device to have a display with a resolution of at least 20,000 pixels, some kind of pointing device, and the ability to enter character data. Although the PDA Profile is still in a very early stage of development at this writing, all indications are that it will include a set of user interface classes that will subset the AWT classes of J2SE. The PDA Profile expert group includes the developers of kAWT, a subset of AWT written for the Palm port of the CLDC reference implementation. To provide compatibility with the MIDP, the PDA Profile may also include the MIDP user interface components, written to use the AWT subset.

The Foundation Profile The Foundation Profile is built on top of the CDC, not the CLDC, and is meant to serve as the foundation for other CDC-based profiles. It bumps up the minimum memory requirements of the CDC to 1024K of non-volatile memory and 512K of volatile memory. It does not provide


126

10/17/2000 4:51 PM

Page 126

CHAPTER 6

any user interface classes; rather, these are provided by a profile based on the Foundation Profile. What the Foundation Profile does is augment the CDC with many of the J2SE APIs that it omits. The complete list is too long to print here, so refer to the specification for all of the details.

The Personal Profile The Personal Profile is the first J2ME-based version of the PersonalJava runtime environment. Rather than existing separately from J2ME, the new Personal Profile builds on top of the Foundation Profile by adding the classes that are necessary for running PersonalJava applications on a CDC-based device. The minimum memory requirements are significantly higher than the Foundation Profile—2.5MB of non-volatile memory and 1MB of volatile memory. Perhaps the biggest addition that the Personal Profile brings to the Foundation Profile is that the Personal Profile includes the user interface classes from PersonalJava.

The RMI Profile The final profile being developed is the RMI Profile. Like the Personal Profile, the RMI Profile is built on top of the Foundation Profile and has the same minimum memory requirements as the Personal Profile. It just adds the J2SE RMI classes to the Foundation Profile. Applications that are built by using the RMI Profile will be compatible and interoperable with RMI-based applications that are built with J2SE 1.2 or higher.

Chapter Summary In this chapter, we described the MIDP in quite some detail and briefly mentioned other profiles that are under development. The MIDP is particularly important because it is the first profile that defines user interface APIs for small devices. In the next part of this book, we will look at implementations that put these specifications into practice.


10/17/2000 4:52 PM

Page 127

PA R T

THREE

Java 2 Micro Edition (J2ME) Implementations


10/17/2000 4:52 PM

Page 128


10/17/2000 4:52 PM

Page 129

CHAPTER

7

The Connected Limited Device Configuration (CLDC) Reference Implementation

A

t this point, you are probably wondering when we will get down to the nitty-gritty details of Java 2 Micro Edition (J2ME) coding. This chapter and the remaining chapters are the ones for which you have been waiting. This chapter shows you how to run CLDC-based Java programs on your desktop computer, running either the Windows or Solaris operating systems, by using the Connected Limited Device Configuration (CLDC) reference implementation.

Overview All of the information in this chapter is based on the CLDC 1.0 reference implementation, which you can find at www.sun.com/software/ communitysource/j2me/. This implementation is free to download and use but is subject to the restrictions of the Sun Community Source License (SCSL).

129


130

10/17/2000 4:52 PM

Page 130

CHAPTER 7

About SCSL The Sun Community Source License allows you to download the source to specific Sun-developed software for your own research and development purposes. If you write a product that requires or is based on the Sun software, you must obtain a deployment license from Sun Microsystems. Refer to the licensing page at www.sun.com/software/communitysource/index.html for more details.

There are two forms of the reference implementation: the official reference platform, which runs on Windows or Solaris, and a port of the reference for Palm devices. We will discuss the Palm port in the next chapter, so in this chapter we will only deal with the reference implementation. Keep in mind that what we are discussing here is an implementation of the CLDC—not the Mobile Information Device Profile (MIDP), which we will discuss later in Chapter 9, “The MIDP Early Access Release.” The CLDC reference implementation, however, does include a number of additional classes that are comparable to what you will find in the MIDP, except that these classes are not as general—and Sun Microsystems does not officially support them. For brevity, we will often refer to the CLDC 1.0 reference implementation as “the CLDC” throughout the remainder of this chapter.

Installation The CLDC is packaged as a single ZIP archive for both Windows and Solaris. Installation is simple. Just extract the contents of the ZIP file into a directory on your desktop system. You do not need to invoke a setup program. The ZIP file contains the following items: ■■

■■

Binaries for the KVM interpreter and the preverification tool (in the bin directory) as well as the complete source for both (in the kvm and tools\preverifier directories) Compiled versions of the CLDC classes and the non-CLDC extensions (in the bin\api directory)


10/17/2000 4:52 PM

Page 131

The Connected Limited Device Configuration (C LD C) Reference Implementation ■■

■■ ■■

■■

131

Documentation for all of the classes, in Hypertext Markup Language (HTML) and Portable Document Format (PDF), along with release notes, the complete CLDC 1.0 specification, and a guide to porting the KVM (in the docs directory) Sample programs (in the samples and bin\samples directories) Source code for the Java Application Manager (JAM), a sample implementation of the application management software referred to by the CLDC specification (in the jam directory) Source code for the JavaCodeCompact (JCC) tool, which is used for pre-loading/pre-linking Java classes for use by the KVM (in the tools\jcc directory). We do not discuss JCC here, because it is primarily a tool for device manufacturers.

The source code for the KVM and the tools might not interest you, but the reference implementation is for device manufacturers (or anyone else who wants to port the KVM to a different platform) as well as third-party developers. This implementation includes everything that is necessary to build the complete reference implementation on either Windows or Solaris platforms. Refer to the release notes and the KVM Porting Guide for details concerning how to compile the KVM and all of the tools. Note that some parts of the KVM are optional and can be enabled or disabled when the virtual machine (VM) is built. In the bin directory, you will find two binaries for the KVM for each platform: a regular KVM (kvm.exe for Windows and kvm for Solaris) and a KVM with JAM support (kvm_j.exe for Windows and kvm_j for Solaris). If you want to experiment with different combinations of optional features, you will have to compile your own version of the KVM.

Running the Samples The CLDC comes with a number of sample programs to get you started. If you have built the KVM yourself, there is a batch file for Windows (kw.bat) or a shell file for Unix (ku) in the samples directory that you can use to run an individual sample. To run the samples by using the pre-built KVM binary, just change these files. For example, the Windows batch files looks like the following:


132

10/17/2000 4:52 PM

Page 132

CHAPTER 7 ..\kvm\VmWin\build\kvm.exe -classpath ..\api\classes;..\samples\classes %1%

Just change the path to the kvm.exe and to the classes: ..\bin\kvm.exe -classpath ..\bin\api\classes;..\bin\samples\classes %1%

Alternatively, you can define a KVM_HOME environment variable and set it to the root of the CLDC installation and change the batch file to the following: %KVM_HOME%\bin\kvm.exe -classpath %KVM_HOME%\bin\api\classes;%KVM_HOME%\bin\samples\classes %1%

Place the batch file somewhere in your command path, and you will be able to run the samples from any directory. Otherwise, you have to run them from within the samples directory. You can define a similar shell script for Unix or just define a shell alias. Now, you are ready to run the samples. The samples are mostly simple games that are meant to demonstrate the user interface classes and the speed of the KVM more than doing anything particularly useful. This statement brings up an interesting point. What kind of user interface does the reference implementation provide? The answer is that the reference implementation provides additional non-CLDC classes that simulate the user interface of a Palm device. In other words, they have ported the classes from the Palm CLDC implementation, which we will discuss in the next chapter, and made them work with Windows and Unix. You should note that these classes—all of which are found in the com.sun.kjava package—are not an official part of the CLDC specification. These and other classes that are not in the java or javax packages are provided solely for testing and demonstration purposes. Remember that configurations are not expected to be used by themselves; instead, applications are meant to run in the context of a profile that provides additional functionality that is not found in the configuration. Run the first sample, UITest, from the samples directory by typing either kw UITest for Windows or ku UITest for Unix. You should immediately see a window displaying a crude Palm-like device, as shown in Figure 7.1. This device is the Palm simulation provided by the CLDC, which is not sophisticated but adequate for testing purposes.


10/17/2000 4:52 PM

Page 133

The Connected Limited Device Configuration (C LD C) Reference Implementation

133

Figure 7.1 The KVM Palm-like user interface for Windows.

The display is 160 pixels wide by 160 pixels high, just like the Palm display. Pen taps are simulated by moving the mouse over the display and pressing the primary mouse button (usually the left button). Pen strokes are simulated by dragging the mouse across the display. The elliptical areas at the bottom of the display represent the buttons on a Palm device. The leftmost area is the power button, followed by the Date Book and Address Book buttons, the scroll up and scroll down buttons, and the To Do and Memo Pad buttons. You can press the power button at any time to exit the simulation, but be aware that on a real Palm device, that action will not terminate a running application, it will just suspend the device. Character input on a real Palm device is done by using pen strokes, but with the simulator, just use the keyboard. The samples are summarized in Table 7.1. Refer to the release notes for detailed descriptions and instructions. Each sample is run by using the kw or ku command and the name of the sample as its only argument. The most interesting and complicated samples are dots.DotGame and missiles.Missiles, the latter being much easier to play on an actual device. You can find the source for each sample in the samples directory.


134

10/17/2000 4:52 PM

Page 134

CHAPTER 7

Table 7.1

CLDC Samples

NAME

DESCRIPTION

dots.DotGame

A game where players take turns connecting dots to outline boxes. You can play against the computer or against another human on another device.

Dragon

Draws dragon-like fractal images wherever you tap on the display.

ManyBalls

Uses threads to animate several bouncing balls.

missiles.Missiles

A game where you try to shoot flying saucers out of the sky while avoiding the missiles as they drop.

Pong

The classic ball-and-paddle game.

Scribble

Lets you scribble on the display while animating a bouncing ball.

StarCruiser

A game where you move your spaceship to avoid oncoming asteroids.

ThreeDLogo

Draws a logo that you can rotate in three dimensions. When you run this game on the Palm, you can even beam the rotation information to another device that is running the same application.

UITest

Demonstrates a few user interface controls.

Compiling, Preparing, and Running Classes After playing with the samples, you should try writing an application of your own. You can perform this task on the desktop computer by using your normal development tools. You will need the compiler and tools from JDK 1.2.2 or higher in order to compile the files, after which you will run them through the preverification tool in order to prepare them for execution by the KVM. The basic command to compile a set of classes is as follows under Windows: javac -g:none -bootclasspath %KVM_HOME%\bin\api\classes -classpath %KVM_CLASSPATH% -d %KVM_TMP_DIR% *.java

This command, and all the commands in this section, should be entered as a single line on the console. The Unix command is identical, except that the paths and environment variables are in shell format instead of MS-DOS format. In either case, it is a fairly standard javac command line, except for the addition of the –g and –bootclasspath options.


10/17/2000 4:52 PM

Page 135


135

The –g option ensures that javac does not generate any debugging information into the class files that it outputs. Also, because javac automatically adds the Java 2 Standard Edition (J2SE) runtime classes to the classpath (a feature that was new to JDK 1.2), the –bootclasspath option overrides this behavior by adding the CLDC classes instead. You must not include the J2SE classes in the classpath in order to ensure that you do not accidentally use classes that are not in the CLDC. Notice that the command references the KVM_HOME, KVM_CLASSPATH, and KVM_TMP_DIR environment variables. Define KVM_HOME as we did for running the samples. KVM_CLASSPATH is the set of directories and/or Java Archive (JAR) files to use when searching for classes that are not explicitly passed to javac for compilation. You can, of course, use the normal CLASSPATH variable instead, but it is often simpler to separate the Java 2 Micro Edition (J2ME) classpath from the J2SE classpath. KVM_TMP_DIR is the temporary output directory where the class files reside before being preverified. The next step is to run the preverifier on the class files: %KVM_HOME%\bin\preverify -d %KVM_OUTPUT_DIR% -classpath %KVM_CLASSPATH%;%KVM_HOME%\bin\api\classes %KVM_TMP_DIR%

The preverifier can work on individual class files or directories of class files. Directories are searched recursively for any class files. Here, we have defined another environment variable, KVM_OUTPUT_DIR, to hold the preverified class files. Note that if the output directory is in the preverifier’s classpath (in other words, if KVM_OUTPUT_DIR is in KVM_CLASSPATH), the preverifier will not work correctly. At this point, you can either run the classes directly or package them into a JAR file. The command to use in order to run them is as follows: %KVM_HOME%\bin\kvm -classpath %KVM_OUTPUT_DIR%;%KVM_CLASSPATH%;%KVM_HOME%\bin\api\classes MainClass

This example assumes, of course, that the class to run is called MainClass. Note that if you do not specify the –classpath option, the KVM uses the value of your CLASSPATH environment variable.


136

10/17/2000 4:52 PM

Page 136

CHAPTER 7

To actually start the application, the KVM loads the specified class and looks for the usual application entry point: public static void main( String[] args ) { // ... do the application stuff }

The application runs until all threads terminate (the CLDC does not enable daemon threads to be created, and all threads have equal standing) or until the System.exit method is called. As you experiment with the KVM, you will find it convenient to define a set of batch files or shell scripts in order to perform these operations and to reduce the amount of typing that you do. In formal projects, you will probably use a makefile of some kind—just like the sample makefiles that come with the CLDC.

The Hello World Application Let’s compile and run a simple application. Define the HelloWorld class as follows: public class HelloWorld { public static void main( String[] args ) { System.out.println( "Hello, world!" ); // Wait for ten seconds try { Thread.sleep( 10000 ); } catch( InterruptedException e ){ } } }

All this class does is print a line of text and wait 10 seconds before exiting. Now, compile, preverify, and run the class. On Windows, the sequence of three commands would be as follows: javac -g:none -bootclasspath %KVM_HOME%\bin\api\classes -classpath %KVM_CLASSPATH% -d %KVM_TMP_DIR% HelloWorld.java


10/17/2000 4:52 PM

Page 137


137

%KVM_HOME%\bin\preverify -d %KVM_OUTPUT_DIR% -classpath %KVM_CLASSPATH%;%KVM_HOME%\bin\api\classes %KVM_TMP_DIR% %KVM_HOME%\bin\kvm -classpath %KVM_CLASSPATH%;%KVM_HOME%\bin\api\classes HelloWorld

You should see the string Hello, world! printed on your console. Are you surprised that the program worked? If you read through the CLDC API specification, you saw that the System.out and System. err output streams were both available. In the reference implementation, these streams are both redirected to the KVM’s own standard output stream and from there to the console. Not all devices support a console, of course, and on those devices, the streams might write to a file, to a database, or to some other device-specific output mechanism. The Palm implementation, for example, writes its output to a record database. In general, then, you should only use System.out for debugging and tracing purposes, because the output might not be visible to the program user.

The Hello World Spotlet To display a user interface and to receive input events, an application must define a class that extends the com.sun.kjava.Spotlet class (the user interface classes were originally created for the Spotless project that we discussed in Chapter 4). Such an application is called a spotlet. We will defer our discussion of spotlets until the next chapter, but here is the HelloWorld application reworked as a spotlet: import com.sun.kjava.*; public class HelloWorldUI extends Spotlet { public static void main( String[] args ) { new HelloWorldUI(); } public HelloWorldUI() { Graphics g = Graphics.getGraphics(); g.clearScreen();


138

10/17/2000 4:52 PM

Page 138

CHAPTER 7 g.drawString( "Hello, world!", 0, 0 ); } }

Compile and preverify this class as we did with HelloWorld, replacing all references to HelloWorld with HelloWorldUI. Run the spotlet, and you will see the output shown in Figure 7.2. Press the simulator’s power button to exit the application.

Spotlets Keep Running Note that when a spotlet is created, the KVM keeps running until the user presses the simulator’s power button or until the spotlet invokes System.exit. A static initializer in the Spotlet class creates a thread that waits for and services input events.

Figure 7.2 The HelloWorldUI spotlet.


10/17/2000 4:52 PM

Page 139


139

Memory Usage When the KVM starts, it immediately allocates all of the memory that it will require to run an application—except for any memory that is separately allocated by native methods. A desktop system running Windows or Unix has much more memory than a typical device targeted by the CLDC. To more properly emulate these devices, the desktop version of the KVM limits the amount of memory that it can allocate for the Java heap to 150,000 bytes. You can change this limit only by recompiling the VM.

The JAM The CLDC reference implementation includes a sample implementation of a JAM. The CLDC specification does not state how the application management software is to be implemented (it does not actually refer to it by a specific name), other than acknowledging its existence. There has to be some way to download and install Java applications and make some general statements about what the applications should do. CLDC-based profiles can be more specific, of course, and the MIDP does just that by requiring specific attributes in a JAR manifest and defining an optional application descriptor. The JAM that accompanies the CLDC reference implementation is just a sample that device manufacturers and other CLDC implementers can use as a basis for their own application management software. In particular, it does not follow the MIDP specification’s manifest and descriptor requirements, although its requirements are similar. To use the JAM, you need three items: a properly-marked JAR file, a descriptor file, and a JAM-enabled version of the KVM. The latter is included with the CLDC reference implementation, and you will find a kvm_j executable in the bin directory. This executable is identical to the KVM executable that you have used so far, except that it supports three new command-line options: ■■ ■■

The –jam option enables JAM. The –repeat option makes the JAM repeat failed downloads until a download succeeds.


140

10/17/2000 4:52 PM

Page 140

CHAPTER 7 ■■

The –appsdir path option specifies the path to the JAM application installation directory. If not specified, it defaults to the instapps subdirectory of the current directory.

You must set the classpath to include the CLDC runtime classes but not the application classes. Also, instead of specifying the name of the main class, you pass the URL of the JAM descriptor, which is a text-file ending (.jam) fetched from either a Web server or from the local file system. For example: kvm -jam -repeat -appsdir http://localhost/MyApp.jam

The JAM descriptor describes the application to be downloaded, installed, and run. This descriptor is really just a JAR manifest with the attributes defined in Table 7.2. For example: Application-Name: MyApp Application-Version: 1.0.0 KVM-Version: 1.0 JAR-File-URL: MyApp.jar JAR-File-Size: 8223 Main-Class: com.mycompany.MyApp Use-Once: no

After fetching the descriptor, the KVM uses these attributes to determine whether a version of the application is already installed locally. If so, and if the version is equal to or greater than the version specified in the descriptor file, then the already-installed JAR file is used to launch the application. Otherwise, a new JAR file is downloaded and run in its place. Table 7.2

JAM Attributes

NAME

DESCRIPTION

Application-Name

The name of the application

Application-Version

The version of the application (a string of the form XX.YY or XX.YY.ZZ, where XX is the major version, YY is the minor version, and ZZ is the micro version)

KVM-Version

The version of the KVM required to run the application

JAR-File-URL

The URL to use to download the application

JAR-File-Size

The size of the application in bytes

Main-Class

The name of the application’s main class

Use-Once

If the value is yes, then the application is immediately deleted after being run once.


10/17/2000 4:52 PM

Page 141


141

Debugging Debugging CLDC-based or MIDP-based applications is in many ways similar to returning to the early days of Java. A VM based on the CLDC specification does not have debugging support, so do not expect anything else than the capability to dump program output to a stream. Individual implementations might provide their own debugging facilities, but it is not a requirement of the specification. Because a debugger is rarely available, the best approach to take is to build two versions of your application right from the beginning: a debug version and a production version. Define a Debug class as follows: // For building the debug version public class Debug { public static final boolean on = true; }

Create a second version of the class, but set the on field to false: // For building the production version public class Debug { public static final boolean on = false; }

Because the classes are identical, you will need to place the compiled files in separate directories. When building the debug version of your application, include the first version of the class in the classpath. When building the production version, include the second version of the class. In your code, wrap your debugging or tracing statements as follows: if( Debug.on ){ // place debugging/tracing code here // i.e. calls to System.out.println }

When building the production version of the application, the compiler will then ignore the wrapped code. You can easily add assertion facilities to the Debug class: public class Debug { public static final boolean on = true; public void assert( boolean condition, String message ){


142

10/17/2000 4:52 PM

Page 142

CHAPTER 7 if( on ){ System.out.println( "ASSERTION FAILURE: " + message ); // optionally throw an exception } } }

When you use assertions, however, wrap them as well: if( Debug.on ) Debug.assert( p != null, "p is null" );

Otherwise, you can end up with unnecessary code in the production version of the application.

Internet Resources If you are interested in the CLDC and all things related to it, consider joining the KVM-Interest mailing list. Originally a mailing list for early users of the KVM, the list has since expanded to cover related technologies such as the CLDC and the MIDP. The messages sent to the list are archived and are available from http://archives.java.sun.com/archives/ kvm-interest.html. You can use that URL to join the list and to receive messages as they are posted or in daily digest format. For other CLDC-related resources, refer to the KVMWorld Web site (www.kvmworld.com) or the book’s Web site at www.ericgiguere.com/ microjava.

Chapter Summary In this chapter, we examined how to compile and run J2ME applications on the desktop by using the CLDC. Now, we move on to running Java applications on Palm devices.


10/17/2000 5:14 PM

Page 143

CHAPTER

8


R

unning Java 2 Micro Edition (J2ME) on the desktop is fine for testing purposes, but at some point you have to run the program on a real device. This chapter shows you how to run J2ME applications on Palm Connected organizers. If you do not own a Palm device, you have no need to worry. You can test your programs by using the Palm OS Emulator, which is a tool that you can download for free.

Using the CLDC with Palm Devices Whether people refer to them as Pilots, Palm Pilots, or Palm organizers, the family of devices from Palm, Inc. is the most successful group of personal digital assistants (PDAs) ever sold. It makes sense that the first port of the CLDC is for the Palm platform, because it has such a large installed base. It’s also the platform for which the KVM was initially developed.

143


144

10/17/2000 5:14 PM

Page 144

CHAPTER 8

A Palm Primer If you have never done any Palm programming or own a different kind of device (such as the PocketPC), this short primer will give you enough background to get started. For more information about Palm programming, consult a book such as Palm Database Programming: The Complete Developer’s Guide or Advanced Palm Programming: Professional Developer’s Guide, both from John Wiley & Sons, Inc. A User’s Perspective There are many models in the Palm Connected organizer family, but they all share a similar form factor. A typical Palm device, the Palm V, was shown in Figure 1.3 in the first chapter and measures about 7.5 cm wide by 11 cm high. This device is small enough to fit comfortably in the palm of your hand, freeing the other hand to press buttons and to use a stylus on the touch-sensitive screen. The screen is 160 pixels wide by 160 pixels high, which is enough for a dozen or so lines of text plus menus. There is no keyboard on the Palm; instead, all text input is entered via the touch screen by using a system of pen strokes called Graffiti. (Die-hard keyboard users can actually buy an external folding keyboard for intensive data entry, as we saw in Chapter 1.) The differences between the various models (starting with the original Pilot and leading up to today’s Palm VII and Palm IIIc) are mostly evolutionary. In general, the more recent the model, the more memory that it has—and the more sophisticated the operating system. All recent models include infrared support, which enables you to beam data and applications from one device to another. The Palm VII is unique in that it has a built-in transceiver for wireless networking via the Palm.Net service. The Palm IIIc is unique because it is the first Palm device with a color screen. Programs written for the original Pilot will usually run unchanged on the newer models. Upward compatibility is an important feature of the Palm family of devices. Another important feature is a Palm device’s capability to synchronize or exchange data with a desktop computer. On the Palm, this function


10/17/2000 5:14 PM

Page 145


145

is referred to as HotSync and is easy to perform. You simply place the device in a cradle that is attached to the desktop computer and press the cradle’s HotSync button. The device opens a communication channel with a background program running on the desktop and proceeds to exchange data by using HotSync conduits. A conduit acts as the intermediary between a program installed on the Palm and a program installed on the desktop computer. Conduits enable the Palm’s built-in Address Book and Date Book applications to synchronize with common desktop applications such as Microsoft Outlook or Lotus Notes, enabling you to share addresses, appointments, and more across both devices. Why has the Palm succeeded where other devices have failed? Rather than trying to cram a full-featured operating system into a small form factor, the Palm design team decided to only include the features that were necessary for a minimalist set of useful applications. A Palm device is not a desktop computer and does not claim to be one. Rather, it is a personal, connected organizer. This device has the basic functionality that you need when you are away from a computer and has the capacity to integrate seamlessly with that computer. And now, this device can run Java programs. Palm has been so successful with its devices that other manufacturers are licensing the platform and building new devices that incorporate the Palm operating system’s applications, look, and feel. A Developer’s Perspective Developers write programs for the Palm either because they own one or because they see the large pool of potential buyers created by the Palm platform’s success. Most Palm programs are written in C or C++ by using the CodeWarrior toolset, although developers can also use a port of the open source GNU C/C++ compiler (GCC). C/C++ programmers need to understand a lot of low-level details about the device in order to get started, and we could easily spend this entire chapter discussing them in great detail. Luckily, most of those details are unimportant to Java programmers. All we need is to understand the limitations of the hardware—why it truly qualifies as a small computing device— and how to reset the device. The rest you can pick up as you go along if it interests you.


146

10/17/2000 5:14 PM

Page 146

CHAPTER 8

The Basic Hardware

Palm devices are battery-operated computing devices (using either two AAA batteries or built-in rechargeable batteries) that run on a Motorola DragonBall processor, which is a low-power derivative of the MC68000 chip found in the early Macintosh and Amiga computers. The Dragon Ball is far from speedy, and the most recent Palm models run at about 20MHz. To save power, a Palm device switches between three modes of operation: sleep mode, doze mode, and running mode. The latter occurs when the device is actively running an application. If the device is waiting for user input, it places itself in doze mode—halting the processor until an interrupt awakens it. Sleep mode turns everything off except the memory chips, the clock, and some low-level circuitry. For this reason, a typical Palm device can last for two weeks without having to replace or recharge the batteries (most of its time is spent in doze or sleep mode).

A Warning for Developers If you keep the device in running mode, its batteries will drain fairly quickly. Do not write Java programs that hog the Central Processing Unit (CPU). The usual warnings about avoiding busy wait loops and other expensive programming practices apply even more to the Palm platform and to similar devices.

The Operating System

The operating system on a Palm device is referred to simply as Palm OS. The current version of Palm OS at this writing is 3.5. On the original models, the operating system was stored in read-only memory (ROM), although a trap facility (operating system functions are called through a dispatch table) made it possible to install minor bug fixes. The newer models store the operating system in Flash memory, enabling them to be upgraded to the latest version by simply downloading an update from Palm’s Web site.


10/17/2000 5:14 PM

Page 147


147

Palm OS uses threads internally, but Palm applications only run on a single thread. In fact, only one application runs at a single time. Users might think that they are merely switching between applications, but in fact, one application is shutting down (after saving its state) and another is starting up (and restoring its state). This programming is clever, and the emphasis is on responsiveness and that instant-on feeling.

Multiple Threads and Java A single thread of execution does not mean that Java programs cannot be multithreaded. Remember that a Java interpreter can do the necessary context switching itself. A single thread to run the interpreter is all that the CLDC requires.

Memory Model

The Palm OS memory model is a bit unusual and quite frustrating to the average developer—especially to a Java developer. A Palm device partitions its RAM into two heaps. The first heap is called the dynamic heap, and it occupies the first 64K to 256K of available memory, depending on the model and the version of the operating system. This RAM stores the application’s runtime heap, the application’s runtime stack, and the system’s global variables. It also stores the TCP/IP protocol stack (32K in size) if networking is enabled. Its contents do not survive a device reset, and the application heap and stack are of course freed whenever the application terminates. The remaining RAM in the device is in the storage heap. Data placed in the storage heap is organized into databases of records (for ordered data) or resources (for unordered data). Palm OS has no notion of a file system, so everything is stored as a database—including the applications themselves. As you might expect, the contents of a database are preserved when the device is reset, except when a hard reset is performed (refer to the following paragraphs). Databases are also writeprotected, modifiable only through special Palm OS APIs—thus, writing to storage memory is significantly slower than writing to dynamic memory.


148

10/17/2000 5:14 PM

Page 148

CHAPTER 8

Prior to Palm OS 3.0, the size of the dynamic heap was no larger than 64K. Palm OS 3.0 increased the size to 96K, of which 32K was used by the TCP/IP protocol stack—leaving only 64K for application and system use (even if the device has 8MB of RAM). In Palm OS 3.5, the size of the dynamic heap varies based on the amount of RAM in the device. If the device has fewer than 2MB of RAM, the dynamic heap is 64K in size. If the device has 2MB or more but fewer than 4MB of RAM, the dynamic heap is 128K; otherwise, the size of the dynamic heap is 256K. Always subtract 32K from the available memory if networking is enabled. Because the amount of dynamic memory is fixed, the size of an application’s runtime heap is quite limited—even if there are several megabytes of free storage memory. Any requirements for further memory must be met by using storage memory, perhaps by implementing a simple virtual memory scheme and paging data in and out of dynamic memory as required. As of this writing, the KVM running on the Palm does not support any memory paging, and all runtime objects are allocated from the dynamic heap. Resetting the Device

If your Palm device ever locks up, you will need to reset it. There are three kinds of reset: soft, modified soft, and hard. A soft reset clears the contents of the dynamic heap and resets the state of the operating system. The contents of storage memory are preserved. In order to perform a soft reset, press the tip of a straightened paper clip or the unscrewed top of a stylus gently into the Reset hole in the back of the device. A modified soft reset is a soft reset that does not notify the applications that the operating system has been reset. Normally, applications are notified by the operating system about significant events. If an application crashes or locks up during this notification, it can freeze the system. To perform this reset, perform a soft reset while pressing and holding down the scroll-up button. A hard reset clears the contents of dynamic and storage memory before resetting the operating system. You will lose any applications that were installed on the device (other than the built-in applications). You should not perform this operation lightly, so be sure to back up your data first


10/17/2000 5:14 PM

Page 149


149

if possible. To perform this reset, press and hold down the power button, push the paper clip or unscrewed stylus top into the Reset hole, remove it, and then release the power button. You will be asked to confirm the hard reset by pressing the scroll-up button. The Palm OS Emulator The Palm OS Emulator (POSE) is an incredibly useful tool for any kind of Palm programming. This emulator enables you to test and debug your applications on your desktop computer without having to install them on an actual device. The development cycle is much faster if you use POSE for your initial testing. POSE is free for downloading from the Palm OS development Web site at www.palmos.com/dev/tech/ tools/emulator. The version described here is 3.0a5, but the emulator is constantly updated—so check the Web site regularly for newer versions. POSE is available for Microsoft Windows, Macintosh, or Linux. POSE is a true emulator, not a simulator. It requires a Palm OS ROM image to work, which you must obtain from a real Palm device or through the Palm OS developer program. Testing with different ROM images is recommended in order to ensure that differences in operating system version and available memory do not cause your application to terminate unnecessarily. POSE provides a utility to obtain the ROM image from a cradled device. To obtain other ROM images, join the free Palm developer program, the Solution Provider Program (SPP), by registering at www.palmos.com/dev/program. Residents of the United States will have immediate access to the ROM images, but residents of other countries will have to sign and send in some simple legal forms before being granted access. A screen shot of POSE running on Windows is shown in Figure 8.1. Its menus enable you to configure POSE to use a specific ROM image with a specific amount of RAM, to reset the device, to initiate a HotSync, to install an application, and to run some random user interface tests called Gremlins. Palm applications are stored in files ending with the .prc extension, and any associated data files end with the .pdb extension. These files must be installed in POSE by using the Install Application/Database menu. If your application does not appear in the Launcher (the Palm OS desktop) after installing it, activate one of the standard applications


150

10/17/2000 5:14 PM

Page 150

CHAPTER 8

Figure 8.1 The Palm OS Emulator in action.

(such as the Address Book) and then return to the Launcher. The application should then be visible.

Installing the Palm CLDC The Palm CLDC implementation is in a separate ZIP file. Like the CLDC reference implementation, it is available free for downloading from Sun Microsystems’ Web site at www.sun.com/software/communitysource/ j2me/. You must still download and install the reference implementation first, however. The Palm port is an overlay that adds new files and directories to the basic CLDC installation. The overlay includes the following elements: ■■

■■

The Palm port of the KVM (KVM.prc) and the utility for capturing the output of the System.out and System.err streams (KVMutil.prc). These files are installed in the bin directory. Compiled versions of the samples, packaged as Palm executables. These files are also installed in the bin directory.


10/17/2000 5:14 PM

Page 151

Java for Palm Connected Organizers ■■

■■

■■

151

Two Java-based utilities, MakePalmApp and ConvPRCtoJAR, for packaging Java applications as Palm executables and vice-versa. You can find the source for these in the tools\palm directory. Palm-specific versions of the CLDC classes as required, with complete source code Complete source code for KVMutil and the Palm version of the KVM

After unzipping the files, you will need to compile the MakePalmApp and ConvPRCtoJAR utilities, bundling them into a JAR file called palmdb.jar. Use something similar to the following: cd %KVM_HOME% mkdir lib mkdir lib\classes cd tools\palm\src\palm\database javac -d %KVM_HOME%\lib\classes *.java copy Wrapper.prc %KVM_HOME%\lib\classes\palm\database copy DefaultTiny.bmp %KVM_HOME%\lib\classes\palm\database cd %KVM_HOME%\lib\classes\palm jar cvf ..\palmdb.jar .

Note that MakePalmApp and ConvPRCtoJAR are J2SE-based applications that run on your desktop. They are not J2ME applications. The final step is to install KVM.prc, KVMutil.prc, and the other .prc files in the bin directory into the POSE or on the device. Palm OS 3.01 or higher is required to run the KVM, so for POSE, the ROM image of a recent device such as the Palm V or the Palm VII will do fine.

Running the Samples Take some time now to run through the samples at least once. Notice how there is a delay between the time that you tap on the sample’s icon and when it actually starts. This delay is unavoidable, unfortunately, as the KVM loads and verifies the class files required by the application. It would be much worse if J2SE-style verification were performed. If you are using the emulator and have access to a real device, this point would be a good time to load the samples onto the device. Some of the games are not too playable when run in the emulator, either because the emulator runs them too quickly or because they depend on button presses that are hard to simulate with a mouse.

-


152

10/17/2000 5:14 PM

Page 152

CHAPTER 8

KVMutil The KVMutil application lets you view the contents of the System.out and System.err streams, either as the Java program runs or after it is done running. This application also enables you to control the amount of heap space that applications allocate. To use KVMutil, tap on its icon. You can also tap on the KVM icon and achieve the same effect. You will see the screen shown in Figure 8.2, and this screen enables you to control the following settings: Show heap stats. If checked, the KVM displays how much heap is allocated when it starts. Max heap size. It configures how much of the dynamic memory heap is allocated by the KVM when it starts Screen output. If set to a non-zero value, the KVM displays System. out and System.err output at the top of the screen when it runs an application. The value is the number of lines to display.

Figure 8.2 The KVMutil screen.


10/17/2000 5:14 PM

Page 153


153

Save output. If this option is checked, characters written to System.out and System.err are saved by the KVM to a Palm database. When the program is done running, start KVMutil again and press the View output button to see the stream contents. If you are running an application with the emulator, console output is also echoed to the STDOUT.txt and STDERR.txt files in the emulator’s installation directory. This action occurs whether or not KVMutil is set to save the output.

Revisiting the Hello World Application Let’s revisit the HelloWorld application. If you recall, this application is trivial: public class HelloWorld { public static void main( String[] args ) { System.out.println( "Hello, world!" ); // Wait for ten seconds try { Thread.sleep( 10000 ); } catch( InterruptedException e ){ } } }

We compile and preverify this program by using the same syntax as before: javac -g:none -bootclasspath %KVM_HOME%\bin\api\classes -classpath %KVM_CLASSPATH% -d %KVM_TMP_DIR% HelloWorld.java %KVM_HOME%\bin\preverify -d %KVM_OUTPUT_DIR% -classpath %KVM_CLASSPATH%;%KVM_HOME%\bin\api\classes %KVM_TMP_DIR%

Instead of running the program directly, however, we must transform it into a Palm executable by using the MakePalmApp tool:


154

10/17/2000 5:14 PM

Page 154

CHAPTER 8 java -classpath %KVM_HOME%\lib\palmdb.jar palm.database.MakePalmApp -v -bootclasspath %KVM_HOME%\bin\api\classes -icon %KVM_HOME%\samples\icons\default.bmp -smallicon %KVM_HOME%\samples\icons\DefaultTiny.bmp -classpath %KVM_OUTPUT_DIR%;%KVM_CLASSPATH% HelloWorld

You will definitely want to define a batch file or shell script/alias to run this rather ugly command line. This line looks confusing at first glance. Remember that the MakePalmApp tool is a Java program, so the first part of the command line—“java –classpath %KVM_HOME%\lib\ palmdb.jar palm.database.MakePalmApp”—is just invoking the tool. If you put the palmdb.jar file into your CLASSPATH (which is safe to do, because MakePalmApp is a J2SE application), you can just use “java palm.database.MakePalmApp” to invoke it. ■■

■■

■■

■■

■■

The arguments to MakePalmApp represent the remainder of the command line, and these arguments are quite numerous: -v turns on verbose output so that you can see what MakePalmApp is doing. Strangely enough, repeating the option—using -v -v— increases the amount of output. -bootclasspath path is the path to the CLDC classes (the ones that are already included in the KVM.prc file). -icon path and -smallicon path are paths to the application’s icons. Each application needs two icons: a large 22-by-22 icon (which will be automatically adjusted to a 32-by-32 size) and a smaller 15-by-9 icon. The icons can be in Windows bitmap format (.bmp), portable bitmap format (.pbn) or Palm OS bitmap format (.bin). For the HelloWorld application, just use any of the bitmap files in the samples\icons directory. If the bitmap is too large for the small icon, MakePalmApp will convert it to a good size. -classpath path is the path to the application classes. If this path is omitted, the current directory is used. Note that the CLASSPATH environment variable is always ignored, so you must explicitly set the classpath with this option.

The final argument is the name of the application’s main class. This name is usually all that MakePalmApp needs to determine which classes are to be included in the generated executable. If classes are loaded dynamically at run time by using Class.forName, however,


10/17/2000 5:14 PM

Page 155


155

you should include those classes as additional arguments to MakePalmApp immediately after the main class. Once you have generated the HelloWorld.prc file, install it on the device or in the emulator. Before running it, tap the KVMutil icon and ensure that the Screen output setting is set to five lines of output. Return to the application launcher and run the HelloWorld application. You should see a display like the one in Figure 8.3. Now, take the HelloWorldUI spotlet and run it through the MakePalmApp process. The output is shown in Figure 8.4, and this output is of course identical to what we saw in Figure 7.2.

Additional MakePalmApp Options Apart from the options that we just discussed, there are additional options that you can (and should) specify when building a Palm executable with MakePalmApp:

Figure 8.3 Running the HelloWorld application.


156

10/17/2000 5:14 PM

Page 156

CHAPTER 8

Figure 8.4 Running the HelloWorldUI spotlet.

■■

■■

■■

-name name sets the application’s short name. The short name is displayed in the launcher underneath the application’s icon. If this option is omitted, MakePalmApp uses the name of the main class without the package name, truncating it if necessary. -networking indicates that the application is network-enabled. A network-enabled application initializes the TCP/IP stack when it starts, making it possible to open socket connections to the external world. If this flag is not specified, the KVM assumes that the application will not perform any network connectivity and adds the 32K that is normally used by the TCP/IP protocol stack to the application’s runtime heap. Without this flag, any attempt to connect will fail, because the KVM leaves no dynamic memory for the protocol stack. -longname name is the full name of the application. This name is displayed by Palm OS when it prompts you to select an application, such as when it asks you which application to delete. Palm OS limits the length of this name to 31 characters. If this option is omitted, MakePalmApp uses the full class name.


10/17/2000 5:14 PM

Page 157

Java for Palm Connected Organizers ■■

■■

■■

■■

157

-version versionstring is the version of the application—a string of the form x.y—where x is the major version and y is the minor version. The version numbers for installed applications are accessible from the application launcher’s menu. If this option is omitted, it defaults to 1.0. -output path specifies the name of the output file. If omitted, it defaults to the name of the main class with a .prc extension. -resource path includes the specified file in the executable. At run time, the program can access the file by using the Class.getResourceAsStream method. -creator creatorID sets the application’s creator ID, which is a four-character (ASCII, not Unicode—they are eight-bit characters) value that uniquely identifies the application. If this option is omitted, MakePalmApp generates one automatically; however, there are no guarantees that a generated creator ID will not conflict with another application.

Of all of the options, the –creator option is the most important. All Palm applications must have a unique creator ID. Creator IDs are registered with Palm, Inc. by using a simple Web-based form at www.palmos.com. If you are going to distribute your application to anyone, be sure to register a creator ID for the application. For testing purposes, you can let MakePalmApp generate one for you. A final option is available. If you have a JAR file that you want to convert to a Palm executable (.prc), use the –JARtoPRC jarfile mainclass option.

Additional APIs Both the reference and Palm CLDC implementations come with additional APIs that are not found in the CLDC specification, such as the user interface classes. These additional APIs are there for two reasons: one, to extend the CLDC with enough functionality in order to make it useable; and two, to serve as guides and examples for device manufacturers who are interested in implementing the CLDC on their own platforms. Understand, however, that the additional APIs can be changed


158

10/17/2000 5:14 PM

Page 158

CHAPTER 8

or removed by Sun Microsystems at any time. Only the additional APIs that are defined by profiles (such as those defined by the MIDP) or that are otherwise guaranteed support by the J2ME implementer should be used. But because no profile supports Palm devices as of yet, the additional non-CLDC APIs are the only game in town for now for that particular platform. With that warning aside, let’s take a look at what these classes can do.

The User Interface As we already mentioned, the CLDC implementations include a set of user interface classes for building spotlets, which are simple applications that have a Palm-like user interface. These classes were, in fact, originally developed for use on Palm devices and were ported to Windows and Unix for use with a simple Palm device simulator. Spotlets are simpler than MIDlets, much more limited, and much more devicespecific. All of the classes discussed here are part of the com.sun. kjava package. The Spotlet Model A spotlet is a class that extends com.sun.kjava.Spotlet. The Spotlet class is roughly analogous to the Canvas class defined by the MIDP: it receives low-level input events and provides a blank slate for drawing on the display. An application can create and use multiple spotlets to display different windows. Like a Canvas, a spotlet is responsible for painting itself, including any user interface controls. Unlike the MIDlet model, however, the spotlet model does not generate paint events. You are responsible for tracking and redrawing any changes to the display. Multiple spotlets can share the display at a single time, because it is up to you to call their update routines in the correct order. There is no concept of visibility. You either draw a spotlet or you do not. Input Events Although multiple spotlets can draw on the display, only one spotlet at a time receives the input focus. This spotlet is referred to as the current spotlet. To make a spotlet the current spotlet, call its register method:


10/17/2000 5:14 PM

Page 159


159

Spotlet s = new MySpotlet(); s.register( Spotlet.NO_EVENT_OPTIONS );

Calling register within the spotlet’s constructor, along with the initial display update, is normal. To remove the input focus, call the unregister method (although normally, this action is not necessary). The register method performs this action automatically when activating a new spotlet. The register method takes one of two parameters: NO_EVENT_OPTIONS or WANT_SYSTEM_KEYS. Both are constants defined by the Spotlet class. Some of the input events on a Palm device are normally handled by the system itself and are referred to as system events. Pressing the Address Book button, for example, shuts down the current application and launches the Address Book. You can trap some of these system events (specifically, the raw key-press events that trigger them) by using WANT_SYSTEM_KEYS when registering the spotlet. The missiles.Missiles sample, for example, uses WANT_SYSTEM_KEYS to use the device’s buttons as a crude game controller. For most applications, use NO_EVENT_OPTIONS.

A Warning about WANT_SYSTEM_KEYS Several of the buttons on a Palm device cause the current application to terminate and a new application to start. Internally, what happens is that the system traps the button press and queues a special event that asks the application to stop. If you register a spotlet with WANT_SYSTEM_KEYS, the system never traps the button press and never generates the stop event. Unless you provide a way to terminate the application by calling System.exit in response to user input, the application runs indefinitely. The only way to stop it is by resetting the device.

Individual events are sent to the current spotlet by directly invoking methods on the class—again, much like the original AWT event model. The com.sun.kjava.Spotlet class defines the following methods (any or all of which the spotlet can override in order to process the events): ■■

public void keyDown( int keyCode ) is called when a Graffiti character is inputted or when a button is pressed. The keyCode parameter is the Palm key code for the character (in ASCII) or


160

10/17/2000 5:14 PM

Page 160

CHAPTER 8

button press. The Spotlet class defines constants for the common buttons that an application would intercept: PAGEUP, PAGEDOWN, CALCICON, MENUICON, KEY_HARD1, KEY_HARD2, KEY_HARD3, KEY_HARD4, and KEY_POWER. Note that the last five button events are trapped only when the input focus option is WANT_SYSTEM_ KEYS. ■■

■■

■■

■■

public void penDown( int x, int y ) is called when the pen touches the screen. The x and y coordinates indicate where the touch occurred and are relative to the top-left corner of the display. public void penMove( int x, int y ) is called when the pen moves while it touches the screen. The x and y coordinates indicate the current pen position. public void penUp( int x, int y ) is called when the pen is removed from the screen. public void beamReceive( byte[] data ) is called when data is received on the infrared port. The byte array holds the data that was received.

As you can see, the events that a spotlet supports are basic. Also, no events ever get routed to specific user interface controls; rather, it is always up to the spotlet to determine (with the control’s help) whether a control is interested in a specific event and to call its methods accordingly. Drawing Because there are no paint events, all drawing is done in response to user input or application-state changes. The graphics subsystem defines a Graphics class with a few basic methods for drawing lines and text on the screen. The graphics capabilities are limited when compared to those of the MIDP or J2SE. To obtain a Graphics object for drawing, call the static getGraphics method. This method returns the one-and-only Graphics object in the system: Graphics g = Graphics.getGraphics();

Implementing the object as a singleton reduces the number of memory allocations required by the graphics subsystem.


10/17/2000 5:14 PM

Page 161


161

Once you have the Graphics object in hand, you can draw anywhere on the display at any time: // Demonstrate basic drawing commands Graphics g = Graphics.getGraphics(); g.clearScreen(); // x1, y1, x2, y2, mode g.drawLine( 0, 0, 159, 159, g.PLAIN ); // x, y, w, h, mode, borderType g.drawBorder( 2, 2, 156, 156, g.PLAIN, g.SIMPLE ); // x, y, w, h, mode, cornerDiameter g.drawRectangle( 10, 10, 140, 140, g.INVERT, 0 ); g.drawString( "Some text", 0, 0 ); g.drawString( "Some inverted text", 0, 20, g.INVERT ); g.drawString( "Some erased text", 0, 40, g.ERASE );

There is no support for color on the KVM, although a version of the KVM with color support is available from the creators of kAWT (discussed later in this chapter). As well, only one font is supported. A Bitmap class is used to represent Palm OS black-and-white bitmaps. Controls The KVM does include classes for drawing a number of user interface controls. These controls have a Palm look and feel but are written entirely in Java. No native peers are used (as in AWT). The supported controls are as follows: Button. Draws text-based or bitmap-based buttons CheckBox. Draws labeled checkboxes Dialog. Displays a pop-up window of text. This spotlet automatically creates a TextBox or ScrollTextBox as appropriate and waits for the user to dismiss it. The owner of the dialog (an object that implements the DialogOwner interface) is notified when the dialog is dismissed. HelpDisplay. Displays a window of help text before starting an application. This spotlet is similar to the Dialog class, but it dynamically creates an instance of a given Spotlet subclass when dismissed. RadioButton. Draws labeled radio buttons. Radio buttons can be grouped together by using the RadioGroup class in order to ensure


162

10/17/2000 5:14 PM

Page 162

CHAPTER 8

that only one button with the group is selected. The RadioGroup is not a user interface control, however. ScrollTextBox. Extends TextBox by adding a VerticalScrollBar to scroll the text SelectScrollTextBox. Extends ScrollTextBox in order to allow the selection/deselection of a line of text Slider. Displays a horizontal slider to select an integer value within a fixed range of values TextBox. Displays one or more lines of non-editable text. The text is wrapped as necessary based on the space or new-line characters in the string. TextField. Displays a single line of labeled, editable text ValueSelector. Displays and lets the user select an integer value in a way similar to a spin control VerticalScrollBar. Draws a vertical scroll bar. The owner of the scroll bar (an object implementing the ScrollOwner interface) is notified whenever the user changes the scroll bar’s value. More sophisticated user interface behaviors are handled by writing custom controls that might or might not use one of the predefined controls as starting points. Remember that there are no paint events and no event delegation in the spotlet model. To draw or refresh a control, call its paint method. To handle user input, call an appropriate method—passing in the key that was pressed or the position of the pen. Consider this simple example: import com.sun.kjava.*; public class PressMe extends Spotlet { public static void main( String[] args ) { new PressMe(); } private Button button = new Button( "Press me!", 1, 80 ); public PressMe() { register( NO_EVENT_OPTIONS );


10/17/2000 5:14 PM

Page 163


163

Graphics.getGraphics().clearScreen(); button.paint(); } public void penDown( int x, int y ) { if( button.pressed( x, y ) ){ System.out.println( "You pressed me!" ); } } }

When the PressMe class receives a pen-down event, it forwards it to the button’s pressed method. If the button is disabled or the event occurs outside its boundaries, pressed returns a value of false. Otherwise, it inverts the button, waits a tenth of a second, redraws the button, and returns a value of true. All of the controls are used similarly, although they expose different event-handling methods.

Databases Palm OS databases are accessed by using the com.sun.kjava. Database class, which is basically a wrapper class whose methods invoke their Palm OS equivalents. The CLDC reference implementation provides a crude simulation of Palm OS databases by creating files in the current directory. Understanding Palm Databases A Palm database is a set of memory blocks allocated from the storage heap and managed as a single entity by the operating system. The memory blocks are allocated independently and can exist throughout the storage heap. The only restrictions are that no block can exceed 64K in size and that all of the blocks must reside on the same memory card.

What Is a Memory Card? In a Palm device, RAM and ROM are packaged together on a piece of hardware called a memory card. In theory, there can be several memory cards per device, but in practice, there is only one (referred to as card 0).


164

10/17/2000 5:14 PM

Page 164

CHAPTER 8

Palm databases come in two formats: resource and record. Resource databases store unordered memory blocks, while record databases store ordered memory blocks. Record indexes start at 0. Databases also have creator IDs, types, and names. The creator ID identifies the application that created the database. The type is a fourcharacter (32-bit) value identifying the purpose of the database (separate from the kind of database it is—resource or record). The name of a database must be fewer than 32 characters long and must be unique among all of the installed databases (and applications—an application is really just a resource database). An easy way to ensure uniqueness is to include the creator ID in the name. Using Databases in Java Palm OS defines a number of APIs for dealing with databases, but the Database class provides only the most basic functionality. To create a database, use the static create method: String name = ....; // up to 31 characters long int creatorID = ....; // 4-character value int typeID = ....; // 4-character value boolean ok = Database.create( 0, name, creatorID, typeID, false );

The last parameter indicates whether or not to create a resource database. You should always set it to false, because the Database class does not expose the necessary Palm OS functionality to properly access resource databases. The creator ID and type parameters must be 32-bit values. Take the four-character ASCII string and convert each character to its two-digit hex value. Combine these values to form an eight-digit hex value. For example, ABCD becomes 0x41424344, because A = 0x41, B = 0x42, C = 0x43, and D = 0x44. The creator ID must match that of the application in order to ensure that the database is deleted whenever the application itself is deleted. The type can be any sequence of four characters, providing that at least one of them is upper-case. To open a database, create a Database object identifying the database in question by its type and creator ID: Database db = new Database( typeID, creatorID, Database.READWRITE ); if( !db.isOpen() ){ // error, couldn’t open database! }


10/17/2000 5:14 PM

Page 165


165

A database can be opened for reading, writing, or both. Once the database is open, you can count the number of records that it holds by calling getNumberOfRecords: int count = db.getNumberOfRecords();

To read a database record, use getRecord: byte[] data = db.getRecord( index );

Similarly, to write an existing database record by using setRecord: byte[] data = ....; db.setRecord( index, data );

To add a new record to the database, use addRecord: db.addRecord( data );

When you are done, call the close method to close the database. (Note that isOpen still returns true after calling the close method, although the database is not open.) No other APIs are available for database manipulation. The Database class provides only the most basic support for Palm OS databases.

Network Connectivity Technically, the Generic Connection framework of the CLDC does not provide any communication drivers, leaving them up to the profiles to define. Both the reference implementation and the Palm port provide sample communication drivers, however, in order to demonstrate their use. The Connector Class The heart of the Generic Connection framework is the javax.microedition.io.Connector class, which is how a CLDC-based application obtains a Connection object. The reference implementation of Connector uses the protocol name in the connection string to dynamically load a factory class that is capable of creating the appropriate


166

10/17/2000 5:14 PM

Page 166

CHAPTER 8

Connection object. In other words, given a connection string of the form protocol://info, it looks for a class called com.sun.cldc. io.platform.protocol.Protocol, where platform identifies the platform that is being used. The reference implementation uses the j2me platform, so if you look in the api\com\sun\cldc\io\j2me directory, you will see that it supports the following protocols: ■■ ■■

■■

datagram for datagram (UDP) communication debug for debugging output. The System.out and System.err streams use this protocol. events for obtaining input events from the windowing system. A thread started by the Spotlet class uses this stream to fetch and dispatch events.

■■

resource for loading files in the class path

■■

serversocket for opening server sockets

■■

socket for opening client sockets

■■

storage for reading and writing to files

■■

testhttp for performing simple HTTP requests

■■

translate for reading localized strings (experimental)

For full documentation on each protocol, read the comments in the Protocol.java file in the appropriate directory. Most communication drivers use native functions to do the actual connecting by using the appropriate system facilities. Note that no implementation of the CLDC is required to support all or any of these communication drivers. An implementation can also add its own protocols. The Palm port of the CLDC defines the following protocols, for example: ■■

comm for direct serial port communication

■■

http for an HTTP request

■■

https for HTTPS requests (HTTP that uses secure sockets)

■■

storage for reading and writing to databases. The driver uses the com.sun.kjava.Database class to read from and write to a database.


10/17/2000 5:14 PM

Page 167


167

The platform for these protocols is palm, so the source code for them is found in the subdirectories of api\com\sun\cldc\io\palm. If a particular protocol cannot be found by using the palm platform, a second try is made using the j2me protocol. HTTP Connections Higher-level protocols are more likely to be supported across different implementations. For example, any device that supports the MIDP must support HTTP connections. A good place to start your experiments with the Generic Connection framework, therefore, is with the HTTP protocol. To make an HTTP connection, use a conventional URL, as in the following: import java.io.InputStream; import javax.microedition.io.Connector; InputStream in; in = Connector.openInputStream( "http://localhost/index.html" );

For the reference CLDC implementation, replace the http protocol with testhttp. The Palm port includes an additional sample called KvmHttpTest that demonstrates how to make simple HTTP and HTTPS connections in order to read files from Web sites. When using the HTTP or HTTPS protocols in your own Palm applications, be sure to use the –networking option when invoking MakePalmApp in order to ensure that networking is enabled when the application runs.

The Tic-Tac-Toe Example Let’s take the tic-tac-toe game model that we developed back in Chapter 3 and build a complete spotlet around it as a further example of how to use Java on Palm devices. You will find complete listings for all of the classes in Appendix A and on the accompanying CD-ROM. The CD-ROM also contains the compiled version of the game and a set of batch files to build it. Refer to the CD-ROM for complete instructions.


168

10/17/2000 5:14 PM

Page 168

CHAPTER 8

Usage The tic-tac-toe game is found in the file TicTacToe.prc. Install this file on your device or in the emulator, and tap on its icon. You will see an empty grid. You are the first player, and the device is the second player. You start the game by tapping on any of the empty cells in the grid to display an X. The device then responds by selecting another cell and displaying a stylized O, as shown in Figure 8.5. After the device has selected a cell, it is your turn again. This interaction continues until all of the cells are filled or until either player completes a row. The game then ends and a dialog announces the winner, as shown in Figure 8.6. Dismiss the dialog to start a new game.

How It Works The tic-tac-toe game is a fairly simple spotlet. This spotlet consists of four classes: TicTacToe, TicTacToePlayer, TicTacToeModel, and TicTacToeModelListener. The latter two were described in

Figure 8.5 The Tic-Tac-Toe game screen.


10/17/2000 5:14 PM

Page 169


169

Figure 8.6 The winner.

Chapter 3. What is new are the TicTacToe and TicTacToePlayer classes. TicTacToe is the main class. Besides extending the Spotlet class, it also implements the DialogOwner and TicTacToeModelListener interfaces: import com.sun.kjava.*; import com.ericgiguere.j2mebook.models.*; public class TicTacToe extends Spotlet implements DialogOwner, TicTacToeModelListener { ...... }

The entry point to the spotlet is of course the main method, which creates an instance of the spotlet. The constructor is as follows: public TicTacToe(){ register( NO_EVENT_OPTIONS ); Graphics.getGraphics.clearScreen(); model = new TicTacToeModel();


170

10/17/2000 5:14 PM

Page 170

CHAPTER 8 model.addListener( this ); model.addListener(new TicTacToePlayer(TicTacToeModel.PLAYER_2)); model.newGame(); }

The constructor creates a model to hold the game state and registers two listeners for the model: the spotlet itself (which will draw the grid and respond to user input) and an instance of the TicTacToePlayer class, which we will describe later. The constructor’s last action is to start a new game, which will invoke the gameStarted method on each of the model’s listeners. TicTacToe’s gameStarted method calculates the cell dimensions and draws the grid and the contents of each cell by calling the paint method. Cell information is stored in an inner class called Cell, one instance of which is created for each cell in the grid. Pen-down events are the only user input to which the game responds: public void penDown( int x, int y ){ if( model != null && model.isGameStarted() ){ for( int i = 0; i < numCells; ++i ){ if( cells[i].contains( x, y ) ){ model.setCellState( i, TicTacToeModel.PLAYER_1 ); return; } } } }

Whenever the user taps the screen, penDown determines which cell is being selected and selects it for Player 1. If the cell is empty, the model will change the cell’s state and then send a gameUpdated notification to the listeners. TicTacToe updates its internal state and repaints the grid: public void gameUpdated( TicTacToeModel model,int index,int value ){ cells[index].state = value; paint(); }

If the game is over, the model calls the gameOver method in order to announce the winner: public void gameOver( TicTacToeModel model ){ String text;


10/17/2000 5:14 PM

Page 171


171

switch( model.getWinner() ){ case TicTacToeModel.PLAYER_1: text = "Player 1 wins!"; break; case TicTacToeModel.PLAYER_2: text = "Player 2 wins!"; break; default: text = "A tie!"; break; } Dialog d = new Dialog( this, "Game Over", text, "OK" ); d.showDialog(); }

The dialog displays the text until dismissed by the user, at which point the main class’s dialogDismissed method is called: public void dialogDismissed( String title ){ register( NO_EVENT_OPTIONS ); model.newGame(); }

This method re-registers the spotlet to receive input events and starts a new game. There is not a lot of complicated user interface code in this sample. Mostly, it is just a matter of drawing lines on the screen in response to user input. The only tricky part is that there is no method to draw circles for the O characters, so the cell painting resorts to drawing a raised (shadowed) rectangle instead.

The Automatic Player The logic for playing tic-tac-toe is contained in the TicTacToePlayer class. Like the TicTacToe class, the TicTacToePlayer class implements TicTacToeModelListener and is the recipient of game events. When you (as Player 1) select a cell in the grid, the TicTacToePlayer representing Player 2 receives a gameUpdated notification. It asks the model for the row totals and looks for any rows that it can fill with a third character in order to win the game. Failing that, it then looks for any rows that Player 1 can use to win the game and that it can then block. Otherwise, it selects a cell at random. Again, refer to


172

10/17/2000 5:14 PM

Page 172

CHAPTER 8

the code in Appendix A for details. The automatic player shows the flexibility that you can get by cleanly separating the model from the rest of the application.

Third-Party Tools and Extensions A few tools and extensions for the Palm CLDC are available from nonSun sources and deserve some investigation on your part.

kAWT Perhaps the best-known KVM extension is kAWT, which is a simplified version of AWT that runs on the KVM. Unlike the original AWT, kAWT requires no native code. All of its drawing is done by using the graphics subsystem exposed by com.sun.kjava.Graphics. kAWT is a commercial product from Stefan Haustein and Michael Kroll but is free for private or educational use. You can download kAWT from the kAWT Web site in Germany: www.kawt.de, or from the CD-ROM accompanying this book. The latest version of kAWT as of this writing is 0.90. What kAWT does is implement a subset of the AWT classes from J2SE. Programs written with kAWT will run unchanged on J2SE, although the reverse is not true unless you are careful to use only the classes and methods that kAWT supports. Figure 8.7 shows a screen shot from the sample application included with kAWT. The disadvantage to using kAWT is that it increases the size of your programs. The full set of kAWT classes adds about 100K to a program. The footprint is reduced somewhat by installing the classes as Palm OS shared libraries, but it is still a significant increase in overall program size. Also, of course, the more classes there are to load, the longer the program startup will take.

Color KVM The creators of kAWT have also ported the KVM to Palm OS 3.5 in order to take advantage of the latter’s new color support. You can get the color KVM from the same site, www.kawt.de.


10/17/2000 5:14 PM

Page 173


173

Figure 8.7 A kAWT application.

JBuilder Handheld Express At this writing, Borland has released a beta version of its Handheld Express, which is an add-on to its JBuilder Java development tool. Handheld Express adds support for the Palm port of the CLDC to JBuilder Foundation 3.5. Both are available as free downloads (after registering with Borland) from the JBuilder Web site at www.borland. com/jbuilder/hhe. Once you have followed the installation instructions (which includes getting the CLDC reference and Palm implementations from the Sun Microsystems Web site), JBuilder can edit and compile J2ME programs. Visual form/screen editing is not available, nor is debugging. A simple Spotlet wizard, shown in Figure 8.8, does help you get started, though.

Jbed MicroEdition (CLDC) At the 2000 JavaOne Conference, a Switzerland-based company called esmertec compared Java programs running with its Jbed MicroEdition


174

10/17/2000 5:14 PM

Page 174

CHAPTER 8

Figure 8.8 JBuilder Handheld Express Spotlet wizard.

(CLDC) runtime environment against the same programs running with the reference implementation of the KVM. The Jbed programs ran noticeably faster and caught the eye of J2ME enthusiasts who had already run up against the KVM’s memory and speed limitations. How had someone been able to write such a fast VM? The company claims that Jbed programs run faster because the VM compiles Java bytecodes to native code, just like the just-in-time compiler used by the classic J2SE VM. This compilation can occur on the desktop computer that hosts the Jbed integrated development environment or dynamically on the device itself. As well, Jbed programs do not suffer from the same memory limitations as the KVM. An early beta of Jbed looks quite promising. The product should be out by the time you read this book, so if you are having performance or memory problems with your J2ME programs, this application is probably worth checking out. The esmertec Web site is www.esmertec.com.


10/17/2000 5:14 PM

Page 175


175

Chapter Summary In this chapter, we looked at how to run J2ME applications on the Palm. Now we can move away from the CLDC and look at the MIDP Early Access release.


10/17/2000 5:14 PM

Page 176


10/17/2000 5:15 PM

Page 177

CHAPTER

9

The Mobile Information Device Profile (MIDP) Early Access Release

B

y itself, the Connected Limited Device Configuration (CLDC) is not enough of a platform on which to build applications. Although the CLDC comes with a library of classes that adds the basic features that applications require, those classes are unsupported and are meant to be used as examples only. The Mobile Information Device Profile (MIDP), on the other hand, is a complete and supported foundation for application development. In this chapter, we will look at the first MIDP implementation: the MIDP Early Access Release.

Overview At this writing, the MIDP had finished its public review—one of the last steps before being published as a formal specification. To coincide with the public review period, an early access version of the MIDP was released so that the development community could start to use the new application programming interfaces (APIs) defined by the MIDP and start porting applications. By the time you read this text, the early access release will undoubtedly have been replaced by a reference implementation of the final MIDP specification, so please check the Sun Microsystems Web site at http://java.sun.com/products/midp for details

177


178

10/17/2000 5:15 PM

Page 178

CHAPTER 9

about how to download the latest MIDP reference implementation. The information here is based solely on what is found in the early access release, so there could be differences between what is available in the reference implementation. If by some chance the reference implementation is not yet available, you can download the early access release from the Java Developer Connection at http://developer.java.sun.com. For brevity, we will often refer to the MIDP early access release as “the MIDP” throughout the remainder of this chapter. Please note that the early access release is based on version 0.9 of the MIDP specification, although at the time of writing the 0.95 specification was the most recent one available.

Installation Like the CLDC reference implementation, the MIDP is installed by extracting the files from the ZIP file that you downloaded from the Sun Web site. Versions for Windows and Solaris are available, but we will limit ourselves to describing the Windows version. The files are extracted directly into the installation directory of your choice, and no setup program is necessary. The ZIP file contains the following items: ■■

■■

■■

■■ ■■

An index.html file describing how to install the release and run the samples Binaries for the MIDP cellular telephone simulator and the preverifier (in the bin directory) Documentation on how to run the simulator and the samples, as well as a complete Javadoc for the classes included in the early access release (in the docs directory) The midp.jar file containing the MIDP classes (in the lib directory) Sample MIDlets that run in the cellular phone simulator (in the lib\ examples.jar file, the sources are found in the src\example directory)

The MIDP directory structure is simpler than the CLDC’s, because the early access release is a binary release that includes no source (except that of the samples).


10/17/2000 5:15 PM

Page 179

The Mobile Information Device Profile (M I D P) Early Access Release

179

Note that the early access release deviates from the MIDP 0.9 and 0.95 specifications in a few minor ways. These deviations are listed in the index.html file accompanying the early access release.

Using the Cellular Phone Simulator Like the CLDC reference implementation, the MIDP early access release includes a simulator that enables you to run J2ME applications on your desktop computer. Unlike the CLDC simulator, the MIDP simulator is quite polished, as shown in Figure 9.1. The simulator emulates a cellular phone, which is one of the profile’s target devices.

Figure 9.1 The MIDP cellular phone simulator.


180

10/17/2000 5:15 PM

Page 180

CHAPTER 9

Running the Simulator You run the simulator by using the midp.exe executable in the bin directory. Use one of the following arguments to run a MIDlet: ■■ ■■

■■

■■

The name of a class specifies the name of the MIDlet class to run. -descriptor file specifies the path to an application descriptor (a text file ending in a .jad extension) that describes a MIDlet suite. The simulator will enable you to choose which MIDlet to run. -transient url appname specifies the URL of an application descriptor and the name of the MIDlet within it to run. The MIDlet name is a name listed in the descriptor, not the class name of the MIDlet. The name is actually optional. If this option is not specified, the simulator will enable you to choose which MIDlet to run. -autotest url appname is similar to –transient except that the application is run repeatedly until the simulator is shut down.

When searching for non-MIDP classes, the cellular phone simulator uses the CLASSPATH environment variable unless the –classpath path option is specified. The midp.jar file does not have to be in the classpath; rather, it is used when compiling applications, not when running them. To exit the simulator at any time when not in autotest mode, simply close the window. In autotest mode, you will have to interrupt the simulator by using Ctrl+Break at the console window. If you are running a specific MIDlet (you were not prompted by the simulator to choose an individual MIDlet from a suite), you can also press the hang up button (the red telephone icon on the right of the simulator).

Web Server Setup When downloading application descriptors from a Web server, the Web server must return a MIME type of text/vnd.sun.j2me.appdescriptor for files ending in .jad. How you define this mapping is specific to the Web server that you are using. For Apache Web servers, add an entry to the mime.types file, or else add the following command to the httpd.conf file: AddType text/vnd.sun.j2me.app-descriptor .jad


10/17/2000 5:15 PM

Page 181


181

Example Invocations A few simple examples demonstrate how to invoke the cellular phone simulator by using each method. Say that you have a MIDlet suite packaged as test.jar whose contents are as follows: /META-INF/MANIFEST /com/mycompany/Test1.class /com/mycompany/Test2.class /icons/Test1.png /icons/Test2.png

Accompanying this Java Archive (JAR) file is an application descriptor, test.jad, whose contents are as follows: MIDlet-Jar-URL: http://localhost/test.jar MIDlet-Jar-Size: 2304 MIDlet-Name: Test MIDlet-Version: 1.0 MIDlet-Vendor: mycompany.com MIDlet-Description: A simple test. MIDlet-1: Test1, /icons/Test1.png, com.mycompany.Test1 MIDlet-2: Test2, /icons/Test2.png, com.mycompany.Test2 MicroEdition-Profile: MIDP-1.0 MicroEdition-Configuration: CLDC-1.0

As you can see, the MIDlet suite has two MIDlets: Test1 and Test2. Assume that you have an Apache Web server installed on your machine such that the URL http://localhost/file maps to c:\apache\htdocs\ file. The Web server is up and running on the default port (port 80) and is configured to serve .jad files by using the correct MIME type. As a final step, place the test.jar and test.jad files in the c:\apache\htdocs directory. To run Test1 in the simulator without using the application descriptor or the Web server, use the following: midp -classpath c:\apache\htdocs\test.jar com.mycompany.Test1

The simulator loads the given class directly from the JAR file. To run either MIDlet by using the application descriptor but not the Web server, use the following:


182

10/17/2000 5:15 PM

Page 182

CHAPTER 9 midp -classpath c:\apache\htdocs\test.jar -descriptor c:\apache\htdocs\test.jad

The simulator uses the descriptor to build a list of MIDlets that it can run. To download and run Test2 from the Web server, use the following: midp -transient http://localhost/test.jad Test2

Omit the MIDlet name, and the simulator will build and present a list of MIDlets to run.

Running the Samples Just like the CLDC, the MIDP comes with a number of samples. The samples are packaged as a single MIDlet suite called examples.jar, which you will find in the lib directory. The simplest way to run the samples is to use the run.jad file that is found in the MIDP installation directory. Run this command from the bin directory: midp -classpath ..\lib\examples.jar -descriptor ..\run.jad

The simulator will list the MIDlets in the JAR. You can run any sample by simply scrolling to it (using the arrow buttons on the simulator or the arrow keys on your keyboard) and selecting it (using the circle button on the simulator or the Enter key on your keyboard). To run the samples in full color, set the SCREEN_DEPTH environment variable to 8 before invoking the simulator: set SCREEN_DEPTH=8 midp -classpath ..\lib\examples.jar -descriptor ..\run.jad

Use a screen depth of 8 for 256 colors, 4 for 16 colors, 2 for four colors, or 1 for black and white. For other environment variables that you can set, refer to the file docs\midp-env.html. The samples are self-explanatory. The Sampler sample, which demonstrates simple drawing commands, is shown in Figure 9.2.


10/17/2000 5:15 PM

Page 183


183

Figure 9.2 The Sampler sample.

Compiling and Preparing Classes You can compile a MIDlet by using the javac command as follows: javac -g:none -bootclasspath %MIDP_HOME%\lib\midp.jar -classpath %MIDP_CLASSPATH% -d %MIDP_TMP_DIR% *.java

Like we did with the CLDC, we defined a MIDP_HOME environment variable and set it to the root of our MIDP installation. We also defined


184

10/17/2000 5:15 PM

Page 184

CHAPTER 9

MIDP_OUTPUT_DIR, MIDP_CLASSPATH, and MIDP_TMP_DIR environment variables. Compiled classes must be run through the preverifier, just like we did with the CLDC. The syntax is the same, except that the class path includes the MIDP classes in place of the CLDC classes: %MIDP_HOME%\bin\preverify -d %MIDP_OUTPUT_DIR% -classpath %MIDP_CLASSPATH%;%MIDP_HOME%\lib\classes %MIDP_TMP_DIR%

Before running the preverifier, however, you should use the jar command to extract the contents of the midp.jar file into the lib\ classes directory: cd %MIDP_HOME%\lib mkdir classes cd classes jar xf ..\midp.jar

If you include the midp.jar file directly into the class path, the preverifier will not find the MIDP classes. Now you can test your application by using the simulator. Once you have tested your MIDlet, you will need to package it into a JAR file along with any other MIDlets in the suite. Do not forget to include a manifest that has the required attributes. You should also define an application descriptor for the suite.

The HelloMIDlet Application The MIDP early access release includes a skeleton MIDlet called HelloMIDlet that you can use as a starting point for your own MIDlets. This application is already included in the examples.jar file, so you can run it like any of the other samples: midp -classpath ..\lib\examples.jar HelloMIDlet

The HelloMIDlet application uses a TextBox to display a string of text and then waits for the user to invoke the exit command. Refer to Figure 9.3.


10/17/2000 5:15 PM

Page 185


185

Figure 9.3 Running the HelloMIDlet application.

While this MIDlet is pretty basic, this application is certainly more complex than the HelloWorld application that we defined previously with the CLDC: // HelloMIDlet.java — from the MIDP early access examples import javax.microedition.midlet.*; import javax.microedition.lcdui.*; public class HelloMIDlet extends MIDlet implements CommandListener { private Command exitCommand;


186

10/17/2000 5:15 PM

Page 186

CHAPTER 9 private Display display; public HelloMIDlet() { display = Display.getDisplay( this ); exitCommand = new Command( "Exit", Command.SCREEN, 2 ); } public void startApp() { TextBox t = new TextBox( "Hello MIDlet", "Test string", 256, 0 ); t.addCommand( exitCommand ); t.setListener( this ); display.setCurrent( t ); } public void pauseApp() { } public void destroyApp( boolean unconditional ) { } public void commandAction( Command c, Displayable s ) { if( c == exitCommand ){ destroyApp( false ); notifyDestroyed(); } } }

When the MIDlet is created, its constructor grabs a reference to a Display object and creates a Command object. The Display object is used later to set the current screen and is valid until the MIDlet is destroyed. The Command object defines an exit command that will be later associated with a screen. When the MIDlet is started, it creates a TextBox screen, associates the exit command with it, and makes the screen current. At this point, the high-level user interface classes takes over and displays the text on the screen. Notice how the MIDlet also implements the CommandListener interface and is registered as a listener with the TextBox. Any commands that are trigged by the user thereby invoke the commandAction method, which in this case just checks to determine whether the exit command was the source and destroys the MIDlet if so. When the application is destroying itself, it notifies the device by calling notifyDestroyed.


10/17/2000 5:15 PM

Page 187


187

Can you still print text by using System.out and System.err? The answer is yes, and the text will appear on the console as you would expect when the application is run on the simulator. On a real device, of course, the text will likely go elsewhere. Again, only use these output streams for tracing and debugging purposes.

The Tic-Tac-Toe Example We can easily adapt the tic-tac-toe game that we developed in the previous chapter, transforming it from a spotlet to a MIDlet. Instead of having the TicTacToe class draw the user interface and interact with the user, however, we are going to move most of its functionality into a separate TicTacToeUI class. TicTacToe is then left as a simple MIDlet that follows the basic outline of the HelloMIDlet application: public class TicTacToe extends MIDlet implements CommandListener { .... }

The complete source for these classes is also listed in Appendix A and is available on the accompanying CD-ROM, along with the compiled version of the game. The compiled version is actually packaged as a MIDlet suite, and when run with the cellular phone simulator, you will see the tic-tac-toe game listed as shown in Figure 9.4. Select the game and then a few cells, and you will see something similar to Figure 9.5. Note how real circles are drawn in this version. The MIDP Graphics calls include a drawArc method for drawing full or partial circles and ellipses. The only real difference between TicTacToe and HelloMIDlet is that the former creates instances of TicTacToeModel, TicTacToePlayer, and TicTacToeUI and registers the latter two as listeners for the model. Because we need to draw directly on the device’s screen, TicTacToeUI extends the Canvas class as well as implements TicTacToeModelListener: public class TicTacToeUI extends Canvas implements TicTacToeModelListener { .... }


188

10/17/2000 5:15 PM

Page 188

CHAPTER 9

Figure 9.4 Accessing TicTacToe from the MIDlet suite.

Just as we did with the Palm version, most of the drawing logic is encapsulated in the gameUpdated method. In fact, the code in both versions is nearly identical, with most of the changes due to the differences in how painting is done (in response to events for MIDP versus completely application-managed events for the Palm) and how user input is obtained. The MIDP version of tic-tac-toe uses the keypad for cell selection. In other words, to select the top-left corner cell, you press 1; to select the bottom-left corner cell, you press 7; and so on. The input is processed by the keyPressed method:


10/17/2000 5:15 PM

Page 189


Figure 9.5 Running the MIDP TicTacToe.

public void keyPressed( int keyCode ){ if( model == null || !model.isGameStarted() ) return; int index; for( index = 0; index < keypad.length; ++index ){ if( keypad[index] == keyCode ) break; } if( index < keypad.length ){ model.setCellState( index, TicTacToeModel.PLAYER_1 ); } }

189


190

10/17/2000 5:15 PM

Page 190

CHAPTER 9

Another difference between the two versions of tic-tac-toe is how the winner is announced. The MIDP version uses an instance of the Alert class: Alert alert = new Alert( "Game Over" ); alert.appendString( msg ); // msg is the string to display alert.setTime( Alert.FOREVER ); Display.getDisplay( midlet ).setCurrent( alert, this );

The call to setCurrent makes the alert the current screen and hides the game board, as shown in Figure 9.6. When the alert is dismissed, it makes the game board the current screen again. When the game board reappears, its showNotify method is invoked in order to start a new game:

Figure 9.6 The tic-tac-toe alert.


10/17/2000 5:15 PM

Page 191


191

protected void showNotify(){ if( model != null && !model.isGameStarted() ){ model.newGame(); repaint(); } }

The user can exit the game at any time by pressing the button marked Exit.

Chapter Summary In this chapter, we examined how to compile and run J2ME applications with the MIDP Early Access Release. Now, we move on to running J2ME applications on Motorola devices.


10/17/2000 5:15 PM

Page 192


10/17/2000 5:16 PM

Page 193

10

CHAPTER


A

s the specification lead for the Mobile Information Device Profile (MIDP), Motorola has devoted a large number of resources to implementing J2ME on its devices. At the JavaOne conference in the early summer of 2000, Motorola demonstrated devices running J2ME and committed to Java-enable all their cellular telephone models by the middle of 2002. In fact, the first MIDP-enabled phone from any vendor, the Motorola i3000, is scheduled to ship in December 2000, shortly after this book is published. In this chapter, we will look at Motorola’s implementation of J2ME using the Motorola J2ME SDK, a beta of which you will find on the CD-ROM accompanying this book. All of the information on this chapter is based on Developer Drop #5 of the Motorola J2ME SDK, which is the version that is available on the CD-ROM. Be sure to check Motorola’s iDEN developer Web site at www.idendev.com for the latest version of the SDK.

193


194

10/17/2000 5:16 PM

Page 194

C HAPTE R 10

The Motorola J2ME SDK Since cellular telephones are familiar to everyone, we can move right along to installing and using the Motorola J2ME SDK, which we will refer to simply as “the SDK” for the remainder of this chapter.

Installing the SDK The SDK is a ZIP file, so to install it just extract the contents on a Windows NT or Windows 98 machine. Be sure to install it to C:\MotoSDK, as some parts of the SDK use this hard-coded path. We will refer to this directory as the installation directory. You’ll also need to install the Java 2 SDK, version 1.2.2 or higher, as parts of the Motorola SDK are written in Java and require J2SE to run. The Motorola SDK does not include an integrated development environment (IDE). You can, however, purchase and use Motorola’s own CodeWarrior Pro 6.0 product, available from its Metrowerks subsidiary. Refer to www.metrowerks.com for details. CodeWarrior Pro is a fullfeatured IDE that can target multiple languages, including Java. The Motorola SDK adds the capability to compile and debug J2ME programs to CodeWarrior, making it the preferred development tool for Motorola devices. However, the SDK can be used with or without CodeWarrior, and in this chapter we use it without an IDE. After installing the SDK, take a few moments to read through the user’s guide, available in PDF format in the installation directory.

Using the SDK The SDK includes everything you need to create MIDP-based J2ME applications for Motorola devices. It includes an emulator that simulates the J2ME environment in various cellular telephones as well as all the files required to build MIDlets. The only thing you need to supply is JDK 1.2.2. The SDK consists of the following directories: docs. Javadoc for both the CLDC and the MIDP classes lib. The compiled classes for building applications lib.tools. Classes for the Motorola-specific tools


10/17/2000 5:16 PM

Page 195


195

libmidlets. The compiled versions of the Motorola MIDP samples preverifier. The Motorola version of the preverification tool src. Source code for the samples vm. Dynamic link libraries for the KVM, for use by the emulator As well, you will find a number of command (batch) files in the installation directory for running and configuring the emulator, which we will describe shortly.

Using the Emulator Just like the Early Access MIDP reference implementation we discussed in the last chapter, the Motorola J2ME SDK includes a cellular telephone emulator for running J2ME applications on your desktop. There are different configurations of the emulator available, such as the generic emulator shown in Figure 10.1 or the iDEN emulator shown in Figure 10.2. You can also define your own configurations using the runConfig.bat file to invoke the configuration tool shown in Figure 10.3—refer to the user’s guide for instructions on how to configure new emulators. You can change the network packet size, the amount of memory available to the VM, and other features that can vary from device to device. To run an emulator, simply invoke the appropriate command file: runEmul.bat to run the generic emulator or one of runMotoi1000.bat, runMotoiDEN.bat, runStarTac.bat to run emulators for specific Motorola cellular telephones. These command files must be invoked from the SDK installation directory, and each takes a fully qualified Java class name as its single argument. For example, to run the PaddleBall sample use this command: runMotoiDEN com.mot.j2me.midlets.paddleball.PaddleBall

The class name must refer to a compiled MIDlet found in either the C:\MotoSDK\lib or C:\MotoSDK\libmidlets directories. You can modify the command file to include your own directories if you would rather not copy your own files into the SDK directories. If no class name is specified, the command file defaults to running the com.mot.j2me.midlets.bounce.Bounce sample.


196

10/17/2000 5:16 PM

Page 196

C HAPTE R 10

Figure 10.1 The generic emulator.

Note that at this writing the emulator does not include any kind of application manager and is limited to running a single MIDlet at a time.

Running the Samples The SDK includes a number of precompiled sample MIDlets, including the PaddleBall and Bounce samples referred to in the previous section.


10/17/2000 5:16 PM

Page 197


197

Figure 10.2 The iDEN emulator.

Developer Drop #5 of the SDK also includes a command file called drop05exe.bat for running all the samples, one at a time. The name of this file will surely change in future versions of the SDK, but look for a file with a similar name and run through all the samples just to get a feel for the emulator and what MIDlets can do. All the samples are described in detail in the user’s guide.


198

10/17/2000 5:16 PM

Page 198

C HAPTE R 10

Figure 10.3 The emulator configuration tool.

Compiling and Preparing Classes Classes are compiled and prepared using the same techniques described in the last chapter. Use the preverifier included with the SDK and place the C:\MotoSDK\lib directory in the classpath for both javac and the preverifier. No other changes to the procedure are required.

The Tic-Tac-Toe Example No substantial changes are required to run the tic-tac-toe game we developed in the last chapter with the Motorola emulator. Minor changes are required to deal with differences in the MIDP specifications


10/17/2000 5:16 PM

Page 199


199

Figure 10.4 Tic-tac-toe on the Motorola emulator.

each supports: The Motorola SDK supports the MIDP 0.95 specification, while the Early Access release discussed in the last chapter supports MIDP 0.9. Apart from these few changes, however, the tic-tac-toe example runs perfectly with the Motorola SDK, as shown in Figure 10.4.


200

10/17/2000 5:16 PM

Page 200

C HAPTE R 10

Chapter Summary In this chapter, we examined how to use the Motorola J2ME SDK to run MIDlets. In the next chapter we discuss running J2ME applications on a different set of wireless devices, the BlackBerry Wireless Handhelds.


10/17/2000 5:17 PM

Page 201

11

CHAPTER

Java for BlackBerry Wireless Handhelds

O

ne of the most popular sets of wireless devices in North America is the Research In Motion (RIM) family of BlackBerry wireless handhelds. RIM is one of the first companies other than Sun Microsystems to release a J2ME implementation. In this chapter, we will take a look at RIM’s JDE for BlackBerry, which is an in-progress MIDP implementation that includes an integrated compiler, debugger and emulator. This complete tool set moves J2ME application development to the level that you have come to expect from the J2SE.

All of the information in this chapter is based on the early-access version of the BlackBerry JDE, which is available on the accompanying CD-ROM. The JDE is quite polished considering that it is a preliminary release, but be sure to check the RIM development Web site at http:// developer.rim.net for an updated version of the JDE.

A BlackBerry Primer RIM has been developing wireless devices for a number of years. Its BlackBerry devices—two-way interactive pagers—are sold by a number of retailers and network operators in Canada and the United States. Although the devices themselves might be of only minor interest to

201


202

10/17/2000 5:17 PM

Page 202

C HAPTE R 11

readers outside the United States and Canada, the BlackBerry JDE is worth exploring by anyone who is doing CLDC- or MIDP-based development because of its integrated environment. Before examining the JDE, however, let’s take a brief look at the technology that drives a BlackBerry device.

A User’s Perspective The BlackBerry wireless handheld family includes several different models. Two of the models, the 950 and the 957, were illustrated in Figures 1.4 and 1.5 back in the first chapter of this book. Each model includes a small but complete QWERTY-style keyboard for entering text as well as a thumb-operated trackwheel for positioning the cursor and selecting. There are two form factors available: a Palm-like form factor with a large screen (shown in Figure 1.5) and a pager-like form factor with a smaller screen (shown in Figure 1.4). The small screen displays six or eight lines of text, while the large screen displays 16 or 20 lines of text. The screen is not touch-sensitive, and all input is done via the keyboard or trackwheel. The trackwheel can also be pressed in order to act as a push button. RIM’s devices are lightweight. The smaller form factor weighs in at less than five ounces (including the battery), while the larger form factor is just a tiny bit heavier (and of course includes a built-in radio modem). The devices work on a single AA battery or on a built-in rechargeable battery, depending on the model. A docking cradle enables the devices to connect to a desktop computer for application installation, backups, and other tasks that require a fast network connection. All RIM devices use either the Mobitex or DataTAC networks for wireless data communication. Unlike the Palm VII, which currently uses Mobitex, the wireless modem in a RIM device is always on (there is no antenna to raise). This feature makes it possible to send and receive e-mail and other notifications at any time. E-mail, of course, has been the primary application for the devices so far, and the keyboard makes sending text a much more pleasant task than using a cellular telephone keypad. Also, unlike the Palm VII, the RIM solution does not require you to obtain a new e-mail address. It integrates with your existing corporate e-mail server or with existing Internet (POP3 or IMAP) mailboxes.


10/17/2000 5:17 PM

Page 203

Java for BlackBerr y Wireless Handhelds

203

A Developer’s Perspective Although the RIM devices were originally referred to as “interactive pagers,” they are capable of doing more than just sending and receiving messages. Third-party developers can use the RIM software-development kit to build their own applications in C++, and now in Java with the BlackBerry JDE. All current RIM devices have a 32-bit Intel 386 processor at their core, although there is speculation that this specification might change in newer devices. Each device includes at least 2MB of Flash memory and at least 300K of RAM. A RIM device has its own operating system and includes APIs that are necessary for accessing the Flash memory and for sending and receiving packets on the radio, in addition to those that are necessary for displaying information and interacting with the user. Up to 31 applications can run simultaneously by using co-operative multi-tasking. C++ applications are developed by using Microsoft’s Developer Studio tool set. The applications are compiled as Windows dynamic link libraries (DLLs) that are downloaded to the device via the cradle. The RIM SDK also includes a simulator that enables you to test your programs without installing them on a real device. Java applications are developed with the BlackBerry JDE, which we will discuss next.

The BlackBerry JDE With a basic understanding of the BlackBerry platform, we can now explore the BlackBerry JDE.

Installing the JDE To install the JDE, simply run the setup.exe program found on the CD-ROM in the RIM folder. You will need a machine that is running Windows 98 or Windows NT in order to use the JDE. The JDE installs a copy of the J2SE 1.3 SDK if you do not already have one on the


204

10/17/2000 5:17 PM

Page 204

C HAPTE R 11

machine. The SDK is used to run the Java-based integrated development environment (IDE) and to compile Java source files. The installation also includes all of the necessary CLDC and MIDP files for building J2ME-based applications that run on RIM devices. Throughout this chapter, we will assume that the JDE is installed in the directory c:\RIMJavaSDK and will refer to that directory as the JDE directory. Once you have installed the JDE, open the index.html file in the JDE directory with your favorite Web browser. Here, you will find links to important information about the JDE and related RIM and Java technologies, as well as a decent user guide for the JDE in Adobe PDF format.

Starting the IDE The heart of the RIM JDE is its IDE. You can run the IDE from your Start menu or directly from the JDE directory by using the following command: java -jar ide.jar

Again, the IDE requires J2SE 1.3 or higher and will refuse to start if it is run with J2SE 1.2. After the initial splash screen, you will be presented with the window shown in Figure 11.1. This window is the IDE, and it should look familiar to anyone who has done any programming with IDEs such as Microsoft’s Developer Studio. The main window is split into a number of configurable view windows. The initial views include a workspace view in the upper-left corner, a source view in the upper-right corner, and an output view in the bottom half.

Using the IDE The IDE organizes things in a fairly conventional manner. Projects define individual applications or code libraries. (A library defines a set of classes that are shared by two or more applications but is not an application in and of itself.) Projects are grouped together to form a workspace and are shown in the workspace view. Only a single workspace is open at a time. You can share projects among workspaces, however. Project and workspace information is stored in simple text files with the extension .jdw for workspaces and .jdp for projects.


10/17/2000 5:17 PM

Page 205


205

Figure 11.1 The BlackBerry IDE.

All Java source files must be part of a project. The project can also contain bitmap images in .GIF format, from which the IDE generates a Java class that can fetch the bitmaps at run time. Other file types are ignored. You compile a project by using the Build command either from the Build menu or by right-clicking the project and selecting the appropriate item from the pop-up menu. You can also use the pop-up menu to assign project dependencies. Applications can only depend on libraries, although libraries can depend on other libraries. When a project is built, any projects that it depends on are built first.


206

10/17/2000 5:17 PM

Page 206

C HAPTE R 11

When an error occurs during compilation, the error messages appear in the output window. You can press F4 or use the Next Error item in the Edit menu to move to each line in the source that generated an error, which makes it fairly simple to fix the errors. The IDE also has the capability to generate a makefile that you can use to build all of the projects in the workspace. This feature is useful when projects need to be built in batch mode. There is no need to invoke the IDE and send it keystrokes in order to simulate user input. Editing a Java class is simply a matter of double-clicking the name of the source file in the workspace view. An editor view will appear, showing you the source to the class in a text field and providing you with basic text-editing capabilities. You can also edit the source code outside the IDE by using your favorite text editor. The IDE detects that you have changed the file the next time it builds the project. You need to use the built-in editor for one thing, however: debugging.

Running and Debugging Code Once you have built an application, you can run it directly from within the IDE by using the RIM simulator. Press F5 or use the Go command in the Debug menu. (Any out-of-date projects are automatically rebuilt before any application is run.) The IDE includes an integrated sourcelevel debugger that works in conjunction with the simulator to help you easily find and correct program bugs. We will discuss the simulator in some detail in the next section, so for now, we will just concentrate on the debugging.

MAN Conflicts The simulator simulates a Mobitex-based device. Each Mobitex device has a unique number called a MAN that identifies it. The simulator uses a MAN of 15000000 by default. If two or more simulators try to use the same MAN, you will receive an error dialog upon startup. Sometimes this situation happens even when only one simulator is running because a previous instance did not shut down properly and left a .man file in the c:\RIMJavaSDK directory. You can usually ignore these errors and simply dismiss the dialog.


10/17/2000 5:17 PM

Page 207


207

The JDE debugger has all of the features that you would expect. Not only can you set breakpoints and trace in and out of code, but you can also view local variables, see the call stack, set watchpoints, and view memory statistics. These features are all available from the View menu. To set a breakpoint, open a source file in the IDE and move the cursor to the appropriate line of code. Press F9 or select the Break at Cursor command from the Debug menu. You will see a red circle appear in the left margin of the line. Repeat the command to remove the breakpoint. The debugger stops whenever it encounters a breakpoint, enabling you to observe the state of the application, change the values of local variables, examine the call stack, and so on. Once execution has been stopped, you can step through the code a line at a time or simply resume execution until the next breakpoint—or some other important event—occurs. Use the preferences dialog shown in Figure 11.2, which is available by selecting the Preferences command from the Edit menu, to control whether or not the debugger stops whenever an exception is thrown. This dialog is handy for tracking obscure bugs, but your application will likely break into the debugger many times before the offending code is reached.

Figure 11.2 Setting debugger preferences.


208

10/17/2000 5:17 PM

Page 208

C HAPTE R 11

Using the Simulator The RIM simulator enables you to run your applications on the desktop without downloading them to an actual device. The integrated development environment starts the simulator automatically (unless configured otherwise). By default, the simulator behaves like a 957 model with the large display (as shown in Figure 11.3). You can make it simulate a 950 model by opening the preferences dialog shown in Figure 11.4 and changing the command line to substitute OsPgrMb.dll for OsHhMb.dll. The smaller simulator is shown in Figure 11.5. You can use either model, and you should test your applications by using both form factors. You can also configure other aspects of the simulator

Figure 11.3 Simulating a 957.


10/17/2000 5:17 PM

Page 209


209

Figure 11.4 Changing the simulator preferences.

Figure 11.5 Simulating a 950.

from this dialog by using the command-line options described in the user guide. When you first run the simulator, you will see a set of icons referred to as a ribbon. These icons represent the applications that you can run


210

10/17/2000 5:17 PM

Page 210

C HAPTE R 11

directly. On an actual device, you would scroll through the ribbon by moving the trackwheel with your thumb to select a particular application, which you would then start by pressing the thumbwheel. On the simulator, you move the trackwheel by using the up and down cursor keys or the mouse, either by using your mouse’s own wheel (if it has one) or by clicking and dragging the on-screen trackwheel (which is tricky to do, so use the cursor keys instead). You can press the trackwheel by pressing either the left or right cursor keys or by right-clicking the trackwheel. Note that the Enter key can often (but not always) be used as a shortcut to pressing the trackwheel.

Navigating with the Cursor Keys If you use the cursor keys to navigate the ribbon, remember that the up and down keys scroll through the items in the ribbon, while the left or right keys start the selected application. Confusing these operations is easy because the ribbon uses a horizontal layout. Your first inclination is to use the left and right keys. If you accidentally start an application that you did not mean to start, you can generally return to the ribbon by pressing the left or right cursor key to display the program’s menu. Then, you can use the up and down cursor keys to navigate to the menu’s Close item and press the left or right cursor key again. On an actual device, the interaction with the trackwheel is actually quite intuitive. The trackwheel simulation is what makes things awkward.

Any time that text input is required in the simulator, just type the characters with your regular keyboard. You can also use the mouse to press the individual keys on the on-screen keyboard. If the 957 is being simulated, your keyboard’s Esc key maps directly to the device’s own escape button, which is located just below the trackwheel. The simulator can even run applications that require wireless network connectivity. Because the simulator does not have a radio modem, it simulates wireless communication by writing data packets to the file system. This feature enables two instances of the simulator running on the same machine to communicate with each other. The simulator can even be configured to drop packets on occasion in order to better emulate real-world radio coverage. To stop the simulator, press its Close icon or use the Stop Simulator command in the IDE’s Debug menu.


10/17/2000 5:17 PM

Page 211


211

Running the Samples The BlackBerry JDE includes a number of sample applications in the Demos workspace that is loaded the first time you start the IDE. With the Demos workspace loaded, press the F5 key to build the samples (you will see the individual commands appear in the output view) and then run the simulator. The simulator will look like Figure 11.3. Only one of the samples, the JavaLogo application, is available directly from the ribbon. You can access the others by selecting and running the Options application and selecting the Java item from the list of options, as shown in Figure 11.6. Press the thumbwheel (or hit Enter) to launch the Java application manager and to see the list of available Java applications, as

Figure 11.6 Selecting the Java option.


212

10/17/2000 5:17 PM

Page 212

C HAPTE R 11

Figure 11.7 The Java application manager.

shown in Figure 11.7. You can run any of these samples by pressing the Enter key or by pressing the trackwheel and selecting the Run menu item. You can return to the application manager by pressing the trackwheel (or the left or right cursor key) and selecting the Close menu item. Most of the samples demonstrate the user interface capabilities that are available with RIM’s Java environment (described in the user guide). The Hello World sample includes a breakpoint at the start of the application, so if you start it, the IDE will activate itself and will enable you to step through the code. This point is a good place to start exploring the built-in debugger.


10/17/2000 5:17 PM

Page 213


213

RIM’s J2ME Implementation With the JDE installed and tested, we can now explore RIM’s J2ME implementation.

Overview RIM was an active participant in the definition of the MIDP, and as such, the RIM Java environment supports the MIDP. At least, it will support the MIDP in the future; however, right now the early-access version only supports the basic CLDC classes plus the MIDP classes for record management. It adds to this support a communications driver for direct radio packet access and its own set of device-specific classes. Full MIDP support is promised and might be available by the time you read this book. For now, RIM applications are built by using RIM-specific user interface classes and utility classes. Not all of these classes will be supported in the final release, so applications that you develop now with the early access version will need to be ported when an MIDPbased version is available. Keep this fact in mind when you write your code. Javadoc for all of the classes included in the JDE is found in the c:\RIMJavaSDK\docs directory. Although the RIM Java environment is CLDC-compliant, it does not include the KVM. It includes a custom-coded Java virtual machine (VM) that was written and optimized specifically for RIM devices, which we will refer to as the RVM. Until the MIDP is fully supported, applications must be compiled and packaged by using RIM’s development tools (as discussed next).

A First Application We will start our exploration by building the standard Hello world application for the RVM. Because one of the samples is called HelloWorld, we will call our version HelloWorld2. Start the IDE and create a new workspace called Test, placing it in whichever directory you want. In the workspace view, right-click the Test.jdw file and create a new project called HelloWorld2. Right-click the new project and select the Properties item to display the project’s properties dialog.


214

10/17/2000 5:17 PM

Page 214

C HAPTE R 11

Figure 11.8 Setting the HelloWorld2 properties.

This dialog specifies whether the project is a library or an application and defines the title, version, and copyright information for the project (as well as the name of the class that is used for storing resources). Fill in this dialog as shown in Figure 11.8. After dismissing the dialog, rightclick the project again and mark it as active so that it can be run and debugged. Active projects are bold in the workspace view. Now you are ready to add some code. Right-click the HelloWorld2 project and create a new file called HelloWorld2.java. Double-click the file that you just created in order to bring up the text editor, and enter the following code just like we wrote in Chapter 7 (except for the name of the class): public class HelloWorld2 { public static void main( String[] args ) { System.out.println( "Hello, world!" ); // Wait for ten seconds try { Thread.sleep( 10000 ); } catch( InterruptedException e ){ } } }


10/17/2000 5:17 PM

Page 215


215

Now, press F5 to build the project and launch the simulator. Start the application manager and then run the HelloWorld2 application. The program starts, but then the debugger comes to the foreground with an uncaught null pointer exception. Unfortunately, it looks like System. out is not defined in this version of the RIM JDE, so it looks like we will have to build a version that uses the RIM user interface classes. Before we do that, though, let’s install the HelloWorld2 application on the ribbon just to make it easier to start (going through the application manager every time is quite tedious). To place an application on the ribbon, you just need to define some application icons for it. An application icon is a monochrome .GIF file that contains a 16-by-16 image (for the 950’s form factor) or a 28-by-28 image (for the 957’s form factor). You should define both icons. For our purposes, we are just going to use the icons from the Java Logo sample application. From the workspace view, right-click the HelloWorld2 project and select the Add File command to open a file dialog. Navigate to the c:\RIMJavaSDK\Demos\Images directory and select the CUP_16.gif and CUP_28.gif files. After adding these files to the project, right-click each one and bring up its properties dialog, as shown in Figure 11.9. Check the appropriate choice to mark each image as an application icon, then rebuild the project. Run the application. You will now see two identical Java logos in the ribbon: one for our application and one for the original Java Logo sample. You should modify the icons, of course, but for testing purposes, you can easily distinguish the applications by their titles.

Figure 11.9 GIF properties.


216

10/17/2000 5:17 PM

Page 216

C HAPTE R 11

A Better Application Let’s modify HelloWorld2 so that it works as promised. We perform this task by making the application extend the net.rim.device. api.ui.UiApplication class as follows: // Display a "hello, world" message import net.rim.device.api.ui.*; import net.rim.device.api.ui.component.*; public class HelloWorld2 extends UiApplication { // Called on entry to the application public static void main( String[] args ) { // Create the application HelloWorld2 app = new HelloWorld2(); // Loop forever, waiting for events app.enterEventDispatcher(); } // Called when the application is activated public void activate() { // Create our main application screen MainScreen screen = new MainScreen(); // Set its title screen.addTitle( new TitleField( "HelloWorld2" ) ); // Add our message screen.add( new LabelField( "Hello, world!" ) ); // Display it pushScreen( screen ); } }

Run the application, and you should see the screen shown in Figure 11.10. This situation is much better. There is no way to exit the application, however, other than by shutting down the simulator or breaking into it from the IDE. We can fix this problem easily enough by listening for events from the thumbwheel and exiting the application whenever the thumbwheel is pressed or rolled. // Display a "hello, world" message and quit // when the thumbwheel is used import net.rim.device.api.ui.*;


10/17/2000 5:17 PM

Page 217


Figure 11.10 The HelloWorld2 application. import net.rim.device.api.ui.component.*; import net.rim.device.api.system.*; public class HelloWorld2 extends UiApplication implements ThumbListener { public static void main( String[] args ) { HelloWorld2 app = new HelloWorld2(); app.enterEventDispatcher(); } public void activate() { MainScreen screen = new MainScreen(); screen.addTitle( new TitleField( "HelloWorld2" ) );

217


218

10/17/2000 5:17 PM

Page 218

C HAPTE R 11 screen.add( new LabelField( "Hello, world!" ) ); screen.addThumbListener( this ); pushScreen( screen ); } // Clean things up and quit private void close() { popScreen(); System.exit( 0 ); } // Called when the thumbwheel is pressed public boolean thumbClick( int status, int time ) { close(); return true; } // Called when the thumbwheel is released public boolean thumbUnclick( int status, int time ) { return false; } // Called when the thumbwheel is rolled "up" public boolean thumbRollUp( int status, int time, int amount ) { close(); return true; } // Called when the thumbwheel is rolled "down" public boolean thumbRollDown( int status, int time, int amount ) { close(); return true; } }

Now that we have a working application, let’s look more closely at how an application is built and then look at the application programming model.

Building Applications by Hand You can build an application from the command line by using the same steps as the IDE. Instead of compiling the files individually with javac,


10/17/2000 5:17 PM

Page 219


219

running them through a preverifier, and then packaging them together in a JAR file, you can use the rapc.exe command: rapc import=base.jar;os.jar;font.jar;i18n.jar;ui.jar;rms.jar properties=HelloWorld2Resources codename=HelloWorld2 HelloWorld2.java HelloWorld2Resources.java

The source files are compiled by using javac (you will need to have the J2SE 1.3 SDK installed and in your search path) and are then run through RIM’s own tools in order to produce three files: HelloWorld2. jar, HelloWorld2.cod, and HelloWorld2.debug. The JAR file contains all of the class files as well as the other two files but is not needed to run the application. The code for the application is stored in the HelloWorld2.cod file. A .cod file can be significantly smaller than the equivalent set of .class files, which is a big advantage to this process. Debugging information is stored separately in the HelloWorld2.debug file. To run the application, all you need to do is copy the .cod file to the simulator’s working directory or onto the device (an application loader is provided with the JDE for transferring .cod files to a real device). The IDE performs this task for you automatically. If you want to debug the application, you will also need to copy the .debug file. Note that if your application includes any images, you will still have to run the IDE at least once in order to generate the resources file.

The Application Model For now, RIM’s J2ME implementation defines its own application model and its own set of user interface classes. The user interface classes are similar to the Swing classes in J2SE. Application Entry One of the classes in an RIM application must extend either net.rim. device.api.system.Application or net.rim.device.api. ui.UiApplication. The former is only used for applications that do not display any user interface, so most applications extend the latter. The application class must define the usual public static void


220

10/17/2000 5:17 PM

Page 220

C HAPTE R 11

main method as the application entry point. The entry point is responsible for creating a single instance of the application class—the application object—and entering the event dispatcher. Event Dispatching Events are processed by calling the application object’s enterEventDispatcher method. This method never returns. The thread that calls it is known as the event dispatching thread (event thread for short). All event callbacks will occur on that thread. The application continues to run, waiting for and dispatching events until explicitly terminated by calling System.exit. Like Swing, the RIM user interface classes are not thread-safe. All operations involving user interface components must take place on the event thread. The application object defines invokeLater and invokeAndWait methods that are similar to Swing’s in order to run code on the event thread. You can call the static method Application.isEvent-DispatchThread to determine whether the current thread is the event thread. The JDK 1.1 event model is used to deliver events. To receive events, a class must implement a listener interface and register itself with the source of the events. Unlike AWT events, however, the event values are passed directly to the event listeners instead of being wrapped in an event object. Screens and Graphics User-interface components are placed on screens that are subclasses of net.rim.device.api.ui.Screen. A screen is roughly analogous to an AWT window. The application maintains a stack of screens with the topmost screen receiving input events. To make a screen visible, you push it onto the stack using the application object’s pushScreen method and later remove them using popScreen. Screens repaint themselves automatically. Applications normally extend a subclass of Screen called MainScreen. Other subclasses of Screen implement menus and pop-up dialogs. A screen is itself a subclass of Manager, which in turn is a subclass of Field. Manager and Field are the RIM analogs of AWT’s Container


10/17/2000 5:17 PM

Page 221


221

and Component classes. All user interface components extend Field, and all containers—user interface classes that group or lay out other user interface components—extend the Manager class. Horizontal and vertical layout managers are provided, but you can easily define your own layout by overriding the subLayout method of any manager. Drawing normally occurs within the paint method of a field or manager. A rim.net.device.api.system.Graphics object is passed to the method. The Graphics object supports basic drawing primitives. The getGraphics method of the Manager class can also be used to obtain a Graphics object if drawing is required outside a paint method, but this technique is not recommended. Instead, invalidate an area of the screen and wait for a paint event. User-Interface Components RIM’s user interface classes define a rich set of components. There are components for displaying lists, read-only text, editable text, formatted text, and bitmaps. Pop-up menus (which are actually implemented as screens) are available, as are choice controls and push buttons. Their use is fairly straightforward (it is just a matter of creating them, initializing their settings, and adding them to the appropriate manager).

Network Communication RIM devices are, of course, network devices that operate on one of two different radio networks. Java programs can access the network directly in order to communicate with applications that are running on other devices or with servers that are running on a network gateway. Although low-level radio access is available (through the net.rim. device.api.system.Radio class), the preferred way to do network communication is by using a datagram connection obtained from the CLDC’s Generic Connection framework (although it is currently only available for the Mobitex network). One of the samples included with the JDE, ChatTest, demonstrates a simple chat application that can be used to send text messages directly from one device to another. You can even run it with a single instance of the simulator and send messages to yourself. Refer to the sample and to the Javadoc for the javax.microedition.io.Connector class for more details.


222

10/17/2000 5:17 PM

Page 222

C HAPTE R 11

The serial port can also be accessed directly by using the Generic Connection framework (for use when the device is in its cradle). Furthermore, when the JDE supports the full MIDP specification, the HTTP protocol will also be supported.

Miscellaneous Classes The JDE supports a number of other classes beyond those that are required for building user interfaces and doing network communication. These classes cover the following areas: Internationalization. Several of the J2SE classes dealing with locales, formatting, and resource bundles are included with the JDE (but as part of a RIM-specific package). Utilities. Generic routines for data-structure manipulation, CRC calculations, and so on RMS. The MIDP Record Management System (RMS) is implemented. BlackBerry-specific. Classes that are of interest only to applications that are running specifically on a BlackBerry device Without a doubt, there will be further additions to this list as the JDE approaches its final release.

The Tic-Tac-Toe Example We conclude this chapter by adapting our tic-tac-toe example to work with the BlackBerry JDE. This version is based on the MIDP version discussed in Chapter 9 and uses the BlackBerry-specific user interface classes because the MIDP user interface components are not available with the early access version of the JDE. When full MIDP support is available, of course, the MIDP version will work without requiring any changes. For the complete code listings, refer to Appendix A. Since the RIM version of the tic-tac-toe game already uses RIM-specific classes, we are also going to adapt it so that the user can use the thumbwheel to move to and select a particular cell in addition to selecting a cell by pressing the keys 0 to 9.


10/17/2000 5:17 PM

Page 223


223

The TicTacToe Class The RIM version of the TicTacToe class is quite simple. After constructing an instance of the class and entering the event loop, the instance’s activate method is called to indicate that the application has been activated. The activate method reads as follows: public void activate() { gameScreen = new TicTacToeUI( this ); model.addListener( gameScreen ); model.addListener( new TicTacToePlayer( TicTacToeModel.PLAYER_2 ) ); model.newGame(); pushScreen( gameScreen ); }

The TicTacToeUI Class All the work is done by the TicTacToeUI class, which extends RIM’s FullScreen class in order to paint over the entire screen. When TicTacToeUI is constructed, it first creates a popup menu containing two text items: menu = new Menu(); menu.add( new MenuStringField( "Select Cell", MENU_SELECT_CELL ) ); menu.add( new MenuStringField( "Close", MENU_CLOSE ) ); menu.addMenuListener( this );

By making MENU_SELECT_CELL the first item in the menu the user can quickly select a cell by pressing the thumbwheel twice. The menu is displayed when the thumbwheel is clicked the first time, using this code: public boolean thumbClick( int status, int time ){ application.pushScreen( menu ); return true; }

Once the menu is pushed onto the screen stack, all input is directed to it. If the user closes the menu without selecting anything the menuClosed method is called:


224

10/17/2000 5:17 PM

Page 224

C HAPTE R 11 public void menuClosed( Menu menu ){ application.popScreen(); }

If on the other hand an item is selected, the menuSelected method is called instead: public void menuSelected( Menu menu, Field field ){ application.popScreen(); switch( ((MenuStringField) field).getId() ){ case MENU_CLOSE: System.exit( 0 ); break; case MENU_SELECT_CELL: model.setCellState( selectedCell, TicTacToeModel.PLAYER_1 ); invalidate(); break; } }

It is always up to the application to formally dismiss a menu by popping it from the screen stack. To allow the user to move from cell to cell using the thumbwheel we need to mark a cell as being selectable. We do this simply by adding a selectable flag to the Cell class. When a specific cell is painted and its selectable flag is set we simply invert the cell’s contents. The actual movement from cell to cell is done by trapping the thumbRollDown and thumbRollUp events: public boolean thumbRollDown(int status, int time, int amount){ moveCell( 1 ); return true; } public boolean thumbRollUp( int status, int time, int amount ){ moveCell( -1 ); return true; }

The actual movement is done by the moveCell method, as follows: private void moveCell( int offset ){ cells[ selectableCell ].setSelectable( false ); selectableCell += offset; if( selectableCell >= numCells ){


10/17/2000 5:17 PM

Page 225


225

selectableCell = 0; } else if( selectableCell < 0 ){ selectableCell = numCells - 1; } cells[ selectableCell ].setSelectable( true ); invalidate(); }

A few more minor changes are required to adapt the TicTacToeUI class for the RIM environment, so please refer to the source code in Appendix A for the details.

Chapter Summary In this chapter, we looked at the RIMJDE, a different implementation of J2ME for a unique class of wireless hand-held devices. In the next chapter, we will move away from J2ME and look at an open source alternative for Palm OS and Windows CE: Waba.


10/17/2000 5:17 PM

Page 226


10/17/2000 5:18 PM

Page 227

12

CHAPTER


B

efore Sun Microsystems released a version of Java that was capable of running on a small computing device such as a Palm Pilot, a small California company called Wabasoft Corporation (www.wabasoft.com) was working on solving the same problem. Wabasoft created a development system called Waba that enables you to write Java programs that run on the Palm and Windows CE operating systems while still having the capability to run on the J2SE platform. Waba is an open-source product that has gained enough of a following that it deserves mention in this book as one alternative to J2ME, especially because it came out before the J2ME reference implementations. Waba is fairly limited, however, so it may not be suitable for your needs. In this chapter, we will look at what Waba is and how to use it.

What Is Waba? Waba is an alternative to Java for small devices. At the heart of the Waba system is the Waba virtual machine (VM), which is a virtual machine that can read and execute a subset of Java bytecodes. Waba is not a Java runtime environment, nor does it claim to be. Waba does, however, enable you to use a familiar language and familiar development tools to write portable applications for Palm and Windows CE 227


228

10/17/2000 5:18 PM

Page 228

C HAPTE R 12

devices. Waba performs this function by providing three elements: a virtual machine, a set of runtime classes, and a set of bridge classes.

The Waba VM The Waba VM accepts a subset of Java bytecodes. Specifically, it accepts and can run all of the standard bytecodes defined by The Java Virtual Machine Specification (except those that deal with long integers, doubles, exceptions, or threads). The classfile format is similarly constrained. The Waba VM can read Java class files that do not contain references to long integers or double values, either as bytecodes or in the constant pool. Exception tables in the class files are silently ignored. To create a Waba application, you need to write Java code that does not use the long or double types, that does not create or otherwise depend on threads, that does not throw or catch exceptions, and that only uses classes you write or that are provided with the VM. Compile the code with a Java compiler as you normally would in order to generate class files that the Waba VM can read. The Waba VM is quite small— about 33K on Palm OS.

The Waba Run Time Class files and bytecodes are not enough by themselves to write programs, of course. You also need a runtime library. Waba defines a set of foundation classes for user interface creation, network connectivity, and general programming. The classes are all defined in the waba package. In fact, the base class in the Waba system is waba.lang. Object—all classes in the Waba runtime library extend it, not java. lang.Object. No class in the waba package extends or implements any class or interface in the java package. You might wonder about references to java.lang.Object, java. lang.String, and java.lang.StringBuffer that are automatically generated by a Java compiler when it generates a class file. String concatenation using the + operator, for example, implicitly creates String and StringBuffer objects. If the Waba run time does not include any of the core classes from the java.lang package, how can Waba run such a class file? What the Waba VM does is simple: Each time it sees a reference to java.lang.Object, java.lang.


10/17/2000 5:18 PM

Page 229


229

String or java.lang.StringBuffer, it simply substitutes waba.lang.Object, waba.lang.String or waba.lang. StringBuffer, respectively. These Waba classes implement a subset of the functionality of their java.lang counterparts, specifically those methods that are called by compiler-generated implicit code. The Waba runtime library is also quite small—about 40K on Palm OS.

The Bridge Classes The final piece in the Waba puzzle is the set of bridge classes. The bridge classes enable you to run Waba applications on a desktop system by using J2SE. In effect, they reimplement the Waba run time by using J2SE APIs. This function enables you to write Waba programs that not only run on Palm OS or Windows CE but that also run wherever J2SE itself runs. Figures 12.1 and 12.2 illustrate how this process works. Waba programs that are run with the bridge classes can run as applets or as standalone applications. Waba application Waba foundation classes Waba VM Windows CE or Palm OS Figure 12.1 Running Waba applications without Java.

Waba application Waba bridge classes J2SE runtime J2SE VM Operating system Figure 12.2 Running Waba applications with Java.


230

10/17/2000 5:18 PM

Page 230

C HAPTE R 12

Besides providing applications with additional portability, the bridge classes make it easier to develop and test the applications. You can use your favorite development environment to create, build, and run your programs, only occasionally building and testing them for an actual device. Even then, you are likely to use an emulator to do most of your testing.

Using Waba Getting ready to use Waba is just a matter of navigating to the Wabasoft Web site and downloading and installing the appropriate files on your device and on your desktop. These files are also available on the CD-ROM accompanying this book.

Installation The first thing to do is install the appropriate Waba VM on your Palm or Windows CE device. Each VM is packaged in a ZIP file with installation instructions. For Palm devices, install the waba.pdb and waba.prc files and then tap on the Waba icon, as shown in Figure 12.3. For Windows CE devices, install the waba.exe and waba.wrp files in a directory on the device. After installing the VM, install the Waba software development kit (SDK), which is packaged as two separate ZIP files. Just unzip the files

Figure 12.3 The Waba VM icon on the Palm.


10/17/2000 5:18 PM

Page 231


231

into a directory and put the bin directory in your system path and the classes directory in your classpath. The bin directory contains the two Waba tools, exegen and warp, while the classes directory contains the Waba bridge classes. If you are interested in looking through the source of the VM or building it yourself, it is available as a separate ZIP file and is distributed under the GNU Public License. This source can be installed along with the Waba SDK. Instructions for building the Waba VM are found on Wabasoft’s Web site.

Running the Samples The first thing to do is to build and run the samples from the SDK. You will need to have J2SE installed on your machine. From the command line, go to the examples directory. This directory contains seven Waba samples, each of which is in its own subdirectory. Each subdirectory includes a make.bat file for building the particular sample. For example, here is how to build the Controls sample: cd c:\wabasdk.10\examples\Controls make

After building a sample, you can run it on your desktop by using the bridge classes. Here is how you run the Controls sample as a Java application: set CLASSPATH=.;c:\wabasdk.10\classes;%CLASSPATH% java waba.applet.Applet Controls

The running application is shown in Figure 12.4. You can also run the sample as an applet by using the HTML file that is provided with each sample as a guide. Once the sample is built, you can also run it with the Waba VM. The make.bat file generates the appropriate files for both Palm OS and Windows CE. Assuming that you have installed the Waba VM on your Palm OS device, simply install the generated .prc and .pdb files. After you HotSync, you will see an icon for the sample. The Controls sample running on Palm OS is shown in Figure 12.5. For Windows CE, copy the .wrp and .lnk files onto the device. You might have to adjust the paths stored in the .lnk file (by default, it assumes that the waba.exe


232

10/17/2000 5:18 PM

Page 232

C HAPTE R 12

Figure 12.4 The Controls sample as a Java application.

Figure 12.5 The Controls sample running on Palm OS.


10/17/2000 5:18 PM

Page 233


233

file is in \Program Files\waba\waba.exe and that the sample is named \Program Files\sample\sample.wrp).

Compiling and Running Classes If you look at any of the make.bat files that build a sample, you will see that the build process for a Waba program is quite simple. The first step is to use the usual javac command to compile the Java source code, ensuring of course that the bridge classes are in the classpath: javac *.java

The next step is to use warp.exe to package the class files into a warp file, which is similar to a Java Archive (JAR) file: warp c AppName *.class

Two files are created: AppName.wrp for Windows CE and AppName. pdb for Palm OS. (Note that if you are building a Palm application that you wish to distribute to others, you should obtain a creator ID for it and assign it to the .pdb file by using Warp’s /c option.) The final step is to generate executables by using exegen.exe: exegen AppName MainClassName AppName

The parameters of exegen specify the name of the output file, the name of the application’s main class, and the names of the .wrp files that contain the application classes. Two additional files are created: AppName.prc for Palm OS and AppName.lnk for Windows CE. Various options are available to control memory usage, the path in the .lnk file, and the bitmap to use as an icon on Palm OS (if no bitmap is specified, a default bitmap is used). You run the application just as we did with the samples.

The HelloWorld Application Once again, we define a simple HelloWorld class: import waba.ui.*; import waba.fx.*;


234

10/17/2000 5:18 PM

Page 234

C HAPTE R 12 public class HelloWorld extends MainWindow { public void onPaint( Graphics g ) { g.setColor( 0, 0, 0 ); g.drawText( "Hello, world!", 0, 0 ); } }

Build the program by using these commands, assuming that the path and classpath are set correctly: javac HelloWorld.java warp c HelloWorld HelloWorld.class exegen HelloWorld HelloWorld HelloWorld

After installing the appropriate files on your device or emulator, run the HelloWorld application. You should see something similar to Figure 12.6.

Figure 12.6 The HelloWorld application.


10/17/2000 5:18 PM

Page 235


235

Debugging Not only do the bridge classes make it possible to run Waba programs with J2SE, they also make it easy to debug a Waba program. Just use any of your usual debugging techniques and tools, such as tracing program execution through calls to System.out. At runtime you can use the waba.sys.Vm.getPlatform method to determine if you’re running with the bridge classes or on an actual device—it returns “Java” only when running with the bridge classes.

The Waba Foundation Classes Although profiles add new classes to a configuration, the core Java classes are common to all implementations of J2ME. In Waba, however, this is not the case. Waba defines a completely different set of runtime classes.

Overview The Waba foundation classes are currently grouped into six packages: 1. waba.fx for drawing graphics and playing sounds 2. waba.io for accessing files and databases and making network or serial port connections 3. waba.lang for the core Java classes Object, String, and StringBuffer 4. waba.sys for basic system functionality 5. waba.ui for user interfaces 6. waba.util for useful utility classes (currently consisting of a scaled-down Vector look-alike) Let’s look at a few of these classes in more detail.

The Application Model A Waba application’s main class extends waba.fx.MainWindow in much the same way as an applet extends java.applet.Applet in


236

10/17/2000 5:18 PM

Page 236

C HAPTE R 12

J2SE. The main class overrides the onStart method in order to initialize itself, usually by adding controls that are to be displayed as part of the main window. When the Waba VM starts the application, it creates an instance of the main class and invokes the onStart method before entering its event loop. A Waba application keeps running until the application calls the main window’s exit method, after which the onExit method is called in order to give the application an opportunity to perform some cleanup. Note that on Palm OS, the application can be terminated at any time by the user switching to another application, so be prepared to handle exits at any time.

The User Interface Waba defines Control and Container classes that are analogs to AWT’s Component and Container classes. In other words, all user interface components extend Control, and all components that can contain other components extend Container. Drawing is done by overriding a control’s onPaint method, as shown in the HelloWorld example. A container will paint its children automatically, but there are no layout managers to place and resize child controls. When you create a control, you must specify its absolute position and size. A Graphics class provides the usual drawing primitives. Drawing can occur directly on the screen or to an off-screen image. Events are trapped by overriding the onEvent method, much like the original AWT. There are no listeners to register. Four basic event types are supported: key events, pen/mouse events, control events, and timer events—although facilities exist for posting user-defined events. Only a few basic user interface controls are supported, including push buttons, radio buttons, checkboxes, labels, and edit fields. Notably missing is some kind of list control, although a tab control is included, as is built-in support for popup dialogs or any kind of window other than the main window.

Input/Output (I/O) All I/O classes in Waba extend the Stream class, which provides basic functions for reading and writing data. Waba supports a File class for


10/17/2000 5:18 PM

Page 237


237

reading or writing to the file system, but it does not work on the Palm because there is no file system available. A Catalog class provides a simple record-oriented database that maps to a native database on the Palm and to a file on Windows CE. A SerialPort class enables a Waba program to access the serial port, and a Socket class enables it to make a network connection.

The Tic-Tac-Toe Example For one final time, let’s adapt the tic-tac-toe game, this time for use with Waba. We actually base this version on the original Palm version discussed in Chapter 8, because the user interface models are similar. Waba’s classes are more complex and feature-complete, however. We start with changes to the TicTacToeModel and TicTacToePlayer classes. These classes have to change a bit because Waba doesn’t support the java.util.Enumeration or java.util.Random classes. Waba’s vector class, waba.util.Vector, is also quite different than J2SE’s java.util.Vector. We simulate random number generation in the player class by getting the current time, so instead of coding the following: import java.util.Random; .... private Random generator = new Random(); .... int cell = ( generator.nextInt() % max );

We code this: import waba.sys.Time; .... Time t = new Time(); int cell = ( ( t.millis + t.second + t.minute ) % max );

This is an adequate solution because the generated values will vary depending on how quickly the user plays the game. As for the model, we need to rewrite the listener notification code to directly iterate over the vector of listeners instead of using an enumeration. Most of the changes occur in the TicTacToe class, which creates and manages the user interface. Since we can paint directly on the main


238

10/17/2000 5:18 PM

Page 238

C HAPTE R 12

window, there is no need for a separate TicTacToeUI class. Most of the differences are in the way events are handled, using the onEvent method of the main window: public void onEvent( Event e ){ if( e instanceof KeyEvent ){ keyPressed( ((KeyEvent) e).key ); } else if( e instanceof PenEvent ){ PenEvent pe = (PenEvent) e; if( pe.type == PenEvent.PEN_DOWN ){ if( model.isGameStarted() ){ penDown( pe.x, pe.y ); } else { model.newGame(); } } } }

This event method merely redirects calls to the penDown and keyPressed methods, which we’re reusing unchanged from the Palm version. Since Waba doesn’t provide any support for even the most rudimentary of dialogs, the tic-tac-toe game simply clears out and reverses an area of the screen and prints the message there. All of this is done in the onPaint method, as follows: public void onPaint( Graphics g ){ g.setColor( 0, 0, 0 ); drawGrid( g ); drawPlayers( g ); if( !model.isGameStarted() ){ g.fillRect( 10, 40, width-20, height-80 ); g.setColor( 255, 255, 255 ); g.drawText( winnerText, 15, 40 ); g.drawText( "Tap to start over", 15, 60 ); } }

The game restarts when the user taps the screen. The remainder of the code is almost completely unchanged when compared to the Palm version.


10/17/2000 5:18 PM

Page 239


239

Chapter Summary Although Waba is not Java, it might be worth looking at as an alternative to J2ME. The fact that it is open source means that you can enhance it yourself or even port it yourself to another platform, which is certainly easier than porting a J2ME implementation. Check this book’s Web site for other alternatives, as well.


10/17/2000 5:18 PM

Page 240


10/17/2000 5:18 PM

Page 241

13

CHAPTER

Final Thoughts

W

e have come to the end of our explorations, so we will finish with some final thoughts on the J2ME.

Alternatives to J2ME For various reasons, J2ME might not meet your needs as a programming platform for small devices. Perhaps you need access to low-level, device-specific APIs that no J2ME implementation exposes. Or maybe J2ME is not available for all of the devices in which you are interested. Or perhaps there are serious performance problems that you cannot easily overcome. Listed here are some alternatives to J2ME. Create your own J2ME implementation. This task is not something to undertake lightly, but if you really want to use J2ME even if it does not currently meet all of your requirements, then consider creating your own implementation. You can perform this action by porting or adapting an existing implementation (such as the CLDC reference implementation) or by contracting with someone to design the implementation for you.

241


242

10/17/2000 5:18 PM

Page 242

C HAPTE R 13

Explore the possibility of using J2SE instead. If your device supports it, J2SE or an earlier conventional form of Java might be a better choice than J2ME. Some EPOC-based (EPOC is an operating system promoted by the Symbian consortium) devices, for example, include either a Java 1.1.4 or a Java 1.1.8 implementation (with support for Java 2 promised later). Use a hardware-based Java VM. Several companies are creating Java runtime environments that incorporate some kind of hardware-based execution engine for better performance. If you are building an embedded system, you might consider including such a runtime environment in your system. Switch to a different programming language. Like we mentioned in the introduction, Java might not be the best language for the job. You could move to a Java-like solution (such as Waba) or to a completely different language and development environment. Obviously, you are reading this book in order to understand J2ME in the hopes of using it in your own projects, so the ideal solution does not involve any of these alternatives. It makes sense to consider them, however, because J2ME is still an immature technology that has lots of room to develop.

Conclusion Where does J2ME go from here? Right now, its functionality is still being fleshed out. Specifications are being written, and implementations are being tested. Only a few early adopters are seriously using J2ME in its current forms, although you can expect that to change as more and more device manufacturers start to include Java VMs with their basic system software. Cellular telephones are a particularly interesting market for Java. Motorola is promising to deliver the first MIDP-enabled phone by the end of 2000, just after this book is published; you will be able to load applications wirelessly onto your cellular phone and keep them there for use even when you are outside your coverage area. And you (and cellular phone manufacturers) can rest easy knowing that the Java sandbox will protect your precious phone from malicious applications. We have just begun the process of moving Java back to the client. Maybe this time, client-side Java will fulfill its promises.

67957_Wiley_Giguere_AppA

10/17/2000 5:18 PM

Page 243

APPENDIX

A


T

his appendix lists the source code for the tic-tac-toe game that we developed in this book.

Common Code Much of the code in the tic-tac-toe game is shared, so we will list these classes first.

TicTacToeModel The most important class, defines the model for the game. We discussed this class at some length in Chapter 3: package com.ericgiguere.j2mebook.models; import java.util.Enumeration; import java.util.Vector; /** * Defines the model for the TicTacToe game. This class * holds all the state information for the game and * notifies any listeners of state changes. The class

243


244

10/17/2000 5:18 PM

Page 244

APPENDIX A * is also responsible for determining if a someone * wins and which cells were used to win, or if * the game is tied. *
* This model can be used to define any tic-tac-toe game * of size n, where 3 6 ){ size = 3; } // Tell anyone waiting that the game is now over. endGame(); // Figure out the dimensions we need to worry about. // The number of cells is n**2, the number of rows is 2*n+2. cellsPerRow = size; numCells = size * size; numTotals = 2 * size + 2; player1Wins = size * PLAYER_1; player2Wins = size * PLAYER_2; // Initialize the cells and totals.


10/17/2000 5:18 PM

Page 251


251

if( cells == null || cells.length < numCells ){ cells = new byte[ numCells ]; } int i; for( i = 0; i < numCells; ++i ){ cells[i] = NO_PLAYER; } if( totals == null || totals.length < numTotals ){ totals = new int[ numTotals ]; } int initial = cellsPerRow * NO_PLAYER; for( i = 0; i < numTotals; ++i ){ totals[i] = NO_PLAYER; } calculateIndices(); // Tell everyone we’re ready and that a new game // has started. gameStarted = true; notifyGameStarted(); } /** * Notify listeners that the game is over. */ private void notifyGameOver(){ Enumeration e = listeners.elements(); while( e.hasMoreElements() ){ TicTacToeModelListener l = (TicTacToeModelListener) e.nextElement(); l.gameOver( this ); } } /** * Notify listeners that the game has started. */ private void notifyGameStarted(){ Enumeration e = listeners.elements(); while( e.hasMoreElements() ){ TicTacToeModelListener l = (TicTacToeModelListener) e.nextElement();


252

10/17/2000 5:18 PM

Page 252

APPENDIX A l.gameStarted( this ); } } /** * Notify listeners that the game has been updated. */ private void notifyGameUpdated( int cell, int value ){ Enumeration e = listeners.elements(); while( e.hasMoreElements() ){ TicTacToeModelListener l = (TicTacToeModelListener) e.nextElement(); l.gameUpdated( this, cell, value ); } } /** * Quits an existing game, notifying any listeners * that the game is over. */ public void endGame(){ if( gameStarted ){ gameStarted = false; notifyGameOver(); } } /** * Removes a listener from this model. * * @param listener the listener to remove. */ public void removeListener( TicTacToeModelListener listener ){ listeners.removeElement( listener ); } /** * Sets the value of a cell. * * @param index the cell index. * @param value the cell value. */ public void setCellState( int index, int value ){ if( !gameStarted || index < 0 || index >= numCells ) return; if( cells[index] != NO_PLAYER ) return; cells[index] = (byte) value;


10/17/2000 5:18 PM

Page 253

Tic-Tac-Toe Source Code calculateTotals(); notifyGameUpdated( index, value ); if( isGameOver() ){ endGame(); } } /** * Sets the value of a cell by row and column. * * @param row the row index of the cell. * @param col the column index of the cell. * @param value the cell value. */ public void setCellState( int row, int col, int value ){ setCellState( row * cellsPerRow + col, value ); } /** * The cells used by the game. */ private byte[] cells; /** * The number of cells per row. */ private int cellsPerRow; /** * Whether a game is active or not. */ private boolean gameStarted; /** * The vector of listeners. */ private Vector listeners = new Vector(); /** * The number of cells in the game. */ private int numCells; /**

253


254

10/17/2000 5:18 PM

Page 254

APPENDIX A * The number of rows in the game. */ private int numTotals; /** * Player 1 is a winner. */ private int player1Wins; /** * Player 2 is a winner. */ private int player2Wins; /** * The indices for each row. */ private int[] rowIndices; /** * The running totals to determine who is winning. */ private int[] totals; }

TicTacToeModelListener The model is accompanied by a listener interface so that interested parties can receive notifications about games that are in progress: package com.ericgiguere.j2mebook.models; /** * Defines an event listener for the TicTacToeModel. * Classes that implement this interface are notified * of the game status held by a model. */ public interface TicTacToeModelListener { /** * A game has just finished. * who won.

The listener can ask the model


10/17/2000 5:18 PM

Page 255


255

* * @param model the model triggering the event. */ void gameOver( TicTacToeModel model ); /** * A game has started. * * @param model the model triggering the event. */ void gameStarted( TicTacToeModel model ); /** * A cell * * @param * @param * @param */

in the game has been updated. model the model triggering the event. cell the index of the updated cell. value the new value of the cell.

void gameUpdated( TicTacToeModel model, int cell, int value ); }

TicTacToePlayer Finally, we define a listener that behaves like a player, selecting cells in response to the user’s own selections: package com.ericgiguere.j2mebook.models; import java.util.Random; /** * Defines an automatic tic-tac-toe player. This player works * by implementing the TicTacToeModelListener interface and * receiving notifications from a TicTacToeModel. When the * opponent sets a cell, the player sets a cell in response. */ public class TicTacToePlayer implements TicTacToeModelListener { /** * Constructs an automatic tic-tac-toe player. * * @param which which player number, either PLAYER_1 or PLAYER_2.


256

10/17/2000 5:18 PM

Page 256

APPENDIX A */ public TicTacToePlayer( int which ){ whichPlayer = which; } /** * Fills the first empty cell in a row with the value * for this player. * * @param model the game model. * @param row the row index. */ private void fillRow( TicTacToeModel model, int row ){ model.getRowIndices( row, indices ); for( int j = 0; j < indices.length; ++j ){ if( model.getCellState( indices[j] ) == TicTacToeModel.NO_PLAYER ){ model.setCellState( indices[j], whichPlayer ); break; } } } /** * Called when a game is started, prepares some values based * on the current settings of the model. * * @param model the game model. */ public void gameStarted( TicTacToeModel model ){ totals = model.getTotals(); canWinValue = ( 2 * whichPlayer ) + TicTacToeModel.NO_PLAYER; dangerValue = ( -2 * whichPlayer ) + TicTacToeModel.NO_PLAYER; indices = new int[ model.getSize() ]; }

/** * Called whenever a cell is updated while a game is in progress. * The automatic player uses this notification to track the * opponent’s moves and to prepare a move in response. * * @param model the game model. * @param index the cell index. * @param value the cell’s new value. */ public void gameUpdated( TicTacToeModel model, int index, int value


10/17/2000 5:18 PM

Page 257


257

){ // Ignore our own moves... if( value == whichPlayer ) return; // Get the updated totals and see if we can win by filing // in a row. Otherwise see if the opposing player is about // to win and fill in the appropriate row... model.fillTotals( totals ); int i; int n = totals.length; for( i = 0; i < n; ++i ){ if( totals[i] == canWinValue ){ fillRow( model, i ); return; } } for( i = 0; i < n; ++i ){ if( totals[i] == dangerValue ){ fillRow( model, i ); return; } } // No danger values, so choose a cell at random... int max = model.getCellCount(); while( !model.isGameOver() ){ int cell = ( generator.nextInt() % max ); if( model.getCellState( cell ) == TicTacToeModel.NO_PLAYER ){ model.setCellState( cell, whichPlayer ); return; } } } /** * Called when the game is over. * * @param model the game model. */

Clears out some values.

public void gameOver( TicTacToeModel model ){ totals = null; indices = null;


258

10/17/2000 5:18 PM

Page 258

APPENDIX A } private private private private private private

int int[] int[] int int Random

whichPlayer; totals; indices; canWinValue; dangerValue; generator = new Random();

}

Palm-Specific Code The Palm version of tic-tac-toe defines just a single class in addition to the common ones we just listed. We discussed this class in Chapter 8.

TicTacToe The class is a spotlet that draws the tic-tac-toe game board and traps user input: // Copyright 2000 by Eric Giguere. // From Java 2 Micro Edition: Professional Developer’s Guide, // published by John Wiley & Sons. package com.ericgiguere.j2mebook.palm; import com.ericgiguere.j2mebook.models.*; import com.sun.kjava.*; /** * A simple tic-tac-toe game for the Palm port of the CLDC. * This game uses the unsupported com.sun.kjava classes * to do the drawing and to get user input. */ public class TicTacToe extends Spotlet implements DialogOwner, TicTacToeModelListener { /** * Starts our game. */ public static void main( String[] args ){ new TicTacToe(); }


10/17/2000 5:18 PM

Page 259


259

/** * Constructs a tic-tac-toe game. */ public TicTacToe() { register( NO_EVENT_OPTIONS ); Graphics.getGraphics().clearScreen(); model = new TicTacToeModel(); model.addListener( this ); model.addListener( new TicTacToePlayer( TicTacToeModel.PLAYER_2 ) ); model.newGame(); } /** * Called when a dialog is dismissed. We re-register the spotlet * and start a new game. * * @param title the title of the dialog. */ public void dialogDismissed( String title ){ register( NO_EVENT_OPTIONS ); model.newGame(); } /** * Draws the tic-tac-toe grid. * * @param g the Graphics object. */ public void drawGrid( Graphics g ){ int i, x, y; x = cellWidth; y = cellHeight; for( i = 0; i < cellsPerRow - 1; ++i ){ g.drawLine( x, 0, x, screenHeight, g.PLAIN ); g.drawLine( 0, y, screenWidth, y, g.PLAIN ); x += cellWidth; y += cellHeight; } } /**


260

10/17/2000 5:18 PM

Page 260

APPENDIX A * Draws each cell. * * @param g the Graphics object. */ public void drawPlayers( Graphics g ){ for( int i = 0; i < numCells; ++i ){ cells[i].paint( g ); } } /** * Called when the game is over. * with the result of the game. * * @param model the game model. */

Displays a dialog

public void gameOver( TicTacToeModel model ){ String text; switch( model.getWinner() ){ case TicTacToeModel.PLAYER_1: text = "Player 1 wins!"; break; case TicTacToeModel.PLAYER_2: text = "Player 2 wins!"; break; default: text = "A tie!"; break; } Dialog d = new Dialog( this, "Game Over", text, "OK" ); d.showDialog(); } /** * Called * * @param * @param * @param */

when a cell in the game is updated. model the game model. index the cell index. value the cell’s new value.

public void gameUpdated( TicTacToeModel model, int index, int value ){ Cell cell = cells[index]; cell.state = value; paint(); }


10/17/2000 5:18 PM

Page 261

Tic-Tac-Toe Source Code /** * Called when a game is started. Clears the screen, * calculates the dimensions of the cells and then paints * the grid. * * @param model the game model. */ public void gameStarted( TicTacToeModel model ){ Graphics.getGraphics().clearScreen(); cellsPerRow = model.getSize(); numCells = cellsPerRow * cellsPerRow; cellHeight cellWidth

= screenHeight / cellsPerRow; = screenWidth / cellsPerRow;

cells = new Cell[ numCells ]; int i, j, y; for( i = 0, y = 0; i < numCells; i += cellsPerRow ){ for( j = 0; j < cellsPerRow; ++j ){ cells[i+j] = new Cell( cellWidth * j + cellsPerRow, y + cellsPerRow ); } y += cellHeight; } this.model = model; paint(); } /** * General game paint routine. * cells. */

Draws the grid and then the

public void paint(){ Graphics g = Graphics.getGraphics(); if( model != null ){ drawGrid( g ); drawPlayers( g ); } } /** * Handles pen presses, checking to see if the user * has pressed over an empty cell. *

261


262

10/17/2000 5:18 PM

Page 262

APPENDIX A * @param x the X coordinate of the pen press. * @parma y the Y coordinate of the pen press. */ public void penDown( int x, int y ){ if( model != null && model.isGameStarted() ){ for( int i = 0; i < numCells; ++i ){ if( cells[i].contains( x, y ) ){ model.setCellState( i, TicTacToeModel.PLAYER_1 ); return; } } } } private private private private private private private private

int int int int int int TicTacToeModel Cell[]

cellsPerRow; numCells; cellHeight; cellWidth; screenHeight = 160; screenWidth = 160; model; cells;

//--------------------------------------------------------/** * Defines a simple inner class for holding the state and * the location of each cell. Since it’s an inner class * each instance has access to the private data of its * parent class, i.e. the cellHeight and cellWidth values. */ private class Cell { int state; int x; int y; /** * Constructs an empty cell at the given location. * * @param x the X value. * @param y the Y value. */ public Cell( int x, int y ){ state = TicTacToeModel.NO_PLAYER; this.x = x; this.y = y; } /**


10/17/2000 5:18 PM

Page 263


263

* Determines whether or not the given point is in the * cell. * * @param px the X value. * @param py the Y value. * * @return true if the point is within the cell. */ public boolean contains( int px, int py ){ return( px >= x && px = y && py = x && px = y && py = 0 && index < numCells ){ model.setCellState( index, TicTacToeModel.PLAYER_1 ); }

275


276

10/17/2000 5:18 PM

Page 276

APPENDIX A return true; } /** * Called by the system when a popup menu closes * without the user selecting any of its items. * Removes the menu by popping it off the display * stack. * * @param menu the menu that just closed. */ public void menuClosed( Menu menu ){ application.popScreen(); } /** * Called by the system when the user selects * a popup menu item. Removes the menu and * then acts on the selection. * * @param menu the menu that was just closed. * @param field the selected field in the menu. */ public void menuSelected( Menu menu, Field field ){ application.popScreen(); switch( ((MenuStringField) field).getId() ){ case MENU_CLOSE: System.exit( 0 ); break; case MENU_SELECT_CELL: model.setCellState( selectableCell, TicTacToeModel.PLAYER_1 ); invalidate(); break; } } /** * Called to perform layout of the screen. * * @param width the screen’s width. * @param height the screen’s height. */ public void sublayout( int width, int height ){ screenHeight = height; screenWidth = width; setExtent( width, height );


10/17/2000 5:18 PM

Page 277

Tic-Tac-Toe Source Code if( model != null ){ initializeCells(); } } /** * Paints the grid and the cells. * * @param g the graphics object. */ public void paint( Graphics g ){ if( model != null ){ drawGrid( g ); drawPlayers( g ); } } /** * Called whenever the screen is shown. Starts a new * game if called after the alert is displayed. */ public void onDisplay(){ if( model != null && !model.isGameStarted() ){ model.newGame(); } } /** * Starts a new game. */ public void run(){ model.newGame(); } /** * Moves the selectable cell to a new cell. * * @param offset the direction and number of * cells to move (negative for up/left, * positive for down/right). */ private void moveCell( int offset ){ cells[ selectableCell ].setSelectable( false ); selectableCell += offset; if( selectableCell >= numCells ){ selectableCell = 0; } else if( selectableCell < 0 ){

277


278

10/17/2000 5:18 PM

Page 278

APPENDIX A selectableCell = numCells - 1; } cells[ selectableCell ].setSelectable( true ); invalidate(); } /** * Called when the user clicks the thumbwheel. * Opens the popup menu in response. * * @param status ignored. * @param time ignored. * @return true to indicate it’s been handled. */ public boolean thumbClick( int status, int time ){ application.pushScreen( menu ); return true; } /** * Called when the user rolls the thumbwheel down. * Moves the selected cell in response. * * @param status ignored. * @param time ignored. * @parma amount ignored. * @return true to indicate it’s been handled. */ public boolean thumbRollDown( int status, int time, int amount ){ moveCell( 1 ); return true; } /** * Called when the user rolls the thumbwheel up. * Moves the selected cell in response. * * @param status ignored. * @param time ignored. * @parma amount ignored. * @return true to indicate it’s been handled. */ public boolean thumbRollUp( int status, int time, int amount ){ moveCell( -1 ); return true; } private int

cellsPerRow;


10/17/2000 5:18 PM

Page 279

Tic-Tac-Toe Source Code private private private private private private private private private private

int int int int int TicTacToeModel TicTacToe Cell[] Menu int

279

numCells; cellHeight; cellWidth; screenHeight; screenWidth; model; application; cells; menu; selectableCell;

//--------------------------------------------------------/** * Defines a simple inner class for holding the state and * the location of each cell. Since it’s an inner class * each instance has access to the private data of its * parent class, i.e. the cellHeight and cellWidth values. */ private class Cell { int state; int x; int y; boolean selectable; /** * Constructs an empty cell at the given location. * * @param x the X value. * @param y the Y value. */ public Cell( int x, int y ){ state = TicTacToeModel.NO_PLAYER; this.x = x; this.y = y; selectable = false; } /** * Determines whether or not the given point is in the * cell. * * @param px the X value. * @param py the Y value. * * @return true if the point is within the cell. */ public boolean contains( int px, int py ){


280

10/17/2000 5:18 PM

Page 280

APPENDIX A return( px >= x && px = y && py '9' ) return; model.setCellState( keyCode - '0', TicTacToeModel.PLAYER_1 ); } /** * Called by Waba whenever an event occurs. * * @param e the event object with information about the event. */

283


284

10/17/2000 5:18 PM

Page 284

APPENDIX A public void onEvent( Event e ){ if( model == null ) return; if( e instanceof KeyEvent ){ keyPressed( ((KeyEvent)e).key ); } else if( e instanceof PenEvent ){ PenEvent pe = (PenEvent) e; if( pe.type == PenEvent.PEN_DOWN ){ if( model.isGameStarted() ){ penDown( pe.x, pe.y ); } else { model.newGame(); } } } } /** * General game paint routine. Draws the grid and then the * cells. Also draws the winner text if the game is over. * * @param g the graphics object. */ public void onPaint( Graphics g ){ g.setColor( 0, 0, 0 ); if( model != null ){ drawGrid( g ); drawPlayers( g ); if( !model.isGameStarted() ){ g.fillRect( 10, 40, width-20, height-80 ); g.setColor( 255, 255, 255 ); g.drawText( winnerText, 15, 40 ); g.drawText( "Tap to start over", 15, 60 ); } } } /** * Handles pen presses, checking to see if the user * has pressed over an empty cell. * * @param x the X coordinate of the pen press. * @parma y the Y coordinate of the pen press. */ public void penDown( int x, int y ){ if( model != null && model.isGameStarted() ){ for( int i = 0; i < numCells; ++i ){


10/17/2000 5:18 PM

Page 285

Tic-Tac-Toe Source Code if( cells[i].contains( x, y ) ){ model.setCellState( i, TicTacToeModel.PLAYER_1 ); return; } } } } private private private private private private private private private

int int int int int int TicTacToeModel Cell[] String

cellsPerRow; numCells; cellHeight; cellWidth; screenHeight; screenWidth; model; cells; winnerText;

//--------------------------------------------------------/** * Defines a simple inner class for holding the state and * the location of each cell. Since it’s an inner class * each instance has access to the private data of its * parent class, i.e. the cellHeight and cellWidth values. */ private class Cell { int state; int x; int y; /** * Constructs an empty cell at the given location. * * @param x the X value. * @param y the Y value. */ public Cell( int x, int y ){ state = TicTacToeModel.NO_PLAYER; this.x = x; this.y = y; } /** * Determines whether or not the given point is in the * cell. * * @param px the X value. * @param py the Y value.

285


286

10/17/2000 5:18 PM

Page 286

APPENDIX A * * @return true if the point is within the cell. */ public boolean contains( int px, int py ){ return( px >= x && px = y && py

Java 2 Micro Edition: Professional Developer's Guide

Java 2 Micro Edition

Java 2 Micro Edition [J2ME]

Professional Eclipse 3 for Java Developers

Professional Eclipse 3 for Java Developers

Professional Java JDK 6 Edition

Программирование мобильных телефонов на Java 2 Micro Edition

Micro Java Game Development

C# for Java Developers

Rails for Java Developers

Professional JavaScript® for Web Developers, Third Edition

Professional JavaScript for Web Developers ~ 2nd Edition

Professional Silverlight 2 for ASP NET Developers

Java for ColdFusion Developers

Programming Java 2 Micro Edition for Symbian OS: A developer's guide to MIDP 2.0

Functional Programming for Java Developers

JasperReports 3.5 for Java Developers

Micro Java(TM) Game Development

Programming Java 2 Micro Edition for Symbian OS: A developer's guide to MIDP 2.0

MIDP 2.0 Style Guide for the Java 2 Platform, Micro Edition

Java 2: A Beginner's Guide

Java 2 Certification Training Guide

Java 2 Certification Training Guide

Java 2 - A Beginner's Guide

Jasperreports: Reporting for Java Developers

Functional Programming for Java Developers

Professional JavaScript? for Web Developers

Professional JavaScript for Web Developers

Professional JavaScript for web developers

Professional JavaScript for Web Developers

Java 2 Enterprise Edition Bible

Java 2 Micro Edition: Professional Developer's Guide