`
`JAVA.
`
`ECCLES SHAE
`
`A Desktop Quick Reference
`
`O’REILLY*
`
`David Flanagan
`
`Page 1 of 238
`
`GOOGLEEXHIBIT 1031
`
`Page 1 of 238
`
`GOOGLE EXHIBIT 1031
`
`

`

`ey
`THIRD EDITION
`
`SOTERAa
`
`JAVA 2/1.2 & 1.3
`
`FLANAGAN
`
`
`
`Page 2 of 238
`
`Page 2 of 238
`
`

`

`
`JAVA.
`
`BALELAE
`
`A Desktop Quick Reference
`
`Page 3 of 238
`
`Page 3 of 238
`
`

`

`THE
`JAVA.
`SERIES
`
`Exploring Java™
`Java” Threads
`
`Java” Network Programming
`
`Java™ Virtual Machine
`
`Java" AWT Reference
`
`Java” Language Reference
`
`Java™ Fundamental Classes Reference
`
`Database Programming with
`JDBC” and Java™
`
`Java™ Distributed Computing
`
`Developing Java Beans”
`Java™ Security
`Java™ Cryptography
`
`Java” Swing
`
`Java™ Servlet Programming
`
`Java" 1/0
`
`Java™ 2D Graphics
`Enterprise JavaBeans”
`
`Also from O'Reilly
`Java™ in a Nutshell
`
`Java™ in a Nutshell, Deluxe Edition
`
`Java™ Examples in a Nutshell
`
`Java™ Enterprise in a Nutshell
`
`Java™ Foundation Classes in a Nutshell
`Java” Power Reference: A Complete
`Searchable Resource on CD-ROM
`
`Page 4 of 238
`
`Page 4 of 238
`
`

`

`
`JAVA.
`
`IPESIRE
`
`A Deskiop Quick Reference
`
`Third Edition
`
`David Flanagan
`
`O’REILLY*
`
`Beijing «+ Cambridge + Farnbam: Kéin+ Paris + Sebastopol + Taipei + Tokyo
`
`Page 5 of 238
`
`Page 5 of 238
`
`

`

