The Java Class Libraries: An Annotated Reference (Java Series)

This example-driven, annotated reference guide to the Java class libraries from two leading Java developers is an essential resource for both beginner and experienced Java programmers.
You will find complete and detailed coverage of all the class libraries, including the Core Packages (java.io, java net, java.util, and java.lang) as well as the Window Toolkit and Applet packages (java.awt, java.awt.image, java.awt.peer, and java.applet), including more than 600 examples and more than 20,000 lines of code. The book has been specifically designed to make it possible to find information on any class or member quickly and easily. Each class description includes a class hierarchy diagram showing its connection to related classes, a detailed overview describing its purpose and key concepts, a convenient member summary which briefly describes each member and arranges the members into related groups, an example demonstrating the class in a "real-world" context, and comprehensive descriptions and examples for each of its members.

PREFACE
How to Use This Book
This book is intended as a reference rather than a tutorial. Its structure is designed to optimize the time it takes for you to look up a class or class member. This book does not explain any part of the Java language. There are several books that you can use to learn the language. The Java(tm) Programming Language, by Ken Arnold and James Gosling, and The Java(tm) Language Specification, by James Gosling, Bill Joy, and Guy Steele are good sources of material for learning the language.

Part I: Java Package Overviews
These chapters briefly describe each package and all the classes that appear in them. Also included are diagrams that show the inheritance hierarchy of the classes that appear in a package.

Part II: Alphabetical Reference to the Java Class Libraries
These chapters cover the alphabetical listing of the classes. Probably the most notable aspect about the structure of this book is the order in which the classes appear. Most other Java books that contain an API alphabetically order the classes within a package and then alphabetically order the packages. The problem with this format is that it always takes two or more steps to locate a class. If you do not know the package, you basically need to go through each of the eight packages looking for the class. If you do know the package, you first need to find the package and then find the class. Even if an index were available for all the classes, you first need to locate the index and then locate the class. The classes in this book are ordered alphabetically without regard to package name. This makes looking up a class as straightforward as looking up a word in a dictionary. Each class is described in its own chapter. Each chapter contains a class description, a picture of the class hierarchy, a class example, a member summary, and descriptions for every member in the class.

Class Descriptions
In the class descriptions, we describe all the properties of the class. For example, the properties of the Graphics class includes the current color, font, paint mode, origin, and clipping rectangle. Describing in one place all of a class's available properties and how the properties behave rather than scattering the property descriptions throughout the member descriptions makes learning all the capabilities of a class much easier. Any terminology used in the member descriptions is introduced and described in the class descriptions. If you find that the description for a member is lacking in detail, go to the class description for more information.

Class Hierarchy Diagrams

A class diagram appears for each class in the Java API. The class diagram shows all the ancestors of the class, its siblings, its immediate descendents, and any interfaces that the class implements. In these diagrams, if a package name precedes a class or interface name, the class or interface is not in the same package as the current class. In the diagrams, we visually distinguish only three kinds of Java entities:

1. The class
2. The abstract class
3. The interface

The mnemonic we use to represent the entities is based on how much of the entity is implemented. For example, in a class all the methods are implemented, so a class appears "full." In an abstract class, one or more methods have not been implemented, so an abstract class appears "partially full." Finally, an interface does not have any methods implemented (only method signatures), so the interface appears "empty."

Examples
Ideally we would have liked to include a unique example for every single member in the Java API. We simply did not have enough time. So we tried to make sure that every member appeared in at least one example. We worked to make the examples as useful as possible so that they demonstrate the member as it would typically be used. For example, in the example for a button we not only show how a button is created; we also show how button events are handled. In some cases, we also try to demonstrate some other class in the Java API. For example, in the Graphics.draw-Oval() example, we not only demonstrate how to draw an oval. We also demonstrate how to use the DataInputStream class to read integers from standard input that are used to locate the ovals. As long as the introduction does not confuse the example, we feel that gently introducing other classes in the Java API is a good way to help you become aware of all available classes in the Java API. The names and structures of most of the examples are the same mainly to make approaching an example easier. As you read more examples, you will become used to the structure and it will become one less thing on which you have to put your attention.

Member Summary
The Member Summary section for each class is to help you when you approach an unfamiliar class. It groups the members of the class into categories that are specific to that class. For example, in the List class the Selection Methods category lists all methods having to do with selections. It is meant to be a quick summary of the class's members, so it does not contain any syntax information other than the name of the method.

Member Descriptions
The member descriptions appear in alphabetical order within a class chapter regardless of what kind of method or field they are. Again, this was done to make locating a member proceed as fast as possible. Overloaded methods are placed together in one member description because they have very similar functionality. The different overloaded forms are typically provided as a convenience for the programmer when specifying parameters. For instance, some overloads eliminate parameters by providing common defaults. To describe overloads with missing parameters, we use a phrase of the form "if the parameter p is not specified, it defaults to the value 3.14." Other overloads take different representations of a value. For example, one overload could take a particular parameter as an integer, while another could take the same parameter as a string containing an integer. Each member description contains some or all of the following fields:

Purpose - A brief description of the purpose of this member
Syntax - The syntactic declaration of this member
Description -

A full description of this member
Parameters - The parameters accepted by this member, if any, listed in alphabetical order
Returns - The value returned by this member, if any
Exceptions - The exceptions and errors thrown by this member, if any, listed in alphabetical order
See Also - Other related classes or members, if any, listed in alphabetical order
Overrides - The method that this member overrides, if any
Example - A code example that illustrates how this member is used. This is sometimes a reference to an example that illustrates the use of this method in another member example or class example.

Conventions Used in This Book
Lucida Sans Typewriter is used for examples, syntax declarations, class names, method names, and field names. Italics is used when defining a new term and for emphasis.

Acknowledgments
We want to thank the many people who made this book possible. Mike Hendrickson, the Acquisition Editor for this book, coordinated the project and, more important, sustained our spirits as the months progressed. Lisa Friendly, as Series Editor, got this project started and believed in us every step of the way. Katie Duffy, Simone Payment, Avanda Peters, Laura Michaels, and Marty Rabinowitz assisted in the production of this book, from coordination with the reviewers, to creating figures and class hierarchy diagrams, to polishing the book's format. Despite the daunting size of this book, Tom Wrensch and Maurice Fitzgerald II gave thorough reviews. Other reviewers who gave useful feedback include Kevin Kluge, Doug Kramer, Bhavesh Mehta, James Robins, and Roland Schemers. Jayashree Vasudevan was tremendously helpful in assisting us with formatting early drafts of this book. Most important, thanks to all of Patrick's fellow Java team members for the wonderful friendships and the incredible journey. And finally, we can't forget our 3 and 5 year olds, Melissa and Kevin, who patiently endured our "Not now's" and stayed home with us, weekend after weekend, while we typed and typed and typed for 6 months. What are we all going to do now that we've published our book? Why, we're going to Disneyland, of course!

Patrick Chan
Rosanna Lee
June, 1996