Programming Wireless Devices with the Java™ 2 Platform, Micro Edition

J2ME™ Connected Limited Device Configuration (CLDC)

Mobile Information Device Profile (MIDP)

Roger Riggs Antero Taivalsaari Mark VandenBrink

Jim Holliday, Editor

ADDISON-WESLEY Boston • San Francisco • New York • Toronto • Montreal

London • Munich • Paris • Madrid Capetown • Sydney • Tokyo • Singapore • Mexico City

Contents

Figures xiii

Foreword xv

Preface xvii

Acknowledgments xxi

Introduction 1

1.1 The Wireless Internet Revolution 1 1.2 Why Java™ Technology for Wireless Devices? 2 1.3 A Bit of History 3 1.4 J2ME™ Standardization Efforts 4

Overview of Java 2 Platform, Micro Edition (J2ME™) 7

2.1 Java 2 Platform 7 2.2 Java 2 Platform, Micro Edition (J2ME) 8 2.3 Key Concepts of the J2ME Architecture 10

2.3.1 Profiles 12 2.3.2 Configurations 14

2.4 The K Virtual Machine (KVM) 16

Goals, Requirements, and Scope 19

3.1 High-Level Goals 19 3.1.1 Dynamic delivery of Java applications and content 20 3.1.2 Third-party application development 20 3.1.3 Independence of network technology standards 21 3.1.4 Compatibility with other wireless application standards. . . 22

3.2 Target Devices 22 3.3 General Notes on Consumer Devices and Embedded Systems 24 3.4 Requirements 26

3.4.1 Hardware requirements of CLDC 27

Vll

3.4.2 Hardware requirements of MIDP 28 3.4.3 Software requirements of CLDC 28 3.4.4 Software requirements of MIDP 29 3.4.5 J2ME requirements 30

3.5 Scope of the CLDC and MIDP Standardization Efforts 30 3.5.1 Scope of CLDC 30 3.5.2 Scope of MIDP 31

4 High-Level Architecture and Security 35

4.1 High-Level Architecture 35 4.2 Security 37

4.2.1 Low-level (virtual machine) security 38 4.2.2 Application-level security 39 4.2.3 End-to-end security 41

5 Connected Limited Device Configuration 43

5.1 CLDC Expert Group 44 5.2 CLDC Application Model 44

5.2.1 Architectural overview 44 5.2.2 The concept of a Java application 45 5.2.3 Application management 46

5.3 Java Language Specification Compatibility 47 5.3.1 No floating point support 47 5.3.2 No finalization 48 5.3.3 Error handling limitations 48

5.4 Java Virtual Machine Specification Compatibility 48 5.4.1 No floating point support 49 5.4.2 Other differences 50 5.4.3 Class file verification 53 5.4.4 Class file format and class loading 55

6 CLDC Libraries 59

6.1 Background and Goals 59 6.2 Classes Derived from J2SE 60

6.2.1 System classes 60 6.2.2 Data type classes 61 6.2.3 Collection classes 61 6.2.4 Input/output classes 61 6.2.5 Calendar and time classes 62 6.2.6 Additional classes 62

6.2.7 Exception and error classes 62 6.2.8 Internationalization support 63 6.2.9 Property support 64

6.3 CLDC-Specific Classes 65 6.3.1 Background and motivation 65 6.3.2 The Generic Connection framework 66 6.3.3 No network protocol implementations defined in CLDC . . 68 6.3.4 Design of the Generic Connection framework 68 6.3.5 Additional remarks 71 6.3.6 Sample code 71

7 Mobile Information Device Profile 79

7.1 MIDP Expert Group 80 7.2 Areas Covered by the MIDP Specification 80

8 MIDP Application Model 83

8.1 Limitations of the CLDC Application Model 83 8.2 MIDlets 85

8.2.1 MIDlet states 89 8.3 MIDlet Suites 92

8.3.1 MIDlet suite packaging 92 8.3.2 MIDlet suite execution environment 96

8.4 MIDP System Software 98 8.4.1 Application management functionality 98

9 MIDP User Interface Libraries 101

9.1 Structure of the MIDP User Interface API 102 9.1.1 Screen model 102 9.1.2 Low-level user interface 104 9.1.3 High-level user interface 104

