G.2. Navigating the Java API

The Java API documentation can be downloaded to your local hard disk or viewed on line. To download the Java API documentation, go to java.sun.com/j2se/5.0/download.jsp and locate the DOWNLOAD link in the J2SE v 1.5.0 Documentation section. You will be asked to accept a license agreement. To do this, click Accept, then click Continue. Click the Java(TM) 2 SDK, Standard Edition Documentation 1.5.0, English link to begin the download. After downloading 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 jdk1.5.0 directory or the directory where you installed Java. (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 FilesJavajdk1.5.0docsapiindex.html page in your browser. To view the API documentation on line, go to java.sun.com/j2se/1.5.0/docs/api/index.html (Fig. G.1).

Figure G.1. Java API overview. (Courtesy of Sun Microsystems, Inc.)

Frames in the API Documentation's index.html Page

The API documentation is divided into three frames (see Fig. G.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 specificationread 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. G.1), there are four linksTree, 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. G.2) displays fields, constructors, methods, interfaces and classes in alphabetical order. For example, if you are looking for Scanner method hasNextInt, but do not know the class name, 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. G.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.

Figure G.2. Viewing the Index page. (Courtesy of Sun Microsystems, Inc.)

(This item is displayed on page 1429 in the print version)

Figure G.3. Scroll to method hasNextInt. (Courtesy of Sun Microsystems, Inc.)

 

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 subsectionsInterfaces, Classes, Enums, Exceptions and Errorseach listed alphabetically. For example, when you click javax.swing in the upper-left frame, the contents of package javax.swing are displayed in the lower-left frame (Fig. G.4). 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 especially helpful.

Figure G.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.)

(This item is displayed on page 1431 in the print version)

 

Viewing the Details of a Class

When you click a class name or interface name in the lower-left frame, the right frame displays 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 G.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 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.

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

(This item is displayed on page 1432 in the print version)

 

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 contains 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 protected nested classesi.e., classes that are defined inside the class. Unless explicitly 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 G.6 shows the Field Summary section of class Color.

   Figure G.6. Field Summary section of class Color. (Courtesy of Sun Microsystems, Inc.)

   (This item is displayed on page 1433 in the print version)

   
3. The Constructor Summary section summarizes the class's constructors. Constructors are not inherited, so this section appears in the documentation for a class only if the class declares one or more constructors. Figure G.7 shows the Constructor Summary section of class JButton.

   Figure G.7. Constructor Summary section of class JButton. (Courtesy of Sun Microsystems, Inc.)

   (This item is displayed on page 1433 in the print version)

   
4. The Method Summary section summarizes the class's public and protected methods. Unless explicitly specified, these methods are public and non-static. Figure G.8 shows the Method Summary section of class BufferedInputStream.

   Figure G.8. Method Summary section of class BufferedInputStream. (Courtesy of Sun Microsystems, Inc.)

   (This item is displayed on page 1434 in the print version)

   

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.

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 G.9 shows the Field Detail section of class Color.

   Figure G.9. Field Detail section of class Color. (Courtesy of Sun Microsystems, Inc.)

   (This item is displayed on page 1435 in the print version)

   
2. The Constructor Detail section provides the first line of each constructor's declaration 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 G.10 shows the Constructor Detail section of class JButton.

   Figure G.10. Constructor Detail section of class JButton. (Courtesy of Sun Microsystems, Inc.)

   (This item is displayed on page 1435 in the print version)

   
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 G.11 shows the Method Detail section of class BufferedInputStream. The method details show you other methods that might be of interest (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.

   Figure G.11. Method Detail section of class BufferedInputStream. (Courtesy of Sun Microsystems, Inc.)

   (This item is displayed on page 1436 in the print version)

   

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.