Continuing the successful format of The Java Class Libraries, the supplement contains descriptions of the new pacakges and classes introduced in the Javao 2 Platform, Standard Edition, version 1.2. It also provides details on how the classes and methods have changed from JDKo 1.1. Together, this supplement and The Java Class Libraries, Second Edition, Volume 1, provide a complete reference to the following packages: java.io, java.lang, java.lang.ref, java.lang.reflect, java.math, java.net, java.text, java.util, java.util.jar, and java.util.zip.
The extensive class and member descriptions contain details crucial for developing robust and professional applets and applications. Each description is supplemented by an example that demonstrates the class or member in a relevant context. Numerous examples facilitate learning-by-example and provide useful code for your projects. The information is presented in an easy-to-use, dictionary-like format. Each class description includes:
ALPHABETICAL REFERENCE OF CLASSES.AbstractCollection.
This book is a companion to The Java Class Libraries, Second Edition, Volume 1. It contains descriptions of the new packages and classes in the Java™ 2 Platform, Standard Edition, Version 1.2. It also provides details of how the classes and methods have changed from the Java™ Developement Kit (JDK™) Version 1.1 to Version 1.2. It is important to understand that some of the material in this book is not complete and refers to material in The Java Class Libraries, Second Edition, Volume 1.
Like The Java Class Libraries, Second Edition, Volume 1. this book is intended as a reference rather than a tutorial. Its format is similar to a dictionary’s in that it is designed to optimize the time it takes for you to look up information about a class or class member. For a tutorial-style presentation of the class libraries, see The Java™ Tutorial by Mary Campione and Kathy Walrath. The Java™ Class Libraries does not explain any part of the Java language. There are several books you can use to learn the language. These include The Java™ Programming Language, by Ken Arnold and James Gosling, and The Java™ Language Specification, by James Gosling, Bill Joy, and Guy Steele.
Following is an overview of this book.
This part briefly describes each package and all of the classes in it. Also included are diagrams that show the inheritance hierarchy of the classes that appear in a package.
Each overview contains not only a general description about the package, but also descriptions of the changes in the package for Version 1.2. Each class that has been introduced in Version 1.2 is labeled with a tag. Each class that has been changed for Version 1.2 is labeled with a tag.
This part covers the alphabetical listing of the classes from the following packages:
java.io java.net java.lang java.text java.lang.ref java.util java.lang.reflect java.util.jar java.math java.util.zip
Only those classes that have been changed or added in Version 1.2 are included. Moreover, within the changed classes, only those members that have been changed or added are included. See the Table of Contents for a list of the classes and members in this book. For information about the classes that are changed, see The Java Class Libraries, Second Edition, Volume 1.
Like The Java Class Libraries, Second Edition, Volume 1, the classes are ordered alphabetically without regard to package name or version.
Each class is described in its own chapter. Each chapter contains a picture of the class hierarchy, a class description, a “Changes for Version 1.2” section for classes that have changed, a class example, a member summary, and descriptions for each member that is changed or new in Version 1.2. Chapters for classes that have changed (as opposed to those that were introduced in Version 1.2) have the label CHANGES FOR VERSION 1.2 in their footer.
Each chapter starts with a class diagram. The class diagram shows all of 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, the different kinds of Java entities are distinguished visually as follows:
Most of these elements are shown in Figure i. The class or interface being described in the current chapter is shaded grey. A solid line represents
extends, while a dotted line represents
In the class description, we describe all of the properties of the class. For example, the properties of the
Graphics class include the current color, font, paint mode, origin, and clipping area. Describing in one place all of a class's available properties and how the properties behave makes learning all of the capabilities of a class much easier than if the property descriptions were scattered throughout the member descriptions.
Any terminology used in the member descriptions is introduced and described in the class descriptions. If you find that the member description lacks detail, go to the class description for more information.
If the class is newly introduced in Version 1.2, its class description is complete. If the class is one that is changed in Version 1.2, the class description is only a summary of the class; the complete class description is in The Java Class Libraries, Second Edition, Volume 1.
If the class is one that is changed in Version 1.2, the chapter contains a “Changes for Version 1.2” section that describes the changes, including the new methods that have been added and how existing methods have changed.
Most of the chapters for new classes have a class example that illustrates how to use the class. Some of the chapters for the changed classes have a class example. For some of the changed classes, the changes are so minor that the class example in The Java Class Libraries, Second Edition, Volume 1 is still relevant.
The member summary is intended to help the reader quickly grasp the key points of the 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 member.
The member summary for both changed and new classes is complete. In a changed class, changed members are labeled with a tag, while new members are labeled with a tag. Only those members with one of these two tags are documented in the chapter. The documentation for unlabeled members in is The Java Class Libraries, Second Edition, Volume 1.
For example, following is the member summary for
In Version 1.2,
ZipInputStream has one new member,
createZipEntry(), and one changed member,
available(). The chapter for
ZipInputStream contains member descriptions for
available(). All other members of
ZipInputStream are described in The Java Class Libraries, Second Edition, Volume 1.
The member descriptions appear in alphabetical order within a class chapter regardless of what kind of method or field they are. This is done to make locating a member proceed as fast as possible.
Overloaded methods are placed together in one member description because they share 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.
In a changed class, each member heading is labeled with either a or a tag. indicates a member whose behavior has changed in Version 1.2. The changes might include an addition of an overloaded form, deprecation, or any other change in the semantics of the member. indicates that the member was introduced in Version 1.2. Following are examples of each tag.
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 and its range 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.|
If an overloaded form has been added to an existing member, the overloaded form has a SINCE 1.2 tag. For example, in Version 1.1 the
String class has a form of
compareTo() that accepts a
String parameter. In Version 1.2, the
String class has two overloaded forms of
compareTo(), one that accepts an
Object and one that accepts a
String.compareTo()’s syntax field looks as follows.
|SINCE 1.2|| |
A changed member, in addition to having its member heading labeled with a tag, always includes the following field.
1.2 CHANGES Description of the old behavior or what has changed in Version 1.2
A method or class is deprecated if its use is no longer recommended. A deprecated method appears in the Member Summary under the Deprecated Methods section. In the chapter body, the deprecated method is annotated by a “deprecated” tag in its method heading. For example,
Component.size() is a deprecated method. It has the following method heading.
If not all of the overloaded forms of the method are deprecated, a DEPRECATED tag appears beside the syntax of each deprecated form. For example, the second of the two forms of
BorderLayout.addLayoutComponent() is deprecated. This is indicated by the DEPRECATED tag, as follows.
The method description contains a deprecation section with instructions on how to replace the usage of the deprecated method, like this:
DEPRECATION A description of how to replace the usage of this deprecated method
All of the code examples in this book have been compiled and run on the FCS version of the Java™ 2SDK, Standard Edition, Version 1.2 (formerly "JDK™ 1.2") either on Solaris or Windows NT or both. Most of the complete examples are available on-line. You can access them and other information about this book at http://java.sun.com/books/Series.
Lucida Sans Typewriter is used for examples, syntax declarations, class names, method names, values, and field names. Italic is used when defining a new term and for emphasis.