9.2 Abstract Commands 105 9.2.1 Commands and command types 105 9.2.2 Command listeners 106

9.3 Interactions with MIDlet Application Lifecycle 106 9.4 Graphics and Canvas in the Low-Level API 107

9.4.1 Redrawing mechanism 108 9.4.2 Drawing model 108 9.4.3 Coordinate system 109 9.4.4 Clipping and translation 110 9.4.5 Color model 110

CONTENTS

9.4.6 Line styles I l l 9.4.7 Fonts I l l 9.4.8 Canvas visibility 112

9.5 Low-level API for Events in Canvases 112 9.5.1 Key events 112 9.5.2 Action keys 112 9.5.3 Pointer events 113

9.6 Graphics Drawing Primitives 113 9.6.1 Scaling to the Canvas 113 9.6.2 Drawing lines 114 9.6.3 Drawing and filling arcs 115 9.6.4 Drawing and filling rectangles 115 9.6.5 Drawing and filling rounded rectangles 116 9.6.6 Drawing text and images 117

9.7 Creating and Using Images 118 9.7.1 Mutable and immutable images 118 9.7.2 Drawing to a mutable image 119 9.7.3 Animation using images 119

9.8 Using Screens 124 9.8.1 List 124 9.8.2 TextBox 127 9.8.3 Alert 128 9.8.4 Ticker 129 9.8.5 Form 130

9.9 Using Items 130 9.9.1 Item 130 9.9.2 String and Stringltem 131 9.9.3 Image and Imageltem 131 9.9.4 TextField 131 9.9.5 DateField 132 9.9.6 ChoiceGroup 132 9.9.7 Gauge 133 9.9.8 ItemStateListener 133

9.10 A Note on Concurrency 133

10 MIDP Networking Libraries 135

10.1 Characteristics of Wireless Data Networks 135 10.2 Network Interface Considerations 136 10.3 The HttpConnection Interface 138

10.3.1 States of a network connection 138 10.3.2 Parsing URLs 139 10.3.3 Establishing a connection 140 10.3.4 HTTP request headers 140 10.3.5 Using an HTTP connection 141 10.3.6 HTTP response headers 143

10.4 Sample Code (NetClientMIDlet.java) 145

11 MIDP Persistence Libraries 157

11.1 The Record Management System 157 11.2 Manipulating Record Stores and Records 158

11.2.1 Manipulating a record store 159 11.2.2 Manipulating records in a record store 161 11.2.3 Converting record data to and from byte arrays 161 11.2.4 Filtering, comparing, listening and enumerating records .162

11.3 Sample Code (RMSMIDlet.java) 166

12 Additional MIDP APIs 177

12.1 Timer Support 177 12.1.1 Using one-shot timers 178 12.1.2 Using repeating timers 178 12.1.3 Sample code (TimerMIDlet.java) 179

12.2 System Properties 183

12.3 Application Resource Files 184 12.4 Exiting a MIDlet 184

13 Sample Applications 187

13.1 The PhotoAlbum Application 188 13.1.1 Class PhotoAlbum 190 13.1.2 Class PhotoFrame 195 13.1.3 Class Animation 205 13.1.4 Descriptor file PhotoAlbum.jad 210

13.2 The AddressBook Application 211 13.2.1 Class AddressBookMIDlet 211 13.2.2 Class SimpleRecord 225 13.2.3 Class SimpleFilter 227 13.2.4 Class SimpleComparator 229 13.2.5 Class NetworkQuery 231

13.3 The Sokoban Game Application 237 13.3.1 Class Sokoban 237

CONTENTS

13.3.2 Class SokoCanvas 241 13.3.3 Class Board 252 13.3.4 Class Score 259

13.4 Development Environments for J2ME 265

14 Summary 267

Appendix A: CLDC Application Programming Interface 271 Almanac Legend 274 java.lang 277 java.io 291 java.util 299 javax.microedition.io 305

Appendix B: MIDP Application Programming Interface 309 java.lang 311 java.util 313 javax.microedition.io 315 javax.microedition.lcdui 317 javax.microedition.midlet 329 javax.microedition.rms 331

Index 335