`Java™ in a Nutshell, Third Edition
`by David Flanagan
`
`Copyright © 1999, 1997, 1996 O'Reilly & Associates, Inc. All rights reserved.
`Printed in the United States of America
`
`Published by O’Reilly & Associates, Inc., 101 Morris Street, Sebastopol, CA 95472.
`
`Editor: Paula Ferguson
`
`Production Editor: Mary Anne Weeks Mayo
`
`Printing History:
`
`February 1996:
`
`First Edition.
`
`Second Edition.
`May 1997:
`November 1999: Third Edition.
`
`Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are
`registered trademarks and The Java™Series is a trademark of O'Reilly & Associates,
`Inc. The association of the imageof a Javan tiger with the topic ofJava is a trademark
`of O'Reilly & Associates, Inc. Java and all Java-based trademarks and logos are
`trademarks or registered trademarks of Sun Microsystems, Inc., in the United States
`and other countries. O’Reilly & Associates, Inc. is independent of Sun Microsystems.
`
`Manyof the designations used by manufacturers andsellers to distinguish their
`products are claimed as trademarks. Where those designations appear in this book,
`and O'Reilly & Associates, Inc. was aware of a trademark claim, the designations
`have been printed in caps orinitial caps.
`
`While every precaution has been taken in the preparation of this book, the publisher
`assumes no responsibility for errors or omissions, or for damages resulting from the
`use of the information contained herein.
`
`ISBN: 1-56592-487-8
`(Ml
`
`{2/00}
`
`Page 6 of 238
`
`Page 6 of 238
`
`

`

`Table of Contents
`
`PHOFACE oececeeecsccececeeveeneeenseveesssisenenssesserscsereassassnenssnsncessassessenseassneasenees xt
`
`Part I: IntroducingJava
`
`Chapter 1—Introduction w.ccceccceccsscecsscssssrsscsinevesvesssesnsevevecseesevenensens 3
`What IS Java? eiccccccccccsetecsssesstceescenapensessenspeseesegenesseanenenaeescceaeesaecesseesons 3
`Key Benefits Of Java ...ccccceccesscsecscssesseseesnessssceeseeecetesseseeersnseceeesesavereres 6
`An Example Program oo... ecscccccccsseeeseseeeerecccenseeeseaeenesntecssesaseegersaeaens 9
`
`Chapter 2—Java Syntaxfrom the Ground Up wocecccccee 19
`The Unicode Character Seto... iccccsessssserseccecrerneenerisesersiessrenreneserees 20
`COMMENIS oo cceeteeeeeteneeesttsaaeecstneeeeereseceeesesaeeeenesseneeesseeaseenens 20
`Identifiers and Reserved Words ooo. escccen rec eneerseecerettereiettsseesteeey 21
`
`Primitive Data TyP@S oo... ccssseseersecseerssescassesenseeceesssessssesreseness 22
`Expressions and Operators wii sccsscseenesesrseeecteseeesereesneriseeensensennees 29
`StaTEMENtS ooo ccc ceeeeeeceteeresssecseeceeaecererececeeeetaeecesesseepsestereneeseess 43
`Methods oo... eeeeceecceesessceeenesseeeveesseceneeseneeserssssseecaeettaneaesenterieetsneseseateae 59
`Classes and ODjeCtS oo ieee cieeneenneni srs 61
`Array TYP@S c.cccsessecesssscsecsssrsesccsensessetansceevsssevessansessasaeensevsccrsssaseesarets 64
`Reference Types oo... cccsccesesceseneecessernteseenerssceecevsetseenteeassnesscenegneneares 70
`Packages and the Java Namespace .......ccccccccccsscsessceeeeeessereseeeseeseneenes 76
`Java File Structure ooo. ccccscccccscesceneectesescersreaesensenneeneenettennectieneesnttass 78
`Defining and Running Java Programs ese cscs teeterrectsesenasnenans 79
`Differences Between C and Java o..cccsscsscssssssscssescneeseestersssssteeeeeeeneees 80
`
`v
`
`Page 7 of 238
`
`Page 7 of 238
`
`

`

`Chapter 3— Object-Oriented Programming inJav@ oo... 82
`The Members of a Class 0. cccccccccssseceesenseseeseccetceesesenaseessseraecsessarens 82
`
`Creating and Initializing ODjects oo... cc cceeenseeeeeeeeeeesereeneeaenaes 88
`Destroying and Finalizing Objects 0... cee eee tee tees treseeeenes 92
`Subclasses and Inheritance cc ccsscsscsssesesssssssseesensssseessesrssesseeateeens 95
`Data Hiding and Encapsulation 1... cc cscceesseessccccseteeseeeetesteresesneens 104
`Abstract Classes and Methods oo... cc cccecsseesecsececeeenscseeseersneeseeeses 110
`Interfaces oo. ceecccccceccvseeesneeccnseccesesaeeeeceseeseneessvssssesessesseseeseeesseesssseasens 112
`Inner Class OVErViCW oo.ce cece cccccsteceeetssseteeenecnsecsesseeaecetseeaeersensenseeats 117
`Static Member Classes oo. cscccccccssesessenesseneenecesscseesssseeseeeeeesessseaenes 118
`
`Member Classes oo. ssessccesssesssersesneceneseesseeceesecnsccsseeesseesecsetaessessessaeens 119
`Local Classes ...cccccescesseceesecersssseseeseceestecsaeecenstssscsesesesacsneseesaersessceasennes 124
`
`ANONYMOUS Classes oo... cece cee eeeteeeee erste csc cceneseeeraeneriesenecnetaees 127
`How Inner Classes Work .0....0.ccccccccesesesectcectetesseseceseeeseecseensecsesenseceaes 130
`Modifier SUMUMALY oo. ssecsseeceteeesseeeeeecssseecsesevesesssseeessssesesssssenees 132
`C++ Features Not Found in Java ....ccccescssssscsssessessesssasescsrscsscssesesenes 135
`
`Chapter 4— TheJava PIAUOTM vaccines 136
`Java Platform Overview ........cccccecceseseseseesesessssecesesseseeessnensesesesseseaeseses 136
`Strings and Characters wicciccsccces ces recesses sseecetesenereeeceeseeees 138
`Numbers and Math occ cccccessccesenesensecrscssnesssseeeeseesseesesenesaes 140
`Dates and Times oo... cceeccecceesceneeneensersseeeseneesneeueseesteensenectsensessessees 143
`ATTAYS ooo ce ccc ccceseneceeee creer ese sseneceeceneeasetaesscsecsesaseecseveeseenerasieeneesenesaeee 144
`Collections occ ccececesecceeeeesceseeseeesseeseeeeesseeeesessesesenecsesesssssevseeseeesaeets 145
`Types, Reflection, and Dynamic Loading oo... cece rece rseeeseeeeeeees 147
`Threads oc scccseesesescssessssscceseseessseeesentersetssessesesterssseeerssecasnssesenseesas 149
`Files and Directories 0... i cceseseeseeseesscsecceeaeseeeueesssneersessssessessessees 153
`Input and Output Streams oo. eee eeetsceectevessecsesseeseesesensaeess 154
`Netovorking oo. ee eee cece eeceenenecstaesscsseceseaenceesesaenenssisnenssataeeenetecs 158
`PLOCESSES .eceseceseecesenceesseerseseseressenesteesevecssascavaesseesessesessssssssasaeaeeaeaeecs 161
`SOCUTILY osc ccieccsecsseeeessstetecseseeesseecarsesssneussaeseasscaecasassssscsssssseseasenvenees 161
`Cryptography occ ececccsesccsseseceseseassesssssssseseesteneesescessrsesersecneaeacseecses 163
`
`Chapter 5—JAVA SCCULIY iciicccsrersrseeessessssssssesssssessstssenes 166
`Security Risks oo. cscescscccecseseeseveeetescssesceeeeeeaeeeeeeneesessesssseassensesenes 166
`Java VM Security and Class File Verification o.cccccccccccsseesceeeeee 167
`Authentication and Cryptography occ scceesseccteneecssecteneetesenseees 168
`ACCESS COMO] oo ceceeceseeeeeesetsetscesssauecseeseenecsesssecassseesecaueseessenes 168
`Security for Everyome oo. cece eeneeeeeeecneeseecseseaetensesesesarseaes 171
`Permission Classes wo... cccseccsssceseeserseeecnesseeseessseesessssseseseseeseesesseeasees 173
`
`
`ui
`
`Page 8 of 238
`
`Page 8 of 238
`
`

`

