The Importance of Sun's Java Documentation

Baldwin explains the use of Sun's Java documentation to help you realize the full potential of programming in Java.

Published:  June 29, 2003
By Richard G. Baldwin

Java Programming Notes # 2


I cannot overemphasize the importance of Sun's Java documentation to aspiring Java programmers.  The documentation package, which can be downloaded for installation and local access, or accessed online contains a wealth of information.

(Note that each time Sun releases a new version of the SDK, they also release a correspondingly new version of the documentation.  Therefore, as new versions are released, the above links will not take you to the latest version of the documentation.)

Since 1997, I have published several hundred Java tutorial lessons on and on my web site at  People often ask me how I have learned so much about Java without ever having attended a training course on Java.  The answer is simple.  I am completely self-taught insofar as Java is concerned.  Virtually everything that I know about Java, I have learned by studying Sun's Java documentation, and by experimenting with the information that I found there.  Virtually everything that you need to know about Java is provided by Sun in their documentation package.


Small core language, large class library

The Java programming environment consists of a small core programming language and a large class library. 

(As of the date of this writing, you can view The Java Language Specification online.  This specification will tell you just about everything that most programmers need to know about the core language.)

The size of the class library grows with the release of each new version of the SDK, because each new version provides capabilities that didn't exist in the previous version.  New capabilities are added through the addition of new classes and new interfaces to the library.

For example, the documentation for the J2SE 1.4.1 API alone consists of more than 6500 hyperlinked HTML files.  The complete documentation package for J2SE 1.4.1 consists of more than 8200 hyperlinked HTML files.

