I started discussing the place to look up Java's classes and methods in
Java's Reference Manual and the place to look up the language's syntax and elements in
The Java Language Manual. Here I'm going to take a deeper look at the documentation of Java's classes, interfaces, and so on in the
the Java API Reference.
At first glance the page that's presented to you by the API reference can be overwhelming. Too much information!
First
let's look at what's in each panel. If you don't have the API reference
open in another tab or window of your browser, open it now. I'll be
referring to what you see. The link is
the Java API Reference.
Bookmark it. Put it on your bookmark bar. Don't tattoo it on your
forearm, though--there'll be a new URL when a new version of Java hits
the streets and you'd be really embarassed to walk around with an old
URL tattooed on your arm, wouldn't you? Writing it on a sticky and
putting it on your monitor's bezel is probably good enough.
In
the upper left frame, we have the list of packages. So far so good. If
you know what package has what you're looking for in it, you can reduce
the stuff listed elsewhere a lot by clicking on the name of the package.
For example, JFrame is in javax.swing. If you click on javax.swing in
the upper left frame, you'll see a change in the display. Now only the
classes, interfaces, and enums and exceptions defined in javax.swing are
listed in the lower left frame. It's a much smaller list to scroll
through. If you don't know the package you're looking for, then you'll
just have to go through the long list, which is in alphabetical order.
In
the upper left frame, click on "All Classes" at the top of the list to
list all the classes, interfaces, enums, and exceptions in the API
again.
Once you find your class on the lower left, you'll get its
documentation in the main panel on the right. This can be overwhelming
as well. Since we've already talked about JFrame, let's look at it.
Click on JFrame in the lower left panel. You can select javax.swing in
the upper left panel first to make selecting JFrame easier if you wish.
In the main window, you'll see the big title "
Class JFrame".
Immediately above that in small type is the package it is in. If you
didn't already know that JFrame is in javax.swing, now you would know.
Remember the package for when you think you're going to look something
up again later. Or, if you want to include a class and don't know what
package to
import
, this is a good way to find out.
Beneath
Class JFrame
you'll see a list of other classes with little stairsteps leading down
from one to another. These are the parent classes of JFrame, from the
most basic object class in Java,
java.lang.Object
to JFrame itself. JFrame inherits from all these classes. Every method and field that they have, JFrame has, too.
You
can see the documentation for any of them by simply clicking on the
class's name. But don't just yet, we're going to look at more of
JFrame's documentation first.
Next down the page is the list of
interfaces that JFrame implements. This means that JFrame has the
methods implemented in it that these interfaces call for. There's a lot
more to an interface than this, but that's a subject for another time.
In essence, JFrame inherits the functions of these interfaces by
implementing the methods they define.
Below the line, we have a
text description of JFrame headed by a pseudocode definition of JFrame.
Some of these text descriptions in Java's API Specification are very
useful, others are less useful. The one for JFrame is middle of the
road. Like many descriptions, it comes in at the middle of the story,
assuming that you have complete and perfect familiarity with some other
part of Java that isn't what you're looking up here. This results in
some look-ups turning into searches for the start of the story. You look
up JFrame, it refers to Frame, then you go back to Window to understand
what they're talking about in java.awt.Frame's documentation. Then
you're reading all about java.awt.Component, and so on. Before you know
it, you're looking at java.lang.Object and wondering what your original
question was, and where all the time has gone.
So don't rely to
heavily on these. Scan them, but if you're not getting what you want,
keep moving down. Usually the later parts of the section are far more
informative and direct. If there's some meta-information you're looking
for on a class, check the related tutorial at Sun, or do a web search
and look for a good intro or tutorial article. (You might even scroll
down below my articles to where I keep a long index to my articles.)
I'm
going to skip on down past the Nested Class Summary and list of nested
classes inherited, too, and jump right into the Field Summary below
them.
Fields are the variables and constants defined for the
class. The first listed have been defined directly in this class. The
listing tells you what they've been defined as, and their purpose.
Following that is a list of ones inherited from each of the parent
classes.
The Constructor Summary tells you what constructors are
available for this class. If you were hoping for a JFrame constructor
that lets you set it visible and give it a size right at the outset,
you'll see you're out of luck. JFrame's constructors only allow you to
define either or both of the JFrame's title and graphics configuration
when it's instantiated (that is, when the Constructor makes a new one.)
So you'll have to set the size and visibility later.
How you set
size and visibility, and do a bunch of other things with a JFrame comes
next. They're part of the Method Summary. First there's the list of
methods defined in JFrame. These are the new methods that JFrame adds to
its parents' methods. Each lists its type and name and parameter list
along with a brief description. Following comes the long, long list of
inherited methods. JFrames have all these methods, too, but their
description lies in the document page for the class they were originally
defined in. Click on their name to go there.
Following this come
the detailed descriptions of JFrame's fields and methods. You could
have gotten here the fast way by clicking on one of the field or method
names in the summaries above. These are the real meat of the Java API
specification. They tell you how to use the class methods, and what they
do. Once you know them, the short description in the summary will
usually be enough for you (if you need even that.)
Having the
whole document hyperlinked makes it far more useful than a paper
document would be. There'd just be too much page-flipping.
If you want to have a copy right on your own machine, you can download the entire thing. The PDF is available
from Sun for Java 6, or you can get it for different versions from links on the
Java SE reference page.
That way you don't have to be on the network all the time, or held hostage to the speed of your connection to look up something.