`Chapter O—JAVABCANS oceeccscccciisiseiissir sien erstissessssseeneenitens 178
`Bean Basics ....ccccccccccccccccccceeesssscssseeeeseeeeceeeeseeeeeeeeeseessseseseeeaceeesueenseces 179
`JavaBeans Conventions i.e sesrsrsseeetrseenareia 181
`Bean Contexts and Services oo... cccccccccccssseccessnereccersssesecessneeeeeesasesese 187
`
`Chapter 7—Java Programming and Documentation °
`CONVENTIONS cece rrr etic nn rer reninereneneseeeeereetieets 189
`
`Naming and Capitalization Conventions 0.0.0... centres 189
`Portability Conventions and Pure Java Rules ..ccccisceeeeeereres 190
`Java Documentation COMMENES 0.0... cccseeceeeeeete reese ssestneansenerees 192
`
`Chapter 8—Java Development TOUS ooo ccsicccetesesssesesee 200
`APPletVICWEoo. ccc rere cedteneansenenessnrsnccseseeseeeenaasaesannas 200
`OXtCHECK cece neers reneeneneeecieeec seceneeisrenerectelasiiiseeiacenaseenesenecet 204 —
`JOT eee ceccecceeseceeenteearsserseessseseseatecesserecceaceessstesseseeerscstecntoneesneeneeneeneees 204
`JAPSIQMET eee eee ce nesceeeeeeneeetereteveeseseseesarereesentacieestesenssseenscseesseneeriey 206
`JAVA eee ee cece erie etree seater errr re cn dc neat eea Stee eee coir snes ends ones eeenegee 208
`JAVA ic ceeeee ee nee erie ereseeeesresiecereieiseenansnsesnenessesseesaenmnnsennaneeries 214
`JAVACOC .iccscccssscsccrserersectsstesessssssenreersseeeccdenseeeenseesestecrisecesseeaneeeeseenetes 217
`JAVAD ices esecctseerscssssecaesessersesevsesseeecneserteteuseesessassessieecsenassasaseanegs 221
`JAVAKCY escccesvecsessessvsesssevsessesaevescsncsunnesssesseneseseseeenesseessessecseesseneeeeenaesaee® 223
`JAVAD oe cece eee ere c ee cree nee nn ee errr ern REE E EERIE ene OL Econ a eaeeeeee eee 225
`JAD ioc ceecsseseessssssesesesssssesssssumssssssstinseessssusesesssssnsnscessnisecsssvaeseessennseensins 227
`KeYtOO] occ cree cece neers sci resenseneseeeeeneesereenseesneneesesens 231
`NALIVEZASCH oo ccececcce cee cee rerecsereeeereseceenieseneseenecresrensciesseseneenneriaeees 234
`POLICYIOO] os eeecceteeesteeescsteveeseceeecneseseetdsaseesensensctesiesscieseeeeenensaneeeeyy 235
`SOLHALVEL occ cceccccecceceeeses ses ssnsceseesevsensecsscsessseesecsessessecscensesseseseseenensenaneas 236
`
`Part If: API Quick Reference
`
`How To Use This Quick Reference ccc 239
`
`Chapter 9— TheJava. DEANS PACRAQE viiciiisicciseeessse 248
`
`Chapter 10— The java.beans.beancontext PACRAE......0000.. 264
`¢
`
`Page 9 of 238
`
`oti
`
`Page 9 of 238
`
`

`

