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
Gamelan.com and on my
web site at www.DickBaldwin.com.
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 http://java.sun.com/j2se/1.4.1/docs/index.html.
(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.
Search
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:
http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/classpath.html
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.)
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 http://www.google.com/ and search for
GREP. You should find several downloadable GREP programs, an interesting
one of which is located at http://www.wingrep.com/.
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.
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.
-end-