J

Using the Java API

Documentation
J.1 Introduction
The Java class library contains thousands of predefined classes and interfaces that program-
mers can use to write their own applications. These classes are grouped into packages based
on their functionality. For example, the classes and interfaces used for file processing are
grouped into the java.io package, and the classes and interfaces for networking applica-
tions are grouped into the java.net package. The Java API documentation lists the pub-
lic and protected members of each class and the public members of each interface in
the Java class library. The documentation overviews all the classes and interfaces, summa-
rizes their members (i.e., the fields, constructors and methods of classes, and the fields and
methods of interfaces) and provides detailed descriptions of each member. Most Java pro-
grammers rely on this documentation when writing programs. Normally, programmers
would search the API to find the following:
1. The package that contains a particular class or interface.
2. Relationships between a particular class or interface and other classes and inter-
faces.
3. Class or interface constants—normally declared as public static final fields.
4. Constructors to determine how an object of the class can be initialized.
5. The methods of a class to determine whether they are static or non-static, the
number and types of the arguments you need to pass, the return types and any
exceptions that might be thrown from the method.
In addition, programmers often rely on the documentation to discover classes and
interfaces that they have not used before. For this reason, we demonstrate the documenta-
tion with classes you know and classes you may not have studied yet. We show how to use
the documentation to locate the information you need to use a class or interface effectively.

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
XI Appendix J Using the Java API Documentation

J.2 Navigating the Java API

The Java API documentation can be downloaded to your local hard disk or viewed online.
To download the Java API documentation, go to java.sun.com/javase/6/download.jsp
and locate the DOWNLOAD link in the Java SE 6 Documentation section. You’ll be asked
to accept a license agreement. To do this, click Accept, then click Continue. Click the Ja-
va(TM) SE Development Kit Documentation 6 link to begin the download. After download-
ing the file, you can use a ZIP file-extraction program, such as WinZip (www.winzip.com),
to extract the files. If you are using Windows, extract the contents to your JDK’s installa-
tion directory. (See the Before You Begin section of this book for information on installing
Java.) To view the API documentation on your local hard disk in Microsoft Windows,
open C:\Program Files\Java\jdk1.6.0\docs\api\index.html page in your browser.
To view the API documentation on line, go to java.sun.com/javase/6/docs/api/
index.html (Fig. J.1). [Note: We released this book to publication several days before the
final Java SE 6 API documentation became available, so all the screen captures presented
here are based on the release candidate documentation.]

Upper-left frame Tree link displays Deprecated link Index link lists Help link
lists all packages the hierarchy of all lists portions of the fields, methods, describes how
in alphabetical packages and API that should no classes and the API is
order. classes. longer be used. interfaces. organized.

Lower-left frame lists all classes and Right frame overviews the API specification and contains descriptions
interfaces in alphabetical order. of each package. When you select a particular class or interface in the

Fig. J.1 | Java API overview. (Courtesy of Sun Microsystems, Inc.)

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
 J.2 Navigating the Java API XII

Frames in the API Documentation’s index.html Page

The API documentation is divided into three frames (see Fig. J.1). The upper-left frame
lists all of the Java API’s packages in alphabetical order. The lower-left frame initially lists
the Java API’s classes and interfaces in alphabetical order. Interface names are displayed in
italic. When you click a specific package in the upper-left frame, the lower-left frame lists
the classes and interfaces of the selected package. The right frame initially provides a brief
description of each package of the Java API specification—read this overview to become
familiar wth the general capabilities of the Java APIs. If you select a class or interface in the
lower-left frame, the right frame displays information about that class or interface.

Important Links in the index.html Page

At the top of the right frame (Fig. J.1), there are four links—Tree, Deprecated, Index and
Help. The Tree link displays the hierarchy of all packages, classes and interfaces in a tree
structure. The Deprecated link displays interfaces, classes, exceptions, fields, constructors
and methods that should no longer be used. The Index link displays classes, interfaces,
fields, constructors and methods in alphabetical order. The Help link describes how the
API documentation is organized. You should probably begin by reading the Help page.