`Chapter 11— The fava.i0 PACRAQC vies 280
`
`Chapter 12— The fava lang PACRASC wccececccccecceteeesiee 328
`
`Chapter 13— The java. lang.refPACRARC oo... 377
`
`Chapter 14— The java.lang.reflect PACRAQE ieee 381
`
`Chapter 15— The java. math PACRAQC wives 391
`
`Chapter 16— Thejava.net PACRAQC .o.ieciecceciceseitieteeieee 395
`
`Chapter 17— Thejava.security PACRAC veces 418
`
`Chapter 18— Thejava.security.acl PACRAQE voces 453
`
`Chapter 19— The java.security.cert PACRAZE i.e 457
`
`Chapter 20— Thejava.security.interfaces PACRAGE «0.0... 466
`
`Chapter 21— Thejava.security.SspeC PACRAZE wcrc 470
`
`Chapter 22— Thejava text PACRAQC weer 476
`
`Chapter 23— Thejava. Util PACRAQC .o.ceececcecccctcesetersetetseneeees 497
`
`Chapter 24— Thejava.utiljar PACRASC wien 544
`
`Chapter 25— Thejava.util.zip PACRAQO weet: 550
`
`Chapter 26— Thejavax.crypto PACRAQE wees 561
`
`Chapter 27— Thejavax.crypto.interfaces PACRAQE 1.0.0.4. 576
`
`
`viii
`
`Page 10 of 238
`
`Page 10 of 238
`
`

`

`Chapter 28— Thejavax.crypto.sp@C PACRAQO wieecececceee 578
`
`Chapter 29— Class, Method, and Field Index occ. 584
`
`TVWOK occ ccccccccceceveeeceseseeesescecsesssessvecsessetstsecstacsessasssasscsesciesecseassestsesees 615
`
`
`ix
`
`Page 11 of 238
`
`Page 11 of 238
`
`

`

`
`
`Preface
`
`This book is a desktop quick reference for Java™ programmers, designed to sit
`faithfully by your keyboard while you program. Part I of the book is a fast-paced,
`“no-fluff introduction to the Java programming language and the core APIs of the
`Java platform. Part II is a quick-reference section that succinctly details every class
`and interface of those core APIs. The book covers Versions 1.0, 1.1, 1.2, and 1.3
`beta of Java.
`
`Changes Since the Second Edition
`Readers who are familiar with the second edition of this book will notice a num-
`ber of changes in this edition. Most notably,
`the AWT and applet APIs are no
`longer documented in this book. The Java platform tripled in size between Java
`1.1 and Java 1.2. Accordingly, and unavoidably, java in a Nutshell has been split
`into three volumes. The volume you are now reading documents only the essen-
`tial APIs of the platform, including the basic language andutility classes, as well as
`classes for input/output, networking, and security. See the Table of Contents for a
`complete list of the packages documented here.
`
`If you are a client-side programmer who is working with graphics or graphical
`user interfaces, you will probably want to supplement this book with Java Foun-
`dation Classes in a Nutshell, which documents all the graphics- and GUlI-related
`classes, including the AWT, Swing, Java 2D, and applet APIs. And, if you are an
`server-side or enterprise programmer, you will likely be interested in Java Enier-
`prise in a Nutshell.
`
`Another big change is that Part I of this book has been almost entirely rewritten.
`Thefirst and second editions of this book assumed knowledge of and experience
`with C or C++. Now that Java has come thoroughly into its own, that assumption
`no longer seems appropriate, so I have rewritten and expanded Chapters 2 and 3
`to explain Java without any reference to C, C++, or any other programming lan-
`guage. Programmers with a modest amount of experience should now be able to
`learn Java programming from this book. These introductory chapters are written in
`
`Page 12 of 238
`
`Page 12 of 238
`
`