(This doesn't include classes in the libraries for J2EE and J2ME.)

Major capabilities reside in the class libraries

Once you understand how OOP is implemented in Java (see my Essence of OOP series of tutorial lessons) and you get beyond while loops, if statements, and other fundamental programming concepts, virtually all the power of Java resides in:

Download versus online versions

If you have the available required space on your disk, I strongly recommend that you download the documentation and install it locally on your disk.  This will make it possible for you access it more rapidly than accessing it on line, which may make you more inclined to use it.

However, to be more general, most of the references to the documentation in this tutorial will refer to the online version.  That will make this material available to all readers without presupposing that it has been downloaded and installed locally.

Top-level online documentation

As of the date of this writing, you can view the top-level page of the documentation for J2SE 1.4.1 at   (Once again, as Sun releases new versions of the SDK, they will establish new URLs for those new versions, and many of the links in this document may become broken.)

Subdivided into categories

When you view the top-level page, you will find a link bar at the top of the page that subdivides the documentation into the following categories:

Of these categories, you will probably most frequently make use of the API & Language category.  However, you should not ignore the other categories.  They will often contain information that you need, and they can make you more efficient in using the API documentation.

As you will see as you read through this lesson, there is other information in the documentation that doesn't fall in one of the categories listed above.  For example, if you have viewed the online version of the top-level page, you will have seen that there is a section entitled "J2SE Platform at a Glance" at the top of the page that provides a visual indication of how the Standard Edition is put together.


If you follow the Search link at the top of the page, (which is a two-step process), you will arrive at a search engine page that gives you the ability to do a keyword search on the online documentation.  (The context here is a search keyword and not a Java keyword, such as while.)  The search capability is fairly typical allowing you to search documents:

Very often, if you know how to describe what you are looking for, this search engine will provide you with a link to the documentation page that you need to view.

However, as is often the case with search engines, unless you are able to narrow your search appropriately, you are likely to get lots of hits that must be investigated.

Of particular interest to many of us is the capability to search for code samples from Sun that contain the keywords of interest.

New to Java Platform?

One of the categories in the online version that doesn't appear in the above list is a category for persons who are new to the Java programming environment.  This category is entitled "New to Java Platform?"  When you follow that link, you will open an online section of the documentation that Sun describes in the following way:

"What do you need to get started? Which Java technology should you use? This collection of links to articles, tutorials, online books, and software downloads helps you find what you need to start writing applications."

Needless to say, information of this sort can be extremely useful to persons who are just getting started with Java.

General Information

The General Information section of the documentation is subdivided into the following categories:

Downloading and installing Java

Of particular interest to most newcomers should be the Download section and the Installation section.

As an aside, if you are running Java under Windows and are having difficulty compiling and executing Java applications, your problem may have to do with the CLASSPATH environment variable.  For example, see the discussion at the following URL:

Pay particular attention to discussions involving the current directory at that URL.

API & Language

This section is subdivided into the following categories:

The first item in the above list is a link to the API Specification.  This is probably the most frequently used section of the entire documentation package.  I am going to put that discussion on hold for right now and come back to it later.

The second item in the above list contains some cautions for developers who may be inclined to use certain packages that may not exist in the future.

You can view or download the specifications for the core language and the virtual machine using the third and fourth items in this section.

Guide to Features - Java Platform

This section typically contains a summary of new features in the current release, plus a long list of links to many of the older features supported by Java.

For example, if you happen to be interested in data collections, you should click on the Collections Framework link.  That will take you to a page that describes The Collections Framework, including such items as:

Information of this sort can be extremely useful when you are just beginning to use a particular feature supported by Java.

Tool Docs

This section provides detailed information on Java tools such as:

For example, this would be a good place to look if you need to learn more about the relationship between the java compiler (javac) and the CLASSPATH environment variable. 

Demos, Tutorials, Training, and Reference

As the name suggests, this section contains links to numerous documents that can help you learn how to become a Java programmer.  This is in addition to the tutorials that you will find in the Guide to Features described above.  Some of the items in this section are available free of charge, and others must be purchased.

Now back to the Java 2 Platform API Specification

Earlier in the discussion under API & Language, I mentioned that the link to the API Specification is probably the most frequently used section of the entire documentation package.  I promised in that discussion that I would come back to the API Specification later.

Shortcuts on the desktop

As a practical matter, I keep two documentation shortcuts on my desktop.  One shortcut links to the top-level documentation installed on my machine.  The second shortcut links to the API Specification section of the documentation installed on my machine (you could do the same thing with the online version if you don't have room to install the documentation package locally).  Having these shortcuts on my desktop makes it quick and easy for me to access the documentation whenever I need to look something up, (which is a very frequent occurrence).

A screen shot

Figure 1 shows a partial screen shot of what you see when you first load the API Specification into your browser.  (This screen shot was adjusted and cropped to make it fit into this narrow publication format.)

Java Docs Screen Shot

Figure 1 API specification screen shot

API specification screen layout

The purpose of providing this partial screen shot is to give you an idea of the general layout of the material as it appears on your screen.  As you can see, the layout consists of three frames when viewed in your HTML browser.  (A version without frames is also available.)

The left-hand frames

The upper left-hand frame contains a list of packages.  The lower left-hand frame contains a list of the classes and interfaces that are contained in the package that is selected in the top left-hand frame.  You make selections in these two frames (or in the link bar at the top of the page) to control the contents of the right-hand frame.

The right-hand frame

When you first access the documentation (and when you select Overview at the top of the page), the right-hand frame contains summary information about all of the packages.

When you select a class in the lower left-hand frame, the right-hand frame contains hyperlinked information about that class, including:

The link bar at the top of the page

Despite the use of hyperlinks, it can still sometimes be difficult to find what you are looking for in the documentation package.  Referring back to Figure 1, you can see the beginning of a link bar at the top of the page in the right-hand frame.  This link bar contains the following hyperlinks:

The various pages that are displayed by selecting these hyperlinks can often help you to find what you are looking for.  Probably the most useful and frequently consulted item in the above list is the Index.

The alphabetical index

The alphabetical index can be extremely useful if you know the full or partial spelling of what you are looking for, beginning with the first character.

For example, assume that you remember (or you can surmise from what you know about Java properties) that there is a method whose name begins with getSystemLookAndFeel, which returns the name of the LookAndFeel class that implements the native look and feel for a particular operating system.  You can easily look this up under G in the alphabetical index.

What you will find when you look it up is a brief description of a method named getSystemLookAndFeelClassName, which matches what you are looking for.  The name of the method is also a hyperlink to the detailed description of the same method as it appears in the documentation for the class named UIManager.

A weakness in the documentation

Unfortunately, there is a major weakness in the search capabilities of the documentation package.  If you don't know the spelling, beginning with the first character, there is no good way to search the documentation without using outside resources.

For example, assume that you remember (or you can surmise from what you know about Java properties) that there is a method whose name includes the characters SystemLookAndFeel, which returns the name of the LookAndFeel class that implements the native look and feel for a particular operating system.  You cannot easily look up the name of the method in the alphabetical index, because you don't know the first character in the method name.

HTML files are text files

The documentation consists of a large number of HTML files.  Because these are simply text files, you can attempt to locate what you need by applying a text search program to those HTML files after you install the documentation on your system.

Using a GREP program

If you are unfamiliar with GREP programs, go to and search for GREP.  You should find several downloadable GREP programs, an interesting one of which is located at

If you have downloaded and installed Sun's Java documentation on your system, you can use a GREP program to search for keywords in the HTML files that constitute the documentation package.

A GREP search example

For example, by using a typical GREP program to search for the keyword SystemLookAndFeel in the j2sdk1.4.1_02\docs\API\index-files folder on my hard drive, I was able to quickly determine that the documentation file named index-7.html contains a hyperlink to "../javax/swing/UIManager.html#getSystemLookAndFeelClassName()".   That is all that I needed to know to go the UIManager class and look up the method named getSystemLookAndFeelClassName.

If I didn't know to search for SystemLookAndFeel, but instead searched simply for LookAndFeel, I would get a fairly large number of hits from the GREP program, but it would still be practical to examine them in an attempt to recognize the name of the method that I was looking for.

In that case, I probably would have noticed rather quickly that there are a large number of links to the page that describes the UIManager class.  I probably would have gone to the documentation for the UIManager class to manually examine the methods in that class before examining all of the hits produced by the GREP program.


There are several ways to search for useful information in the Sun documentation.  There is no single approach that will solve all of your needs to find information in the documentation. You simply need to become familiar with the different ways to search for information in the documentation and be prepared to use the approach that does the best job in each situation.

Copyright 2003, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.

About the author

Richard Baldwin is a college professor (at Austin Community College in Austin, TX) and private consultant whose primary focus is a combination of Java, C#, and XML. In addition to the many platform and/or language independent benefits of Java and C# applications, he believes that a combination of Java, C#, and XML will become the primary driving force in the delivery of structured information on the Web.

Richard has participated in numerous consulting projects, and he frequently provides onsite training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin's Programming Tutorials, which has gained a worldwide following among experienced and aspiring programmers. He has also published articles in JavaPro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.