Viewing the Index Page

If you do not know the name of the class you are looking for, but you do know the name
of a method or field, you can use the documentation’s index to locate the class. The Index
link is located near the upper-right corner of the right frame. The index page (Fig. J.2) dis-
plays fields, constructors, methods, interfaces and classes in alphabetical order. For exam-
ple, if you are looking for Scanner method hasNextInt, but do not know the class name,

Classes, interfaces and their members are listed in alphabetical

order. Click a letter to view all fields, constructors, methods, Click the Index link to display
interfaces and classes that start with that letter. the documentation’s index.

Fig. J.2 | Viewing the Index page. (Courtesy of Sun Microsystems, Inc.)

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
XIII Appendix J Using the Java API Documentation

you can click the H link to go to the alphabetical listing of all items in the Java API that
begin with "h". Scroll to method hasNextInt (Fig. J.3). Once there, each method named
hasNextInt is listed with the package name and class to which the method belongs. From
there, you can click the class name to view the class’s complete details, or you can click the
method name to view the method’s details.

Viewing a Specific Package

When you click the package name in the upper-left frame, all classes and interfaces from
that package are displayed in the lower-left frame and are divided into five subsections—
Interfaces, Classes, Enums, Exceptions and Errors—each listed alphabetically. For exam-
ple, the contents of package javax.swing are displayed in the lower-left frame (Fig. J.4)

Click the method name to Click the class name to view

view the method’s details. the class’s complete details.

Fig. J.3 | Scroll to method hasNextInt. (Courtesy of Sun Microsystems, Inc.)

Click a package name in the upper- Click the package name in the lower-
left frame to view all classes and left frame to display a summary of Contents of package javax.swing
interfaces defined in the package. that package in the right frame. are displayed in the lower-left frame.

Fig. J.4 | Clicking a package name in the upper-left frame to view all classes and interfaces
declared in this package. (Courtesy of Sun Microsystems, Inc.)

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
 J.2 Navigating the Java API XIV

when you click javax.swing in the upper-left frame. You can click the package name in
the lower-left frame to get an overview of the package. If you think that a package contains
several classes that could be useful in your application, the package overview can be espe-
cially helpful.

Viewing the Details of a Class

When you click a class name or interface name in the lower-left frame, the right frame dis-
plays the details of that class or interface. First you will see the class’s package name followed
by a hierarchy that shows the class’s relationship to other classes. You will also see a list of
the interfaces implemented by the class and the class’s known subclasses. Figure J.5 shows
the beginning of the documentation page for class JButton from the javax.swing package.
The page first shows the package name in which the class appears. This is followed by the

Click the class name to view detailed Detailed information about the class
information about the class. is displayed in the right frame.

JButton class

Interfaces
implemented by

JButton

Description of
class JButton

Click the link to load

the page that
contains a tutorial
on how to use
buttons. [Note: Most
classes do not have
links to tutorials.]

Fig. J.5 | Clicking a class name to view detailed information about the class. (Courtesy of Sun
Microsystems, Inc.)

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
XV Appendix J Using the Java API Documentation

class hierarchy that leads to class JButton, the interfaces class JButton implements and the
subclasses of class JButton. The bottom of the right frame shows the beginning of class
JButton’s description. Note that when you look at the documentation for an interface, the
right frame does not display a hierarchy for that interface. Instead, the right frame lists the
interface’s superinterfaces, known subinterfaces and known implementing classes.

Summary Sections in a Class’s Documentation Page

