Guide to the Source Directory Structure
This directory contains one sub-directory for each chapter of the
book.  These sub-directories hold the .java files for the various
examples and exercises in each chapter. For instance, the directory
Common contains the file Nothing.java, which is referred to in
Chapter 2: Common Program Components.

In some cases, additional sub-directories have been created beneath
the individual chapter directories. For instance, for Chapter 3, the
directory Creating contains sub-directories Bank and Ships. These
collect related groups of examples and exercises.

In order to run many of these examples, additional .class files are
required. These supply, for instance, GUI functionality. The
corresponding .java sources of these classes may be found in "src"
sub-directories, such as the Creating/Bank/src and
Creating/Ships/src.  These sources typically contain more complex
features of Java than will have been covered at that stage of the
book.

The utilities directory contains packaged versions of several of
these GUI classes, and javadoc documentation on them. The .class
files for this package are stored in utilities.jar.

Applets     - Chapter 20: Applets
Arrays      - Chapter  9: Arrays and Further Statements
AWT         - Chapter 16: AWT Applications
Bits        - Chapter  1: Bits, Bytes, and Java
Collections - Chapter 10: Collection Classes
Common      - Chapter  2: Common Program Components
Creating    - Chapter  3: Creating and Using Objects
Defining    - Chapter  4: Defining Classes
Exceptions  - Chapter 11: Exceptions
IO          - Chapter 12: Input-Output
Inheritance - Chapter 14: Class Inheritance
Interfaces  - Chapter 13: Interfaces
Nested      - Chapter 15: Abstract and Nested Classes
Networks    - Chapter 19: Networking
Packages    - Chapter  8: Packages and Utility Classes
Repetition  - Chapter  7: Adding Repetitive Behavior
Selection   - Chapter  6: Adding Selective Behavior
Sequence    - Chapter  5: Adding Sequential Behavior
Simulation  - Chapter 21: Simulation
Swing       - Chapter 17: Swing
Threads     - Chapter 18: Threads

utilities - utility classes, such as SimpleInput
utilities.jar - JAR file of utility classes.


A Note on Classpaths
====================
The Java compiler and interpreter use classpath information to
determine where to look for the sources and .class files comprising a
program. Unfortunately, getting the classpath right can be a source
of great confusion. Most, if not all, of these example programs
assume that the source and associated .class files are held in the
same folder.  That is, little use is made of packages, in order to
simplify issues surrounding classpaths. As the Java 2 Platform is
able to locate its own classes, no it should not be necessary to set
a classpath in order to run the programs accompanying this book.
This is because, if no explicit classpath has been set within the
host environment, both the compiler and interpreter will look for
files in the current folder - referred to as . (dot).

However, in many environments, a classpath will have been set by
other programs that have associated Java packages. Where this is the
case, neither the compiler nor the interpreter will look for files in
the current folder, unless dot is explicitly included in the
classpath.

Consider the case of the Hello.java file in the Common folder. If an
attempt to run this program with the interpreter, thus

    java Hello

results in the error message

    Exception in thread "main" java.lang.NoClassDefFoundError: Hello

but the file Hello.class clearly exists within the current folder,
try the following:

    java -classpath . Hello

If this works, then it suggests that your environment already
includes a setting for classpath, but that this does not include
dot.

There are two alternatives available to you:

    + When you compile and run the programs from this book, always
    include the -classpath directive to the compiler and
    interpreter.

    + Amend the setting of the classpath environment variable, so
    that it includes an explicit dot. You should be aware that this
    could affect the running of existing programs that use the same
    environment variable.  However, this method is the most
    convenient.

The change you need to make to your environment depends upon the
operating system you are using.

On Windows 95 and 98 systems, use a text editor to add the following
line to the end of your autoexec.bat file. This file is usually to be
found at the root level of the C: drive

    set classpath=%classpath%;.;

On Windows NT systems, you will need to amend the setting from the
Control Panel. Select:

    My Computer/Control Panel/System/Environment

find the classpath variable, and append a dot to it. This should be
separated from any existing settings with a semicolon.

On UNIX and Linux systems, where to set the CLASSPATH variable
depends upon the shell you are using. For instance, csh users should
edit their .cshrc file and bash users should edit their .bashrc file.
At the end of a .cshrc file, for instance, you might add the
following line:

    setenv CLASSPATH "$CLASSPATH:."

Note that a colon (:) is used as the separator on UNIX systems,
whereas semicolon (;) is used on Windows systems.


Date of last update: 17th November 1999