`

`a tight, concise style, so programmers who already know Java should find them
`useful as a language reference.
`
`Another new feature of Part I is Chapter 4, The Java Platform. This chapter is an
`introduction to the APIs documented in the reference section of the book.
`It
`includes more than 60 detailed API usage examples that show how to accomplish
`common tasks with the predefined classes of the Java platform.
`
`Finally, the quick-reference section in Part II of the book has a new look that dra-
`matically improves the readability of the reference material and packs even more
`API information into a small space. Even if you are already familiar with the sec-
`ond edition, you should take the time to read the How To Use This Quick Reference
`section at the beginning of Part I; it explains the new quick-reference format and
`shows you how to get the most outofit.
`
`Contents of This Book
`
`The first eight chapters of this book document the Java language, the Java plat-
`form, and the Java developmenttools that are supplied with Sun’s Java SDK (soft-
`ware development kit):
`
`Chapter 1: Introduction
`This chapter is an overview of the Java language and the Java platform that
`explains the important features and benefits of Java.
`It concludes with an
`example Java program and walks the new Java programmerthroughit line by
`line.
`
`Chapter 2: Java Syntax From the Ground Up
`This chapter explains the details of the Java programming language. It is a
`long and detailed chapter. Experienced Java programmers can use it as a lan-
`guage reference. Programmers with substantial experience with languages
`such as C and C++ should be able to pick up Java syntax by reading this
`chapter. The chapter does not assume years of programming experience, or
`even familiarity, with C or C++, however. Even beginning programmers, with
`only modest experience, should be able to learn Java programming by study-
`ing this chapter carefully.
`
`Chapter 3: Object-Oriented Programming in Java
`This chapter describes how the basic Java syntax documented in Chapter 2 is
`used to write object-oriented programs in Java. The chapter assumes no prior
`experience with OO programming. It can be used as a tutorial by new pro-
`grammers or as a reference by experienced Java programmers.
`
`Chapter 4: TheJava Platform
`This chapter is an overview of the essential Java APIs covered in this book.It
`contains numerous short examples that demonstrate how to perform common
`tasks with the classes and interfaces that comprise the Java platform. Program-
`mers who are new to Java, and especially those who learn best by example,
`should find this a valuable chapter.
`
`
`
`xii Preface
`
`Page 13 of 238
`
`Page 13 of 238
`
`

`

`Chapter 5: Java Security
`This chapter explains the Java security architecture that allows untrusted code
`to run in a secure environment from which it cannot do any malicious dam-
`age to the host system. It is important for all Java programmers to have at
`least a passing familiarity with Java security mechanisms.
`
`Chapter 6: JavaBeans
`This chapter documents the JavaBeans™ component framework and explains
`what programmers need to know to create and use the reusable, embeddable
`Java classes knownas beans.
`
`Chapter 7: Java Programming and Documentation Conventions
`This chapter documents important and widely adopted Java programming
`conventions and also explains how you can make your Java code self-docu-
`menting by including specially formatted documentation comments.
`
`Chapter 8: Java Development Tools
`The Java SDK shipped by Sun includes a numberof useful Java development
`tools, most notably the Java interpreter and the Java compiler. This chapter
`documents thosetools.
`
`These first eight chapters teach you the Java language and get you up and running
`with the Java APIs. The bulk of the book, however, is the API quick reference,
`Chapters 9 through 29, which is a succinct but detailed API reference formatted for
`optimum ease of use. Please be sure to read the How To Use This Quick Reference
`section, which appears at the beginning of the reference section; it explains how
`to get the most out of this section.
`
`Related Books
`O'Reilly & Associates, Inc, publishes an entire series of books on Java program-
`ming. These books include Java Foundation Classes in a Nutshell and Java Enter-
`prise in a Nutshell, which, as mentioned earlier, are companions to this book.
`
`A related reference work is the Java Power Reference. It is an electronic Java quick
`reference on CD-ROM that uses the java in a Nutshell style. But since it
`is
`designed for viewing in a web browser,it is fully hyperlinked and includes a pow-
`erful search engine. It is wider in scope but narrower in depth than the Java in a
`Nutshell books. The Java Power Reference covers all the APIs of the Java 2 plat-
`form, plus the APIs of many standard extensions. But it does not include tutorial
`chapters on the various APIs, nor does it include descriptions of the individual
`classes.
`
`You can find a complete list of Java books from O'Reilly & Associates at
`http.//jjava.oreilly.com/, Books that focus on the core Java APIs, as this one does,
`include:
`
`ExploringJava, by Pat Niemeyer and Joshua Peck
`A comprehensive tutorial introduction to Java, with an emphasis on client-side
`Java programming.
`
`
`
`Preface xiii
`
`Page 14 of 238
`
`Page 14 of 238
`
`

`

