Java's Reference Manual

Java has a peculiar name for the reference where you look up Java classes and their methods and member variables. It's called the "API Specification." If you want to know what something does, or how to use it, you look it up in the Java API Specification for the version of Java that you're using.

The online home of these Java language reference manuals is at http://download.oracle.com/javase/

Look for the link here to "API Specification."

Here are direct links for several versions of Java in current use:
Java SE 5.0 (a.k.a. Java 1.5.0): http://download.oracle.com/javase/1.5.0/docs/api/

Java SE 6: http://download.oracle.com/javase/6/docs/api/

Java SE 7: http://download.oracle.com/javase/7/docs/api/

Your Java Version
To find the version of Java that you're using, open a Terminal or Command Line window and enter the command "java -version" (without the quotes, of course.) It will print out something like this:

java version "1.5.0_13"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-b05-241)
Java HotSpot(TM) Client VM (build 1.5.0_13-121, mixed mode, sharing)

The key item here is the information in the quotes in the first line, "1.5.0_13". For the purposes of figuring out which version of the API specification we want to be referring to, we look at the digits before the underscore. In this case, "1.5.0" is the part that's important to us. For this version of Java, we'd select the link for J2SE 1.5.0.

Another approach that's simpler is to simply go to the most recent API reference. Within the API reference, it lists what version of Java each feature appeared. You want to check that on each item before you dig into reading about what cool things it can do--it's terrible to spend a bunch of time reading about a class and methods that solve your programming problem only to have your compiler reject it because you're using a version that doesn't have that feature yet!

You also want to make sure that your compiler version matches your JVM version. "java -version" gives you the version of your JVM (Java Virtual Machine) a.k.a. Java Runtime Environment (they're not exactly the same thing, but close enough for this discussion and the terms JVM and JRE tend to get used interchangeably.)

To get your compiler version, enter the command "javac -version" at the Command Line or command prompt of your Terminal window. Some versions may want you to enter "javac --version" instead of "javac -version", so if you get a big long error message instead of a version message, try using two dashes (or read the usage message and see what it says, it may want "javac -v" or something.)

If your compiler version is newer than your JVM version, you'll want to follow the instructions for your system to point it to the newer JVM as a default so that you are interpreting your programs with the same version of Java that you are compiling it with. Your Java compiler may be compiling code that your JVM can't run, otherwise! The Java Development Kit (JDK), which contains the compiler, also has a JRE bundled with it that matches the version of the compiler. So you shouldn't have to download any updates to get a JRE that matches your compiler, you just have to let your system know which version of the JRE you want it to run.

How this is done varies between different operating systems, so consult the online information on how to do this for your OS or distro.

If your JRE is a newer version than your compiler, you'll probably want to update your compiler so that you can take advantage of all the features of your JVM. Once again, this is a system-specific process.

Looking Things Up in the Java API Specification

Once you're at the correct API specification (say language reference manual or library reference in your mind) you can find a list of classes on the lower left hand side (in the frames view.) Chances are you don't know what package the classes are in that you want to look up, at least at first, so scanning through the long alphabetic list of class names is usually the place to start. There are also names in italic, these are names of interfaces.

Let's say we want to look up System.out.println() which has appeared in many of our examples here. The class name is System, so we click on System in the lower left hand frame. This makes the documentation page for System appear on the right side frame.

Above the words "Class System" you'll see the name of the package that System is part of, java.lang. Click on java.lang in the upper left hand frame and you'll see that it updates the lower left frame to show a much shorter list, a list of the interfaces, classes, enums, and errors that are part of the java.lang package. It's worthwhile to remember the package your commonly used classes are part of, for this and other reasons.

We wanted to look up System.out.println(). Back on the main frame on the right side of the window we can scroll down a little to see the Field Summary, where out is listed. This field, or member variable, is System.out. Click on out.

out is a PrintStream object, which means that it has all the methods of the PrintStream class, among other things. Below its verbose description is a set of links to PrintStream methods, including PrintStream.println(). Click on this link now.

This takes you to a list of different versions of the println() method, which do different things depending on what sort of data is inside the parentheses. In the examples we've been using so far, we've been using "System.out.println("Hello")" so we've been putting String data inside the parens ("Hello").

If we scroll down a bit we see println(String x), which tells us what the expected behavior is for a call of println() with a string inside the parens.

Try looking up some other classes and methods. For example, take a look at what the Scanner class can do.