2. How to Use the CD-ROM

The APIs of the Java 2 platform are comparable in breadth and depth to those of a modern, full-featured operating system. The number of packages and classes is large, and the territory they cover is vast. Think of the material on the Java Power Reference CD-ROM as an atlas for the Java 2 platform. It is a collection of maps that provide a bird's-eye view of the platform. The atlas lays the APIs out before you, guides you through them, and opens them up for your exploration.

Contents:

Contents of the Atlas
Opening the Atlas
Navigating the Atlas
Searching the Atlas
The Platform Map
Package Maps
Class Maps
Class Title
Class Synopsis
Functional grouping of members
Member flags
Class Hierarchy
Subclasses
Implementations
Properties Table
Inherited Members
Cross References

2.1 Contents of the Atlas

Just as an atlas contains maps drawn to different scales, the CD-ROM contains quick-reference pages at different levels of abstraction, as shown in Figure 2.1. The three levels of abstraction are:

Platform map

This is the highest level of abstraction. The platform map summarizes the entire Java 2 platform and its standard extensions by organizing packages into functionally related groups. This map is the table of contents for the atlas - the starting point for your explorations of Java 2.

Package maps

One level down, we have the package maps. Each package map displays a list of all the Java classes and interfaces contained in a single package. Each map begins with an alphabetical list of the classes and interfaces in the package. That alphabetical listing is followed by a functional listing that groups classes and interfaces by type and by inheritance hierarchy.

Class maps

This is the lowest level of abstraction. It describes a single class or interface and provides a synopsis of all fields and methods of that class or interface. This is also the most commonly used map, and the map that is most densely packed with information. The bulk of this chapter is an explanation of how to use the information provided in these class maps.

Figure 2.1: The maps of the Java Power Reference

Figure 2.1

2.2 Opening the Atlas

The maps contained in the atlas are HTML pages, designed to be viewed with a web browser. To start using the Java Power Reference, simply point your web browser to the index.htm file on the CD-ROM. This file contains a link to the Java Power Reference itself and also contains links to an online version of this booklet. Click on the Java Power Reference, and your browser will open the platform map for the Java 2 platform. You may want to bookmark that page.

For best results, you should use a web browser that supports JavaScript 1.1. We recommend that you use Netscape Navigator 4 or later or Internet Explorer 4 or later.

The Java Power Reference is intended for frequent use while you program. To ensure the quickest access to it, you may want to copy the HTML files from the CD to your hard disk. Beware, however, that the files require over 75 MB of disk space. Also, please note that you are only allowed to copy the files to the hard disk of your own computer, not to computers that belong to your friends or colleagues. Similarly, you are not allowed to redistribute the files over a network.

2.3 Navigating the Atlas

The Java Power Reference CD-ROM is fully hyperlinked. From the platform map, you can click on the name of any package to see the package map for that package. From a package map, you can click on the name of any class or interface to see the class map for that class. A class map usually contains many links to other related class maps; you can follow those links directly, without going back through the platform map and package map.

The hyperlinks go in the other direction as well. From a class map, you can always follow a link back to the package map for the package that contains the class. And from any class map or package map, you can follow a link back to the top-level platform map. In addition to the hyperlinks, you can always use the Back and Forward buttons in your browser.

