The API Pages

There are more than 1,000 core Java classes, and every one of them has been described in detail by the Java creators. Unlike a lot of manufacturers' technical specifications, these descriptions are well-written, accurate, and helpful. They are provided as a set of interconnected HTML pages that you can download to your hard drive and view with the Web browser of your choice. Like Java itself, they are freely downloadable. If you have not already done so, please download them before continuing with this chapter. You can find instructions on how to do this in Appendix A.

The API pages do a fine job of presenting each class in detail. In fact, they do such a good job that there is no need to duplicate their effort in this chapter. Instead, we will begin by showing you how to use the API pages. After that, we will mostly give you just an overview of the classes and methods, while encouraging you to use your new API skills to look up details when you need them.

Digression: A Personal Anecdote

Quite a while ago, before the birth of the World Wide Web, I worked for a company that made computers. These computers used a programming language that was a bit like C, but it was object-oriented. In addition to the language, there were a number of classes that supported I/O, graphical user interfaces, math, and so on. If you saw it today, you would probably be reminded of Java, but with fewer supplied classes.

There were several dozen of these classes. Their documentation consisted of two manuals that listed the classes in alphabetical order. For each class, the manuals listed the inheritance hierarchy, the data, and the methods.

Those of us who wrote programs for this system each had our own copy of the manuals. You could tell how long someone had been working there by the shape their manuals were in. Those books took a beating. We were always flipping back and forth. If I wanted to remind myself what a certain method of a certain class did, I might find that the method wasn't explained where I expected an explanation, because the class I was reading about inherited the method from its superclass. So I would look up the superclass (which might be in the other volume), and I would see that it returned an object reference, and I would have to look up that object's explanation because I hadn't seen it before.

I flipped a lot of pages because a lot of information for one class was (quite rightly) presented in the description of a different class. For example:

• The class's superclass

• The type of a non-primitive variable

• The type of a non-primitive method argument

• The type of a non-primitive method return value

• Any class, method, or variable mentioned for any reason in the description I was reading

A set of HTML documents would have eliminated all that page-turning. The only problem was, this was 1988 and there was no HTML. The Web was just a glimmer in the eyes of a few people in Switzerland, and hypertext was an idea that wasn't discussed much outside of universities. We programmers would often wonder, "Couldn't we fix it so I could read all this on my screen, and somehow click on names of classes and data and methods to read their explanations?" But we didn't invent the World Wide Web.

Fast-forward to right now. We don't have a few dozen classes; we have more than a thousand. If you printed their explanations in books, how many yards of shelf space would be required? How long would it take to look something up? Fortunately, it's all in HTML files, and fortunately, someone invented the Web. But it wasn't me.

Starting at the Top

To get the most out of this section, read it in front of your computer. You will be invited to look at various API pages. If you haven't yet downloaded and installed them, do it now!

Appendix A suggested that you download the Java documentation into j2sdk1.4.1_02\docs (depending on your operating system, the path separator might be a forward slash). In the docs directory, there is a directory called api. Display the contents of that directory. Double-click on the icon for index.html. Your browser will appear, displaying a fairly large page with 3 frames. This is the index. It is your entry point into the dozens of millions of bytes of information that are your electronic documentation.

The API pages are copyrighted, so we can't show you a picture of the index. Its structure is shown in Figure 12.1.

Figure 12.1: Structure of the API index

The index has 3 frames:

• The packages frame

• The classes frame

• The details frame

Look at the packages frame in the upper-left corner of your browser. It is a list of all the core Java packages. Subpackages are also listed. Notice that the 2nd package in the list is java.awt, which is followed by its 10 subpackages.

The remainder of the left edge of the page is occupied by the classes frame. Initially, all the classes of all the core packages are displayed. When you click on an individual package in the packages frame, the classes frame displays the contents of the selected package. Figure 12.2 shows the structure of the classes frame.

Figure 12.2: Structure of the classes frame

The classes frame shows all the interfaces, classes, exceptions, and errors of the selected package. (If you haven't yet selected a package, or if you select All Classes in the packages frame, you see everything for all packages.) Each interface, class, exception, and error is a link.

We haven't discussed errors in this book. They are like exceptions, but they indicate something deeply wrong with a program. As a programmer, you should avoid throwing or catching errors. So for the remainder of this book, we will continue to ignore their existence.

Try it. In the packages frame, click on java.awt. (We will spend the last three chapters of this book learning how to use this package.) The classes frame shows that java.awt has a large number of interfaces, a very large number of classes, a few exceptions, and one error.

Now go back to the packages frame, scroll down a bit, and click on java.lang. Click on the link for the Boolean class, which is the first link in the list of classes. The details frame displays a complete explanation of the class.

The class description is quite long, even for a simple class like java.lang.Boolean. It is divided into 3 sections, as shown in Figure 12.3.

Figure 12.3: Class description

The class overview presents the class name, its inheritance hierarchy, and a text description. All elements of the inheritance hierarchy are links, so it's easy to look up a class's superclass.

The field, constructor, and method summaries are the really useful part of this frame. Figure 12.4 shows their structure.

Figure 12.4: Field/constructor/ method summaries

Each field, constructor, and method is listed alphabetically, along with a brief description. To see a more detailed description, click on the name of the field, constructor, or method. The name is a link to the position, further down on the same page, of the detailed description. Any class name in the detailed description is a link to the API page for that class. Try it. In the method summary section, click on the link for toString(). You see an explanation that is somewhat deeper than that brief one that appeared in the summary. Any exceptions thrown by any constructor or method are listed in the detailed description.

Any field, constructor, method, or class mentioned anywhere in the details frame is itself a link. The return type of the toString() method is String. Click on one of the occurrences of this word. The details frame displays the description of the java.lang.String class.

Between the summary and detail sections is a short section that lists all the methods that the class inherits from all its parent superclasses.

Typically, a session with the API pages goes like this. You want to look up a particular method of a particular class, for any of the same reasons you would look up a word in a dictionary. You want to know:

• How to spell it.

• How to use it.

• What it means.

For a method, you probably want to know one of the following:

• Its spelling.

• Its return type.

• Its argument list.

• What it does.

• What exceptions it throws.

You begin your session by scrolling through the packages frame until you find the right package. You click on it, so that the classes frame displays the contents of the package. You scroll through the classes frame until you find the class you want. You click on the class link to make the details frame display the class description.

Now you scroll through the alphabetical list of methods until you find the one you want. The summary information might be enough. If not, you click on the method name to view the detailed description.

If you're looking for the method's return type or argument list, you might find yourself looking at the name of a class that you don't recognize. No problem. Click on the class name (it's a link) and read its API page.

The API pages contain more information than is presented here, but this is enough to get you going. If you are curious about the additional API information, a good place to start is the very top of any class description page. Click on the Use, Tree, or Index link.

Deprecated Methods

Occasionally, an API page might tell you that a certain method is deprecated. A deprecated method is one that was introduced in an early revision of Java, and since then has been replaced with something more robust, modern, bug-free, or trustworthy. You are strongly cautioned not to use anything that is deprecated. Sun reserves the right to remove anything deprecated from future revisions.

Ordinarily, Java is backward-compatible. This means that if you write Java code that compiles successfully and runs correctly with the current revision of Java, your code will still compile successfully and run with the same behavior as before in any future revision of Java. But if you use deprecated methods, you no longer get backward-compatibility. If one of the methods you call has been removed, your code will no longer work.