By Barry Burd

The people at Sun Microsystems who created Java thought of Java as having two parts. Just as English has its grammar and commonly used names, the Java programming language has its specification (its grammar) and its Application Programming Interface (its commonly used names). Whenever you write Java programs, you could keep two important pieces of documentation — one for each part of the language — on your desk:

  • The Java Language Specification: This documentation includes rules like, “Always put an open parenthesis after the word for” and “Use an asterisk to multiply two numbers.”

  • The Application Programming Interface: Java’s Application Programming Interface (API) contains thousands of tools that were added to Java after the language’s grammar was defined. These tools range from the commonplace to the exotic.

    For instance, the tools include a routine named pow that can raise 5 to the 10th power for you. A more razzle-dazzle tool (named JFrame) displays a window on your computer’s screen. Other tools listen for the user’s button clicks, query databases, and do all kinds of useful things.

You can download the Language Specification, the API documents, and all the other Java documentation (or view the documents online) by poking around at Oracle.

The first part of Java, the Language Specification, is relatively small. That doesn’t mean you won’t take plenty of time finding out how to use the rules in the Language Specification. Other programming languages, however, have double, triple, or ten times the number of rules.

The second part of Java — the API — can be intimidating because it’s so large. The API contains nearly 4,000 tools and keeps growing with each new Java language release. Pretty scary, eh? Well, the good news is that you don’t have to memorize anything in the API. Nothing. None of it.

You can look up the stuff you need to use in the documentation and ignore the stuff you don’t need. What you use often, you’ll remember. What you don’t use often, you’ll forget (like any other programmer).

No one knows all there is to know about the Java API. If you’re a Java programmer who frequently writes programs that open new windows, you know how to use the API JFrame class. If you seldom write programs that open windows, the first few times you need to create a window, you can look up the JFrame class in the API documentation.

If you took a typical Java programmer and kept that programmer from looking up anything in the API documentation, the programmer would probably be able to use less than 2 percent of all the tools in the Java API.

You may love the For Dummies style, but unfortunately, Java’s official API documentation isn’t written that way. The API documentation is both concise and precise.

In a way, nothing about the Java API is special. Whenever you write a Java program — even the smallest, simplest Java program — you create a class that’s on par with any of the classes defined in the official Java API.

The API is just a set of classes and other tools that were created by ordinary programmers who happen to participate in the official Java Community Process (JCP) and in the OpenJDK Project. Unlike the tools that you create, the tools in the API are distributed with every version of Java.

Visit the web if you’re interested in the JCP’s activities or the OpenJDK Project.

The folks at the JCP don’t keep the Java programs in the official Java API a secret. If you want, you can look at all these programs. When you install Java on your computer, the installation puts a file named src.zip on your hard drive. You can open src.zip with your favorite unzipping program. There, before your eyes, is all the Java API code.