The hyperlinks have another function as well. In order to keep the maps succinct and usable, classes and interfaces are listed without their package names. In other words, a link to the java.lang.String class simply says String, instead of spelling out the full name of the class. However, when you place the mouse over the String hyperlink, the full name of the class appears in the status line of your browser. (If it doesn't, you are probably using a very old browser or you have JavaScript turned off.) Having the package name of a class or interface appear in the status line can be very useful. For example, before following a link to the List class, you may want to check whether it refers to java.awt.List or java.util.List.

In many situations, the easiest way to navigate through this atlas is to use the search capability to jump directly to a particular map. The search capability is the index of the atlas. Type in the name of the package, class, method, or field you are interested in, and you are taken to the appropriate page (as described in the following section).

2.4 Searching the Atlas

One of the most powerful features of the Java Power Reference is that you can search it for any named package, class, method, or field. Just enter a name into the search field and hit Return. If your search string uniquely identifies a package, class, method, or field, you are taken directly to the appropriate package map or class map. If there is more than one match for your search string, you get a list of hyperlinked matches. Click on any of the links to see further details.

Figure 2.2 shows the search field and the results of a search.

Figure 2.2: Searching the Java Power Reference

Figure 2.2

Here are some guidelines for searching the Java Power Reference:

2.5 The Platform Map

The platform map, shown in Figure 2.3, is the highest-level view of the Java platform. It begins with a table of functional groups of packages. Clicking on a group links you to a table of packages in the group. From here, you can click on an individual package name to view the package map for that package. The platform map is organized functionally rather than alphabetically because there are simply too many packages for an alphabetical list to be useful. The functional organization is ideal when you are exploring the Java platform. On the other hand, if you already know exactly which package you are interested in, the quickest way to get there is usually to type its name into the search field and hit Return.

Figure 2.3: The platform map

Figure 2.3

2.6 Package Maps

A package map summarizes the contents of one package of the Java platform. An example is shown in Figure 2.4. Each package map begins with an alphabetical listing of the classes and interfaces in the package. If you already know the name of the class you are looking for, this alphabetical listing makes it easy to find. (Remember, too, that you can search for a class by name using the search field.)

Figure 2.4: A package map

Figure 2.4

The alphabetical class listing is followed by a short package description. This description briefly explains the purpose of the package and lists the most important classes and interfaces in it. It gives you a starting place for your explorations of the package.

The package description is followed by a functional listing of the package contents. In this section, classes and interfaces are grouped by category, rather than by name. For example, all exception classes in a package are grouped together, as are all event classes, component classes, and collection classes. In addition to this grouping by category, classes are arranged into a class hierarchy, with subclasses following their superclass and indented with respect to that superclass.

The purpose of this functional grouping of classes and interfaces is to make it easier to understand the organization and contents of the package. It also serves as a better starting point for your explorations of the package. If you don't already know the name of the class or interface you are looking for, you will find the functional organization more useful than the alphabetical listing.

2.7 Class Maps

A class map summarizes the contents of one class or interface of the Java platform. Class maps typically contain more information than the platform map or package maps. Each class map contains a number of sections, and each section contains a specific type of information. Some of this information is quite dense and requires detailed explanation. The sections that follow explain the layout of a class map step by step.

2.7.1 Class Title

Each class map begins with a title section that contains the name of the class and other high-level class details, as Figure 2.5 illustrates. As you can see, the name of the class appears in the top left of this section. The name of the package that contains the class appears in a smaller font beneath the class name. The package name is a hyperlink, providing an easy way to move from a class map to the containing package map.

Figure 2.5: The class title section of a class map

Figure 2.5

The top right of the title section contains version information for the class. This specifies the first release of the Java Development Kit that contained the class. Or, for standard extensions that are released independently of the JDK, it specifies the first version of the extension that contained the class. In addition, if the class or interface has been deprecated, that fact is also noted in the top right of the title section.

Finally, the area beneath the version number contains class flags that specify high-level information about a class. Flags such as "collection," "Swing component," and "event listener" specify a general category for the class. Flags such as "serializable," "cloneable," "runnable," and "accessible" specify common interfaces implemented by the class. For exception classes, the flags "checked" and "unchecked" specify whether the exception must be declared in the throws clause of a method that may throw it.

2.7.2 Class Synopsis

The title section is followed by the synopsis section, which is really the heart of a class map. This section contains the Java API that is defined by the class or interface. Using standard Java syntax, this section displays the class declaration followed by the signatures of all of the fields, methods, and inner classes defined by the class. Figure 2.6 shows the synopsis section for a relatively simple class; in larger classes, the synopsis section can be substantially longer.

Figure 2.6: The synopsis section of a class map

Figure 2.6

The first line of the synopsis section is the class declaration itself. This line includes class modifiers such as public and abstract, defines the superclass of the class, and lists the interfaces that it implements. This is high-level information about the class as a whole. The remainder of the synopsis is API information about the members (methods, fields, and inner classes) of the class.

2.7.2.1 Functional grouping of members

The first thing to note about the member API information is that the members are grouped functionally rather than alphabetically. Constructors, methods, fields, and inner classes are all listed separately. Instance methods are kept separate from static (class) methods. Constants are separated from non-constant fields. Public members are listed separately from protected members. These categorizations of class members should be familiar to readers of Java in a Nutshell. Readers have found that grouping members by category breaks a class down into smaller, more comprehensible segments, making the class easier to understand. This grouping also makes it easier for you to find a desired member.

The Java Power Reference takes this functional grouping of members a step further. In addition to grouping members by their general type, it also groups them by use or purpose. For example, the property accessor methods used by Swing components and many other classes are functionally related because they all access property values. These methods follow naming conventions that make this relationship even more apparent. The same is true for the event registration methods of Swing and AWT GUI components. The JavaBeans and Swing programming models encourage programmers to think about components and other classes in terms of the properties they define and the events they trigger. Thus, these property accessor methods and event listener registration methods are grouped together into special sections, instead of being mixed in with the other public instance methods defined by the class.

The Java Power Reference also groups methods based on hierarchy considerations. When a class implements an interface, it is reasonable to assume that the methods of that interface are functionally related to each other. Thus, these methods are grouped together. Similarly, when a class overrides methods of one of its superclasses, it often overrides a related set of methods. So overriding methods are grouped together, based on the superclass that they override. Even when the overriding methods are not closely related in functional terms, their grouping helps you understand how a class relates to and interacts with its superclass.

There are quite a few functional groupings used for class members in the Java Power Reference. Some have a clear purpose and require no explanation. Others are more complex and do require explanation. For completeness, all of the functional categories are listed here, in the order in which they appear in the class synopsis:

Constructors

Displays the constructors for the class. Public constructors and protected constructors are displayed separately in subgroupings. If a class defines no constructor at all, the Java compiler adds a default no-argument constructor that is displayed here. If a class defines only private constructors, it cannot be instantiated, so a special, empty grouping entitled "No Constructor" indicates this fact. Constructors are listed first because the first thing you do with most classes is instantiate them by calling a constructor.

Constants

Displays all of the constants (i.e., fields that are declared static and final) defined by the class. Public and protected constants are displayed in separate subgroups. Constants are listed here, near the top of the class synopsis, because constant values are often used throughout the class as legal values for method parameters and return values.

Inner Classes

Groups all of the inner classes and interfaces defined by the class or interface. For each inner class, there is a single-line synopsis. Each inner class also has its own class map that includes a full class synopsis for the inner class. Like constants, inner classes are listed near the top of the class synopsis because they are often used by a number of other members of the class.

Static Methods

Lists the static methods (class methods) of the class, broken down into subgroups for public static methods and protected static methods.

Event Listener Registration Methods

Lists the public instance methods that register and deregister event listener objects with the class. The names of these methods begin with the words "add" and "remove" and end in "Listener". These methods are always passed a java.util.EventListener object. The methods are typically defined in pairs, so the pairs are listed together. The methods are listed alphabetically by event name, rather than by method name.

Property Accessor Methods

Lists the public instance methods that set or query the value of a property or attribute of the class. The names of these methods begin with the words "set," "get," and "is," and their signatures follow the patterns set out in the JavaBeans specification. Although the naming conventions and method signature patterns are defined for JavaBeans, classes and interfaces throughout the Java platform define property accessor methods that follow these conventions and patterns. Looking at a class in terms of the properties it defines can be a powerful tool for understanding the class, so property methods are grouped together in this section.

Property accessor methods are listed alphabetically by property name, not by method name. This means that the "set," "get," and "is" methods for a property all appear together. The Java Power Reference defines a property accessor method in a somewhat more general way than the JavaBeans specification does. A method is considered to be a property accessor if it follows the JavaBeans conventions itself or if it has the same name as a method that follows those conventions. Consider the setSize() method of the Component class. There are two versions of this method, and, since they have the same name, they obviously share a purpose and deserve to be grouped together. However, only one version of the method strictly follows the JavaBeans signature patterns. The relaxed definition of what constitutes a property accessor method allows these two methods to be listed together, as they should be.

Instance Methods

Contains all of the instance methods that are not event registration methods or property accessor methods and that do not implement an interface or override a method of a superclass. The methods are broken into public and protected subgroups.

Implementing Methods

Groups the methods that implement the same interface. There is one subgroup for each interface implemented by the class. Methods that are defined by the same interface are almost always related to each other, so this is a useful functional grouping of methods.

Note that if an interface method is also an event registration method or a property accessor method, it is listed both in this group and in the event or property group. This situation does not arise often, but when it does, all of the functional groupings are important and useful enough to warrant the duplicate listing. When an interface method is listed in the event or property group, it displays an "Implements:" flag that specifies the name of the interface of which it is part.

Overriding Methods

Groups the methods that override methods of a superclass broken down into subgroups by superclass. This is typically a useful grouping, because it helps to make it clear how a class modifies the default behavior of its superclasses. In practice, it is also often true that methods that override the same superclass are functionally related to each other.

Sometimes a method that overrides a superclass is also a property accessor method or (more rarely) an event registration method. When this happens, the method is grouped with the property or event methods and displays a flag that indicates which superclass it overrides. The method is not listed with other overriding methods, however. Note that this is different from interface methods, which, because they are more strongly functionally related, may have duplicate listings in both groups.

Static Fields

Lists any static class fields that are not constants, breaking them into public and protected subgroups. In practice, static fields are fairly rare. They are listed near the bottom of the class synopsis because they are usually less important than the constructors, constants, inner classes, and methods that precede them.

Instance Fields

Contains any instance fields defined by the class, breaking them into public and protected subgroups. Many classes define no such accessible fields. For those that do, many object-oriented programmers prefer not to use those fields directly, but instead to use accessor methods when such methods are available.

Deprecated Members

Deprecated methods and deprecated fields are grouped at the very bottom of the class synopsis. Use of these methods and fields is strongly discouraged.

2.7.2.2 Member flags

Within a class synopsis, member synopses are grouped as explained previously. Each member synopsis is a single line that defines the API for that member. These synopses use Java syntax, so their meaning is immediately clear to any Java programmer. There is some auxiliary information associated with each member synopsis, however, that requires explanation.

Recall that a class map begins with a title section that includes the release in which the class was first defined. When a member is introduced into a class after the initial release of the class, the version in which the member was introduced appears, in small print, to the left of the member synopsis. Furthermore, if a member has been deprecated, that fact is indicated with a hash mark (#) to the left of the member synopsis.

The area to the right of the member synopsis is used to display a variety of member flags that provide additional information about the member. Some of these flags provide additional specification details that do not appear in the member API itself. Other flags contain implementation-specific information. This information can be quite useful in understanding the class and in debugging, but it may differ between implementations. The implementation-specific flags displayed in the Java Power Reference are based on Sun's implementation of Java for Microsoft Windows.

The following flags may be displayed to the right of a member synopsis:

native

An implementation-specific flag that indicates that a method is implemented in native code. Although native is a Java keyword and can appear in method signature, it is part of the method implementation, not part of its specification. Therefore, this information is included with the member flags, rather than as part of the member synopsis. This flag is useful as a hint about the expected performance of a method.

synchronized

An implementation-specific flag that indicates that a method implementation is declared synchronized, meaning that it obtains a lock on the object or class before executing. Like the native keyword, the synchronized keyword is part of the method implementation, not part of the specification, so it appears as a flag, not in the method synopsis itself. This flag is a useful hint that the method is probably implemented in a thread-safe manner.

Whether or not a method is thread-safe is part of the method specification, and this information should appear (although it often does not) in the method documentation. There are a number of different ways to make a method thread-safe, however, and declaring the method with the synchronized keyword is only one possible implementation. In other words, a method that does not bear the synchronized keyword can still be thread-safe.

Overrides:

Indicates that a method overrides a method in one of its superclasses. The flag is followed by the name of the superclass that the method overrides. This is a specification detail, not an implementation detail. This flag is used only when the overriding method is grouped with event registration or property accessor methods. As explained in the discussion of functional grouping of methods, overriding methods are usually grouped in a special section based on the superclass they override. In these sections, the "Overrides:" flag is not necessary.

Implements:

Indicates that a method implements a method in an interface. The flag is followed by the name of the interface that is implemented. This is a specification detail, not an implementation detail. Because methods that implement interface methods are grouped into special sections, this flag is used only when the method is duplicated in the event registration or property accessor section.

empty

Indicates that the implementation of the method has an empty body. This can be a hint to the programmer that the method may need to be overridden in a subclass. The Applet.init() method is a good example of this type of method.

constant

An implementation flag that indicates that a method has a trivial implementation. Only methods with a void return type can be truly empty. Any method declared to return a value must have at least a return statement. The "constant" flag indicates that the method implementation is empty except for a return statement that returns a constant value. Such a method might have a body like return null; or return false;. Like the "empty" flag, this flag indicates that a method may need to be overridden.

default:

Used with property accessor methods that read the value of a property. The flag is followed by the default value of the property. Strictly speaking, default property values are a specification detail. In practice, however, these defaults are not always documented, and care should be taken, because the default values may change between implementations.

Not all properties have a "default:" flag. A default value is determined by dynamically loading the class in question, instantiating it using a no-argument constructor, and then calling the property "get" method to find out what it returns. This technique can be used only on classes that can be dynamically loaded and instantiated and that have no-argument constructors, so default values are shown for those classes only. Furthermore, note that when a class is instantiated using a different constructor, the default values for its properties may be different.

bound

Indicates that a property is a bound property. In other words, the class generates a java.beans.PropertyChangeEvent when the property changes. This is a specification detail, but it is sometimes not documented. Information about bound properties is obtained from the BeanInfo object for the class.

constrained

Indicates that a property is constrained. In other words, the property setter method may throw a java.beans.PropertyVetoException. This is a specification detail, not an implementation detail.

expert

Indicates that the BeanInfo object for this class specifies that this property or event is intended for use by experts only. This hint is intended for visual programming tools, but users of the Java Power Reference may find the hint useful as well.

hidden

Indicates that the BeanInfo object for this class specifies that this property or event is for internal use only. This is a hint that visual programming tools should hide the property or event from the programmer. The Java Power Reference does not hide these properties and events, of course, but this flag does indicate that you should probably avoid using the property or event.

preferred

Indicates that the BeanInfo object for this class specifies that the property or event is in some way the default or preferred property or event. This is a hint to visual programming tools to display the property or event in a prominent way, and it is also a useful hint to users of the Java Power Reference.

=

For constant fields, this flag is followed by the constant value of the field. Only constants of primitive types and constants with the value null are displayed. Some constant values are specification details, while others are implementation details. The reason that symbolic constants are defined, however, is so you can write code that does not rely directly upon the constant value. Use this flag to help you understand the class, but do not rely upon the constant values in your own programs.

2.7.3 Class Hierarchy

Now that we've examined the functional grouping of members and member flags within the class synopsis, let's pull back and look at the whole picture of a class map again. Each class map begins with a title section, followed by the synopsis section. While the synopsis contains the bulk of the information about the class, it does not contain all of the information. The synopsis section is followed by a hierarchy diagram, like the one pictured in Figure 2.7.

Figure 2.7: The hierarchy and subclasses sections of a class map

Figure 2.7

As you can see, the hierarchy diagram for a class displays all of the superclasses of the class, all of the interfaces it implements, as well as all of the interfaces implemented by each of its superclasses. The rectangular boxes along the left edge of the diagram form the class tree. This tree begins with the root class java.lang.Object and moves down through the class hierarchy to the class being documented. To the right of each class, connected by dotted lines, are the interfaces it implements. Interfaces are displayed in octagons, rather than rectangles. Note that interfaces may themselves have interfaces that appear to their right. Interfaces do not have superclasses, so the hierarchy diagram for an interface often consists of only a single octagon.

2.7.4 Subclasses

The hierarchy diagram just described displays the classes and interfaces above a given class in the inheritance hierachy. The section that follows the diagram lists the classes that appear below it in the hierarchy. If a class has subclasses, or an interface has subinterfaces, the hierarchy diagram is followed by a "Subclasses" section that lists those subclasses or subinterfaces. Figure 2.7 illustrates this "Subclasses" section.

2.7.5 Implementations

Most interfaces do not have subinterfaces, and therefore do not have a "Subclasses" section. Many interfaces, however, do have implementations. All implementations of a given interface are listed in the "Implementations" section.

2.7.6 Properties Table

The "Hierarchy," "Subclasses," and "Implementations" sections are followed by a section entitled "JavaBeans Properties." This section contains a summary table of the properties defined by the class or interface. For each property, the table lists the property name, its type, its accessor methods, its default value, and any relevant flags. Figure 2.8 shows what such a table looks like.

Figure 2.8: The property table section of a class map

Figure 2.8

2.7.7 Inherited Members

The synopsis section of a class map lists only the members implemented directly by a class. Of course, when you are using the class, you can also use members that are inherited by the class from its superclasses. The next three sections in a class map display these inherited methods, under the titles "Inherited Properties," "Inherited Events," and "Inherited Methods." Figure 2.9 shows what one of these sections looks like.

Figure 2.9: The inherited methods section of a class map

Figure 2.9

Each section displays the appropriate inherited members broken down by the superclass from which they are inherited. The sections list inherited properties, events, and methods; they do not provide synopses for them. If you need more information about one, you need to visit the class map of the superclass from which it is inherited.

Some classes such as java.awt.Component define a huge number of methods, and a complete listing of inherited methods would be too long to be useful. In this case, the method list is omitted.

2.7.8 Cross References

The final sections of a class map are the cross references. These sections list the other classes, methods, and fields that use the class in some way. Some classes, such as java.lang.String, are so widely used that the cross reference lists become too long to be useful. In cases like these, the cross reference lists are omitted. Figure 2.10 shows what some of these sections look like.

Figure 2.10: Two cross reference sections of a class map

Figure 2.10

The Java Power Reference provides the following cross reference sections:

Passed To

Displays a list of methods that take a parameter of this type.

Returned By

Displays a list of methods that return a value of this type.

Thrown By

For error and exception classes, displays a list of methods that throw the error or exception.

Type Of

Displays a list of fields of this type.

Uses

Displays a list of classes and interfaces that this class uses. This section is different from the others, in that it contains implementation-level information obtained by scanning the bytecode of the class. As a result, this list may contain classes that do not appear anywhere in the public API (the specification) of the class.

Used By

Displays the reverse of the "Uses" section. It lists classes that use this class in their implementation. The classes that appear in this list may not use this class in their public API (specification).