`Java Threads, by Scott Oaks and Henry Wong
`Java makes multithreaded programming easy, but doing it right canstill be
`tricky. This book explains everything you need to know.
`
`Java I/O, by Elliotte Rusty Harold
`Java’s stream-based input/output architecture is a thing of beauty. This book
`coversit in the detail it deserves.
`
`Java Network Programming, by Elliotte Rusty Harold
`This book documents the Java networking APIs in detail.
`
`Java Security, by Scott Oaks
`This book explains the Java access-control mechanismsin detail and also doc-
`uments the authentication mechanisms of digital signatures and message
`digests.
`
`Java Cryptography, by Jonathan Knudsen
`Thorough coverage of the Java Cryptography Extension, the javax.crypto.*
`packages, and everything you need to know aboutcryptographyin Java.
`
`DevelopingJava Beans, by Robert Englander
`A complete guide to writing components that work with the JavaBeans API.
`
`‘Java Programming Resources Online
`This book is a quick reference designed for speedy access to frequently needed
`information. It does not, and cannot, tell you everything you need to know about
`Java. In addition to the bookslisted earlier, there are several valuable (and free)
`electronic sources of information about Java programming,
`
`Sun’s main web site for all things related to Java is bitp:/fava.sun.com/. The web
`site specifically for Java developers is bttp.//developerjava.sun.com/ Much of the
`content on this developer site is password-protected, and access to it requires
`(free) registration.
`
`Sun distributes electronic documentation for all Java classes and methods in its
`javadoc HTML format. Although this documentation is somewhat difficult to navi-
`gate and is rough or outdated in places, it is still an excellent starting point when
`you need to know more about a particular Java package, class, method, or field. If
`you do not already have the javadoc files with your Java distribution, see
`bitp://java.sun.com/docs/ for a link to the latest available version. Sun also dis-
`tributes its excellent Java Tutorial online. You can browse and download it from
`http:/Hava.sun.com/docs/books/tutoriay.
`For Usenet discussion (in English) about Java, try the comp.langjava.programmer
`and related comp.langjava.* newsgroups. You can find the very comprehensive
`comp.langjava programmer FAQ by Peter van der Linden at bitp:/Avww.afu.com/
`javafag.btm.
`
`Finally, don’t forget O’Reilly’s Java web site. bitp:/4ava.oreilly.com/ contains Java
`news and commentary and a monthly tips-and-tricks column by O'Reilly Java
`author Jonathan Knudsen.
`
`
`
`xiv Preface
`
`Page 15 of 238
`
`Page 15 of 238
`
`

`

`
`
`Examples Online
`The examples in this book are available online and can be downloaded from the
`home page for the book at htip://www.oreilly.com/catalog/javanut3. You also may
`want to visit this site to see if any important notes or errata about the book have
`been published there.
`
`Conventions Used in This Book
`
`We use the following formatting conventions in this book:
`
`Italic
`
`Used for emphasis and to signify the first use of a term. Italic is also used for
`commands, email addresses, web sites, FIP sites, file and directory names,
`and newsgroups.
`
`Bold
`
`Occasionally used to refer to particular keys on a computer keyboard or to
`portions of a user interface, such as the Back button or the Options menu.
`Letter Gothic
`
`Used in all Java code and generally for anything that you would type literally
`when programming,
`including keywords, data types, constants, method
`names, variables, class names, and interface names.
`
`Letter Gothic Oblique
`Used for the names of function arguments and generally as a placeholder to
`indicate an item that should be replaced with an actual value in your pro-
`gram.
`
`Franklin, Gothic Book Condensed
`Used for the Java class synopses in the quick-reference section. This very nar-
`row font allows us to fit a lot of information on the page without a lot of dis-
`tracting line breaks. This font is also used for code entities in the descriptions
`in the quick-reference section.
`Franklin Gothic Demi Condensed
`Used for highlighting class, method,field, property, and constructor names in
`the quick-reference section, which makesit easier to scan the class synopses.
`
`Franklin Gothie Book CompressedItalic
`Used for method parameter names and comments in the quick-reference sec-
`tion.
`
`Requestfor Comments
`
`Please help us improve future editions of this book by reporting any errors, inac-
`curacies, bugs, misleading or confusing statements, and even plain old typos that
`you find. Please also let us know what we can do to make this book more useful
`to you. We take your comments seriously and will try to incorporate reasonable
`suggestions into future editions. You can contact us by writing:
`
`
`
`Preface xv
`
`Page 16 of 238
`
`Page 16 of 238
`
`

`