Other parts of each API page are listed below. Each part is presented only if the class con-
tains or inherits the items specified. Class members shown in the summary sections are
public unless they are explicitly marked as protected. A class’s private members are not
shown in the documentation, because they cannot be used directly in your programs.
1. The Nested Class Summary section summarizes the class’s public and pro-
tected nested classes—i.e., classes that are defined inside the class. Unless explic-
itly specified, these classes are public and non-static.
2. The Field Summary section summarizes the class’s public and protected fields.
Unless explicitly specified, these fields are public and non-static. Figure J.6
shows the Field Summary section of class Color.
3. The Constructor Summary section summarizes the class’s constructors. Con-
structors are not inherited, so this section appears in the documentation for a class
only if the class declares one or more constructors. Figure J.7 shows the Construc-
tor Summary section of class JButton.
4. The Method Summary section summarizes the class’s public and protected
methods. Unless explicitly specified, these methods are public and non-static.
Figure J.8 shows the Method Summary section of class BufferedInputStream.
Note that the summary sections typically provide only a one-sentence description of
a class member. Additional details are presented in the detail sections discussed next.

Field Summary
section of class
Click the field name
to go to the Field
Detail section,
which provides
additional

Click the field type

to go to its page. If
the field has the
same type as its
class, clicking it will
return you to the top

Fig. J.6 | Field Summary section of class Color. (Courtesy of Sun Microsystems, Inc.)

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
 J.2 Navigating the Java API XVI

Constructor
Summary

Click the
parameter type to

Click the constructor

name to go to the
Constructor Detail
section, which provides
additional information
about the constructor.

Fig. J.7 | Constructor Summary section of class JButton. (Courtesy of Sun Microsystems,
Inc.)

Method
Summary

Click the
method name
to go to the
Method
Detail section,
which provides
additional

Fig. J.8 | Method Summary section of class BufferedInputStream. (Courtesy of Sun

Microsystems, Inc.)

Detail Sections in a Class’s Documentation Page

After the summary sections are detail sections that normally provide more discussion of
particular class members. There is not a detail section for nested classes. When you click
the link in the Nested Class Summary for a particular nested class, a documentation page
describing that nested class is displayed. The detail sections are described below.
1. The Field Detail section provides the declaration of each field. It also discusses
each field, including the field’s modifiers and meaning. Figure J.9 shows the Field
Detail section of class Color.

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
XVII Appendix J Using the Java API Documentation

Field Detail
section describes
the purpose of

Fig. J.9 | Field Detail section of class Color. (Courtesy of Sun Microsystems, Inc.)

2. The Constructor Detail section provides the first line of each constructor’s dec-
laration and discusses the constructors. The discussion includes the modifiers of
each constructor, a description of each constructor, each constructor’s parameters
and any exceptions thrown by each constructor. Figure J.10 shows the Construc-
tor Detail section of class JButton.
3. The Method Detail section provides the first line of each method. The discussion
of each method includes its modifiers, a more complete method description, the
method’s parameters, the method’s return type and any exceptions thrown by the
method. Figure J.11 shows the Method Detail section of class Buffered-
InputStream. The method details show you other methods that might be of in-
terest (labeled as See Also). If the method overrides a method of the superclass,
the name of the superclass method and the name of the superclass are provided
so you can link to the method or superclass for more information.

Constructor

Fig. J.10 | Constructor Detail section of class JButton. (Courtesy of Sun Microsystems,
Inc.)

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.
 J.2 Navigating the Java API XVIII

Method read throws IOException. Click Method read overrides the read method in
IOException to load the IOException class FilterInputStream. Click the name of the
information page and learn more about the exception overridden method to view detailed information
type (e.g., why such an exception might be thrown). about the superclass’s version of that method.

Method
Detail
section

Fig. J.11 | Method Detail section of class BufferedInputStream. (Courtesy of Sun

Microsystems, Inc.)

As you look through the documentation, you will notice that there are often links to
other fields, methods, nested-classes and top-level classes. These links enable you to jump
from the class you are looking at to another relevant portion of the documentation.

© 2007 by Pearson Education, Inc., Upper Saddle River, NJ. All Rights Reserved.