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:
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:
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.
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.
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.
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.
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).
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.
Here are some guidelines for searching the Java Power Reference:
The search facility uses JavaScript code. That means that it requires a browser that supports JavaScript 1.1 (i.e., Navigator 3 or later or Internet Explorer 4 or later). If you have turned off JavaScript support in your browser, you'll need to turn it back on for searching to work.
Searches are not case-sensitive. If you want to see the class
map for java.lang.String
, you can type
"string", "String", or
"STRING".
When searching for a class, type only the class name, not the fully qualified name. In other words, don't type the package name as part of the class name. The Java Power Reference does not index classes by their package names, so typing a full name like "java.lang.Thread" does not work. Just type "Thread" instead.
When searching for a package, type the complete name of the
package and the package map for that package will be
displayed. Thus, if you type "javax.swing",
you are taken to the package map for the
javax.swing
package.
You can also enter a single component of a package name to see a list of all packages that contain that component (assuming that there is more than one). For example, if you type "swing", you get a list of all packages that contain "swing" in their names. If you are interested in only these packages, this may be a more useful listing to you than the listing provided by the top-level platform map.
To search for a method or field, type the unqualified name of the method or field. In other words, do not include the class or package name. Because the Java 2 API is so large, there is often more than one method or field with a given name. This means that when searching for a method or field, you are often presented with a list of links to choose from, instead of having a single unique match displayed for you.
Remember that the Java Power Reference does not display individual quick-reference pages for methods and fields. When you search for a method or field, the search results direct you to the appropriate method or field synopsis within the class map of the class that contains the method or field. Also, remember that Java classes may contain more than one method with the same name.
You can follow your search string with the wildcard
character *
, which matches anything. For
example, if you search for "thread", you see
the class map for the java.lang.Thread
class. If you search for
"thread*
", however, you are
given a list of links to the Thread
,
ThreadDeath
,
ThreadGroup
, and
ThreadLocal
classes. And if you search
for "thr*
", you get links to
those four classes plus the Throwable
class.
If you put an *
at the beginning of your
search string, you get results that approximate a wildcard
search. Normally, the Java Power
Reference searches for package, class, method, or
field names that match your search string exactly. If you
begin the search string with an *
, it
also looks for packages, classes, methods, and fields that
contain your search string as a "subword." Many
Java class, method, and field names contain multiple words,
where each word starts with an capital letter. For example,
the ThreadLocal
class has a name that
contains two words. So, if you search for the string
"*
local", you find the
classes ThreadLocal
and
InheritableThreadLocal
, along with quite
a few methods and fields that have the word
"local" in their name.
Remember that placing an *
at the
beginning of a search string does not result in a fully
general wildcard search. For example, the search string
"*
local" matches a method
named isLocal()
, but does not match a
method named islocal()
. Because
"islocal" does not have mixed-case
capitalization, it does not have "local" as a
subword. Placing an *
at the beginning
of a search string simply makes the search algorithm
consider subwords within class, method, and field names.
This yields results that are similar to, but not the same
as, a true wildcard search.
You can place an *
at both the beginning and the end of a
search string. If you search for "*
str*
", the
Java Power Reference
looks for package, class, method, and field names that start
with "str" or that contain a subword that
starts with "str".
Search targets that begin and end with *
can sometimes
return too many results to be really useful. "*
str*
"
is such
a target. It returns many matches, including classes such as
String
, StringBuffer
,
StringReader
, Stroke
,
KeyStroke
, and DynStruct
.
The *
character is allowed only at the
beginning or end of a search string. You may not use it in
the middle of a string.
The Java Power Reference search capability works like an index. Like the index of a printed book, you can use it only to search for a single word at a time. Do not try to use it like an Internet search engine that accepts multiple words and phrases.
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.
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.)
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
Lists the static methods (class methods) of the class, broken down into subgroups for public static methods and protected static 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.
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.
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.
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.
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.
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.
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 methods and deprecated fields are grouped at the very bottom of the class synopsis. Use of these methods and fields is strongly discouraged.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The Java Power Reference provides the following cross reference sections:
Displays a list of methods that take a parameter of this type.
Displays a list of methods that return a value of this type.
For error and exception classes, displays a list of methods that throw the error or exception.
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.
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).