`O'Reilly & Associates, Inc.
`101 Morris Street
`Sebastopol, CA 95472
`1-800-998-9938 (in the United States or Canada)
`1-707-829-0515 (Cinternational/local)
`1-707-829-0104 (fax)
`
`You can also send us messages electronically. To be put on the mailing list or
`request a catalog, send emailto:
`
`info@oreilly.com
`
`To ask technical questions or comment on the book, send email to:
`
`bookquestions@oreilly.com
`
`We have a website for the book, where we'll list examples, errata, and any plans
`for future editions. You can access this pageat:
`
`bttp:/Avww.oreilly.com/catalogjavanut3/
`
`For more information about this book and others, see the O’Reilly website:
`
`http:/Avww.oreilly.com
`
`How the Quick Reference Is Generated
`
`For the nerdy or merely inquisitive reader, this section explains a bit about how
`the quick-reference material in Java in a Nutshell and related booksis created.
`
`As Java has evolved, so has my system for generating Java quick-reference mate-
`rial. The current system is part of a larger commercial documentation browser sys-
`tem I’m developing
`(visit
`bttp:/Avww.davidflanagan.com/Jude/
`for more
`information aboutit). The program works in two passes: the first pass collects and
`organizes the API information, and the second pass outputs that information in the
`form of quick-reference chapters.
`
`Thefirst pass begins by reading the class files for all of the classes and interfaces
`to be documented. Almost all of the API information in the quick reference is
`available in these class files. The notable exception is the names of method argu-
`ments, which are not stored in class files. These argument names are obtained by
`parsing the Java source file for each class and interface. Where source files are not
`available,
`I obtain method argument names by parsing the API documentation
`generated by javadoc. The parsers I use to extract API information from the source
`files and javadocfiles are created using the Antlr parser generator developed by
`Terrence Parr of the Magelang Institute. (See biip:/Avww.antlr.org/ for details on
`this very powerful programmingtool.)
`
`Once the API information has been obtained by reading class files, source files,
`and javadoc files, the program spends some time sorting and cross-referencing
`everything. Then it stores all the API information into a single large data file.
`
`The second pass reads API information from that data file and outputs quick-refer-
`ence chapters using a custom SGML format. The SGML markupis fairly complex,
`but the code that generates it is quite mundane. Once I’ve generated the SGML
`
`xui Preface
`
`Page 17 of 238
`
`Page 17 of 238
`
`

`

`output, I hand it off to the production team at O’Reilly & Associates. They process
`it and convert it to troff source code. The troff source is processed with the GNU
`groff program Cfip://fip.gnu.org/gnu/grof/) and a custom set of troff macros to
`produce PostScript outputthat is shipped directly to the printer.
`
`Acknowledgments
`
`Manypeople helped in the creation of this book, and I am grateful to them all. I
`am indebted to the many, many readers of the first two editions who wrote in
`with comments, suggestions, bug reports, and praise. Their many small contribu-
`tions are scattered throughout the book. Also, my apologies to those who made
`the many good suggestions that could not be incorporated into this edition.
`
`Paula Ferguson, a friend and colleague, has been the editorof all three editions of
`this book. Her careful reading and always-practical suggestions have made the
`book stronger, clearer, and more useful. She guided the evolution of Java in a
`Nutshell from a single book into a three-volumeseries and, at times, juggled edit-
`ing tasks for all three books at once. Finally, Paula went above and beyond the
`call of editorial duty by designing the hierarchy diagrams foundat thestart of each
`reference chapter.
`
`Mike Loukides provided high-level direction and guidance for the first edition of
`the book. Eric Raymond and Troy Downing reviewed that first edition—they
`helped spot my errors and omissions and offered good advice on making the
`book more useful to Java programmers.
`
`For the second edition, John Zukowski reviewed my Java 1.1 AWT quick-reference
`material, and George Reese reviewed most of the remaining new material. The
`second edition was also blessed with a “dream team” of technical reviewers from
`Sun. John Rose, the author of the Java inner class specification, reviewed the chap-
`ter on inner classes. Mark Reinhold, author of the new character stream classes in
`java.io, reviewed my documentation of these classes. Nakul Saraiya, the designer
`of
`the new Java Reflection API,
`reviewed my documentation
`of
`the
`java.lang.reflect package. ] am very grateful to these engineers and architects;
`their efforts made this a stronger, more accurate book.
`
`The third edition also benefited greatly from the contributions of reviewers who
`are intimately familiar with the Java platform. Joshua Bloch, one of the primary
`authors of the Java collections framework, reviewed my descriptions of the collec-
`tions classes and interfaces. Joshua was also helpful in discussing the Timer and
`TimerTask classes of Java
`1.3 with me. Mark Reinhold,
`creator of
`the
`java.lang.ref package, explained the package to me and reviewed my documen-
`tation of it. Scott Oaks reviewed my descriptions of the Java security and cryptog-
`raphy classes and interfaces. Joshua, Mark, and Scott are all engineers with Sun
`Microsystems, and I’m very grateful for their time. The documentation of the
`javax.crypto package and its subpackages was also reviewed by Jon Eaves. Jon
`worked on a clean-room implementation of the Java Cryptography Extension
`(which is available from bitp./Avww.aba.net.au/), and his comments were quite
`helpful. Jon now works for Fluent Technologies (hitp:/Avww,fluent.com.au/) con-
`sulting in Java and electronic commerce. Finally, Chapter 1 was improved by the
`comments of reviewers who were not already familiar with the Java platform:
`
`Preface xvii
`
`Page 18 of 238
`
`Page 18 of 238
`
`

`

`Christina Byrne reviewed it from the standpoint of a novice programmer, and
`Judita Byrne of Virginia Power offered her comments as a professional COBOL
`programmer.
`
`The O'Reilly & Associates production team has doneits usual fine work of creating
`a book out of the electronic files I submit. My thanks to them all. And a special
`thanks to Lenny Muellner and Chris Maden, who worked overtime to implement
`the new and improved format of the quick-reference section.
`
`As always, my thanks andlove to Christie.
`
`David Flanagan
`bttp://jwww.davidflanagan.com/
`September 1999
`
`xviii Preface
`
`Page 19 of 238
`
`Page 19 of 238
`
`

`

`PART I
`
`IntroducingJava
`
`Part I is an introduction to the Java language and the Java platform. These
`chapters provide enough information for you to get started using Java
`right away.
`
`Chapter 1, Introduction
`Chapter 2, Java Syntax From the Ground Up
`Chapter 3, Object-Oriented Programming in Java
`Chapter 4, TheJava Platform
`Chapter 5, Java Security
`Chapter 6, JavaBeans
`Chapter 7, Java Programming and Documentation Conventions
`Chapter 8, Java Development Tools
`
`Page 20 of 238
`
`Page 20 of 238
`
`

`

`=ai35S3
`
`
`
`CHAPTER1
`
`Introduction
`
`Welcome to Java. Since its introduction in late 1995, the Java language and plat-
`form have taken the programming world by storm. This chapter begins by explain-
`ing what Java is and why it has become so popular. Then, as a tutorial
`introduction to the language, it walks you through a simple Java program you can
`type in, compile, and run.
`
`WhatIsJava?
`
`it is important to distinguish between the Java programming
`In discussing Java,
`language, the Java Virtual Machine, and the Java platform. The Java programming
`language is the language in which Java applications (including applets, servlets,
`and JavaBeans components) are written. When a Java program is compiled, it is
`converted to byte codes that are the portable machine language of a CPU architec-
`ture known as the Java Virtual Machine(also called the Java VM or JVM). The JVM
`can be implemented directly in hardware, but it
`is usually implemented in the
`form of a software program that interprets and executes byte codes.
`
`The Java platform is distinct from both the Java language and Java VM. The Java
`platform is the predefined set of Java classes that exist on every Java installation;
`these classes are available for use by all Java programs. The Java platform is also
`sometimes referred to as the Java runtime environment or the core Java APIs
`(application programming interfaces). The Java platform can be extended with
`optional] standard extensions. These extension APIs exist in some Javainstallations,
`but are not guaranteed to exist in all installations.
`
`The Java Programming Language
`
`The Java programming languageis a state-of-the-art, object-oriented language that
`has a syntax similar to that of C. The language designers strove to make the Java
`language powerful, but, at the same time, they tried to avoid the overly complex
`features that have bogged down other object-oriented languages, such as C++. By
`keeping the