More Java

School of Computer Science

University of KwaZulu-Natal

February 10, 2008

1
 C ONTENTS

Contents 1

1 Introduction to Objects 7
1.1 What is Object Oriented Programming? . . . . . . . . . . . . . . . . . . . . . . . . . 7
Object Orientation as a New Paradigm: The Big Picture . . . . . . . . . . . . . . . . 8
1.2 Fundamentals of Objects and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Objects and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Class Members and Instance Members . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Creating and Destroying Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Everything is NOT an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.3 Introduction to Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.4 Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.5 Creating Jar Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
APIs and Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
1.6 Mixing Static and Non-static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Static Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

2 Object Oriented Analysis and Design 39

2.1 Introduction to Software Engineering . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Software Engineering Life-Cycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Object-oriented Analysis and Design . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Documenting Designs: The Unified Modelling Language . . . . . . . . . . . . . . . 43
2.2 A Case Study: Card Games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.3 Creating Abstractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Designing the classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Black Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Preconditions and Postconditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.4 Example: A Simple Card Game . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3 Nested Classes 63
3.1 Nested Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.2 Example of Inner Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.3 Anonymous Inner Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

4 Inheritance 71

5 Abstract Classes and Polymorphism 81

1
 5.1 Abstract Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
5.2 Polymorphism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
More Polymorphism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

6 Graphical User Interfaces in JAVA 101

6.1 Introduction: The Modern User Interface . . . . . . . . . . . . . . . . . . . . . . . . 101
6.2 The Basic GUI Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
JFrame and JPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Components and Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Events and Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.3 Applets and HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
JApplet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Reusing Your JPanels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Applets on Web Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.4 Graphics and Painting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
6.5 Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
MouseEvent and MouseListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Anonymous Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.6 Basic Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
JButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
JLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
JCheckBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
JTextField and JTextArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.7 Basic Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Basic Layout Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
A Simple Calculator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
A Little Card Game . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.8 Images and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Image File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

7 A Solitaire Game - Klondike 151

7.1 Klondike Solitaire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.2 Card Games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
The CardNames Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
The Deck class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.3 Implementation of Klondike . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
The CardPile class (the base class) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
The Solitaire class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Completing the Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

8 Generic Programming 161

8.1 Generic Programming in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8.2 ArrayLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

2
 8.3 Parameterized Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
8.4 The Java Collection Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.5 Iterators and for-each Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
8.6 Equality and Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
8.7 Generics and Wrapper Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.8 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

9 Correctness and Robustness 177

9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Horror Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Java to the Rescue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Problems Remain in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
9.2 Writing Correct Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Provably Correct Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Robust Handling of Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
9.3 Exceptions and try..catch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Exceptions and Exception Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
The try Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Throwing Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Mandatory Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Programming with Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
9.4 Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

10 Input and Output 197

10.1 Streams, Readers, and Writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Character and Byte Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
PrintWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Data Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Reading Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
The Scanner Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
10.2 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Reading and Writing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
10.3 Programming With Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Copying a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

3
 P REFACE
These notes are intended for a Second course in Object-Oriented Programming with Java. It is
assumed that students have taken a first year course in Programming and are familiar with ba-
sic (procedural) programming and introductory object-based programming in Java. The student
should be familiar with the various control constucts, Arrays (one and two dimensional), the con-
cepts of class and object, input/output and the concept of classes and objects.
Theses notes are, in the most part, taken from David J. Eck’s online book Introduction to
Programming Using Java, Version 5.0, December 2006. The online book is available at
http://math.hws.edu/javanotes/ .
We’ve refactored and used in whole or parts of Chapters 4, 5, 6, 8, 9, 10, and 11. Subsections
of some these chapters were ommitted, minor editing changes were made and a few subsections
were added. A notable change has been the use of the Scanner class and the printf method
for input and output.
Some sections were also taken from “Introduction to Computer Science using Java Java 5.0
version, January 2006” by Bradley Kjell, Central Connecticut State University.
The sections on UML (chapter 6) were adapted from the user manual of the UML tool: Um-
brello (http://docs.kde.org/stable/en_GB/kdesdk/umbrello/).
The definitions of various software engineering terms and concepts were adapted from wikipedia
(http://wikipedia.org/).
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License. (This li-
cense allows you to redistribute this book in unmodified form. It allows you to make and distribute
modified versions, as long as you include an attribution to the original author, clearly describe the
modifications that you have made, and distribute the modified work under the same license as the
original. See the http://creativecommons.org/licenses/by-sa/2.5/ for full details.)
The LATEX source for these notes are available on request.

5
 CHAPTER 1
I NTRODUCTION TO O BJECTS
O BJECT- ORIENTED PROGRAMMING (OOP) represents an attempt to make programs more closely
model the way people think about and deal with the world. In the older styles of programming,
a programmer who is faced with some problem must identify a computing task that needs to be
performed in order to solve the problem. Programming then consists of finding a sequence of in-
structions that will accomplish that task. But at the heart of object-oriented programming, instead
of tasks we find objects – entities that have behaviors, that hold information, and that can interact
with one another. Programming consists of designing a set of objects that model the problem at
hand. Software objects in the program can represent real or abstract entities in the problem do-
main. This is supposed to make the design of the program more natural and hence easier to get
right and easier to understand.
An object-oriented programming language such as JAVA includes a number of features that
make it very different from a standard language. In order to make effective use of those features,
you have to “orient” your thinking correctly.

1.1 What is Object Oriented Programming?

O BJECT- ORIENTATION 1 is a set of tools and methods that enable software engineers to build
reliable, user friendly, maintainable, well documented, reusable software systems that fulfills the
requirements of its users. It is claimed that object-orientation provides software developers with
new mind tools to use in solving a wide variety of problems. Object-orientation provides a new
view of computation. A software system is seen as a community of objects that cooperate with
with each other by passing messages in solving a problem.
An object-oriented programming laguage provides support for the following object-oriented
concepts:

Objects and Classes

Inheritance
1 This discussion is based on Chapter 2 of An Introduction to Object-Oriented Programming by Timothy Budd.

7
 Polymophism and Dynamic binding

Object Orientation as a New Paradigm: The Big Picture

It is claimed that the problem-solving techniques used in object-oriented programming more
closely models the way humans solve day-to-day problems.2
So lets consider how we solve an everyday problem: Suppose you wanted to send flowers to
a friend named Robin who lives in another city.To solve this problem you simply walk to your
nearest florist run by, lets say, Fred. You tell Fred the kinds of flowers to send and the address to
which they should be delivered. You can be assured that the flowers will be delivered.
Now, lets examine the mechanisms used to solve your problem.

• You first found an appropriate agent (Fred, in this case) and you passed to this agent a
message containing a request.

• It is the responsibility of Fred to satisfy the request.

• There is some method (an algorithm or set of operations) used by Fred to do this.

• You do not need to know the particular methods used to satisfy the request—such informa-
tion is hidden from view.

Off course, you do not want to know the details, but on investigation you may find that Fred
delivered a slightly different message to another florist in the city where your friend Robin lives.
That florist then passes another message to a subordinate who makes the floral arrangement.The
flowers, along with yet another message, is passed onto a delivery person and so on. The florists
also has interactions with wholesalers who, in turn, had interactions with flower growers and so
on.
This leads to our first conceptual picture of object-oriented programming:

An object-oriented program is structured as community of interacting agents called

objects. Each object has a role to play. Each object provides a service or performs
an action that is used by other members of the community.

Messages and Responsibilities

Members of an object-oriented community make requests of each other. The next important prin-
ciple explains the use of messages to initiate action:

Action is initiated in object-oriented programming by the transmission of a message to

an agent (an object) responsible for the actions. The message encodes the request for
an action and is accompanied by any additional information (arguments/parameters)
needed to carry out the request. The receiver is the object to whom the message is
sent. If the receiver accepts the message, it accepts responsibility to carry out the
indicated action. In response to a message, the receiver will perform some method to
satisfy the request.

There are some important issues to point out here:

• The client sending the request need not know the means by which the request is carried out.
In this we see the principle of information hiding.
2 This discussion is based on Chapter 2 of An Introduction to Object-Oriented Programming by Timothy Budd.

8
 • Another principle implicit in message passing is the idea of finding someone else to do the
work i.e. reusing components that may have been written by someone else.

• The interpretation of the message is determined by the receiver and can vary with different
receivers. For example, if you sent the message “deliver flowers” to a friend, she will
probably have understood what was required and flowers would still have been delivered
but the method she used would have been very different from that used by the florist.

• In object-oriented programming, behaviour is described in terms of responsibilities.

• Client’s requests for actions only indicates the desired outcome. The receivers are free to
pursue any technique that achieves the desired outcomes.

• Thinking in this way allows greater independence between objects.

• Thus, objects have responsibilities that they are willing to fulfill on request. The collection
of reponsibilities associated with an object is often called a protocol.

Classes and Instances

The next important principle of object-oriented programming is

All objects are instances of a class. The method invoked by an object in response to a
message is determined by the class of the receiver. All objects of a given class use the
same method in response to similar messages.

Fred is an instance of a category or class of people i.e. Fred is an instance of a class of florists.
The term florist represents a class or category of all florists. Fred is an object or instance of a class.
We interact with instances of a class but the class determines the behaviour of instances. We
can tell a lot about how Fred will behave by understanding how Florists behave. We know, for
example, that Fred, like all florists can arrange and deliver flowers.
In the real world there is this distinction between classes and objects. Real-world objects share
two characteristics: They all have state and behavior. For example, dogs have state (name, color,
breed, hungry) and behavior (barking, fetching, wagging tail). Students have state (name, student
number, courses they are registered for, gender) and behavior (take tests, attend courses, write
tests, party).

1.2 Fundamentals of Objects and Classes

We move now from the conceptual picture of objects and classes to a discussion of software classes
and objects.3
Objects are closely related to classes. A class can contain variables and methods. If an object
is also a collection of variables and methods, how do they differ from classes?

Objects and Classes

Objects
In object-oriented programming we create software objects that model real world objects. Soft-
ware objects are modeled after real-world objects in that they too have state and behavior. A
3 This discussion is based on the “Object-oriented Programming Concepts” section of the Java Tutorial by Sun
MicroSystems.

9
 Figure 1.1: An Object

software object maintains its state in one or more variables. A variable is an item of data named
by an identifier. A software object implements its behavior with methods. A method is a function
associated with an object.

Definition: An object is a software bundle of variables and related methods.

An object is also known as an instance. An instance refers to a particular object. For e.g.
Karuna’s bicycle is an instance of a bicycle—It refers to a particular bicycle. Sandile Zuma is an
instance of a Student.
The variables of an object are formally known as instance variables because they contain the
state for a particular object or instance. In a running program, there may be many instances of an
object. For e.g. there may be many Student objects. Each of these objects will have their own
instance variables and each object may have different values stored in their instance variables. For
e.g. each Student object will have a different number stored in its StudentNumber variable.

Encapsulation
Object diagrams show that an object’s variables make up the center, or nucleus, of the object.
Methods surround and hide the object’s nucleus from other objects in the program. Packaging an
object’s variables within the protective custody of its methods is called encapsulation.
Encapsulating related variables and methods into a neat software bundle is a simple yet pow-
erful idea that provides two benefits to software developers:

• Modularity: The source code for an object can be written and maintained independently of
the source code for other objects. Also, an object can be easily passed around in the system.
You can give your bicycle to someone else, and it will still work.

• Information-hiding: An object has a public interface that other objects can use to communi-
cate with it. The object can maintain private information and methods that can be changed
at any time without affecting other objects that depend on it.

Messages
Software objects interact and communicate with each other by sending messages to each other.
When object A wants object B to perform one of B’s methods, object A sends a message to object
B
There are three parts of a message: The three parts for the message
System.out.println{‘‘Hello World’’}; are:

10
 Figure 1.2: A Message

• The object to which the message is addressed (System.out)

• The name of the method to perform (println)

• Any parameters needed by the method (“Hello World!”)

Classes
In object-oriented software, it’s possible to have many objects of the same kind that share charac-
teristics: rectangles, employee records, video clips, and so on. A class is a software blueprint for
objects. A class is used to manufacture or create objects.
The class declares the instance variables necessary to contain the state of every object. The
class would also declare and provide implementations for the instance methods necessary to oper-
ate on the state of the object.

Definition: A class is a blueprint that defines the variables and the methods common
to all objects of a certain kind.

After you’ve created the class, you can create any number of objects from that class.
A class is a kind of factory for constructing objects. The non-static parts of the class specify,
or describe, what variables and methods the objects will contain. This is part of the explanation of
how objects differ from classes: Objects are created and destroyed as the program runs, and there
can be many objects with the same structure, if they are created using the same class.

Types
JAVA, like most programming languages classifies values and expressions into types. For e.g.
String’s and int’s are types. A type basically specifies the allowed values and allowed opera-
tions on values of that type.

Definition: A type is a set of values together with one or more operations that can be
applied uniformly to all these values.

A type system basically gives meaning to collections of bits. Because any value simply con-
sists of a set of bits in a computer, the hardware makes no distinction between memory addresses,

11
instruction code, characters, integers and floating-point numbers. Types inform programs and
programmers how they should treat those bits.
For example the integers are a type with values in the range −2, 147, 483, 648 t o +2, 147, 483, 647
and various allowed operations that include addition, subtraction, modulus etc.
The use of types by a programming language has several advantages:

• Safety. Use of types may allow a compiler to detect meaningless or invalid code. For
example, we can identify an expression "Hello, World" / 3 as invalid because one cannot
divide a string literal by an integer. Strong typing offers more safety.

• Optimization. Static type-checking may provide useful information to a compiler. The

compiler may then be able to generate more efficient code.

• Documentation. Types can serve as a form of documentation, since they can illustrate the
intent of the programmer. For instance, timestamps may be a subtype of integers – but if a
programmer declares a method as returning a timestamp rather than merely an integer, this
documents part of the meaning of the method.

• Abstraction. Types allow programmers to think about programs at a higher level, not both-
ering with low-level implementation. For example, programmers can think of strings as
values instead of as a mere array of bytes.

There are fundamentally two types in JAVA: primitive types and objects types i.e. any variable
you declare are either declared to be one of the primitive types or an object type. int, double
and char are the built-in, primitive types in JAVA.
The primitive types can be used in various combinations to create other, composite types.
Every time we define a class, we are actually defining a new type. For example, the Student
class defined above introduces a new type. We can now use this type like any other type: we can
declare variables to be of this type and we can use it as a type for parameters of methods.
Before a variable can be used, it must be declared. A declaration gives a variable a name, a type
and an initial value for e.g. int x = 8 declares x to be of type int. All objects that we declare
also have to be of a specified type—the type of an object is the class from which it is created.
Thus, when we declare objects we state the type like so: Student st = new Student();.
This statement declares the variable st to be of type Student. This statement creates a new
object of the specified type and runs the Student constructor. The constructor’s job is to properly
initialize the object.
The String type is another example of an object type. Student and String are composite
types and give us the same advantages as the built-in types. The ability to create our own types is
a very powerful idea in modern languages.
When declaring variables, we can assign initial values. If you do not specify initial values, the
compiler automatically assigns one: Instance variables of numerical type (int, double, etc.) are
automatically initialized to zero; boolean variables are initialized to false; and char variables,
to the Unicode character with code number zero. The default initial value of object types is null.

Class Members and Instance Members

A class definition is made of members or components. A class can define variables (or fields) and
methods. Variables and methods can be static or non-static i.e. they are defined with or without
the keyword static.
e.g.
static double lastStudentNumber; //a static member/variable/field

12
 double studentNumber; //a non−static variable

static void printLastNumber() {...} //a static member/method

void printNumber() {...} //a non−static method

The non-static members of a class (variables and methods) are also known as instance variables
and methods while the non-static members are also known as class variables and class methods.
Each instance of a class (each object) gets its own copy of all the instance variables defined in the
class. When you create an instance of a class, the system allocates enough memory for the object
and all its instance variables.
In addition to instance variables, classes can declare class variables. A class variable contains
information that is shared by all instances (objects) of the class. If one object changes the variable,
it changes for all other objects of that type. e.g. A Student number generator in a NewStudent
class.
You can invoke a class method directly from the class, whereas you must invoke instance
methods on a particular instance. e.g. The methods in the Math class are static and can be invoked
without creating an instance of the Math class for e.g. we can say Math.sqrt(x).
Consider a simple class whose job is to group together a few static member variables for
example a class could be used to store information about the person who is using the program:
class UserData { static String name; static int age; }

In programs that use this class, there is one copy each of the variables UserData.name and
UserData.age. There can only be one “user,” since we only have memory space to store data
about one user. The class, UserData, and the variables it contains exist as long as the program
runs. Now, consider a similar class that includes non-static variables:
class PlayerData { String name; int age; }

In this case, there is no such variable as PlayerData.name or PlayerData.age, since

name and age are not static members of PlayerData. There is nothing much in the class except
the potential to create objects. But, it’s a lot of potential, since it can be used to create any number
of objects! Each object will have its own variables called name and age. There can be many
“players” because we can make new objects to represent new players on demand. A program
might use this class to store information about multiple players in a game. Each player has a name
and an age. When a player joins the game, a new PlayerData object can be created to represent
that player. If a player leaves the game, the PlayerData object that represents that player can
be destroyed. A system of objects in the program is being used to dynamically model what is
happening in the game. You can’t do this with “static” variables!
An object that belongs to a class is said to be an instance of that class and the variables that
the object contains are called instance variables. The methods that the object contains are
called instance methods.
For example, if the PlayerData class, is used to create an object, then that object is an
instance of the PlayerData class, and name and age are instance variables in the object. It is
important to remember that the class of an object determines the types of the instance variables;
however, the actual data is contained inside the individual objects, not the class. Thus, each object
has its own set of data.
The source code for methods are defined in the class yet it’s better to think of the instance
methods as belonging to the object, not to the class. The non-static methods in the class merely
specify the instance methods that every object created from the class will contain. For example
a draw() method in two different objects do the same thing in the sense that they both draw
something. But there is a real difference between the two methods—the things that they draw can
be different. You might say that the method definition in the class specifies what type of behavior

13
the objects will have, but the specific behavior can vary from object to object, depending on the
values of their instance variables.
The static and the non-static portions of a class are very different things and serve very different
purposes. Many classes contain only static members, or only non-static. However, it is possible
to mix static and non-static members in a single class. The “static” definitions in the source
code specify the things that are part of the class itself, whereas the non-static definitions in the
source code specify things that will become part of every instance object that is created from
the class. Static member variables and static member methods in a class are sometimes called
class variables and class methods, since they belong to the class itself, rather than to
instances of that class.
So far, we’ve been talking mostly in generalities. Let’s now look at a specific example to see
how classes and objects work. Consider this extremely simplified version of a Student class,
which could be used to store information about students taking a course:
public class Student {

public String name; // Student’s name. public double test1,

test2, test3; // Grades on three tests.

public double getAverage() { // compute average test grade return

(test1 + test2 + test3) / 3; }

}// end of class Student

None of the members of this class are declared to be static, so the class exists only for
creating objects. This class definition says that any object that is an instance of the Student class
will include instance variables named name, test1, test2, and test3, and it will include an
instance method named getAverage(). The names and tests in different objects will generally
have different values. When called for a particular student, the method getAverage() will com-
pute an average using that student’s test grades. Different students can have different averages.
(Again, this is what it means to say that an instance method belongs to an individual object, not to
the class.)
In JAVA, a class is a type, similar to the built-in types such as int and boolean. So, a class
name can be used to specify the type of a variable in a declaration statement, the type of a formal
parameter, or the return type of a method. For example, a program could define a variable named
std of type Student with the statement
Student std;
However, declaring a variable does not create an object! This is an important point, which is
related to this Very Important Fact:

In JAVA, no variable can ever hold an object. A variable can only hold a reference to
an object.

You should think of objects as floating around independently in the computer’s memory. In
fact, there is a special portion of memory called the heap where objects live. Instead of holding
an object itself, a variable holds the information necessary to find the object in memory. This
information is called a reference or pointer to the object. In effect, a reference to an object is the
address of the memory location where the object is stored. When you use a variable of class type,
the computer uses the reference in the variable to find the actual object.
In a program, objects are created using an operator called new, which creates an object and
returns a reference to that object. For example, assuming that std is a variable of type Student,
declared as above, the assignment statement

14
 std = new Student();
would create a new object which is an instance of the class Student, and it would store a reference
to that object in the variable std. The value of the variable is a reference to the object, not the
object itself. It is not quite true to say that the object is the “value of the variable std”. It
is certainly not at all true to say that the object is “stored in the variable std.” The proper
terminology is that “the variable std refers to the object,”.
So, suppose that the variable std refers to an object belonging to the class Student. That
object has instance variables name, test1, test2, and test3. These instance variables can
be referred to as std.name, std.test1, std.test2, and std.test3. This follows the usual
naming convention that when B is part of A, then the full name of B is A.B. For example, a program
might include the lines
System.out.println("Hello, " + std.name + ". Your test grades are:");
System.out.println(std.test1);
System.out.println(std.test2);
System.out.println(std.test3);
This would output the name and test grades from the object to which std refers. Sim-
ilarly, std can be used to call the getAverage() instance method in the object by saying
std.getAverage(). To print out the student’s average, you could say:
System.out.println( "Your average is " + std.getAverage() );
More generally, you could use std.name any place where a variable of type String is
legal. You can use it in expressions. You can assign a value to it. You can pass it as a pa-
rameter to method. You can even use it to call methods from the String class. For example,
std.name.length() is the number of characters in the student’s name.
It is possible for a variable like std, whose type is given by a class, to refer to no object at all.
We say in this case that std holds a null reference. The null reference is written in JAVA as
“null”. You can store a null reference in the variable std by saying “std = null;” and you
could test whether the value of “std” is null by testing “if (std == null) . . .”.
If the value of a variable is null, then it is, of course, illegal to refer to instance variables or
instance methods through that variable–since there is no object, and hence no instance variables
to refer to. For example, if the value of the variable st is null, then it would be illegal to refer
to std.test1. If your program attempts to use a null reference illegally like this, the result is an
error called a null pointer exception.
Let’s look at a sequence of statements that work with objects:
Student std, std1, // Declare four variables of
std2, std3; // type Student.
std = new Student(); // Create a new object belonging
// to the class Student, and
// store a reference to that
// object in the variable std.
std1 = new Student(); // Create a second Student object
// and store a reference to
// it in the variable std1.
std2 = std1; // Copy the reference value in std1
// into the variable std2.
std3 = null; // Store a null reference in the
// variable std3.

std.name = "John Smith"; // Set values of some instance variables.

std1.name = "Mary Jones";

15
 // (Other instance variables have default
// initial values of zero.)

After the computer executes these statements, the situation in the computer’s memory looks
like this:

This picture shows variables as little boxes, labeled with the names of the variables. Objects
are shown as boxes with round corners. When a variable contains a reference to an object, the
value of that variable is shown as an arrow pointing to the object. The variable std3, with a value
of null, doesn’t point anywhere. The arrows from std1 and std2 both point to the same object.
This illustrates a Very Important Point:

When one object variable is assigned to another, only a reference is copied. The
object referred to is not copied.

When the assignment “std2 = std1;” was executed, no new object was created. Instead,
std2 was set to refer to the very same object that std1 refers to. This has some consequences
that might be surprising. For example, std1.name and std2.name are two different names for
the same variable, namely the instance variable in the object that both std1 and std2 refer to.
After the string “Mary Jones” is assigned to the variable std1.name, it is also be true that the
value of std2.name is “Mary Jones”. There is a potential for a lot of confusion here, but you
can help protect yourself from it if you keep telling yourself, “The object is not in the variable.
The variable just holds a pointer to the object.”
You can test objects for equality and inequality using the operators == and !=, but here again,
the semantics are different from what you are used to. The test “if (std1 == std2)”, tests
whether the values stored in std1 and std2 are the same. But the values are references to objects,
not objects. So, you are testing whether std1 and std2 refer to the same object, that is, whether
they point to the same location in memory. This is fine, if its what you want to do. But sometimes,
what you want to check is whether the instance variables in the objects have the same values. To
do that, you would need to ask whether
std1.test1 == std2.test1 && std1.test2 == std2.test2 && std1.test3
== std2.test3 && std1.name.equals(std2.name)}

16
 I’ve remarked previously that Strings are objects, and I’ve shown the strings “Mary Jones”
and “John Smith” as objects in the above illustration. A variable of type String can only hold
a reference to a string, not the string itself. It could also hold the value null, meaning that it does
not refer to any string at all. This explains why using the == operator to test strings for equality is
not a good idea.
The fact that variables hold references to objects, not objects themselves, has a couple of other
consequences that you should be aware of. They follow logically, if you just keep in mind the
basic fact that the object is not stored in the variable. The object is somewhere else; the variable
points to it.
Suppose that a variable that refers to an object is declared to be final. This means that the
value stored in the variable can never be changed, once the variable has been initialized. The value
stored in the variable is a reference to the object. So the variable will continue to refer to the same
object as long as the variable exists. However, this does not prevent the data in the object from
changing. The variable is final, not the object. It’s perfectly legal to say
final Student stu = new Student();

stu.name = "John Doe"; // Change data in the object;

// The value stored in stu is not changed!
// It still refers to the same object.
Next, suppose that obj is a variable that refers to an object. Let’s consider what happens
when obj is passed as an actual parameter to a method. The value of obj is assigned to a formal
parameter in the method, and the method is executed. The method has no power to change the
value stored in the variable, obj. It only has a copy of that value. However, that value is a reference
to an object. Since the method has a reference to the object, it can change the data stored in the
object. After the method ends, obj still points to the same object, but the data stored in the object
might have changed. Suppose x is a variable of type int and stu is a variable of type Student.
Compare:
void dontChange(int z) { void change(Student s) {
z = 42; s.name = "Fred";
} }

The lines: The lines:

x = 17; stu.name = "Jane";

dontChange(x); change(stu);
System.out.println(x); System.out.println(stu.name);

outputs the value 17. outputs the value "Fred".

The value of x is not The value of stu is not changed ,

changed by the method, but stu.name is.
which is equivalent to This is equivalent to

z = x; s = stu;
z = 42; s.name = "Fred";

Access Control
When writing new classes, it’s a good idea to pay attention to the issue of access control. Recall
that making a member of a class public makes it accessible from anywhere, including from other
classes. On the other hand, a private member can only be used in the class where it is defined.

17
 In the opinion of many programmers, almost all member variables should be declared private.
This gives you complete control over what can be done with the variable. Even if the variable it-
self is private, you can allow other classes to find out what its value is by providing a public
accessor method that returns the value of the variable. For example, if your class contains a
private member variable, title, of type String, you can provide a method
public String getTitle() { return title; }
that returns the value of title. By convention, the name of an accessor method for a variable
is obtained by capitalizing the name of variable and adding “get” in front of the name. So, for
the variable title, we get an accessor method named “get” + “Title”, or getTitle(). Because
of this naming convention, accessor methods are more often referred to as getter methods. A
getter method provides “read access” to a variable.
You might also want to allow “write access” to a private variable. That is, you might want
to make it possible for other classes to specify a new value for the variable. This is done with
a setter method. (If you don’t like simple, Anglo-Saxon words, you can use the fancier term
mutator method.) The name of a setter method should consist of “set” followed by a capitalized
copy of the variable’s name, and it should have a parameter with the same type as the variable. A
setter method for the variable title could be written
public void setTitle( String newTitle ) { title = newTitle; }
It is actually very common to provide both a getter and a setter method for a private member
variable. Since this allows other classes both to see and to change the value of the variable, you
might wonder why not just make the variable public? The reason is that getters and setters are
not restricted to simply reading and writing the variable’s value. In fact, they can take any action
at all. For example, a getter method might keep track of the number of times that the variable has
been accessed:
public String getTitle() {
titleAccessCount++; //Increment member variable titleAccessCount.
return title;
}
and a setter method might check that the value that is being assigned to the variable is legal:
public void setTitle( String newTitle ) {
if ( newTitle == null ) //Don’t allow null strings as titles!
title = "(Untitled)"; // Use an appropriate default value instead.
else
title = newTitle; }
Even if you can’t think of any extra chores to do in a getter or setter method, you might change
your mind in the future when you redesign and improve your class. If you’ve used a getter and
setter from the beginning, you can make the modification to your class without affecting any of
the classes that use your class. The private member variable is not part of the public interface
of your class; only the public getter and setter methods are. If you haven’t used get and set from
the beginning, you’ll have to contact everyone who uses your class and tell them, “Sorry guys,
you’ll have to track down every use that you’ve made of this variable and change your code.”

Creating and Destroying Objects

Object types in JAVA are very different from the primitive types. Simply declaring a variable
whose type is given as a class does not automatically create an object of that class. Objects must
be explicitly constructed. For the computer, the process of constructing an object means, first,
finding some unused memory in the heap that can be used to hold the object and, second, filling

18
in the object’s instance variables. As a programmer, you don’t care where in memory the object
is stored, but you will usually want to exercise some control over what initial values are stored
in a new object’s instance variables. In many cases, you will also want to do more complicated
initialization or bookkeeping every time an object is created.

Initializing Instance Variables

An instance variable can be assigned an initial value in its declaration, just like any other variable.
For example, consider a class named PairOfDice. An object of this class will represent a pair of
dice. It will contain two instance variables to represent the numbers showing on the dice and an
instance method for rolling the dice:
public class PairOfDice {

public int die1 = 3; // Number showing on the first die.

public int die2 = 4; // Number showing on the second die.

public void roll() {

// Roll the dice by setting each of the dice to be
// a random number between 1 and 6.
die1 = (int)(Math.random()*6) + 1;
die2 = (int)(Math.random()*6) + 1;
}

} // end class PairOfDice

The instance variables die1 and die2 are initialized to the values 3 and 4 respectively. These
initializations are executed whenever a PairOfDice object is constructed. It is important to
understand when and how this happens. Many PairOfDice objects may exist. Each time one is
created, it gets its own instance variables, and the assignments “die1 = 3” and “die2 = 4” are
executed to fill in the values of those variables. To make this clearer, consider a variation of the
PairOfDice class:
public class PairOfDice {

public int die1 = (int)(Math.random()*6) + 1;

public int die2 = (int)(Math.random()*6) + 1;

public void roll() {

die1 = (int)(Math.random()*6) + 1;
die2 = (int)(Math.random()*6) + 1;
}

} // end class PairOfDice

Here, the dice are initialized to random values, as if a new pair of dice were being thrown onto
the gaming table. Since the initialization is executed for each new object, a set of random initial
values will be computed for each new pair of dice. Different pairs of dice can have different initial
values. For initialization of static member variables, of course, the situation is quite different.
There is only one copy of a static variable, and initialization of that variable is executed just
once, when the class is first loaded.
If you don’t provide any initial value for an instance variable, a default initial value is pro-
vided automatically. Instance variables of numerical type (int, double, etc.) are automatically
initialized to zero if you provide no other values; boolean variables are initialized to false; and
char variables, to the Unicode character with code number zero. An instance variable can also be

19
a variable of object type. For such variables, the default initial value is null. (In particular, since
Strings are objects, the default initial value for String variables is null.)

Constructors
Objects are created with the operator, new. For example, a program that wants to use a PairOfDice
object could say:
PairOfDice dice; // Declare a variable of type PairOfDice.

dice = new PairOfDice(); // Construct a new object and store a

// reference to it in the variable.
In this example, “new PairOfDice()” is an expression that allocates memory for the object,
initializes the object’s instance variables, and then returns a reference to the object. This reference
is the value of the expression, and that value is stored by the assignment statement in the variable,
dice, so that after the assignment statement is executed, dice refers to the newly created object.
Part of this expression, “PairOfDice()”, looks like a method call, and that is no accident. It is,
in fact, a call to a special type of method called a constructor. This might puzzle you, since
there is no such method in the class definition. However, every class has at least one constructor.
If the programmer doesn’t write a constructor definition in a class, then the system will provide a
default constructor for that class. This default constructor does nothing beyond the basics:
allocate memory and initialize instance variables. If you want more than that to happen when an
object is created, you can include one or more constructors in the class definition.
The definition of a constructor looks much like the definition of any other method, with three
differences.

1. A constructor does not have any return type (not even void).

2. The name of the constructor must be the same as the name of the class in which it is defined.

3. The only modifiers that can be used on a constructor definition are the access modifiers
public, private, and protected. (In particular, a constructor can’t be declared static.)

However, a constructor does have a method body of the usual form, a block of statements.
There are no restrictions on what statements can be used. And it can have a list of formal param-
eters. In fact, the ability to include parameters is one of the main reasons for using constructors.
The parameters can provide data to be used in the construction of the object. For example, a con-
structor for the PairOfDice class could provide the values that are initially showing on the dice.
Here is what the class would look like in that case:
The constructor is declared as “public PairOfDice(int val1, int val2)...”, with
no return type and with the same name as the name of the class. This is how the JAVA compiler rec-
ognizes a constructor. The constructor has two parameters, and values for these parameters must be
provided when the constructor is called. For example, the expression “new PairOfDice(3,4)”
would create a PairOfDice object in which the values of the instance variables die1 and die2
are initially 3 andÂă4. Of course, in a program, the value returned by the constructor should be
used in some way, as in
PairOfDice dice; // Declare a variable of type PairOfDice.

dice = new PairOfDice(1,1); // Let dice refer to a new PairOfDice

// object that initially shows 1, 1.
Now that we’ve added a constructor to the PairOfDice class, we can no longer create an
object by saying “new PairOfDice()”! The system provides a default constructor for a class

20
only if the class definition does not already include a constructor, so there is only one constructor
in the class, and it requires two actual parameters. However, this is not a big problem, since we
can add a second constructor to the class, one that has no parameters. In fact, you can have as
many different constructors as you want, as long as their signatures are different, that is, as long as
they have different numbers or types of formal parameters. In the PairOfDice class, we might
have a constructor with no parameters which produces a pair of dice showing random numbers:
public class PairOfDice {

public int die1; // Number showing on the first die.

public int die2; // Number showing on the second die.

public PairOfDice() {
// Constructor. Rolls the dice, so that they initially
// show some random values.
roll(); // Call the roll() method to roll the dice.
}

public PairOfDice(int val1, int val2) {

// Constructor. Creates a pair of dice that
// are initially showing the values val1 and val2.
die1 = val1; // Assign specified values
die2 = val2; // to the instance variables.
}

public void roll() {

// Roll the dice by setting each of the dice to be
// a random number between 1 and 6.
die1 = (int)(Math.random()*6) + 1;
die2 = (int)(Math.random()*6) + 1;
}

} // end class PairOfDice

Now we have the option of constructing a PairOfDice object with “new PairOfDice()”
or with “new PairOfDice(x,y)”, where x and y are int-valued expressions.
This class, once it is written, can be used in any program that needs to work with one or more
pairs of dice. None of those programs will ever have to use the obscure incantation “(int)(Math.random()*6)+1”,
because it’s done inside the PairOfDice class. And the programmer, having once gotten the dice-
rolling thing straight will never have to worry about it again. Here, for example, is a main program
that uses the PairOfDice class to count how many times two pairs of dice are rolled before the
two pairs come up showing the same value. This illustrates once again that you can create several
instances of the same class:
public class RollTwoPairs {

public static void main(String[] args) {

PairOfDice firstDice; // Refers to the first pair of dice.

firstDice = new PairOfDice();

PairOfDice secondDice; // Refers to the second pair of dice.

secondDice = new PairOfDice();

int countRolls; // Counts how many times the two pairs of

// dice have been rolled.

21
 int total1; // Total showing on first pair of dice.
int total2; // Total showing on second pair of dice.

countRolls = 0;

do { // Roll the two pairs of dice until totals are the same.

firstDice.roll(); // Roll the first pair of dice.

total1 = firstDice.die1 + firstDice.die2; // Get total.
System.out.println("First pair comes up " + total1);

secondDice.roll(); // Roll the second pair of dice.

total2 = secondDice.die1 + secondDice.die2; // Get total.
System.out.println("Second pair comes up " + total2);

countRolls++; // Count this roll.

System.out.println(); // Blank line.

} while (total1 != total2);

System.out.println("It took " + countRolls

+ " rolls until the totals were the same.");

} // end main()

} // end class RollTwoPairs

Constructors are methods, but they are methods of a special type. They are certainly not in-
stance methods, since they don’t belong to objects. Since they are responsible for creating objects,
they exist before any objects have been created. They are more like static member methods,
but they are not and cannot be declared to be static. In fact, according to the JAVA language
specification, they are technically not members of the class at all! In particular, constructors are
not referred to as “methods”.
Unlike other methods, a constructor can only be called using the new operator, in an expression
that has the form
new class−name{parameter−list}

where the parameter−list is possibly empty. I call this an expression because it computes and
returns a value, namely a reference to the object that is constructed. Most often, you will store
the returned reference in a variable, but it is also legal to use a constructor call in other ways, for
example as a parameter in a method call or as part of a more complex expression. Of course, if
you don’t save the reference in a variable, you won’t have any way of referring to the object that
was just created.
A constructor call is more complicated than an ordinary method call. It is helpful to understand
the exact steps that the computer goes through to execute a constructor call:

1. First, the computer gets a block of unused memory in the heap, large enough to hold an
object of the specified type.

2. It initializes the instance variables of the object. If the declaration of an instance variable
specifies an initial value, then that value is computed and stored in the instance variable.
Otherwise, the default initial value is used.

22
 3. The actual parameters in the constructor, if any, are evaluated, and the values are assigned
to the formal parameters of the constructor.

4. The statements in the body of the constructor, if any, are executed.

5. A reference to the object is returned as the value of the constructor call.

The end result of this is that you have a reference to a newly constructed object. You can use this
reference to get at the instance variables in that object or to call its instance methods.
For another example, let’s rewrite the Student class. I’ll add a constructor, and I’ll also take
the opportunity to make the instance variable, name, private.
public class Student {
private String name; // Student’s name.
public double test1, test2, test3; // Grades on three tests.

// Constructor for Student objects−provides a name for the Student.

Student(String theName) {
name = theName;
}

// Getter method for the private instance variable, name.

public String getName() {
return name;
}

// Compute average test grade.

public double getAverage() {
return (test1 + test2 + test3) / 3;
}
}// end of class Student
An object of type Student contains information about some particular student. The construc-
tor in this class has a parameter of type String, which specifies the name of that student. Objects
of type Student can be created with statements such as:
std = new Student("John Smith");
std1 = new Student("Mary Jones");
In the original version of this class, the value of name had to be assigned by a program after it
created the object of type Student. There was no guarantee that the programmer would always
remember to set the name properly. In the new version of the class, there is no way to create
a Student object except by calling the constructor, and that constructor automatically sets the
name. The programmer’s life is made easier, and whole hordes of frustrating bugs are squashed
before they even have a chance to be born.
Another type of guarantee is provided by the private modifier. Since the instance variable,
name, is private, there is no way for any part of the program outside the Student class to get
at the name directly. The program sets the value of name, indirectly, when it calls the constructor.
I’ve provided a method, getName(), that can be used from outside the class to find out the name
of the student. But I haven’t provided any setter method or other way to change the name. Once a
student object is created, it keeps the same name as long as it exists.

Garbage Collection
So far, this section has been about creating objects. What about destroying them? In JAVA, the
destruction of objects takes place automatically.

23
 An object exists in the heap, and it can be accessed only through variables that hold references
to the object. What should be done with an object if there are no variables that refer to it? Such
things can happen. Consider the following two statements (though in reality, you’d never do
anything like this):
Student std = new Student("John Smith"); std = null;
In the first line, a reference to a newly created Student object is stored in the variable std.
But in the next line, the value of std is changed, and the reference to the Student object is gone.
In fact, there are now no references whatsoever to that object stored in any variable. So there is no
way for the program ever to use the object again. It might as well not exist. In fact, the memory
occupied by the object should be reclaimed to be used for another purpose.
JAVA uses a procedure called garbage collection to reclaim memory occupied by objects that
are no longer accessible to a program. It is the responsibility of the system, not the programmer,
to keep track of which objects are “garbage”. In the above example, it was very easy to see that
the Student object had become garbage. Usually, it’s much harder. If an object has been used
for a while, there might be several references to the object stored in several variables. The object
doesn’t become garbage until all those references have been dropped.
In many other programming languages, it’s the programmer’s responsibility to delete the
garbage. Unfortunately, keeping track of memory usage is very error-prone, and many serious
program bugs are caused by such errors. A programmer might accidently delete an object even
though there are still references to that object. This is called a dangling pointer error,
and it leads to problems when the program tries to access an object that is no longer there. An-
other type of error is a memory leak, where a programmer neglects to delete objects that are no
longer in use. This can lead to filling memory with objects that are completely inaccessible, and
the program might run out of memory even though, in fact, large amounts of memory are being
wasted.
Because JAVA uses garbage collection, such errors are simply impossible. Garbage collection
is an old idea and has been used in some programming languages since the 1960s. You might
wonder why all languages don’t use garbage collection. In the past, it was considered too slow
and wasteful. However, research into garbage collection techniques combined with the incredible
speed of modern computers have combined to make garbage collection feasible. Programmers
should rejoice.

Everything is NOT an object

Wrapper Classes and Autoboxing
Recall that there are two kinds of types in JAVA: primitive types and object types (Classes). In
some object-oriented languages, everything is an object. However in JAVA and in C++, the primi-
tive types like int and double are not objects. This decision was made for memory and process-
ing efficiency—it takes less memory to store an int than it is to store an object.
Sometimes, however, it is necessary to manipulate the primitive types as if they were objects.
To make this possible, you can define wrapper classes whose sole aim is to contain one of the
primitive types. They are used for creating objects that represent primitive type values.
For example the JAVA API contains the classes Double (that wraps a single double) and
Integer that wraps a single integer. These classes contain various static methods including
Double.parseDouble and Integer.parseInteger that are used to convert strings to nu-
merical values. The Character class wraps a single char type. There is a similar class for each
of the other primitive types, Long, Short, Byte, Float, and Boolean.
Remember that the primitive types are not classes, and values of primitive type are not objects.
However, sometimes it’s useful to treat a primitive value as if it were an object. You can’t do that

24
literally, but you can “wrap” the primitive type value in an object belonging to one of the wrapper
classes.
For example, an object of type Double contains a single instance variable, of type double.
The object is a wrapper for the double value. For example, you can create an object that wraps
the double value 6.0221415e23 with
Double d = new Double(6.0221415e23);
The value of d contains the same information as the value of type double, but it is an object.
If you want to retrieve the double value that is wrapped in the object, you can call the method
d.doubleValue(). Similarly, you can wrap an int in an object of type Integer, a boolean
value in an object of type Boolean, and so on. (As an example of where this would be useful, the
collection classes that will be studied in Chapter 10 can only hold objects. If you want to add a
primitive type value to a collection, it has to be put into a wrapper object first.)
In JAVA 5.0, wrapper classes have become easier to use. JAVA 5.0 introduced automatic con-
version between a primitive type and the corresponding wrapper class. For example, if you use a
value of type int in a context that requires an object of type Integer, the int will automatically
be wrapped in an Integer object. For example, you can say Integer answer = 42; and the
computer will silently read this as if it were Integer answer = new Integer(42);.
This is called autoboxing. It works in the other direction, too. For example, if d refers to an
object of type Double, you can use d in a numerical expression such as 2*d. The double value
inside d is automatically unboxed and multiplied by 2. Autoboxing and unboxing also apply to
method calls. For example, you can pass an actual parameter of type int to a method that has a
formal parameter of type Integer. In fact, autoboxing and unboxing make it possible in many
circumstances to ignore the difference between primitive types and objects.
The wrapper classes contain a few other things that deserve to be mentioned. Integer
contains constants Integer.MIN_VALUE and Integer.MAX_VALUE, which are equal to the
largest and smallest possible values of type int, that is, to −2147483648 and 2147483647 re-
spectively. It’s certainly easier to remember the names than the numerical values. There are
similar named constants in Long, Short, and Byte. Double and Float also have constants
named MIN_VALUE and MAX_VALUE. MAX_VALUE still gives the largest number that can be repre-
sented in the given type, but MIN_VALUE represents the smallest possible positive value. For type
double, Double.MIN_VALUE is 4.9 × 10−324 . Since double values have only a finite accuracy,
they can’t get arbitrarily close to zero. This is the closest they can get without actually being equal
to zero.
The class Double deserves special mention, since doubles are so much more complicated
than integers. The encoding of real numbers into values of type double has room for a few special
values that are not real numbers at all in the mathematical sense. These values named constants in
the class: Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY, and Double.NaN.
The infinite values can occur as values of certain mathematical expressions. For example, dividing
a positive number by zero will give Double.POSITIVE_INFINITY. (It’s even more complicated
than this, actually, because the double type includes a value called “negative zero”, written −0.0.
Dividing a positive number by negative zero gives Double.NEGATIVE_INFINITY.) You also
get Double.POSITIVE_INFINITY whenever the mathematical value of an expression is greater
than Double.MAX_VALUE. For example, 1e200*1e200 is considered to be infinite. The value
Double.NaN is even more interesting. “NaN” stands for Not a Number, and it represents an
undefined value such as the square root of a negative number or the result of dividing zero by zero.
Because of the existence of Double.NaN, no mathematical operation on real numbers will ever
throw an exception; it simply gives Double.NaN as the result.
You can test whether a value, x, of type double is infinite or undefined by calling the boolean-
valued static methods Double.isInfinite(x) and Double.isNaN(). (It’s especially impor-

25
tant to use Double.isNaN() to test for undefined values, because Double.NaN has really weird
behavior when used with relational operators such as ==. In fact, the values of x == Double.NaN
and x != Double.NaN are both false, no matter what the value of x, so you really can’t use these
expressions to test whether x is Double.NaN.)

1.3 Introduction to Error Handling

I N ADDITION TO THE CONTROL STRUCTURES that determine the normal flow of control in a
program, Java has a way to deal with “exceptional” cases that throw the flow of control off its
normal track. When an error occurs during the execution of a program, the default behavior is to
terminate the program and to print an error message. However, Java makes it possible to “catch”
such errors and program a response different from simply letting the program crash. This is done
with the try..catch statement. In this section, we will take a preliminary, incomplete look at using
try..catch to handle errors.

Exceptions
The term exception is used to refer to the type of error that one might want to handle with a
try..catch. An exception is an exception to the normal flow of control in the program. The
term is used in preference to “error” because in some cases, an exception might not be considered
to be an error at all. You can sometimes think of an exception as just another way to organize a
program.
Exceptions in Java are represented as objects of type Exception. Actual exceptions are
defined by subclasses of Exception. Different subclasses represent different types of exceptions
We will look at only two types of exception in this section: NumberFormatException and
IllegalArgumentException.
A NumberFormatException can occur when an attempt is made to convert a string into a
number. Such conversions are done, for example, by Integer.parseInt and Integer.parseDouble
. Consider the method call Integer.parseInt(str) where str is a variable of type String.
If the value of str is the string “42”, then the method call will correctly convert the string into
the int 42. However, if the value of str is, say, “fred”, the method call will fail because
“fred” is not a legal string representation of an int value. In this case, an exception of type
NumberFormatException occurs. If nothing is done to handle the exception, the program will
crash.
An IllegalArgumentException can occur when an illegal value is passed as a parameter
to a method. For example, if a method requires that a parameter be greater than or equal to zero,
an IllegalArgumentException might occur when a negative value is passed to the method.
How to respond to the illegal value is up to the person who wrote the method, so we can’t simply
say that every illegal parameter value will result in an IllegalArgumentException. However,
it is a common response.
One case where an IllegalArgumentException can occur is in the valueOf method of
an enumerated type. Recall that this method tries to convert a string into one of the values of the
enumerated type. If the string that is passed as a parameter to valueOf is not the name of one of
the enumerated type’s value, then an IllegalArgumentException occurs. For example, given
the enumerated type
enum Toss { HEADS, TAILS };

Toss.valueOf("HEADS") correctly returns Toss.HEADS, but Toss.valueOf(‘‘FEET’’)

results in an IllegalArgumentException.

26
try . . . catch
When an exception occurs, we say that the exception is “thrown”. For example, we say that
Integer.parseInt(str) throws an exception of type NumberFormatException when the
value of str is illegal. When an exception is thrown, it is possible to “catch” the exception and
prevent it from crashing the program. This is done with a try..catch statement. In somewhat
simplified form, the syntax for a try..catch is:

27
 try {
statements−1
}
catch ( exception−class−name variable−name ) {
statements−2
}

The exception-class-name in the catch clause could be NumberFormatException, IllegalArgumentExcepti

or some other exception class. When the computer executes this statement, it executes the state-
ments in the try part. If no error occurs during the execution of statements−1, then the computer
just skips over the catch part and proceeds with the rest of the program. However, if an excep-
tion of type exception-class-name occurs during the execution of statements−1, the computer
immediately jumps to the catch part and executes statements−2, skipping any remaining state-
ments in statements−1. During the execution of statements−2, the variable-name represents
the exception object, so that you can, for example, print it out. At the end of the catch part, the
computer proceeds with the rest of the program; the exception has been caught and handled and
does not crash the program. Note that only one type of exception is caught; if some other type of
exception occurs during the execution of statements−1, it will crash the program as usual.
(By the way, note that the braces, { and }, are part of the syntax of the try..catch statement.
They are required even if there is only one statement between the braces. This is different from
the other statements we have seen, where the braces around a single statement are optional.)
As an example, suppose that str is a variable of type String whose value might or might
not represent a legal real number. Then we could say:
try {
double x;
x = Double.parseDouble(str);
System.out.println( "The number is " + x );
}
catch ( NumberFormatException e ) {
System.out.println( "Not a legal number." );
}

If an error is thrown by the call to Double.parseDouble(str), then the output statement

in the try part is skipped, and the statement in the catch part is executed.
It’s not always a good idea to catch exceptions and continue with the program. Often that can
just lead to an even bigger mess later on, and it might be better just to let the exception crash the
program at the point where it occurs. However, sometimes it’s possible to recover from an error.
For example, suppose that we have the enumerated type
enum Day {MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY}

and we want the user to input a value belonging to this type. TextIO does not know about this
type, so we can only read the user’s response as a string. The method Day.valueOf can be used
to convert the user’s response to a value of type Day. This will throw an exception of type Ille-
galArgumentException if the user’s response is not the name of one of the values of type Day, but
we can respond to the error easily enough by asking the user to enter another response. Here is a
code segment that does this. (Converting the user’s response to upper case will allow responses
such as “Monday” or “monday” in addition to “MONDAY”.)
Scanner keyboard = new Scanner(System.in);
Day weekday; // User’s response as a value of type Day.
while ( true ) {
String response; // User’s response as a String.
keyboard.put("Please enter a day of the week: ");

28
 response = keyboard.nextLinen();
response = response.toUpperCase();
try {
weekday = Day.valueOf(response);
break;
}
catch ( IllegalArgumentException e ) {
System.out.println( response +
" is not the name of a day of the week." );
}
}

The break statement will be reached only if the user’s response is acceptable, and so the loop
will end only when a legal value has been assigned to weekday.

1.4 Javadoc
Good programming means extensive comments and documentation. At the very least, explain the
method of each instance variable, and for each method explain its purpose, parameters, returns,
where applicable. You should also strive for a consistent layout and for expressive variable names.
A program that is well-documented is much more valuable than the same program without
the documentation. Java comes with a tool called javadoc that can make it easier to produce the
documentation is a readable and organized format. JavaDoc is a program that will automatically
extract/generate an HTML help-page from code that is properly commented. In particular, it is
designed produce a help file that, for a class, lists the methods, constructors and public fields, and
for each method explains what it does together with pre-conditions, post-conditions, the meaning
of the parameters, exceptions that may be thrown and other things.
Javadoc is especially useful for documenting classes and packages of classes that are meant to
be used by other programmers. A programmer who wants to use pre-written classes shouldn’t need
to search through the source code to find out how to use them. If the documentation in the source
code is in the correct format, javadoc can separate out the documentation and make it into a set of
web pages. The web pages are automatically formatted and linked into an easily browseable Web
site. Sun Microsystem’s documentation for the standard Java API was produced using javadoc.
Javadoc documentation is prepared from special comments that are placed in the Java source
code file. Recall that one type of Java comment begins with /* and ends with */. A Javadoc
comment takes the same form, but it begins with /** rather than simply /*.
/**
* This method prints a 3N+1 sequence to standard output, using
* startingValue as the initial value of N. It also prints the number
* of terms in the sequence. The value of the parameter, startingValue,
* must be a positive integer.
*/

static void print3NSequence(int startingValue) { ...

You can have Javadoc comments for methods, member variables, and for classes. The Javadoc
comment always immediately precedes the thing it is commenting on. Like any comment, a
Javadoc comment is ignored by the computer when the file is compiled. But there is a tool called
javadoc that reads Java source code files, extracts any Javadoc comments that it finds, and creates
a set of Web pages containing the comments in a nicely formatted, interlinked form. By default,
javadoc will only collect information about public classes, methods, and member variables, but
it allows the option of creating documentation for non-public things as well. If javadoc doesn’t

29
find any Javadoc comment for something, it will construct one, but the comment will contain only
basic information such as the name and type of a member variable or the name, return type, and
parameter list of a method. This is syntactic information. To add information about semantics and
pragmatics, you have to write a Javadoc comment.
In addition to normal text, the comment can contain certain special codes. For one thing, the
comment can contain HTML mark-up commands. (HTML is the language that is used to create
web pages, and Javadoc comments are meant to be shown on web pages.) The javadoc tool will
copy any HTML commands in the comments to the web pages that it creates. As an example,
you can add <p> to indicate the start of a new paragraph. (Generally, in the absence of HTML
commands, blank lines and extra spaces in the comment are ignored.)
In addition to HTML commands, Javadoc comments can include doc tags, which are processed
as commands by the javadoc tool. A doc tag has a name that begins with the character . I will only
discuss three tags: @param, @return, and @throws. These tags are used in Javadoc comments
for methods to provide information about its parameters, its return value, and the exceptions that
it might throw. These tags are always placed at the end of the comment, after any description of
the method itself. The syntax for using them is:
@param parameter−name description−of−parameter

@return description−of−return−value

@throws exception−class−name description−of−exception

The descriptions can extend over several lines. The description ends at the next tag or at the
end of the comment. You can include a @param tag for every parameter of the method and a
@throws for as many types of exception as you want to document. You should have a @return tag
only for a non-void method. These tags do not have to be given in any particular order. Here is an
example that doesn’t do anything exciting but that does use all three types of doc tag:
If you want to create Web-page documentation, you need to run the javadoc tool. You can use
javadoc in a command line interface similarly to the way that the javac and java commands are
used. Javadoc can also be applied in the Eclipse integrated development environment: Just right-
click the class or package that you want to document in the Package Explorer, select "Export," and
select "Javadoc" in the window that pops up. Consult the documentation for more details.

30
 /**
* This method computes the area of a rectangle, given its width
* and its height. The length and the width should be positive numbers.
* @param width the length of one side of the rectangle
* @param height the length the second side of the rectangle
* @return the area of the rectangle
* @throws IllegalArgumentException if either the width or the height
* is a negative number.
*/
public static double areaOfRectangle( double length, double width ) {
if ( width < 0 || height < 0 )
throw new IllegalArgumentException("Sides must have positive length.");
double area;
area = width * height;
return area;
}

1.5 Creating Jar Files

As the final topic for this chapter, we look again at jar files. Recall that a jar file is a “java archive”
that can contain a number of class files. When creating a program that uses more than one class,
it’s usually a good idea to place all the classes that are required by the program into a jar file, since
then a user will only need that one file to run the program. Jar files can also be used for stand-alone
applications. In fact, it is possible to make a so-called executable jar file. A user can run
an executable jar file in much the same way as any other application, usually by double-clicking
the icon of the jar file. (The user’s computer must have a correct version of JAVA installed, and
the computer must be configured correctly for this to work. The configuration is usually done
automatically when JAVA is installed, at least on Windows and Mac OS.)
The question, then, is how to create a jar file. The answer depends on what programming
environment you are using. There are two basic types of programming environment – command
line and IDE. Any IDE (Integrated Programming Environment) for JAVA should have a command
for creating jar files. In the Eclipse IDE, for example, it’s done as follows: In the Package Explorer
pane, select the programming project (or just all the individual source code files that you need).
Right-click on the selection, and choose “Export” from the menu that pops up. In the window that
appears, select “JAR file” and click “Next”. In the window that appears next, enter a name for the
jar file in the box labeled “JAR file”. (Click the “Browse” button next to this box to select the file
name using a file dialog box.) The name of the file should end with “.jar”. If you are creating a
regular jar file, not an executable one, you can hit “Finish” at this point, and the jar file will be
created. You could do this, for example, if the jar file contains an applet but no main program.
To create an executable file, hit the “Next” button twice to get to the “Jar Manifest Specification”
screen. At the bottom of this screen is an input box labeled “Main class”. You have to enter the
name of the class that contains the main() method that will be run when the jar file is executed.
If you hit the “Browse” button next to the “Main class” box, you can select the class from a list
of classes that contain main() methods. Once you’ve selected the main class, you can click the
“Finish” button to create the executable jar file.
It is also possible to create jar files on the command line. The JAVA Development Kit in-
cludes a command-line program named jar that can be used to create jar files. If all your
classes are in the default package (like the examples in this book), then the jar command is
easy to use. To create a non-executable jar file on the command line, change to the direc-
tory that contains the class files that you want to include in the jar. Then give the command

31
jar cf JarFileName.jar *.class where JarFileName can be any name that you want to
use for the jar file. The “*“ in “*.class” is a wildcard that makes *.class match every class file
in the current directory. This means that all the class files in the directory will be included in the
jar file. If you want to include only certain class files, you can name them individually, separated
by spaces. (Things get more complicated if your classes are not in the default package. In that
case, the class files must be in subdirectories of the directory in which you issue the jar file.)
Making an executable jar file on the command line is a little more complicated. There has
to be some way of specifying which class contains the main() method. This is done by cre-
ating a manifest file. The manifest file can be a plain text file containing a single line of
the form Main−Class: ClassName where ClassName should be replaced by the name of
the class that contains the main() method. For example, if the main() method is in the class
MosaicDrawFrame, then the manifest file should read “Main−Class: MosaicDrawFrame”.
You can give the manifest file any name you like. Put it in the same directory where you will issue
the jar command, and use a command of the form jar cmf ManifestFileName JarFileName.jar *.class
to create the jar file. (The jar command is capable of performing a variety of different operations.
The first parameter to the command, such as “cf” or “cmf”, tells it which operation to perform.)
By the way, if you have successfully created an executable jar file, you can run it on the
command line using the command “java −jar”. For example:
java −jar JarFileName.jar

APIs and Packages

One of the important advantages of object-oriented programming is that it promotes reuse. When
writing any piece of software, a programmer can use a large and growing body of pre-written
software. The JAVA SDK (software development kit) consists of thousands of classes that can
be used by programmers. So, learning the JAVA language means also being able to use this vast
library of classes.

Toolboxes

Someone who wants to program for Macintosh computers – and to produce programs that look
and behave the way users expect them to – must deal with the Macintosh Toolbox, a collection of
well over a thousand different methods. There are methods for opening and closing windows, for
drawing geometric figures and text to windows, for adding buttons to windows, and for responding
to mouse clicks on the window. There are other methods for creating menus and for reacting to
user selections from menus. Aside from the user interface, there are methods for opening files and
reading data from them, for communicating over a network, for sending output to a printer, for
handling communication between programs, and in general for doing all the standard things that a
computer has to do. Microsoft Windows provides its own set of methods for programmers to use,
and they are quite a bit different from the methods used on the Mac. Linux has several different
GUI toolboxes for the programmer to choose from.
The analogy of a “toolbox” is a good one to keep in mind. Every programming project in-
volves a mixture of innovation and reuse of existing tools. A programmer is given a set of tools
to work with, starting with the set of basic tools that are built into the language: things like vari-
ables, assignment statements, if statements, and loops. To these, the programmer can add existing
toolboxes full of methods that have already been written for performing certain tasks. These tools,
if they are well-designed, can be used as true black boxes: They can be called to perform their
assigned tasks without worrying about the particular steps they go through to accomplish those
tasks. The innovative part of programming is to take all these tools and apply them to some partic-

32
ular project or problem (word-processing, keeping track of bank accounts, processing image data
from a space probe, Web browsing, computer games,...). This is called applications programming.
A software toolbox is a kind of black box, and it presents a certain interface to the programmer.
This interface is a specification of what methods are in the toolbox, what parameters they use, and
what tasks they perform. This information constitutes the API, or Applications Programming
Interface, associated with the toolbox. The Macintosh API is a specification of all the methods
available in the Macintosh Toolbox. A company that makes some hardware device – say a card
for connecting a computer to a network – might publish an API for that device consisting of a
list of methods that programmers can call in order to communicate with and control the device.
Scientists who write a set of methods for doing some kind of complex computation – such as
solving “differential equations”, say – would provide an API to allow others to use those methods
without understanding the details of the computations they perform.
The JAVA programming language is supplemented by a large, standard API. You’ve seen part
of this API already, in the form of mathematical methods such as
Math.sqrt(), the String data type and its associated methods, and the
System.out.print() methods. The standard JAVA API includes methods for working with
graphical user interfaces, for network communication, for reading and writing files, and more. It’s
tempting to think of these methods as being built into the JAVA language, but they are technically
methods that have been written and made available for use in JAVA programs.
JAVA is platform-independent. That is, the same program can run on platforms as diverse as
Macintosh, Windows, Linux, and others. The same JAVA API must work on all these platforms.
But notice that it is the interface that is platform-independent; the implementation varies from
one platform to another. A JAVA system on a particular computer includes implementations of all
the standard API methods. A JAVA program includes only calls to those methods. When the JAVA
interpreter executes a program and encounters a call to one of the standard methods, it will pull up
and execute the implementation of that method which is appropriate for the particular platform on
which it is running. This is a very powerful idea. It means that you only need to learn one API to
program for a wide variety of platforms.

J AVA’s Standard Packages

Like all methods in JAVA, the methods in the standard API are grouped into classes. To provide
larger-scale organization, classes in JAVA can be grouped into packages, which were introduced
briefly in Subection2.6.4. You can have even higher levels of grouping, since packages can also
contain other packages. In fact, the entire standard JAVA API is implemented in several packages.
One of these, which is named “java”, contains several non-GUI packages as well as the original
AWT graphics user interface classes. Another package, “javax”, was added in JAVA version 1.2
and contains the classes used by the Swing graphical user interface and other additions to the API.
A package can contain both classes and other packages. A package that is contained in another
package is sometimes called a “sub-package.” Both the java package and the javax package contain
sub-packages. One of the sub-packages of java, for example, is called “awt”. Since awt is con-
tained within java, its full name is actually java.awt. This package contains classes that represent
GUI components such as buttons and menus in the AWT, the older of the two JAVA GUI toolboxes,
which is no longer widely used. However, java.awt also contains a number of classes that form
the foundation for all GUI programming, such as the Graphics class which provides methods for
drawing on the screen, the Color class which represents colors, and the Font class which repre-
sents the fonts that are used to display characters on the screen. Since these classes are contained
in the package java.awt, their full names are actually java.awt.Graphics, java.awt.Color
and java.awt.Font. (I hope that by now you’ve gotten the hang of how this naming thing works
in JAVA.) Similarly, javax contains a sub-package named javax.swing, which includes such

33
classes as javax.swing.JButton, javax.swing.JMenu, and javax.swing.JFrame. The
GUI classes in javax.swing, together with the foundational classes in java.awt are all part of
the API that makes it possible to program graphical user interfaces in JAVA.
The java package includes several other sub-packages, such as java.io, which provides facil-
ities for input/output, java.net, which deals with network communication, and java.util, which
provides a variety of “utility” classes. The most basic package is called java.lang. This package
contains fundamental classes such as String, Math, Integer, and Double.
It might be helpful to look at a graphical representation of the levels of nesting in the java
package, its sub-packages, the classes in those sub-packages, and the methods in those classes.
This is not a complete picture, since it shows only a very few of the many items in each element:

The official documentation for the standard JAVA 5.0 API lists 165 different packages, includ-
ing sub-packages, and it lists 3278 classes in these packages. Many of these are rather obscure or
very specialized, but you might want to browse through the documentation to see what is available.
Even an expert programmer won’t be familiar with the entire API, or even a majority of it. In
this book, you’ll only encounter several dozen classes, and those will be sufficient for writing a
wide variety of programs.

Using Classes from Packages

Let’s say that you want to use the class java.awt.Color in a program that you are writing. Like
any class, java.awt.Color is a type, which means that you can use it declare variables and
parameters and to specify the return type of a method. One way to do this is to use the full name
of the class as the name of the type. For example, suppose that you want to declare a variable
named rectColor of type java.awt.Color. You could say:
java.awt.Color rectColor;

This is just an ordinary variable declaration of the form “type-name variable-name;”. Of

course, using the full name of every class can get tiresome, so JAVA makes it possible to avoid
using the full names of a class by importing the class. If you put
import java.awt.Color;

at the beginning of a JAVA source code file, then, in the rest of the file, you can abbreviate the
full name java.awt.Color to just the simple name of the class, Color. Note that the import
line comes at the start of a file and is not inside any class. Although it is sometimes referred to as

34
as a statement, it is more properly called an import directive since it is not a statement in the usual
sense. Using this import directive would allow you to say
Color rectColor;
to declare the variable. Note that the only effect of the import directive is to allow you to use
simple class names instead of full “package.class” names; you aren’t really importing anything
substantial. If you leave out the import directive, you can still access the class – you just have to
use its full name. There is a shortcut for importing all the classes from a given package. You can
import all the classes from java.awt by saying
import java.awt.*;
The “*” is a wildcard that matches every class in the package. (However, it does not match sub-
packages; you cannot import the entire contents of all the sub-packages of the java packages by
saying importjava.*.)
Some programmers think that using a wildcard in an import statement is bad style, since it
can make a large number of class names available that you are not going to use and might not
even know about. They think it is better to explicitly import each individual class that you want
to use. In my own programming, I often use wildcards to import all the classes from the most
relevant packages, and use individual imports when I am using just one or two classes from a
given package.
In fact, any JAVA program that uses a graphical user interface is likely to use many classes from
the java.awt and java.swing packages as well as from another package named java.awt.event,
and I usually begin such programs with
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
A program that works with networking might include: “import java.net.*;”, while one
that reads or writes files might use “import java.io.*;”. (But when you start importing lots
of packages in this way, you have to be careful about one thing: It’s possible for two classes
that are in different packages to have the same name. For example, both the java.awt package
and the java.util package contain classes named List. If you import both java.awt.* and
java.util.*, the simple name List will be ambiguous. If you try to declare a variable of type
List, you will get a compiler error message about an ambiguous class name. The solution is
simple: use the full name of the class, either java.awt.List or java.util.List. Another
solution, of course, is to use import to import the individual classes you need, instead of importing
entire packages.)
Because the package java.lang is so fundamental, all the classes in java.lang are automatically
imported into every program. It’s as if every program began with the statement “import java.lang.*;”.
This is why we have been able to use the class name String instead of java.lang.String,
and Math.sqrt() instead of java.lang.Math.sqrt(). It would still, however, be perfectly
legal to use the longer forms of the names.
Programmers can create new packages. Suppose that you want some classes that you are
writing to be in a package named utilities. Then the source code file that defines those classes
must begin with the line
package utilities;
This would come even before any import directive in that file. Furthermore, the source code
file would be placed in a folder with the same name as the package. A class that is in a package
automatically has access to other classes in the same package; that is, a class doesn’t have to
import the package in which it is defined.

35
 In projects that define large numbers of classes, it makes sense to organize those classes into
packages. It also makes sense for programmers to create new packages as toolboxes that provide
functionality and API’s for dealing with areas not covered in the standard JAVA API. (And in fact
such “toolmaking” programmers often have more prestige than the applications programmers who
use their tools.)
However, I will not be creating any packages in this textbook. For the purposes of this book,
you need to know about packages mainly so that you will be able to import the standard packages.
These packages are always available to the programs that you write. You might wonder where the
standard classes are actually located. Again, that can depend to some extent on the version of JAVA
that you are using, but in the standard JAVA 5.0, they are stored in jar files in a subdirectory of
the main JAVA installation directory. A jar (or “JAVA archive”) file is a single file that can contain
many classes. Most of the standard classes can be found in a jar file named classes.jar. In fact,
JAVA programs are generally distributed in the form of jar files, instead of as individual class files.
Although we won’t be creating packages explicitly, every class is actually part of a package. If
a class is not specifically placed in a package, then it is put in something called the default package,
which has no name. All the examples that you see in this book are in the default package.

1.6 Mixing Static and Non-static

Classes, as I’ve said, have two very distinct purposes. A class can be used to group together a set
of static member variables and static member methods. Or it can be used as a factory for making
objects. The non-static variables and methods in the class definition specify the instance variables
and methods of the objects. In most cases, a class performs one or the other of these roles, not
both.
Sometimes, however, static and non-static members are mixed in a single class. In this case,
the class plays a dual role. Sometimes, these roles are completely separate. It is also possible for
the static and non-static parts of a class to interact. This happens when instance methods use static
member variables or call static member methods. An instance method belongs to an object, not to
the class itself, and there can be many objects with their own versions of the instance method. But
there is only one copy of a static member variable. So, effectively, we have many objects sharing
that one variable.
Suppose, for example, that we want to write a PairOfDice class that uses the Random class
for rolling the dice. To do this, a PairOfDice object needs access to an object of type Random.
But there is no need for each PairOfDice object to have a separate Randomobject. (In fact, it
would not even be a good idea: Because of the way ran dom number generators work, a program
should, in general, use only one source of random numbers.) A nice solution is to have a single
Random variable as a static member of the PairOfDice class, so that it can be shared by all
PairOfDice objects. For example:
import java.util.Random;

public class PairOfDice {

\code{private static Random randGen = new Random();}

public int die1; // Number showing on the first die.

public int die2; // Number showing on the second die.

public PairOfDice() {
// Constructor. Creates a pair of dice that

36
 // initially shows random values.
roll();
}
public void roll() {
// Roll the dice by setting each of the dice to be
// a random number between 1 and 6.
die1 = randGen.nextInt(6) + 1;
die2 = randGen.nextInt(6) + 1;
}
} // end class PairOfDice
As another example, let’s rewrite the Student class. I’ve added an ID for each student and a
static member called nextUniqueID . Although there is an ID variable in each student object,
there is only one nextUniqueID variable.
public class Student {

private String name; // Student’s name.

private int ID; // Unique ID number for this student.
public double test1, test2, test3; // Grades on three tests.

private static int nextUniqueID = 0;

// keep track of next available unique ID number

Student(String theName) {
// Constructor for Student objects; provides a name for the Student,
// and assigns the student a unique ID number.
name = theName;
nextUniqueID++;
ID = nextUniqueID;
}
public String getName() {
// Accessor method for reading value of private
// instance variable, name.
return name;
}
public int getID() {
// Accessor method for reading value of ID.
return ID;
}
public double getAverage() {
// Compute average test grade.
return (test1 + test2 + test3) / 3;
}
} // end of class Student
The initialization “nextUniqueID = 0” is done once, when the class is first loaded. When-
ever a Student object is constructed and the constructor says “nextUniqueID++;”, it’s always
the same static member variable that is being incremented. When the very first Student object
is created, nextUniqueID becomes 1. When the second object is created, nextUniqueID be-
comes 2. After the third object, it becomes 3. And so on. The constructor stores the new value of
nextUniqueID in the ID variable of the object that is being created. Of course, ID is an instance
variable, so every object has its own individual ID variable. The class is constructed so that each
student will automatically get a different value for its IDvariable. Furthermore, the ID variable is
private, so there is no way for this variable to be tampered with after the object has been created.
You are guaranteed, just by the way the class is designed, that every student object will have its

37
own permanent, unique identification number. Which is kind of cool if you think about it.

Static Import
The import directive makes it possible to refer to a class such as java.awt.Color using its sim-
ple name, Color. All you have to do is say import java.awt.Color or import java.awt.*.
Uou still have to use compound names to refer to static member variables such as System.out
and to static methods such as Math.sqrt.
Java 5.0 introduced a new form of the import directive that can be used to import static
members of a class in the same way that the ordinary import directive imports classes from a
package. The new form of the directive is called a static import, and it has syntax
import static package−name class−name static−member−name;
to import one static member name from a class, or
import static package−name class−name.*;
to import all the public static members from a class. For example, if you preface a class definition
with
import static java.lang.System.out;
then you can use the simple name out instead of the compound name System.out. This means
you can use out.println instead of System.out.println. If you are going to work exten-
sively with the Mathclass, you can preface your class definition with
import static java.lang.Math.*;
This would allow to say sqrtinstead of Math.sqrt, log instead of Math.log, PI instead
of Math.PI, and so on.
Note that the static import directive requires a package−name, even for classes in the standard
package java.lang. One consequence of this is that you can’t do a static import from a class in
the default package.

38
 CHAPTER 2
O BJECT O RIENTED A NALYSIS
AND D ESIGN

2.1 Introduction to Software Engineering

T HE DIFFICULTIES INHERENT with the development of software has led many computer scien-
tists to suggest that software development should be treated as an engineering activity. They argue
for a disciplined approach where the software engineer uses carefully thought out methods and
processes.
The term software engineering has several meanings (from wikipedia):

* As the broad term for all aspects of the practice of computer programming, as opposed to
the theory of computer programming, which is called computer science;

* As the term embodying the advocacy of a specific approach to computer programming, one
that urges that it be treated as an engineering profession rather than an art or a craft, and
advocates the codification of recommended practices in the form of software engineering
methodologies.

* Software engineering is

(1) "the application of a systematic, disciplined, quantifiable approach to the develop-

ment, operation, and maintenance of software, that is, the application of engineering
to software," and
(2) "the study of approaches as in (1)." IEEE Standard 610.12

Software Engineering Life-Cycles

A decades-long goal has been to find repeatable, predictable processes or methodologies that im-
prove productivity and quality of software. Some try to systematize or formalize the seemingly
unruly task of writing software. Others apply project management techniques to writing software.

39
Without project management, software projects can easily be delivered late or over budget. With
large numbers of software projects not meeting their expectations in terms of functionality, cost,
or delivery schedule, effective project management is proving difficult.
Software engineering requires performing many tasks, notably the following, some of which
may not seem to directly produce software.

• Requirements Analysis Extracting the requirements of a desired software product is the

first task in creating it. While customers probably believe they know what the software is
to do, it may require skill and experience in software engineering to recognize incomplete,
ambiguous or contradictory requirements.

• Specification Specification is the task of precisely describing the software to be written, usu-
ally in a mathematically rigorous way. In reality, most successful specifications are written
to understand and fine-tune applications that were already well-developed. Specifications
are most important for external interfaces, that must remain stable.

• Design and Architecture Design and architecture refer to determining how software is to
function in a general way without being involved in details. Usually this phase is divided
into two sub-phases.

• Coding Reducing a design to code may be the most obvious part of the software engineering
job, but it is not necessarily the largest portion.

• Testing Testing of parts of software, especially where code by two different engineers must
work together, falls to the software engineer.

• Documentation An important (and often overlooked) task is documenting the internal de-
sign of software for the purpose of future maintenance and enhancement. Documentation is
most important for external interfaces.

• Maintenance Maintaining and enhancing software to cope with newly discovered problems
or new requirements can take far more time than the initial development of the software. Not
only may it be necessary to add code that does not fit the original design but just determin-
ing how software works at some point after it is completed may require significant effort
by a software engineer. About 2/3 of all software engineering work is maintenance, but
this statistic can be misleading. A small part of that is fixing bugs. Most maintenance is
extending systems to do new things, which in many ways can be considered new work. In
comparison, about 2/3 of all civil engineering, architecture, and construction work is main-
tenance in a similar way.

Object-oriented Analysis and Design

A large programming project goes through a number of stages, starting with specification of the
problem to be solved, followed by analysis of the problem and design of a program to solve it.
Then comes coding, in which the program’s design is expressed in some actual programming
language. This is followed by testing and debugging of the program. After that comes a long
period of maintenance, which means fixing any new problems that are found in the program and
modifying it to adapt it to changing requirements. Together, these stages form what is called the
software life cycle. (In the real world, the ideal of consecutive stages is seldom if ever achieved.
During the analysis stage, it might turn out that the specifications are incomplete or inconsistent.
A problem found during testing requires at least a brief return to the coding stage. If the problem

40
is serious enough, it might even require a new design. Maintenance usually involves redoing some
of the work from previous stages....)
Large, complex programming projects are only likely to succeed if a careful, systematic ap-
proach is adopted during all stages of the software life cycle. The systematic approach to pro-
gramming, using accepted principles of good design, is called software engineering. The software
engineer tries to efficiently construct programs that verifyably meet their specifications and that
are easy to modify if necessary. There is a wide range of “methodologies” that can be applied to
help in the systematic design of programs. (Most of these methodologies seem to involve draw-
ing little boxes to represent program components, with labeled arrows to represent relationships
among the boxes.)
We have been discussing object orientation in programming languages, which is relevant to
the coding stage of program development. But there are also object-oriented methodologies for
analysis and design. The question in this stage of the software life cycle is, How can one discover
or invent the overall structure of a program? As an example of a rather simple object-oriented
approach to analysis and design, consider this advice: Write down a description of the problem.
Underline all the nouns in that description. The nouns should be considered as candidates for
becoming classes or objects in the program design. Similarly, underline all the verbs. These are
candidates for methods. This is your starting point. Further analysis might uncover the need for
more classes and methods, and it might reveal that subclassing can be used to take advantage of
similarities among classes.
This is perhaps a bit simple-minded, but the idea is clear and the general approach can be
effective: Analyze the problem to discover the concepts that are involved, and create classes to
represent those concepts. The design should arise from the problem itself, and you should end up
with a program whose structure reflects the structure of the problem in a natural way.

Object Oriented Software Engineering

Object Oriented Software Engineering rests on three principles:

• Abstraction: Ignore the details. In philosophical terminology, abstraction is the thought

process wherein ideas are distanced from objects. In computer science, abstraction is a
mechanism and practice to reduce and factor out details so that one can focus on few con-
cepts at a time.
Abstraction uses a strategy of simplification, wherein formerly concrete details are left am-
biguous, vague, or undefined. [wikipedia:Abstraction]

• Modularization: break into pieces. A module can be defined variously, but generally must
be a component of a larger system, and operate within that system independently from the
operations of the other components. Modularity is the property of computer programs that
measures the extent to which they have been composed out of separate parts called modules.
Programs that have many direct interrelationships between any two random parts of the
program code are less modular than programs where those relationships occur mainly at
well-defined interfaces between modules.

• Information hiding: separate the implementation and the function. The principle of infor-
mation hiding is the hiding of design decisions in a computer program that are most likely
to change, thus protecting other parts of the program from change if the design decision is
changed. Protecting a design decision involves providing a stable interface which shields
the remainder of the program from the implementation (the details that are most likely to
change).

41
 Figure 2.1: A Simple Methodology

We strive for responsibility-driven design: each class should be responsible for its own data.
We strive for loose coupling: each class is largely independent and communicates with other
classes via a small well-defined interface. We strive for cohesion: each class performs one and
only one task (for readability, reuse).

A Simple Methodology
The following is a simple methodology that we will use:

Discovering Classes: Class-Responsibility-Collaboration cards

C LASS -R ESPONSIBILITY -C OLLABORATION CARDS (CRC cards) are a brainstorming tool used
in the design of object-oriented software. They were proposed by Ward Cunningham. They are
typically used when first determining which classes are needed and how they will interact.
CRC cards are usually created from index cards on which are written:
1. The class name.

42
 2. The package name (if applicable).
3. The responsibilities of the class.
4. The names of other classes that the class will collaborate with to fulfill its responsibilities.
For example consider the CRC Card for a Playing Card class:

The responsibilities are listed on the left. The classes that the Playing Card class will
collaborate with are listed on the right.
The idea is that class design is undertaken by a team of developers. CRC cards are used as a
brainstorming technique. The team attempts to determine all the classes and their responsibilities
that will be needed for the application. The team runs through various usage scenarios of the
application. For e.g. one such scenario for a game of cards may be “the player picks a card from
the deck and hand adds it to his hand”. The team uses the CRC cards to check if this scenario can
be handled by the responsibilites assigned to the classes. In this way, the design is refined until the
team agrees on a set of classes and has agreed on their responsibilities.
Using a small card keeps the complexity of the design at a minimum. It focuses the designer
on the essentials of the class and prevents him from getting into its details and inner workings at
a time when such detail is probably counter-productive. It also forces the designer to refrain from
giving the class too many responsibilities.

Documenting Designs: The Unified Modelling Language

T HIS SECTION WILL GIVE YOU A QUICK OVERVIEW of the basics of UML. It is taken from
the user documentation of the UML tool Umbrello and wikipedia. Keep in mind that this is not
a comprehensive tutorial on UML but rather a brief introduction to UML which can be read as
a UML tutorial. If you would like to learn more about the Unified Modelling Language, or in
general about software analysis and design, refer to one of the many books available on the topic.
There are also a lot of tutorials on the Internet which you can take as a starting point.
The Unified Modelling Language (UML) is a diagramming language or notation to specify,
visualize and document models of Object Oriented software systems. UML is not a development
method, that means it does not tell you what to do first and what to do next or how to design your
system, but it helps you to visualize your design and communicate with others. UML is controlled
by the Object Management Group (OMG) and is the industry standard for graphically describing
software. The OMG have recently completed version 2 of the UML standard—known as UML2.
UML is designed for Object Oriented software design and has limited use for other program-
ming paradigms.
UML is not a method by itself, however it was designed to be compatible with the leading
object-oriented software development methods of its time (e.g., OMT, Booch, Objectory). Since
UML has evolved, some of these methods have been recast to take advantage of the new notation
(e.g., OMT) and new methods have been created based on UML. Most well known is the Rational
Unified Process (RUP) created by the Rational Software Corporation.

43
Modelling There are three prominent parts of a system’s model:

• Functional Model
Showcases the functionality of the system from the user’s Point of View. Includes Use Case
Diagrams.

• Object Model
Showcases the structure and substructure of the system using objects, attributes, operations,
and associations. Includes Class Diagrams.

• Dynamic Model
Showcases the internal behavior of the system. Includes Sequence Diagrams, Activity Dia-
grams and State Machine Diagrams.

UML is composed of many model elements that represent the different parts of a software
system. The UML elements are used to create diagrams, which represent a certain part, or a point
of view of the system. In UML 2.0 there are 13 types of diagrams. Some of the more important
diagrams are:

• Use Case Diagrams show actors (people or other users of the system), use cases (the sce-
narios when they use the system), and their relationships

• Class Diagrams show classes and the relationships between them

• Sequence Diagrams show objects and a sequence of method calls they make to other objects.

• Collaboration Diagrams show objects and their relationship, putting emphasis on the ob-
jects that participate in the message exchange

• State Diagrams show states, state changes and events in an object or a part of the system

• Activity Diagrams show activities and the changes from one activity to another with the
events occurring in some part of the system

• Component Diagrams show the high level programming components (such as KParts or
Java Beans).

• Deployment Diagrams show the instances of the components and their relationships.

Use Case Diagrams Use Case Diagrams describe the relationships and dependencies between
a group of Use Cases and the Actors participating in the process.
It is important to notice that Use Case Diagrams are not suited to represent the design, and
cannot describe the internals of a system. Use Case Diagrams are meant to facilitate the commu-
nication with the future users of the system, and with the customer, and are specially helpful to
determine the required features the system is to have. Use Case Diagrams tell, what the system
should do but do not–and cannot–specify how this is to be achieved.
A Use Case describes–from the point of view of the actors–a group of activities in a system
that produces a concrete, tangible result.
Use Cases are descriptions of the typical interactions between the users of a system and the
system itself. They represent the external interface of the system and specify a form of require-
ments of what the system has to do (remember, only what, not how).
When working with Use Cases, it is important to remember some simple rules:

44
 Figure 2.2: Umbrello UML Modeller showing a Use Case Diagram

• Each Use Case is related to at least one actor

• Each Use Case has an initiator (i.e. an actor)

• Each Use Case leads to a relevant result (a result with a business value)

An actor is an external entity (outside of the system) that interacts with the system by partici-
pating (and often initiating) a Use Case. Actors can be in real life people (for example users of the
system), other computer systems or external events.
Actors do not represent the physical people or systems, but their role . This means that when a
person interacts with the system in different ways (assuming different roles) he will be represented
by several actors. For example a person that gives customer support by the telephone and takes
orders from the customer into the system would be represented by an actor “Support Staff” and an
actor “Sales Representative”
Use Case Descriptions are textual narratives of the Use Case. They usually take the form of a
note or a document that is somehow linked to the Use Case, and explains the processes or activities
that take place in the Use Case.

Class Diagrams Class Diagrams show the different classes that make up a system and how
they relate to each other. Class Diagrams are said to be "static" diagrams because they show the
classes, along with their methods and attributes as well as the static relationships between them:
which classes "know" about which classes or which classes "are part" of another class, but do not
show the method calls between them.
A Class defines the attributes and the methods of a set of objects. All objects of this class
(instances of this class) share the same behavior, and have the same set of attributes (each object

45
 Figure 2.3: Umbrello UML Modeller showing a Class Diagram

Figure 2.4: Visual representation of a Class in UML

has its own set). The term "Type" is sometimes used instead of Class, but it is important to mention
that these two are not the same, and Type is a more general term.
In UML, Classes are represented by rectangles, with the name of the class, and can also show
the attributes and operations of the class in two other "compartments" inside the rectangle.
In UML, Attributes are shown with at least their name, and can also show their type, initial
value and other properties. Attributes can also be displayed with their visibility:

• + Stands for public attributes

• # Stands for protected attributes

• - Stands for private attributes

Operations (methods) are also displayed with at least their name, and can also show their
parameters and return types. Operations can, just as Attributes, display their visibility:

• + Stands for public operations

46
 Figure 2.5: Visual representation of a generalization in UML

Figure 2.6: Visual representation of an Association in UML Aggregation

• # Stands for protected operations

• - Stands for private operations

Class Associations Classes can relate (be associated with) to each other in different ways:
Inheritance is one of the fundamental concepts of Object Orientated programming, in which
a class "gains" all of the attributes and operations of the class it inherits from, and can override/-
modify some of them, as well as add more attributes and operations of its own.

• Generalization In UML, a Generalization association between two classes puts them in a

hierarchy representing the concept of inheritance of a derived class from a base class. In
UML, Generalizations are represented by a line connecting the two classes, with an arrow
on the side of the base class.

• Association An association represents a relationship between classes, and gives the common
semantics and structure for many types of "connections" between objects.
Associations are the mechanism that allows objects to communicate to each other. It de-
scribes the connection between different classes (the connection between the actual objects
is called object connection, or link .
Associations can have a role that specifies the purpose of the association and can be uni- or
bidirectional (indicates if the two objects participating in the relationship can send messages
to the other, of if only one of them knows about the other). Each end of the association also
has a multiplicity value, which dictates how many objects on this side of the association can
relate to one object on the other side.
In UML, associations are represented as lines connecting the classes participating in the
relationship, and can also show the role and the multiplicity of each of the participants.
Multiplicity is displayed as a range [min..max] of non-negative values, with a star (*) on the
maximum side representing infinite.

• Aggregations Aggregations are a special type of associations in which the two participating
classes don’t have an equal status, but make a "whole-part" relationship. An Aggregation

47
 Figure 2.7: Visual representation of an Aggregation relationship in UML

Figure 2.8:

describes how the class that takes the role of the whole, is composed (has) of other classes,
which take the role of the parts. For Aggregations, the class acting as the whole always has
a multiplicity of one.
In UML, Aggregations are represented by an association that shows a rhomb on the side of
the whole.

• Composition Compositions are associations that represent very strong aggregations. This
means, Compositions form whole-part relationships as well, but the relationship is so strong
that the parts cannot exist on its own. They exist only inside the whole, and if the whole is
destroyed the parts die too.
In UML, Compositions are represented by a solid rhomb on the side of the whole.

Other Class Diagram Items Class diagrams can contain several other items besides classes.

• Interfaces are abstract classes which means instances can not be directly created of them.
They can contain operations but no attributes. Classes can inherit from interfaces (through
a realisation association) and instances can then be made of these diagrams.

• Datatypes are primitives which are typically built into a programming language. Common
examples include integers and booleans. They can not have relationships to classes but
classes can have relationships to them.

• Enums are a simple list of values. A typical example is an enum for days of the week. The
options of an enum are called Enum Literals. Like datatypes they can not have relationships
to classes but classes can have relationships to them.

• Packages represent a namespace in a programming language. In a diagram they are used to

represent parts of a system which contain more than one class, maybe hundereds of classes.

Sequence Diagrams Sequence Diagrams show the message exchange (i.e. method call) be-
tween several Objects in a specific time-delimited situation. Objects are instances of classes.
Sequence Diagrams put special emphasis in the order and the times in which the messages to the
objects are sent.
In Sequence Diagrams objects are represented through vertical dashed lines, with the name of
the Object on the top. The time axis is also vertical, increasing downwards, so that messages are
sent from one Object to another in the form of arrows with the operation and parameters name.
Messages can be either synchronous, the normal type of message call where control is passed
to the called object until that method has finished running, or asynchronous where control is passed

48
 Figure 2.9: Umbrello UML Modeller showing a Sequence Diagram

back directly to the calling object. Synchronous messages have a vertical box on the side of the
called object to show the flow of program control.

Collaboration Diagrams Collaboration Diagrams show the interactions occurring between

the objects participating in a specific situation. This is more or less the same information shown
by Sequence Diagrams but there the emphasis is put on how the interactions occur in time while
the Collaboration Diagrams put the relationships between the objects and their topology in the
foreground.
In Collaboration Diagrams messages sent from one object to another are represented by ar-
rows, showing the message name, parameters, and the sequence of the message. Collaboration
Diagrams are specially well suited to showing a specific program flow or situation and are one of
the best diagram types to quickly demonstrate or explain one process in the program logic.

State Diagram State Diagrams show the different states of an Object during its life and the
stimuli that cause the Object to change its state.
State Diagrams view Objects as state machines or finite automata that can be in one of a set of
finite states and that can change its state via one of a finite set of stimuli. For example an Object
of type NetServer can be in one of following states during its life:

• Ready

• Listening

• Working

• Stopped

and the events that can cause the Object to change states are

• Object is created

49
 Figure 2.10: Umbrello UML Modeller showing a Collaboration Diagram

• Object receives message listen

• A Client requests a connection over the network

• A Client terminates a request

• The request is executed and terminated

• Object receives message stop ... etc

Activity Diagram Activity Diagrams describe the sequence of activities in a system with the
help of Activities. Activity Diagrams are a special form of State Diagrams, that only (or mostly)
contains Activities.
Activity Diagrams are always associated to a Class , an Operation or a Use Case .
Activity Diagrams support sequential as well as parallel Activities. Parallel execution is repre-
sented via Fork/Wait icons, and for the Activities running in parallel, it is not important the order
in which they are carried out (they can be executed at the same time or one after the other)

2.2 A Case Study: Card Games

2.3 Creating Abstractions

I N THIS SECTION , we look at some specific examples of object-oriented design in a domain that is
simple enough that we have a chance of coming up with something reasonably reusable. Consider
card games that are played with a standard deck of playing cards (a so-called “poker” deck, since
it is used in the game of poker).

50
 Figure 2.11: Umbrello UML Modeller showing a State Diagram

Figure 2.12: Umbrello UML Modeller showing an Activity Diagram

51
Designing the classes
When designing object-oriented software, a crucial first step is to identify the objects that will
make up the application. One approach to do this is to identify the nouns in the problem descrip-
tion. These become candidates for objects. Next we can identify verbs in the description: these
suggest methods for the objects.
Consider the following description of a card game:

In a typical card game, each player gets a hand of cards. The deck is shuffled and
cards are dealt one at a time from the deck and added to the players’ hands. In some
games, cards can be removed from a hand, and new cards can be added. The game
is won or lost depending on the value (ace, 2, ..., king) and suit (spades, diamonds,
clubs, hearts) of the cards that a player receives.

If we look for nouns in this description, there are several candidates for objects: game, player,
hand, card, deck, value, and suit. Of these, the value and the suit of a card are simple values,
and they will just be represented as instance variables in a Card object. In a complete program,
the other five nouns might be represented by classes. But let’s work on the ones that are most
obviously reusable: card, hand, and deck.
If we look for verbs in the description of a card game, we see that we can shuffle a deck
and deal a card from a deck. This gives use us two candidates for instance methods in a Deck
class: shuffle() and dealCard(). Cards can be added to and removed from hands. This gives
two candidates for instance methods in a Hand class: addCard() and removeCard(). Cards
are relatively passive things, but we need to be able to determine their suits and values. We will
discover more instance methods as we go along.

Black Boxes
A Method is an abstraction mechanism and consists of instructions for performing some task,
chunked together and given a name. "Chunking" allows you to deal with a potentially very com-
plicated task as a single concept. Instead of worrying about the many, many steps that the computer
might have to go though to perform that task, you just need to remember the name of the method.
Whenever you want your program to perform the task, you just call the method. Methods are a
major tool for dealing with complexity.
A method is sometimes said to be a "black box" because you can’t see what’s "inside" it (or,
to be more precise, you usually don’t want to see inside it, because then you would have to deal
with all the complexity that the method is meant to hide). Of course, a black box that has no way
of interacting with the rest of the world would be pretty useless. A black box needs some kind of
interface with the rest of the world, which allows some interaction between what’s inside the box
and what’s outside. A physical black box might have buttons on the outside that you can push,
dials that you can set, and slots that can be used for passing information back and forth. Since we
are trying to hide complexity, not create it, we have the first rule of black boxes:
The interface of a black box should be fairly straightforward, well-defined, and easy
to understand.
Your television, your car, your VCR, your refrigerator... are all examples of black boxes in the
real world. You can turn your television on and off, change channels, and set the volume by using
elements of the television’s interface – dials, remote control, don’t forget to plug in the power –
without understanding anything about how the thing actually works. The same goes for a VCR,
although if stories about how hard people find it to set the time on a VCR are true, maybe the VCR
violates the simple interface rule.

52
 Now, a black box does have an inside – the code in a method that actually performs the task,
all the electronics inside your television set. The inside of a black box is called its implementation.
The second rule of black boxes is that:

To use a black box, you shouldn’t need to know anything about its implementation;
all you need to know is its interface.

In fact, it should be possible to change the implementation, as long as the behavior of the box, as
seen from the outside, remains unchanged. For example, when the insides of TV sets went from
using vacuum tubes to using transistors, the users of the sets didn’t even need to know about it –
or even know what it means. Similarly, it should be possible to rewrite the inside of a method, to
use more efficient code, for example, without affecting the programs that use that method.
Of course, to have a black box, someone must have designed and built the implementation
in the first place. The black box idea works to the advantage of the implementor as well as of
the user of the black box. After all, the black box might be used in an unlimited number of
different situations. The implementor of the black box doesn’t need to know about any of that.
The implementor just needs to make sure that the box performs its assigned task and interfaces
correctly with the rest of the world. This is the third rule of black boxes:

The implementor of a black box should not need to know anything about the larger
systems in which the box will be used. In a way, a black box divides the world into two
parts: the inside (implementation) and the outside. The interface is at the boundary,
connecting those two parts.

You should not think of an interface as just the physical connection between the box and the rest
of the world. The interface also includes a specification of what the box does and how it can be
controlled by using the elements of the physical interface. It’s not enough to say that a TV set has
a power switch; you need to specify that the power switch is used to turn the TV on and off!
To put this in computer science terms, the interface of a method has a semantic as well as
a syntactic component. The syntactic part of the interface tells you just what you have to type
in order to call the method. The semantic component specifies exactly what task the method
will accomplish. To write a legal program, you need to know the syntactic specification of the
method. To understand the purpose of the method and to use it effectively, you need to know the
method’s semantic specification. I will refer to both parts of the interface – syntactic and semantic
– collectively as the contract of the method.
The contract of a method says, essentially, "Here is what you have to do to use me, and here
is what I will do for you, guaranteed." When you write a method, the comments that you write
for the method should make the contract very clear. (I should admit that in practice, methods’
contracts are often inadequately specified, much to the regret and annoyance of the programmers
who have to use them.)
You should keep in mind that methods are not the only example of black boxes in program-
ming. For example, a class is also a black box. We’ll see that a class can have a "public" part,
representing its interface, and a "private" part that is entirely inside its hidden implementation. All
the principles of black boxes apply to classes as well as to methods.

Preconditions and Postconditions

When working with methods as building blocks, it is important to be clear about how a method
interacts with the rest of the program. A convenient way to express the contract of a method is in
terms of preconditions and postconditions.

53
 The precondition of a method is something that must be true when the method is
called, if the method is to work correctly.
For example, for the built-in method Math.sqrt(x), a precondition is that the parameter, x, is
greater than or equal to zero, since it is not possible to take the square root of a negative number. In
terms of a contract, a precondition represents an obligation of the caller of the method. If you call a
method without meeting its precondition, then there is no reason to expect it to work properly. The
program might crash or give incorrect results, but you can only blame yourself, not the method.
A postcondition of a method represents the other side of the contract. It is something that will
be true after the method has run (assuming that its preconditions were met – and that there are
no bugs in the method). The postcondition of the method Math.sqrt() is that the square of the
value that is returned by this method is equal to the parameter that is provided when the method is
called. Of course, this will only be true if the preconditiion – that the parameter is greater than or
equal to zero – is met. A postcondition of the built-in method System.out.print() is that the
value of the parameter has been displayed on the screen.
Preconditions most often give restrictions on the acceptable values of parameters, as in the
example of Math.sqrt(x). However, they can also refer to global variables that are used in
the method. The postcondition of a method specifies the task that it performs. For a method,
the postcondition should specify the value that the method returns. Methods are often described
by comments that explicitly specify their preconditions and postconditions. When you are given
a pre-written method, a statement of its preconditions and postcondtions tells you how to use it
and what it does. When you are assigned to write a method, the preconditions and postconditions
give you an exact specification of what the method is expected to do. Its a good idea to write
preconditions and postconditions as part of comments are given in the form of Javadoc comments,
but I will explicitly label the preconditions and postconditions. (Many computer scientists think
that new doc tags @precondition and @postcondition should be added to the Javadoc system for
explicit labeling of preconditions and postconditions, but that has not yet been done.

The Deck Class:

First, we’ll design the deck class in detail. When a deck of cards is first created, it contains 52
cards in some standard order. The Deck class will need a constructor to create a new deck. The
constructor needs no parameters because any new deck is the same as any other. There will be
an instance method called shuffle() that will rearrange the 52 cards into a random order. The
dealCard() instance method will get the next card from the deck. This will be a method with a
return type of Card, since the caller needs to know what card is being dealt. It has no parameters
– when you deal the next card from the deck, you don’t provide any information to the deck; you
just get the next card, whatever it is. What will happen if there are no more cards in the deck
when its dealCard() method is called? It should probably be considered an error to try to deal a
card from an empty deck, so the deck can throw an exception in that case. But this raises another
question: How will the rest of the program know whether the deck is empty? Of course, the
program could keep track of how many cards it has used. But the deck itself should know how
many cards it has left, so the program should just be able to ask the deck object. We can make this
possible by specifying another instance method, cardsLeft(), that returns the number of cards
remaining in the deck. This leads to a full specification of all the methods in the Deck class:
/** Constructor. Create a shuffled deck of cards.
* @precondition: None
* @postcondition: A deck of 52, shuffled cards is created.*/
public Deck()

/** Shuffle all cards in the deck into a random order.

54
 * @precondition: None
* @postcondition: The existing deck of cards with the cards
* in random order.*/
public void shuffle()

/** Returns the size of the deck

* @return the number of cards that are still left in the deck.
* @precondition: None
* @postcondition: The deck is unchanged. */
public int size()

/** Determine if this deck is empty

* @return true if this deck has no cards left in the deck.
* @precondition: None
* @postcondition: The deck is unchanged. */
public boolean isEmpty()

/** Deal one card from this deck

* @return a Card from the deck.
* @precondition: The deck is not empty
* @postcondition: The deck has one less card. */
public Card deal()

This is everything you need to know in order to use the Deck class. Of course, it doesn’t tell
us how to write the class. This has been an exercise in design, not in programming. With this
information, you can use the class in your programs without understanding the implementation.
The description above is a contract between the users of the class and implementors of the class—it
is the “public interface” of the class.

The Hand Class:

We can do a similar analysis for the Hand class. When a hand object is first created, it has no cards
in it. An addCard() instance method will add a card to the hand. This method needs a parameter
of type Card to specify which card is being added. For the removeCard() method, a parameter
is needed to specify which card to remove. But should we specify the card itself (“Remove the
ace of spades”), or should we specify the card by its position in the hand (“Remove the third card
in the hand”)? Actually, we don’t have to decide, since we can allow for both options. We’ll
have two removeCard() instance methods, one with a parameter of type Card specifying the
card to be removed and one with a parameter of type int specifying the position of the card in
the hand. (Remember that you can have two methods in a class with the same name, provided
they have different types of parameters.) Since a hand can contain a variable number of cards, it’s
convenient to be able to ask a hand object how many cards it contains. So, we need an instance
method getCardCount() that returns the number of cards in the hand. When I play cards, I like
to arrange the cards in my hand so that cards of the same value are next to each other. Since this
is a generally useful thing to be able to do, we can provide instance methods for sorting the cards
in the hand. Here is a full specification for a reusable Hand class:
/** Create a Hand object that is initially empty.
* @precondition: None
* @postcondition: An empty hand object is created.*/
public Hand() {

/** Discard all cards from the hand, making the hand empty.
* @precondition: None

55
* @postcondition: The hand object is empty. */
public void clear() {

/** If the specified card is in the hand, it is removed.

* @param c the Card to be removed.
* @precondition: c is a Card object and is non−null.
* @postcondition: The specified card is removed if it exists.*/
public void removeCard(Card c) {

/** Add the card c to the hand.

* @param The Card to be added.
* @precondition: c is a Card object and is non−null.
* @postcondition: The hand object contains the Card c
* and now has one more card.
* @throws NullPointerException is thrown if c is not a
* Card or is null. */
public void addCard(Card c) {

/** Remove the card in the specified position from the hand.
* @param position the position of the card that is to be removed,
* where positions start from zero.
* @precondition: position is valid i.e. 0 < position < number cards
* @postcondition: The card in the specified position is removed
* and there is one less card in the hand.
* @throws IllegalArgumentException if the position does not exist in
* the hand. */
public void removeCard(int position) {

/** Return the number of cards in the hand.

* @return int the number of cards in the hand
* @precondition: none
* @postcondition: No change in state of Hand. */
public int getCardCount() {

/** Gets the card in a specified position in the hand.

* (Note that this card is not removed from the hand!)
* @param position the position of the card that is to be returned
* @return Card the Card at the specified position.
* @throws IllegalArgumentException if position does not exist.
* @precondition: position is valid i.e. 0 < position < number cards.
* @postcondition: The state of the Hand is unchanged. */
public Card getCard(int position) {

/** Sorts the cards in the hand in suit order and in value order
* within suits. Note that aces have the lowest value, 1.
* @precondition: none
* @postcondition: Cards of the same
* suit are grouped together, and within a suit the cards
* are sorted by value. */
public void sortBySuit() {

/** Sorts the cards in the hand so that cards are sorted into
* order of increasing value. Cards with the same value
* are sorted by suit. Note that aces are considered
* to have the lowest value.
* @precondition: none

56
 * @postcondition: Cards are sorted in order of increasing value.*/
public void sortByValue() {

The Card Class

The class will have a constructor that specifies the value and suit of the card that is being created.
There are four suits, which can be represented by the integers 0, 1, 2, and 3. It would be tough to
remember which number represents which suit, so I’ve defined named constants in the Card class
to represent the four possibilities. For example, Card.SPADES is a constant that represents the
suit, spades. (These constants are declared to be public final static ints. It might be better
to use an enumerated type, but for now we will stick to integer-valued constants. I’ll return to the
question of using enumerated types in this example at the end of the chapter.) The possible values
of a card are the numbers 1, 2, ..., 13, with 1 standing for an ace, 11 for a jack, 12 for a queen, and
13 for a king. Again, I’ve defined some named constants to represent the values of aces and face
cards.
A Card object can be constructed knowing the value and the suit of the card. For example, we
can call the constructor with statements such as:
card1 = new Card( Card.ACE, Card.SPADES ); // Construct ace of spades.
card2 = new Card( 10, Card.DIAMONDS ); // Construct 10 of diamonds.
card3 = new Card( v, s ); // This is OK, as long as v and s
// are integer expressions.
A Card object needs instance variables to represent its value and suit. I’ve made these
private so that they cannot be changed from outside the class, and I’ve provided getter methods
getSuit() and getValue() so that it will be possible to discover the suit and value from out-
side the class. The instance variables are initialized in the constructor, and are never changed after
that. In fact, I’ve declared the instance variables suit and value to be final, since they are
never changed after they are initialized. (An instance variable can be declared final provided it
is either given an initial value in its declaration or is initialized in every constructor in the class.)
Finally, I’ve added a few convenience methods to the class to make it easier to print out cards
in a human-readable form. For example, I want to be able to print out the suit of a card as the word
“Diamonds”, rather than as the meaningless code number 2, which is used in the class to represent
diamonds. Since this is something that I’ll probably have to do in many programs, it makes sense to
include support for it in the class. So, I’ve provided instance methods getSuitAsString() and
getValueAsString() to return string representations of the suit and value of a card. Finally,
I’ve defined the instance method toString() to return a string with both the value and suit, such
as “Queen of Hearts”. Recall that this method will be used whenever a Card needs to be converted
into a String, such as when the card is concatenated onto a string with the + operator. Thus, the
statement
System.out.println( "Your card is the " + card );
is equivalent to
System.out.println( "Your card is the " + card.toString() );
If the card is the queen of hearts, either of these will print out
‘‘Your card is the Queen of Hearts’’.
Here is the complete Card class. It is general enough to be highly reusable, so the work that
went into designing, writing, and testing it pays off handsomely in the long run.
/** An object of type Card represents a playing card from a
* standard Poker deck, including Jokers. The card has a suit, which
* can be spades, hearts, diamonds, clubs, or joker. A spade, heart,

57
 * diamond, or club has one of the 13 values: ace, 2, 3, 4, 5, 6, 7,
* 8, 9, 10, jack, queen, or king. Note that "ace" is considered to be
* the smallest value. A joker can also have an associated value;
* this value can be anything and can be used to keep track of several
* different jokers.
*/
public class Card {
public final static int SPADES = 0; // Codes for the 4 suits.
public final static int HEARTS = 1;
public final static int DIAMONDS = 2;
public final static int CLUBS = 3;

public final static int ACE = 1; // Codes for the non−numeric cards.
public final static int JACK = 11; // Cards 2 through 10 have their
public final static int QUEEN = 12; // numerical values for their codes.
public final static int KING = 13;

/** This card’s suit, one of the constants SPADES, HEARTS, DIAMONDS,
* CLUBS. The suit cannot be changed after the card is
* constructed. */
private final int suit;

/** The card’s value. For a normal cards, this is one of the values
* 1 through 13, with 1 representing ACE. The value cannot be changed
* after the card is constructed. */
private final int value;

/** Creates a card with a specified suit and value.

* @param theValue the value of the new card. For a regular card (non−joker),
* the value must be in the range 1 through 13, with 1 representing an Ace.
* You can use the constants Card.ACE, Card.JACK, Card.QUEEN, and Card.KING.
* For a Joker, the value can be anything.
* @param theSuit the suit of the new card. This must be one of the values
* Card.SPADES, Card.HEARTS, Card.DIAMONDS, Card.CLUBS, or Card.JOKER.
* @throws IllegalArgumentException if the parameter values are not in the
* permissible ranges */
public Card(int theValue, int theSuit) {
if (theSuit != SPADES && theSuit != HEARTS && theSuit != DIAMONDS &&
theSuit != CLUBS )
throw new IllegalArgumentException("Illegal playing card suit");
if (theValue < 1 || theValue > 13)
throw new IllegalArgumentException("Illegal playing card value");
value = theValue;
suit = theSuit;
}

/** Returns the suit of this card.

* @returns the suit, which is one of the constants Card.SPADES,
* Card.HEARTS, Card.DIAMONDS, Card.CLUBS */
public int getSuit() {
return suit;
}

/** Returns the value of this card.

* @return the value, which is one the numbers 1 through 13. */

58
 public int getValue() {
return value;
}

/** Returns a String representation of the card’s suit.

* @return one of the strings "Spades", "Hearts", "Diamonds", "Clubs".*/
public String getSuitAsString() {
switch ( suit ) {
case SPADES: return "Spades";
case HEARTS: return "Hearts";
case DIAMONDS: return "Diamonds";
case CLUBS: return "Clubs";
default: return "Null";
}
}

/** Returns a String representation of the card’s value.

* @return for a regular card, one of the strings "Ace", "2",
* "3", ..., "10", "Jack", "Queen", or "King". */
public String getValueAsString() {
switch ( value ) {
case 1: return "Ace";
case 2: return "2";
case 3: return "3";
case 4: return "4";
case 5: return "5";
case 6: return "6";
case 7: return "7";
case 8: return "8";
case 9: return "9";
case 10: return "10";
case 11: return "Jack";
case 12: return "Queen";
default: return "King";
}
}

/** Returns a string representation of this card, including both

* its suit and its value. Sample return values
* are: "Queen of Hearts", "10 of Diamonds", "Ace of Spades", */
public String toString() {
return getValueAsString() + " of " + getSuitAsString();
}

} // end class Card

2.4 Example: A Simple Card Game

We will finish this section by presenting a complete program that uses the Card and Deck classes.
The program lets the user play a very simple card game called HighLow. A deck of cards is
shuffled, and one card is dealt from the deck and shown to the user. The user predicts whether the
next card from the deck will be higher or lower than the current card. If the user predicts correctly,
then the next card from the deck becomes the current card, and the user makes another prediction.

59
This continues until the user makes an incorrect prediction. The number of correct predictions is
the user’s score.
My program has a method that plays one game of HighLow. This method has a return value
that represents the user’s score in the game. The main()method lets the user play several games
of HighLow. At the end, it reports the user’s average score.
Note that the method that plays one game of HighLow returns the user’s score in the game as
its return value. This gets the score back to the main program, where it is needed. Here is the
program:

import java.util.Scanner;
/**
* This program lets the user play HighLow, a simple card game
* that is described in the output statements at the beginning of
* the main() method. After the user plays several games,
* the user’s average score is reported.
*/
public class HighLow {

Scanner keyboard = new Scanner(System.in);

public static void main(String[] args) {

System.out.println("This program lets you play the simple card game,");

System.out.println("HighLow. A card is dealt from a deck of cards.");
System.out.println("You have to predict whether the next card will be");
System.out.println("higher or lower. Your score in the game is the");
System.out.println("number of correct predictions you make before");
System.out.println("you guess wrong.");
System.out.println();

int gamesPlayed = 0; // Number of games user has played.

int sumOfScores = 0; // The sum of all the scores from
// all the games played.
double averageScore; // Average score, computed by dividing
// sumOfScores by gamesPlayed.
boolean playAgain; // Record user’s response when user is
// asked whether he wants to play
// another game.

do {
int scoreThisGame; // Score for one game.
scoreThisGame = play(); // Play the game and get the score.
sumOfScores += scoreThisGame;
gamesPlayed++;
System.out.print("Play again? ");
playAgain = keyboard.nextBoolean();
} while (playAgain);

averageScore = ((double)sumOfScores) / gamesPlayed;

System.out.println();
System.out.println("You played " + gamesPlayed + " games.");
System.out.printf("Your average score was %1.3f.\n", averageScore);

60
} // end main()

/**
* Let’s the user play one game of HighLow, and returns the
* user’s score on that game. The score is the number of
* correct guesses that the user makes.
*/
private static int play() {

Deck deck = new Deck(); // Get a new deck of cards, and

// store a reference to it in
// the variable, deck.

Card currentCard; // The current card, which the user sees.

Card nextCard; // The next card in the deck. The user tries
// to predict whether this is higher or lower
// than the current card.

int correctGuesses ; // The number of correct predictions the

// user has made. At the end of the game,
// this will be the user’s score.

char guess; // The user’s guess. ’H’ if the user predicts that
// the next card will be higher, ’L’ if the user
// predicts that it will be lower.

deck.shuffle(); // Shuffle the deck into a random order before

// starting the game.

correctGuesses = 0;
currentCard = deck.dealCard();
System.out.println("The first card is the " + currentCard);

while (true) { // Loop ends when user’s prediction is wrong.

/* Get the user’s prediction, ’H’ or ’L’ (or ’h’ or ’l’). */

System.out.print("Will the next card be higher(H) or lower(L)? ");

do {
guess = keyboard.next().charAt(0);
guess = Character.toUpperCase(guess);
if (guess != ’H’ && guess != ’L’)
System.out.print("Please respond with H or L: ");
} while (guess != ’H’ && guess != ’L’);

/* Get the next card and show it to the user. */

nextCard = deck.dealCard();
System.out.println("The next card is " + nextCard);

61
 /* Check the user’s prediction. */

if (nextCard.getValue() == currentCard.getValue()) {
System.out.println("The value is the same as the previous card.");
System.out.println("You lose on ties. Sorry!");
break; // End the game.
}
else if (nextCard.getValue() > currentCard.getValue()) {
if (guess == ’H’) {
System.out.println("Your prediction was correct.");
correctGuesses++;
}
else {
System.out.println("Your prediction was incorrect.");
break; // End the game.
}
}
else { // nextCard is lower
if (guess == ’L’) {
System.out.println("Your prediction was correct.");
correctGuesses++;
}
else {
System.out.println("Your prediction was incorrect.");
break; // End the game.
}
}

/* To set up for the next iteration of the loop, the nextCard

becomes the currentCard, since the currentCard has to be
the card that the user sees, and the nextCard will be
set to the next card in the deck after the user makes
his prediction. */

currentCard = nextCard;
System.out.println();
System.out.println("The card is " + currentCard);

} // end of while loop

System.out.println();
System.out.println("The game is over.");
System.out.println("You made " + correctGuesses
+ " correct predictions.");
System.out.println();

return correctGuesses;

} // end play()
} // end class

62
 CHAPTER
3
N ESTED C LASSES

Contents
2.1 Introduction to Software Engineering . . . . . . . . . . . . . . . . . . . . . . . . 39
Software Engineering Life-Cycles . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Object-oriented Analysis and Design . . . . . . . . . . . . . . . . . . . . . . . . 40
Documenting Designs: The Unified Modelling Language . . . . . . . . . . . . 43
2.2 A Case Study: Card Games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.3 Creating Abstractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Designing the classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Black Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Preconditions and Postconditions . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.4 Example: A Simple Card Game . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3.1 Nested Classes

A class seems like it should be a pretty important thing. A class is a high-level building block
of a program, representing a potentially complex idea and its associated data and behaviors. I’ve
always felt a bit silly writing tiny little classes that exist only to group a few scraps of data together.
However, such trivial classes are often useful and even essential. Fortunately, in Java, I can ease
the embarrassment, because one class can be nested inside another class. My trivial little class
doesn’t have to stand on its own. It becomes part of a larger more respectable class. This is
particularly useful when you want to create a little class specifically to support the work of a larger
class. And, more seriously, there are other good reasons for nesting the definition of one class
inside another class.
In Java, a nested class is any class whose definition is inside the definition of another class.
Nested classes can be either named or anonymous. I will come back to the topic of anonymous
classes later in this section. A named nested class, like most other things that occur in classes, can
be either static or non-static.

63
 The definition of a static nested looks just like the definition of any other class, except that it
is nested inside another class and it has the modifier static as part of its declaration. A static
nested class is part of the static structure of the containing class. It can be used inside that class to
create objects in the usual way. If it has not been declared private, then it can also be used outside
the containing class, but when it is used outside the class, its name must indicate its membership
in the containing class. This is similar to other static components of a class: A static nested class
is part of the class itself in the same way that static member variables are parts of the class itself.
For example, suppose a class named WireFrameModel represents a set of lines in three-
dimensional space. (Such models are used to represent three-dimensional objects in graphics
programs.) Suppose that the WireFrameModel class contains a static nested class, Line, that
represents a single line. Then, outside of the class WireFrameModel, the Line class would be
referred to as WireFrameModel.Line. Of course, this just follows the normal naming conven-
tion for static members of a class. The definition of the WireFrameModel class with its nested
Line class would look, in outline, like this:

public class WireFrameModel {

. . . // other members of the WireFrameModel class

static public class Line {

// Represents a line from the point (x1,y1,z1)
// to the point (x2,y2,z2) in 3−dimensional space.
double x1, y1, z1;
double x2, y2, z2;
} // end class Line

. . . // other members of the WireFrameModel class

} // end WireFrameModel

Inside the WireFrameModel class, a Line object would be created with the constructor
“new Line()”. Outside the class, “new WireFrameModel.Line()” would be used.
A static nested class has full access to the static members of the containing class, even to the
private members. Similarly, the containing class has full access to the members of the nested
class. This can be another motivation for declaring a nested class, since it lets you give one class
access to the private members of another class without making those members generally available
to other classes.
When you compile the above class definition, two class files will be created. Even though the
definition of Line is nested inside WireFrameModel, the compiled Line class is stored in a sepa-
rate file. The full name of the class file for the Line class will be WireFrameModel$Line.class.
Non-static nested classes are referred to as inner classes. Inner classes are not, in practice,
very different from static nested classes, but a non-static nested class is actually associated with
an object rather than to the class in which it is nested. This can take some getting used to.
Any non-static member of a class is not really part of the class itself (although its source code
is contained in the class definition). This is true for inner classes, just as it is for any other non-
static part of a class. The non-static members of a class specify what will be contained in objects
that are created from that class. The same is true – at least logically – for inner classes. It’s as if
each object that belongs to the containing class has its own copy of the nested class. This copy
has access to all the instance methods and instance variables of the object, even to those that are
declared private. The two copies of the inner class in two different objects differ because the
instance variables and methods they refer to are in different objects. In fact, the rule for deciding
whether a nested class should be static or non-static is simple: If the nested class needs to use any

64
instance variable or instance method, make it non-static. Otherwise, it might as well be static.
From outside the containing class, a non-static nested class has to be referred to using a name
of the form variableName. NestedClassName, where variableName is a variable that refers
to the object that contains the class. This is actually rather rare, however. A non-static nested class
is generally used only inside the class in which it is nested, and there it can be referred to by its
simple name.
In order to create an object that belongs to an inner class, you must first have an object that
belongs to the containing class. (When working inside the class, the object “this” is used im-
plicitly.) The inner class object is permanently associated with the containing class object, and it
has complete access to the members of the containing class object. Looking at an example will
help, and will hopefully convince you that inner classes are really very natural. Consider a class
that represents poker games. This class might include a nested class to represent the players of the
game. This structure of the PokerGame class could be:
public class PokerGame { // Represents a game of poker.

private class Player { //Represents one of the players in this game.

...

} // end class Player

private Deck deck; // A deck of cards for playing the game.

private int pot; // The amount of money that has been bet.
...
} // end class PokerGame
If game is a variable of type PokerGame, then, conceptually, game contains its own copy of
the Player class. In an an instance method of a PokerGame object, a new Player object would
be created by saying “new Player()”, just as for any other class. (A Player object could
be created outside the PokerGame class with an expression such as “game.newÂăPlayer()”.
Again, however, this is very rare.) The Player object will have access to the deck and pot
instance variables in the PokerGame object. Each PokerGame object has its own deck and pot
and Players. Players of that poker game use the deck and pot for that game; players of another
poker game use the other game’s deck and pot. That’s the effect of making the Player class non-
static. This is the most natural way for players to behave. A Player object represents a player
of one particular poker game. If Player were a static nested class, on the other hand, it would
represent the general idea of a poker player, independent of a particular poker game.

3.2 Example of Inner Classes

We’ve so far considered two structured data types âĂŞ arrays, which are used for storing sequences
of data items all of the same type, and strings, used for storing sequences of characters. The
problems we need to solve don’t always fit into these simplistic constraints, and it is useful to
consider a number of variations on these basic structures which may be suitable under different
circumstances.
Arrays are used to store data items all of the same type, for example, all elements of
int[][] myArr = new int[4][5];
are integers.
This is limiting as at times we wish to store some information about a particular entity (eg
a person, or a book, or a can of paint), and the information is not all of the same type. Typical
attributes might be

65
 person: name (String),
ID number (long),
date of birth (date object, or 3 integers),
annual salary (double) âò
e.
book: title (String),
author (String),
ISBN number (long),
year published (int) âò
e.
paint: product code (int or String),
colour code (int or String),
description (String),
volume in litres (int),
selling price (double),
number of cans in stock (int) âò
e.

If we are designing a class to deal with a single instance of such an object we would define
attributes of different types and write a constructor, Getâòe and Setâòe methods and any other
methods required to provide the object with functionality.
However, consider the case where we do not require the individual objects to have functional-
ity, but rather merely wish to use them to store data, and in particular wish to deal with many such
objects, for example, all the persons employed by a company, or all the books in a library, or all
the cans of paint in a shop. In that case the class we’re designing would be an Employer class, or
a Library class, or a Paintshop class and an attribute of such a class would be an array of persons
or books or paint.
In order to define an array of such objects we need to define a class from which to instantiate
the objects to form the elements of the array. Such a class only needs to have context and mean-
ing within its parent class âĂŞ for example, a book within the Library, or a can of paint within
the Paintshop âĂŞ and so is not defined as a general purpose, stand-alone class with full object
functionality, but rather as an inner class.
An inner class is a class defined within another class (called its outer class), and which has
meaning and scope only within that enclosing class. It’s purpose is to support the work of the
containing outer class. In this context an inner class can be thought of as a “user-defined data
type” in that we are defining our own structure with component elements (fields) of any type
which together represent some entity. The outer class can access the attributes of its inner class
directly.
For example, consider a class representing a university course which needs to store information
about the students registered for that course such as student name and number, class mark, exam
mark and final mark. An inner class can be defined to represent a student with suitable attributes,
and the course class can have an array of such student objects as attribute.
// A course class consisting of a number of student objects
// Illustrates using an inner class

import java.io.*;

// The Course class

public class Course{

// inner class to represent a student

private class Student {

private long stNum; // student number

private String stName; // student name

66
 private double examMark=0; // stored
private double classMark=0; // stored
private double finalMark=0; // calc from class&exam

} // end of Student class

// attributes of class Course

private String courseName; // module name
private int nSt; // num students registered
private Student [] students; // array of Student objects
private int nPass; // num students who passed

// constructor − creates a course object with name,

// number of students and array of registered Students,
Course(String name, int numSt, String fname) throws IOException {
courseName = name;
nSt = numSt;
students = new Student[nSt];

Scanner fin = new Scanner(new File(fname));

for (int i=0;i<nSt;i++) { // sets up the array of students

// instantiate each student object
students[i] = new Student();
// read attrib values from file and calc final amark
students[i].stNum = fin.nextLong();
students[i].examMark = fin.nextDouble();
students[i].classMark = ifn.nextDouble();
students[i].stName = fin.nextl();
students[I].finalMark =
(students[i].examMark*2 + students[i].classMark)/3.0;
}
}

// sort Student array into ascending order on student number

public void SortStudents() {
int pass = 0;
boolean swapped;

do {
pass++;
swapped = false;
for (int st=0;st<(nSt−pass);st++) {
if (students[st].stNum>students[st+1].stNum) {
// exchange references. âĂŞ no need to copy data values
Student temp = students[st];
students[st] = students[st+1];
students[st+1] = temp;
swapped = true;
}
}
} while (swapped); // if no swops made => sorted
}

67
 // Displays the student data
public void Display() {
System.out.println(courseName + "\n−−−−−−−−−");

for (int st=0;st<nSt;st++) {

System.out.println(GenIO.format(students[st].stNum,9)+" "
+ (students[st].stName)
+ (students[st].examMark)
+ (students[st].classMark)
+ (students[st].finalMark));
}
}
Note that the attributes of class Student can be accessed in class Course even though they are
declared private since Student is defined inside Course and is hence within its scope. The indi-
vidual attributes are referenced using the particular object name (eg students[i] for that particular
object in the array) together with the attribute required as in
students[i].finalMark = (students[i].examMark*2 + students[i].classMark)/3.0;
In other words, since this is an internal class it is not necessary to provide Get.. and Set..
methods to access the attribute values from the methods of outer class.
When creating an array of objects there are 3 steps to follow to instantiate the array correctly:

1. declare an array of the appropriate object type private Student [] students;

2. instantiate this array to hold the required number of elements (objects) students = new Student[nSt];
or 1 and 2 can be combined as in private Student [] students = new Student[nSt];

3. instantiate each object in the array

for (int i=0;i<nSt;i++){
students[i] = new Student();
...
}

Recall the process that occurs when an array (or any object) is declared.
declare: int [] marks;
instantiate: marks = new int[5];

or

declare: Time lecture;

instantiate: lecture = new Time(); (assuming no constructor)
The declaration defines the object name and allocates a variable to hold the reference (address)
of the object; the instantiation reserves the memory needed to hold the array elements or object
attributes and stores the address of this memory block in the object variable.
In the 3 step declaration of an array of objects,

1. the first declaration defines the name of the array of objects and allocates a variable to hold
its address;

2. the instantiation of this array serves as the declaration of the n objects in the array and
reserves the n units of storage needed to hold the memory address of each object;

68
 3. the instantiation of each of the n objects in the array reserves space for that object’s attributes
and puts their start address in the array element for that object.

The inner class discussed above provides a means of grouping items of dissimilar data types
into a single object, but no methods are provided to give functionality to the class âĂŞ it merely
represents a data structure.
Another approach is to include some limited functionality to augment the basic data represen-
tation of the inner class. This does not normally consist of a full range of methods of different
types providing a variety of behaviours âĂŞ such functionality is usually reserved for independent
classes (discussed below) âĂŞ but typically the class is provided with one or more constructors to
allow the object to be instantiated with specific values and not just defaults, and a toString method
to allow for default display of the object’s attributes values.
The inner class Student of the Course class discussed above has been modified to illustrate this
approach of incorporating some limited functionality into the inner class.
// inner class to represent a student
private class Student {
private long stNum; // student number
private String stName; // student name
private double examMark=0; // stored
private double classMark=0; // stored
private double finalMark=0; // calc from class&exam

// constructor − creates a student object with number and name

Student(long num,String name) {
stNum = num;
stName = name;
}

// returns a String containing all the details for this student.

public String toString() {
String outString = "";

outString = stNum + " "

+ stName
+ examMark
+ classMark
+ finalMark;

return outString;
}
} // end of Student class

3.3 Anonymous Inner Classes

In some cases, you might find yourself writing an inner class and then using that class in just a
single line of your program. Is it worth creating such a class? Indeed, it can be, but for cases like
this you have the option of using an anonymous inner class. An anonymous class is created
with a variation of the newoperator that has the form
new superclass−or−interface( parameter−list) {
methods−and−variables
}

69
 This constructor defines a new class, without giving it a name, and it simultaneously creates an
object that belongs to that class. This form of the new operator can be used in any statement where
a regular “new” could be used. The intention of this expression is to create: “a new object be-
longing to a class that is the same as superclass-or-interface but with these methods-and-variables
added.” The effect is to create a uniquely customized object, just at the point in the program where
you need it. Note that it is possible to base an anonymous class on an interface, rather than a class.
In this case, the anonymous class must implement the interface by defining all the methods that
are declared in the interface. If an interface is used as a base, the parameter−list is empty.
Otherwise, it contains parameters for a constructor in the superclass.
Anonymous classes are often used for handling events in graphical user interfaces, and we
will encounter them several times in the chapters on GUI programming. For now, we will look
at one not-very-plausible example. Consider the Drawable interface, which is defined earlier in
this section. Suppose that we want a Drawable object that draws a filled, red, 100-pixel square.
Rather than defining a new, separate class and then using that class to create the object, we can use
an anonymous class to create the object in one statement:
Drawable redSquare = new Drawable() {
void draw(Graphics g) {
g.setColor(Color.red);
g.fillRect(10,10,100,100);
}
};
The semicolon at the end of this statement is not part of the class definition. It’s the semicolon
that is required at the end of every declaration statement.
When a Java class is compiled, each anonymous nested class will produce a separate class
file. If the name of the main class is MainClass, for example, then the names of the class
files for the anonymous nested classes will be MainClass$1.class, MainClass$2.class,
MainClass$3.class, and so on.

70
 CHAPTER
4
I NHERITANCE
Object oriented languages have a feature called inheritance. Inheritance enables you to define a
new class based upon an existing class. The new class is similar to the existing class, but has
additional member variables and methods. This makes programming easier because you can build
upon an existing class instead of starting out from scratch. Inheritance (and other features of object
oriented languages) is responsible for the enormous success of modern software. Programmers
are able to build upon previous work and to continuously improve and upgrade existing software.
For example, graphical user interface programming is done by using inheritance with the basic
graphical classes that are contained in a standard library. The classes needed for a particular
application are created by customizing these basic classes.

Problems with Hacking Code Instead of creating new classes from old classes by inheri-
tance, you couldjust copy the source code for the old class and modify it so that it does exactly
what you want. But this leads to problems.
If you have the source code for a class, you could copy the code and change it to do what you
wanted. Before object oriented programming that was what was done. But there are at least two
problems with this:

1. It is hard to stay organized. Say that you already have several dozen classes and that you
need additional classes based on the original ones. Also, say that you need several classes
based on the new classes. You will end up with dozens of source files which are all versions
of other source files that have been changed in various ways. Without careful planning you
will end up with an unorganized, inconsistent, buggy mess.
2. You need to study the original code. Say that you have a complicated class that basically
does what you want, but you need a small modification. If you edit the source code, even to
make a small change, you risk breaking something. So you must study the original code to
be sure that your changes are correct. This may not be easy.

The automatic inheritance mechanism of Java greatly relieves both of these problems. In a
diagram (see Fig. 5.1) showing inheritance, an arrow points from the new class to the class it is
based upon. The arrow is sometimes labeled “is a”.

71
 Figure 4.1: Inheritance Diagram

Figure 4.2: Inheritance Diagram

In these notes, clouds represent classes and rectangles represent objects. This style of rep-
resenting classes comes from the book Object-oriented Analysis and Design, by Grady Booch
(Addison-Wesley, 1994). In official UML (Unified Modeling Language) both classes and objects
are represented with rectangles.

Single Inheritance The class that is used to define a new class is called a parent class (or
superclass or base class.) The class based on the parent class is called a child class (or subclass
or derived class.)
In Java, (unlike with humans) children inherit characteristics from just one parent. This is
called single inheritance. Some languages allow a child to inherit from more than one parent.
This is called multiple inheritance. With multiple inheritance, it is sometimes hard to tell which
parent contributed what characteristics to the child (as with humans). Java avoids these problems
by using single inheritance.
A parent can have any number of children. But a child can have only one parent. There are
three sets of phrases for describing inheritance relationships: parent/child, base class/derived class,
superclass/subclass.
Programmers use all three sets interchangebly.

Is-a Relationship A parent class cannot inherit characteristics from its child class. Inheritance
goes in only one direction.
The picture shows a parent class and a child class. The line between them shows the “is-a”
relationship. The arrow points to the parent class from the child class. The picture can be read
as “a Ford is-a automobile.” The phrase “is-a” is in common use in computer science. The arrow
between a child and parent is sometimes called an “is-a link”. The clouds represent classes. This

72
 Figure 4.3: Inheritance Diagram

Figure 4.4: Is-a Relationship

Figure 4.5: Objects

picture does not show objects.

Inheritance is between classes, not between objects.

A parent class is a blueprint that is followed when an object is constructed. A child class of
the parent is another blueprint (that looks much like the original), but with added features. The
child class is used to construct objects that look like the parent’s objects, but with added features.
The picture shows a parent class and a child class, and some objects that have been constructed
from each. These objects are shown as rectangles (to convey the idea that they are more real than
the classes, which are only designs). In the picture, “Joe’s car,” “Mary’s Ford,” and “Bob’s Ford”

73
 Figure 4.6: Hierarchies

represent actual objects. The cloudy classes represent designs, not actual objects. Objects are
constructed as a program runs. An object is constructed by following a description in a class file,
the result of compiling a Java source program.

Hierarchies This picture shows a hierarchy of classes. It shows that “Ford is-a automobile,”
“Nissan is-a automobile,” and that “VW is-a automobile.” It also shows that “Sentra is-a Nissan.”
In a hierarchy, each class has at most one parent but might have several children classes. The class
at the top of the hierarchy has no parent. This class is called the root of the hierarchy.
A class may be the parent for a child class and may be a child of another class. Just as with
human relationships, a person is a child of some humans and a parent to others. The syntax for
deriving a child class from a parent class is:
class childClass extends parentClass {
// new characteristics of the child class go here

Video Store Example Programming in Java consists mostly of creating class hierarchies and
instantiating objects from them. The Java Development Kit gives you a rich collection of base
classes that you can extend to do your work.
Here is a program that uses a class Video to represent videos available at a rental store. Inher-
itance is not explicitly used in this program (so far).
class Video {
String title; // name of the item
int length; // number of minutes
boolean avail; // is the video in the store?

// constructor
public Video( String ttl ) {
title = ttl; length = 90; avail = true;
}

// constructor

74
 public Video( String ttl, int lngth ) {
title = ttl; length = lngth; avail = true;
}

public void show() {

System.out.println( title + ", " + length + " min. available:" + avail );
}

public class VideoStore {

public static void main ( String args[] ) {
Video item1 = new Video("Jaws", 120 );
Video item2 = new Video("Star Wars" );

item1.show();
item2.show();
}
}
The Video class has basic information in it, and could be used for documentaries and instruc-
tional videos. But more information is needed for movie videos. Let us make a class that is similar
to Video, but now includes the name of the director and a rating.
class Movie extends Video {
String director; // name of the director
String rating; // G, PG, R, or X

// constructor
public Movie( String ttl, int lngth, String dir, String rtng ) {
super( ttl, lngth ); // use the super class’s constructor
director = dir;
rating = rtng; //initialize what’s new to Movie
}
}
The class Movie is a subclass of Video. An object of type Movie has the following members
in it:
title inherited from Video
length inherited from Video
avail inherited from Video
show() inherited from Video
director defined in Movie
rating defined in Movie
Both classes are defined: the Video class can be used to construct objects of that type, and now
the Movie class can be used to construct objects of the Movie type.
A child class inherits both variables and methods e.g. the method show in the superclass Video
is inherited in the subclass Movie.
The class definition for Video has a constructor that initializes the member data of Video
objects. The class Movie has a constructor that initializes the data of Movie objects.
The constructor for class Movie looks like this:
// constructor
public Movie( String ttl, int lngth, String dir, String rtng ){
super(ttl, lngth); // use the super class’s constuctor
director = dir; rating = rtng; // initialize the members new to Movie

75
 }
The statement super(ttl, lngth) invokes a constructor of the parent to initialize some of
the data. There are two constructors in the parent. The one that is invoked is the one that matches
the argument list in super(ttl, lngth). Then the next two statements initialize the members
that only Movie has. Note: super() must be the first statement in the subclass’s constructor.
The statement that invokes the parent’s constructor called is super() because the parent of a
class is sometimes called its superclass.
A constructor for a child class always starts with an invocation of one of the constuctors in
the parent class. If the parent class has several constructors then the one which is invoked is
determined by matching argument lists. For example, we could define a second constructor for
Movie that does not include an argument for length. It starts out by invoking the parent constructor
that does not have an argument for length:
// alternate constructor
public Movie( String ttl, String dir, String rtng ){
super( ttl ); // invoke the matching parent class constructor
director = dir; rating = rtng; // initialize members unique to Movie
}
A child constructor always invokes a parent constructor.
Examine the following proposed constructor for Movie:
// proposed constructor
public Movie( String ttl, int lngth, String dir, String rtng ){
title = ttl; // do what the parent’s constuctor does.
length = lngth;
avail = true;

director = dir; rating = rtng;

}
It looks like there is no need to invoke the parent class’s constructor since all variables are
initialized in this one. However a constructor from the parent class is always invoked even if you
don’t explicity ask for it.
The Java compiler automatically (automagically) inserts a call to super in the first line of the
constructor. The above code can be regarded as “shorthand” for this:
// proposed constructor
public Movie( String ttl, int lngth, String dir, String rtng ){
super(); // invoke the parent’s no−argument constructor
title = ttl; // do what the parent’s constuctor does.
length = lngth;
avail = true;

director = dir; rating = rtng;

}
As always, super() comes first, even if you don’t write it in. If the parent does not have a no-
argument constructor, then using this “shorthand” causes a syntax error. In our program the class
definition for Video (the superclass) lacks a no-argument constructor. The proposed constructor
(above) calls for such a constructor so it would cause a syntax error.
A class has a no-argument constructor when:

1. The programmer can write a no-argument constructor for a class.

2. If the programmer does not write any constructors for a class, then a no-argument construc-
tor (called the default constructor) is automatically supplied.

76
 3. If the programmer writes even one constructor for a class then the default constructor is not
automatically supplied.

In the example program, the class definition for Video includes a constructor, so the default
constructor was not automatically supplied. So the constructor proposed for Movie causes a syntax
error. Let us not use it.
Here is an example program that makes use of the two classes:
public class VideoStore{
public static void main ( String args[] ) {
Video item1 = new Video("Microcosmos", 90 );
Movie item2 = new Movie("Jaws", 120, "Spielberg", "PG" );
item1.show();
item2.show();
}
}
The program prints:
Microcosmos, 90 min. available:true
Jaws, 120 min. available:true
The statement item2.show() calls the show() method of item2. This method was inherited
without change from the class Video. This is what it looks like:
public void show() {
System.out.println( title + ", " + length +
" min. available:" + avail ); }
It does not mention the new variables that have been added to objects of type Movie, so nothing
new is printed out. We cannot change show() in Video to include the line System.out.println( "dir: "+ dire
because the class Video does not define the instance variables director and rating, so its show()
method can’t use them.

Overriding Methods We need a new show() method in the class Movie:

//added to class Movie
public void show() {
System.out.println( title + ", " + length +
" min. available:" + avail );
System.out.println("dir: " + director + " " + rating );
}
Now, even though the parent has a show() method the new definition of show() in the child
class will override the parent’s version.
A child’s method overrides a parent’s method when it has the same signature as a parent
method. Now the parent has its method, and the child has its own method with the same signature.
(Remember that the signature of a method is the name of the method and its parameter list.)
An object of the parent type includes the method given in the parent’s definition. An object of
the child type includes the method given in the child’s definition.
With the change in the class Movie the following program will print out the full information
for both items.
class videoStore{
public static void main ( String args[] ) {
Video item1 = new Video("Microcosmos", 90 );
Movie item2 = new Movie("Jaws", 120, "Spielberg", "PG" );
item1.show();

77
 item2.show();
}
}
The line item1.show() calls the show() method defined in Video, and the line item2.show()
calls the show() method defined in Movie.
Microcosmos, 90 min. available:true Jaws,
120 min. available:true
dir: Spielberg PG
Notice that the Movie class includes some code that is already written.

Using super in a Child’s Method Sometimes (as in the example) you want a child class to
have its own method, but that method includes everything the parent’s method does. You can use
the super reference in this situation. For example, here is Video’s method:
public void show() {
System.out.println( title + ", " + length + "
min. available:" + avail ); }
Here is Movie’s method without using super:
public void show() {
System.out.println( title + ", " + length
+ " min. available:" + avail );
System.out.println( "dir: " + director+ " " + rating );
}
Movie’s method would better be written using super:
public void show() {
super.show();
System.out.println( "dir: " + director + " " + rating ); }
Unlike the case when super is used in a constructor, inside a method super does not have to
be used in the first statement. Two reasons why using super in this way is a good thing to do.

1. You should not have to write the same code more than once.

2. A change made to the method in the parent class is inherited by the child class.

Music Video Class So far the video rental application has two classes: Video and Movie. Say
that you wanted to create a new class, MusicVideo that will be like Video but will have two new
instance variables: artist (the name of the performer) and category (“R&B”, “Pop”, “Classical”,
“Other” ). Both of these will be Strings.
The MusicVideo class will need its own constructor and its own show() method.
The new class looks like this:
class MusicVideo extends Video{
String artist;
String category;

// The constructor will go here

// The show() method will go here

78
 Figure 4.7: Many Subclasses

The MusicVideo class is a subclass of Video. The Movie class is not shown, but is also a
subclass of Video. Remember that a class can have several subclasses.
MusicVideo inherits title, length, and avail from its parent and adds artist and category. Notice
that MusicVideo inherits only from its parent Video. It does not inherit anything from its sibling
class Movie. Here is the definition so far:
We need a constructor for MusicVideo. We will use four parameters for title, length, artist and
category. Initialize avail to true.
// constructor
public MusicVideo ( String ttl, int len, String art, String cat ) {
super( ttl, len );
artist = art;
category = cat;
}

Note that the super reference must be in the first statement of the constructor. To finish the
MusicVideo class, we write a show() method for it using a super reference to do the things already
done by the parent class.
The show() method for MusicVideo can use super.show() where ever it needs to. It is the first
statement (below) because that is where it makes the most sense.
public void show() {
System.out.println( title + ", " + length +
" min. available:" + avail ); }
}

You may have noticed a major design flaw in the definitions of these classes âĂŤ none has a
rental price! Say that it was your job to fix this problem. How can this be fixed?
All videos have a rental price, so the fixes should be made to the parent class Video. A new
variable rent should be added to the parent class. Then modify its constructor and its show()
method. The two child classes will inherit these changes. Fixing the parent class fixes all of its
children.

The Object Class

Remember the rule: every constructor starts out with a super() constructor. If you don’t explicitly
put it in, then the Java compiler automatically puts it in for you. Now look at the definition of
Video.
This is correct. All classes have a parent class (a super class) except one. The class at the top
of the Java class hierarchy is called Object. If a class definition does not specify a parent class then
it automatically has Object as a parent class. The compiler automatically assumes, for example:

79
class Video extends Object . . . It is not possible to write a class definition that does not have
Object as its ultimate ancestor.
If you define a class that does not explicitly extend another class, then it automatically extends
Object. If you define the class so that it extends a class other than Object, then that class either
extends another class or extends Object. Now that class in turn must either extend another class
or extend Object. There is no way to end the chain except by (ultimately) extending Object. You
might cleverly try to have class A extend class B, and have class B extend class A. But this (and
other loops) is not allowed. Ultimately, every Java object inherits its object-like behavior from
the class Object. When an object is constructed a chain of constructors is invoked starting with
the one in Object and ending with the one in the requested class. The fundamental parts of the
object are put together by the constructor in Object, then additional parts are added down the chain
until the requested class is reached. Construction starts with the constructor in Object because each
constructor (except Object’s constructor) starts by invoking its super() constructor (with or without
arguments).
The parent class does not have to be recompiled each time a new child class is derived from it.

80
 CHAPTER

5
A BSTRACT C LASSES AND
P OLYMORPHISM
Classes in a hierarchy are related by the is-a relationship. For example, a Nissan is-a Automobile,
and a Sentra is-a Nissan. This chapter discusses how reference variables are used for objects from
different classes within a hierarchy. Another subject is the idea of an abstract class âĂŤ a class
that cannot be instantiated but that can be the parent of other classes.

Greeting Card Hierarchy The example of this chapter is a hierarchy of greeting cards types.
The parent class is Card, and its children classes are Valentine, Holiday, and Birthday.

81
 A card object will have a greeting() method that writes out a greeting. Each type of card
contains an appropriate greeting. The Holiday card says “Season’s Greetings.” The Birthday card
says “Happy Birthday.” The Valentine cards says “Love and Kisses.” In this example, an object
must be an instance of one of the three child types: Valentine, Holiday, and Birthday. There will be
no such thing as an object that is merely a “Card.” The Card class represents the abstract concept
of "Card." All actual card objects must be more specific.

5.1 Abstract Class

For this example, all card objects are one of the three types (Valentine, Holiday, or Birthday) and
the parent class Card is used only to group them into a hierarchy. There will never be an object that
is just a card. This is useful to do, just as a store has all its various greeting cards in one display,
arranged into several categories.

An abstract class in Java is a class that is never instantiated. Its purpose is to be a

parent to several related classes. The children classes inherit from the abstract parent
class.

82
 In hierarchy drawings abstract classes are drawn with dotted lines. An abstract class is defined
like this:
abstract class ClassName {
. . . . . // definitions of methods and variables
}
Access modifiers such as public can be placed before abstract. Even though it can not be
instantiated, an abstract class can define methods and variables that children classes inherit.
In this example, each card class has its own version of the greeting() method. Each
class has a greeting(), but each one is implemented differently. It is useful to put an ab-
stract greeting() method in the parent class. This says that each child inherits the “idea” of
greeting(), but each implementation is different. Here is the class definition of the abstract
class Card:
abstract class Card {
String recipient; // name of who gets the card

public abstract void greeting(); // abstract greeting() method

}
This is the complete definition of this abstract class. Notice the abstract method. Abstract
classes can (but don’t have to) contain abstract methods. Also, an abstract class can contain non-
abstract methods, which will be inherited by the children.
An abstract method has no body. (It has no statements.) It declares an access modifier,
return type, and method signature followed by a semicolon. A non-abstract child class
inherits the abstract method and must define a non-abstract method that matches the
abstract method.
An abstract child of an abstract parent does not have to define non-abstract methods for the abstract
signatures it inherits. This means that there may be several steps between an abstract base class to
a child class that is completely non-abstract. Since no constructor is defined in Card the default no-
argument constructor is automatically supplied by the compiler. However, this constructor cannot
be used directly because no Card object can be constructed.
This stuff takes thought and practice. It took years for computer scientists to agree on this idea,
and they have not stopped arguing about it. Abstract classes are used to organize the “concept”
of something that has several different versions in the children. The abstract class can include
abstract methods and non-abstract methods. Here is a class definition for class Holiday. It is a
non-abstract child of an abstract parent:
class Holiday extends Card {
public Holiday( String r ) {
recipient = r;
}

public void greeting() {

System.out.println("Dear " + recipient + ",\n");
System.out.println("Season’s Greetings!\n\n");
}
}
The class Holiday is not an abstract class. Objects can be instantiated from it. Its constructor
implicitly calls the no-argument constructor in its parent, Card, which calls the constructor in
Object. So even though it has an abstract parent, Holiday objects are as much objects as any other.
• Holiday inherites the abstract method greeting() from its parent.

83
 • Holiday must define a greeting() method that includes a method body (statements between
braces).

• The definition of greeting() must match the signature given in the parent.

• If Holiday did not define greeting(), then Holiday would be declared an abstract class.
This would make it an abstract child of an abstract parent.

Each of the classes that inherit from Card has a greeting() method. By using an abstract
class a programmer can make all children of that class look alike in important ways.
Not everything defined in an abstract classes needs to be abstract. The variable recipient is
defined in Card and inherited in the usual way. However, if a class contains even one abstract
method, then the class itself has to be declared to be abstract. Here is a program to test the two
classes.
abstract class Card {
String recipient;
public abstract void greeting();
}

class Holiday extends Card {

public Holiday( String r ) {
recipient = r;
}

public void greeting() {

System.out.println("Dear " + recipient + ",\n");
System.out.println("Season’s Greetings!\n\n");
}
}

public class CardTester{

public static void main ( String[] args ) {
Holiday hol = new Holiday("Santa");
hol.greeting();
}
}
This is a complete, runable program. You could write this program without using an abstract
class.

Advantage of Abstract Classes Abstract classes are a way of organizing a program. You
can get the same thing done without using this way to organize. This is a matter of program design,
which is not easy at all. Here is a sample run of the program:
Dear Santa,

Season’s Greetings!
The advantage of using an abstract class is that you can group several related classes together as
siblings. Grouping classes together is important in keeping a program organized and understand-
able. The picture shows this program after its object has been constructed.
It would be nice to deal some other cards. Here is the Birthday class:
class Birthday extends Card {
int age;

84
 Figure 5.1: Inheritance Diagram

public Birthday ( String r, int years ) {

recipient = r;
age = years;
}

public void greeting() {

System.out.println("Dear " + recipient + ",\n");
System.out.println("Happy " + age + "th Birthday\n\n");
}
}
The Valentine class is much the same, except for some added passion:
class Valentine extends Card {
int kisses;

public Valentine ( String r, int k ) {

recipient = r;
kisses = k;
}

public void greeting() {

System.out.println("Dear " + recipient + ",\n");
System.out.println("Love and Kisses,\n");
for ( int j=0; j<kisses; j++ )
System.out.print("X");
System.out.println("\n\n");
}
}
Each message() method from each of the sibling classes is different but they all meet the re-
quirement of the abstract parent class, Card. All that Card asked for was: public abstract void greeting();
Each sibling did that in its own way.
Here a class that tests and uses the other classes.
public class CardTester{
public static void main ( String[] args ) {
String me;
Scanner input = new Scanner( System.in );
System.out.print("Your name: ");

85
 Figure 5.2: Card Objects

me = input.next();

Holiday hol = new Holiday( me );

hol.greeting();

Birthday bd = new Birthday( me, 21 );

bd.greeting();

Valentine val = new Valentine( me, 7 );

val.greeting();

}
}
The abstract Card class can be used as a model of what each new type of card should look like.
By using hierarchical organization and inheritance it is easy to add many more card classes
and to create a well organized program. This was unthinkable not too many years ago. Here is a
sample run of this program:
Your name:
Sue
Dear Sue,

Season’s Greetings!

Dear Sue,

Happy 21th Birthday

Dear Sue,

Love and Kisses,

XXXXXXX

86
 When the main() method has constructed its three objects, the situation is as in the picture.
There are three classes that can be instantiated, and one object of each class has been instantiated.
Of course, as many objects as you need of each type (except Card) can be instantiated.
Although there are 4 classes only 3 be instantiated. The parent class Card is an abstract class
and therefore cannot be instantiated. You can’t instantiate an abstract class do the following:
. . . .

public static void main ( String[] args ) { . . . .

Card card = new Card() ; // can’t instantiate abstract class

card.greeting() ;

. . . .
}
Because Card is an abstract class, the compiler flags this as a syntax error. Card does have a
constructor that is (implicitly) invoked by its children, but it cannot be invoked directly. However,
the following is OK:
. . . .

public static void main ( String[] args ) {

. . . .

Card card = new Valentine( "Joe", 14 ) ; // a Valentine is−a Card

card.greeting() ;

. . . .
}
It is OK to save a reference to a Valentine object in a reference variable of type Card because
Valentine is-a Card. You can think of the reference variable Card as being a card rack designed to
hold any type of a Card.
It would be OK to do the following:
Card card2 = new Holiday( "Bob" );
Card card3 = new Birthday( "Emily" ) ;
Both are correct, since Holiday is-a Card and Birthday is-a Card.
A reference variable of a class “C” can be used with any object that is related by inheritance to
class “C”. For example, a Card reference variable card2 can hold a reference to a Holiday object,
a Valentine object, or a Birthday object. Often at run time, a reference variable of a parent class
type holds a reference to a child object.

Important Point: When a method is invoked, it is the class of the object (not of the
variable) that determines which method is run.

This is what you would expect. The method that is run is part of the object (at least conceptually).
For example:
Card card = new Valentine( "Joe", 14 ) ;
card.greeting();

Card card2 = new Holiday( "Bob" ) ;

card2.greeting();

Card card3 = new Birthday( "Emily", 12 ) ;

87
 card3.greeting();

This will run the greeting() method for a Valentine, then it will run the greeting() method for a
Holiday, then it will run the greeting() method for a Birthday. The type of the object in each case
determines which version of the method is run.
It is not necessary to use three different variables for this program fragment. Just one could
have be used for each object in succession (assuming that the program does no more than is
shown.)

5.2 Polymorphism
Polymorphism means “having many forms.” In Java, it means that a single variable might be used
with several objects of related classes at different times in a program. When the variable is used
with “dot notation” variable.method() to invoke a method, exactly which method is run depends
on the object that the variable currently refers to. Here is an example:
. . . . // class definitions as before

public class CardTester { public static void main ( String[] args ) {

Card card = new Holiday( "Amy" );

card.greeting(); //Invoke a Holiday greeting()

card = new Valentine( "Bob", 3 );

card.greeting(); //Invoke a Valentine greeting()

card = new Birthday( "Cindy", 17 );

card.greeting(); //Invoke a Birthday greeting()

}
}

The program will write

Dear Amy,

Season’s Greetings!

Dear Bob,

Love and Kisses,

XXX

Dear Cindy,

Happy 17th Birthday

What types of objects a reference variable can refer to:

A variable can hold a reference to an object whose class is a descendant of the class
of the variable.

The class of the object must be a descendant of the class of the variable that holds a reference
to that object. A descendant of a class is a child of that class, or a child of a child of that class, and

88
 Figure 5.3: Is-a Relationship

so on. Siblings are not descendants of each other (you did not inherit anything from your brother,
thank goodness.)
Note: there are some complications to this rule which are skipped in these notes, since you
will probably never need to know them. Here are some variable declarations:
Card c;
Birthday b;
Valentine v;
Holiday h
Consider the following correct and incorrect statements
c = new Valentine("Debby", 8); //OK
b = new Valentine("Elroy", 3); //WRONG
v = new Valentine("Fiona", 3); //OK
h = new Birthday ("Greg", 35); //WRONG

Another Hierarchy Here is a picture of another hierarchy: There are no abstract classes
in this hierarchy, so each class can be instantiated. As seen previously, the following is OK:
parentReferenceVariable = referenceToChild ; A reference variable of a parent type
can hold a reference to an object of one of its child types (or a reference to one of their child types,
and so on.) However, the opposite direction // don’t do this childReferenceVariable = referenceToPa
can not be done. Here are some variables:
Rodent rod;
Rat rat;
Mouse mou;
The table below shows correct and incorrect code snippets.
rod = new Rat(); //OK
rod = new FieldMouse(); //OK
mou = new Rat(); //NOT OK
mou = new Rodent(); //NOT OK
rat = new Rodent(); //NOT OK
rat = new LabRat(); //OK
rat = new FieldMouse(); //NOT OK
rat = new Mouse(); //NOT OK

89
More Polymorphism
Recall that polymorphism is when a reference variable may at different times in a program refer
to objects of different (but related) classes.

(Review: ) The signature of a method is the name of the method and types in its
parameter list, something like this: someMethod( int, double, String ) The return type
is not part of the signature. The names of the parameters do not matter, just their
types.

The name of a method is not enough to uniquely identify it because there may be several
versions of a method, each with different parameters. Using the types in the parameter list says
more carefully which method you want. The return type can’t be used because of the following
situation. Say that there are two someMethod() methods: one defined in a parent class like this:
int someMethod( int x, double y, String z ) {
//method body
}
and another method defined in a child class like this:
short someMethod( int a, double b, String c ) {
// completely different method body
}
Somewhere else in the program someMethod() is called:
long w = child.someMethod(12, 34.9, "Which one?");
The value on the right of the = could be either int or short. Both can be converted to a long value
needed for the variable w. You can not tell which someMethod() matches the statement. In other
words, the signatures of the two methods are not unique.
E.g. These two methods have different signatures:
double aMethod( int x, String y){. . .}
short aMethod( int a, double b){. . .}

Overriding abstract Methods An abstract class will usually contain abstract methods. An
abstract method definition consists of:
• optional access modifier (public, private, and others),

• the reserved word abstract,

• the class of the return value,

• a method signature,

• a semi-colon.
No curly braces or method body follow the signature. Here is the abstract class Parent including
the abstract compute() method:
abstract class Parent {
public abstract int compute( int x, String j);
}
If a class has one or more abstract methods it must be declared to be abstract. An abstract class
may have methods that are not abstract (the usual sort of method). These methods are inherited by
children classes in the usual way.

90
 • A non-abstract child class of an abstract parent class must override each of the abstract
methods of its parent. A non-abstract child must override each abstract method inherited
from its parent by defining a method with the same signature and same return type.

– Objects of the child class will include this method.

• A child may define additional methods with signatures different from the parent’s method.

– Child objects will include these methods in addition to the first one.

• It is an error if a child defines a method with the same signature as a parent method, but with
a different return type.

These rules are not really as terrible as they seem. After working with inheritance for a while
the rules will seem clear. Here is a child of Parent:
class Child extends Parent {
public int compute( int x, String j )
{ . . . }
}
The child’s compute() method correctly overrides the parent’s abstract method.
For e.g. the following does not correctly override the parent’s abstract method:
class Child extends Parent
{
public double compute( int x, String j )
{ . . . }
}
It is an error if a child defines a method with the same signature as a parent method, but with a
different return type.
Non-abstract children must override the abstract methods of their parents. Here is our situa-
tion:
class Parent {
public abstract int compute( int x, String j);
}

class Child extends Parent{

// child’s compute method
}
Examine each of the following choices for filling the blank. What will the new definition do?
Override the parent’s method, define an additional method, or be an error? (If the choice defines
an additional method, assume that the required method is also defined.)
method defined in Child Override,
Additional,
or Error?
−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
public int compute( int x,String j ){ . . . } //Override

public int compute( int stuff, String str ){ . . . } //Override.

(Parameter
names don’t
matter, just
their types.)

91
 public int Compute( int x, String j ){ . . . } Additional
Method

public int compute( String j, int x){ . . . } Additional

Method−−the
parameter
order
matters.

public double compute( int x, String j){ . . . } Error−−if the

signature is
the same, the
return type
must match
the
parent.

If child class defines just one method, and that method has the same name as the parent’s
abstract method, but with a different signature then the child class must be abstract. Since the
child did not define a method with the same signature and same return type as the parent, it must
be declared to be abstract. It is OK to have an abstract child of an abstract parent.
Let us use the hierarchy of classes used previously to illustrate these ideas.
The diagram shows that the class Card is an abstract class (which, therefore, cannot be instan-
tiated.) Card has a single abstract method, greeting(). The other three classes are ordinary classes
which can be instantiated. They inherit from Card, so each must define a greeting() method which
is not abstract.

(Review: ) When a method is invoked as here: referenceVariable.greeting().

The class of the object determines which method is run not the class of the reference
variable

It makes sense that the object’s method is invoked, since, after all, the method is part of the object
and the method uses the object’s data. Here is an example from previously:
. . . . // class definitions as before

public class CardTester

{
public static void main ( String[] args ) throws IOException
{

Card card = new Holiday( "Amy" );

card.greeting(); //Invoke a Holiday greeting()

card = new Valentine( "Bob", 3 );

card.greeting(); //Invoke a Valentine greeting()

card = new Birthday( "Cindy", 17 );

card.greeting(); //Invoke a Birthday greeting()

}
}

The reference variable card is used three times, each time with a different class of object. Since
Card is a parent to the three different classes, the variable card can be used for each.

92
 Figure 5.4: Card Hierarchy

Note that a variable Valentine val cannot be used with a Holiday object because Valentine val
and Holiday are siblings. Since they are not related by inheritance, a reference variable of one
type cannot be used with an object of the other type.

Extended Hierarchy The Card hierarchy is extended by adding two new classes:

• A YouthBirthday birthday card for young people. This card will add the line “How you have
grown!” to the usual birthday greeting.

• An AdultBirthday birthday card for old people. This card will add the line “You haven’t
changed at all!” to the usual birthday greeting.

The class Birthday is the parent for these two new classes. The diagram omits the other two
classes, but assume that they are still defined. Each of the new classes would ordinarily inherit the

93
 Figure 5.5: Extended Hierarchy

greeting() method from Birthday. But we want to override that method with a specialized method
in each of the new classes. Here is the class definition of Birthday from previously:
class Birthday extends Card{
int age;

public Birthday ( String r, int years ) {

recipient = r;
age = years;
}

public void greeting() {

System.out.println("Dear " + recipient + ",\n");
System.out.println("Happy " + age + "th Birthday\n\n");
}
}
Here is a class definition of YouthBirthday:
class YouthBirthday extends Birthday{
public YouthBirthday ( String r, int years ) {
super ( r, years )
}

public void greeting() {

super.greeting();
System.out.println("How you have grown!!\n");
}
}
Note that we invoke the superclass constructor by using super. In a constructor, super must
appear before anything else (although in this example there isn’t anything else.) Recall that even
if you don’t put it in explicitly the compiler will automatically put a call to super as the first thing
a constructor does.
When the greeting() method of a YouthBirthday object is invoked, first its superclass’s method
will run, then the rest of the new method will run.
The following code

94
 YouthBirthday yb = new YouthBirthday( "Valerie", 7 );
yb.greeting();
will print:
Dear Valerie,

Happy 7th Birthday

How you have grown!!

Using Polymorphism Assume that AdultBirthday has been defined. It will look much like
YouthBirthday but with a slightly different birthday message. Here is a program fragment (part of
main() in another class):
AdultBirthday ab = new AdultBirthday( "Walter", 47);
ab.greeting();
It will write out:
Dear Walter,

Happy 47th Birthday

You haven’t changed at all!

Now inspect the following code:
Card crd = new YouthBirthday( "Valerie", 7 );
crd.greeting();

crd = new AdultBirthday( "Walter", 47 );

crd.greeting();

crd = new Birthday( "Zoe", 30 );

crd.greeting();
Notice that crd can be used for each of the three objects.
The program will output:
Dear Valerie,

Happy 7th Birthday

How you have grown!!

Dear Walter,

Happy 47th Birthday

You haven’t changed at all!

Dear Zoe,

Happy 30th Birthday

95
The abstract class Card is related to each of the three classes by inheritance, and so the variable
crd can be used with each of them. Now inspect the following:
YouthBirthday birth;
birth = new Birthday( "Terry", 23 );

This code is incorrect. A reference variable for a child class (YouthBirthday) cannot be used for
an object of a parent class (Birthday).
Parents can accommodate children, but children can’t accommodate parents. If you find this
rule hard to remember, just think of yourself and your parents: It is OK for you to go home and
stay in your parent’s house for a few days, but it’s not OK for them to stay in your dorm room for
a few days.
Now let us re-write YouthBirthday in order to show more about polymorphism. Say that you
want two greeting() methods for YouthBirthday:

1. The parent’s greeting() method.

• This will be included by inheritance.

2. A method with the name of the sender as a parameter.

• This will be an additional methodâĂŢit will not override the parent’s method.
• In addition to what the parent’s method does, this method will write out “How you
have grown!! Love,” followed by the name of the sender.

The revised class is seen below. Now objects of the YouthBirthday class have two methods:
greeting(), and greeting( String ).
// Revised version
class YouthBirthday extends Birthday{
public YouthBirthday ( String r, int years ){
super ( r, years )
}

// additional method−−−does not override parent’s method

public void greeting( String sender ) {
super.greeting();
System.out.println("How you have grown!!\n");
System.out.println("Love, " + sender +"\n" );
}
}

Here is a YouthBirthday object using each of its two methods:

YouthBirthday yBday = new YouthBirthday( "Henry", 12 );
yBday.greeting();
yBday.greeting( "Alice" );

This program fragment will write out

Dear Henry,
Happy 12th Birthday

Dear Henry,
Happy 12th Birthday
How you have grown!!
Love, Alice

96
 The “top” of the hierarchy of cards is the class Card. Sometimes this is called the root of the
hierarchy. A variable of the root type, Card, can be used with any of its descendants:
Card crd = new YouthBirthday( "Valerie", 7 );
crd.greeting(); // print a youth birthday greeting

crd = new AdultBirthday( "Walter", 47 );

crd.greeting(); // print an adult birthday greeting

crd = new Birthday( "Zoe", 30 );

crd.greeting(); // print a generic birthday greeting

Holiday hol = new Holiday( "Kelly" );

Valentine val = new Valentine( "Jill", 42 );

crd = hol;
crd.greeting(); // print a holiday greeting

crd = val;
crd.greeting(); // print a valentine greeting

When a program uses several related objects, it is often useful to have a reference variable than
can be used with any of them.

Array of Related Objects Now any object that belongs in the hierarchy can fit into any slot
of the array. This is like the greeting card display at the drug store that holds a different selection
of cards in different seasons of the year. Here is a program snippet:
Card[] cards = new Card[12];

cards[0] = new YouthBirthday( "Valerie", 7 );

cards[1] = new AdultBirthday( "Walter", 47 );
cards[2] = new Birthday( "Zoe", 30 );
cards[3] = new Holiday( "Kelly" );
cards[4] = new Valentine( "Jill", 42 );

for ( int j=0; j <= 4; j++ )

cards[j].greeting();

This code will create 5 cards objects of various varieties and put them into the array. Then it
will ask each object in the array to write out its own version of the greeting. This will work fine:
Dear Valerie,
Happy 7th Birthday
How you have grown!!

Dear Walter,
Happy 47th Birthday
You haven’t changed at all!

Dear Zoe,
Happy 30th Birthday

Dear Kelly,
Season’s Greetings!

Dear Jill,

97
 Love and Kisses,
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
(I’ve eliminated some blank lines from the actual output.)
Now say that this code follows the above. What will it do?
Card temp;

temp = cards[0];
cards[0] = cards[1];
cards[1] = temp;
It exchanges the objects in the first two slots of the array.

The Object class This sort of activity is very common in programming. You will see it a lot
in the future. Notice that no new objects were created; but different reference variables were used
for already-existing objects. In Java, there is a pre-defined class that is the ultimate ancestor of all
other classes. This class is called Object. When you define a class of your own like this:
class MyNewClass {

}
You are actually defining a child of the Object class. The following is the exact equivalent of the
above:
class MyNewClass extends Object{

}
Every class in Java âĂŤ your own and every class in every library âĂŤ descends from Object. This
will be important to remember when you get to graphical user interfaces.
Since every class is a descendant of Object, an Object reference variable can be used with an
object of any class. For example:
Object obj;

String str = "Yertle" ;

Double dbl = new Double( 32.0 );
YouthBirthday ybd = new YouthBirthday( "Ian", 4 );

obj = str;
obj = dbl;
obj = ybd;
Each of the last three statements is correct (although in this program, useless.) It would not
be correct if this followed the above statements: obj.greeting(); It is true that obj refers to a
YouthBirthday object, which has a greeting() method. But the compiler needs to be told this
with a type cast. The following is OK:
((YouthBirthday)obj).greeting();
A typecast is used to tell the compiler what is “really” in a variable that itself is not specific enough.
The following is not OK:
Object obj;
String str = "Yertle" ;

obj = str; ((YouthBirthday)obj).greeting();

98
The instanceof Operator A typecast is used to tell the compiler what is “really” in a vari-
able that itself is not specific enough. You have to tell the truth. In a complicated program,
a reference variable might end up with any of several different objects, depending on the input
data or other unpredictable conditions. To deal with this, the instanceof operator is used.
variable instanceof Class.
This operator evaluates to true or false depending on whether the variable refers to an object of
type Class. For example in the following fragment, instanceof is used to ensure that the object
referenced by obj is used correctly:
Object obj;
YouthBirthday ybd = new YouthBirthday( "Ian", 4 );
String str = "Yertle" ;

obj = ybd;

if ( obj instanceof YouthBirthday )

((YouthBirthday)obj).greeting();

if ( obj instanceof String )

System.out.print( (String)obj );
instanceof will also return true if the class of the object on the left is a child (or grandchild
or greatgrandchild or ...) of the class on the right.
If you don’t know in advance what classes a variable might hold instanceof will not help.
You can use it to test for several possible classes, but only if you know what the possibilities are.

99
 CHAPTER
6
G RAPHICAL U SER I NTERFACES
IN JAVA

Contents
5.1 Abstract Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
5.2 Polymorphism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
More Polymorphism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

6.1 Introduction: The Modern User Interface

W HEN COMPUTERS WERE FIRST INTRODUCED, ordinary people,including most programmers,
couldn’t get near them. They were locked up in rooms with white-coated attendants who would
take your programs and data, feed them to the computer, and return the computer’s response
some time later. When timesharing – where the computer switches its attention rapidly from one
person to another – was invented in the 1960s, it became possible for several people to interact
directly with the computer at the same time. On a timesharing system, users sit at “terminals”
where they type commands to the computer, and the computer types back its response. Early
personal computers also used typed commands and responses, except that there was only one
person involved at a time. This type of interaction between a user and a computer is called a
command-line interface.
Today most people interact with computers in a completely different way. They use a Graph-
ical User Interface, or GUI. The computer draws interface components on the screen. The com-
ponents include things like windows, scroll bars, menus, buttons, and icons. Usually, a mouse is
used to manipulate such components.
A lot of GUI interface components have become fairly standard. That is, they have similar ap-
pearance and behavior on many different computer platforms including M ACINTOSH, W INDOWS,
and L INUX. JAVA programs, which are supposed to run on many different platforms without mod-
ification to the program, can use all the standard GUI components. They might vary a little in

101
appearance from platform to platform, but their functionality should be identical on any computer
on which the program runs.
Below is a very simple JAVA program–actually an “applet,”–that shows a few standard GUI
interface components. There are four components that the user can interact with: a button, a
checkbox, a text field, and a pop-up menu. These components are labeled. There are a few other
components in the applet. The labels themselves are components (even though you can’t interact
with them). The right half of the applet is a text area component, which can display multiple lines
of text, and a scrollbar component appears alongside the text area when the number of lines of text
becomes larger than will fit in the text area. And in fact, in JAVA terminology, the whole applet is
itself considered to be a “component.”

JAVA actually has two complete sets of GUI components. One of these, the AWT or Abstract
Windowing Toolkit, was available in the original version of JAVA. The other, which is known as
Swing, is included in JAVA version 1.2 or later, and is used in preference to the AWT in most
modern JAVA programs. The applet that is shown above uses components that are part of Swing.
When a user interacts with the GUI components in this applet, an “event” is generated. For
example, clicking a push button generates an event, and pressing return while typing in a text field
generates an event. Each time an event is generated, a message is sent to the applet telling it that
the event has occurred, and the applet responds according to its program. In fact, the program
consists mainly of “event handlers” that tell the applet how to respond to various types of events.
In this example, the applet has been programmed to respond to each event by displaying a message
in the text area.
The use of the term “message” here is deliberate. Messages are sent to objects. In fact,
JAVA GUI components are implemented as objects. JAVA includes many predefined classes that
represent various types of GUI components. Some of these classes are subclasses of others. Here
is a diagram showing some of Swing’s GUI classes and their relationships:

Note that all GUI classes are subclasses, directly or indirectly, of a class called JComponent,
which represents general properties that are shared by all Swing components. Two of the direct

102
subclasses of JComponent themselves have subclasses. The classes JTextArea and JTextField,
which have certain behaviors in common, are grouped together as subclasses of JTextComponent.
Also, JButton and JToggleButton are subclasses of JAbstractButton, which represents
properties common to both buttons and checkboxes.
Just from this brief discussion, perhaps you can see how GUI programming can make effective
use of object-oriented design. In fact, GUI’s, with their “visible objects,” are probably a major
factor contributing to the popularity of OOP.

6.2 The Basic GUI Application

T HERE ARE TWO BASIC TYPES of GUI program in JAVA: stand-alone applications and applets.
An applet is a program that runs in a rectangular area on a Web page. Applets are generally small
programs, meant to do fairly simple things, although there is nothing to stop them from being
very complex. Applets were responsible for a lot of the initial excitement about JAVA when it was
introduced, since they could do things that could not otherwise be done on Web pages. However,
there are now easier ways to do many of the more basic things that can be done with applets, and
they are no longer the main focus of interest in JAVA. Nevertheless, there are still some things that
can be done best with applets, and they are still fairly common on the Web.
A stand-alone application is a program that runs on its own, without depending on a Web
browser. You’ve been writing stand-alone applications all along. Any class that has a main()
method defines a stand-alone application; running the program just means executing this main()
method. However, the programs that you’ve seen up till now have been “command-line” programs,
where the user and computer interact by typing things back and forth to each other. A GUI program
offers a much richer type of user interface, where the user uses a mouse and keyboard to interact
with GUI components such as windows, menus, buttons, check boxes, text input boxes, scroll
bars, and so on. The main method of a GUI program creates one or more such components and
displays them on the computer screen. Very often, that’s all it does. Once a GUI component has
been created, it follows its own programming—programming that tells it how to draw itself on the
screen and how to respond to events such as being clicked on by the user.
A GUI program doesn’t have to be immensely complex. We can, for example write a very
simple GUI “Hello World” program that says “Hello” to the user, but does it by opening a window
where the greeting is displayed:
import javax.swing.JOptionPane;

public class HelloWorldGUI1 {

public static void main(String[] args) {

JOptionPane.showMessageDialog( null, "Hello World!" ); }

When this program is run, a window appears on the screen that contains the message “Hello
World!”. The window also contains an “OK” button for the user to click after reading the message.
When the user clicks this button, the window closes and the program ends. By the way, this
program can be placed in a file named HelloWorldGUI1.java, compiled, and run just like any
other JAVA program.
Now, this program is already doing some pretty fancy stuff. It creates a window, it draws the
contents of that window, and it handles the event that is generated when the user clicks the button.
The reason the program was so easy to write is that all the work is done by showMessageDialog(),
a static method in the built-in class JOptionPane. (Note: the source code “imports” the class

103
javax.swing.JOptionPane to make it possible to refer to the JOptionPane class using its
simple name.)
If you want to display a message to the user in a GUI program, this is a good way to do it:
Just use a standard class that already knows how to do the work! And in fact, JOptionPane is
regularly used for just this purpose (but as part of a larger program, usually). Of course, if you
want to do anything serious in a GUI program, there is a lot more to learn. To give you an idea of
the types of things that are involved, we’ll look at a short GUI program that does the same things
as the previous program – open a window containing a message and an OK button, and respond
to a click on the button by ending the program – but does it all by hand instead of by using the
built-in JOptionPane class. Mind you, this is not a good way to write the program, but it will
illustrate some important aspects of GUI programming in JAVA.
Here is the source code for the program. I will explain how it works below, but it will take the
rest of the chapter before you will really understand completely.
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

public class HelloWorldGUI2 {

private static class HelloWorldDisplay extends JPanel {

public void paintComponent(Graphics g) {
super.paintComponent(g);
g.drawString( "Hello World!", 20, 30 );
}
}

private static class ButtonHandler implements ActionListener {

public void actionPerformed(ActionEvent e) {
System.exit(0);
}
}

public static void main(String[] args) {

HelloWorldDisplay displayPanel = new HelloWorldDisplay();

JButton okButton = new JButton("OK");
ButtonHandler listener = new ButtonHandler();
okButton.addActionListener(listener);

JPanel content = new JPanel();

content.setLayout(new BorderLayout());
content.add(displayPanel, BorderLayout.CENTER);
content.add(okButton, BorderLayout.SOUTH);

JFrame window = new JFrame("GUI Test");

window.setContentPane(content);
window.setSize(250,100);
window.setLocation(100,100);
window.setVisible(true);

104
JFrame and JPanel
In a JAVA GUI program, each GUI component in the interface is represented by an object in the
program. One of the most fundamental types of component is the window. Windows have many
behaviors. They can be opened and closed. They can be resized. They have “titles” that are
displayed in the title bar above the window. And most important, they can contain other GUI
components such as buttons and menus.
JAVA, of course, has a built-in class to represent windows. There are actually several different
types of window, but the most common type is represented by the JFrame class (which is included
in the package javax.swing). A JFrame is an independent window that can, for example, act
as the main window of an application. One of the most important things to understand is that a
JFrame object comes with many of the behaviors of windows already programmed in. In partic-
ular, it comes with the basic properties shared by all windows, such as a titlebar and the ability to
be opened and closed. Since a JFrame comes with these behaviors, you don’t have to program
them yourself! This is, of course, one of the central ideas of object-oriented programming. What
a JFrame doesn’t come with, of course, is content, the stuff that is contained in the window.
If you don’t add any other content to a JFrame, it will just display a large blank area. You can
add content either by creating a JFrame object and then adding the content to it or by creating a
subclass of JFrame and adding the content in the constructor of that subclass.
The main program above declares a variable, window, of type JFrame and sets it to refer to a
new window object with the statement:
JFrame window = new JFrame("GUI Test");.
The parameter in the constructor, “GUI Test”, specifies the title that will be displayed in the
titlebar of the window. This line creates the window object, but the window itself is not yet
visible on the screen. Before making the window visible, some of its properties are set with these
statements:
window.setContentPane(content);
window.setSize(250,100);
window.setLocation(100,100);
The first line here sets the content of the window. (The content itself was created earlier in the
main program.) The second line says that the window will be 250 pixels wide and 100 pixels high.
The third line says that the upper left corner of the window will be 100 pixels over from the left
edge of the screen and 100 pixels down from the top. Once all this has been set up, the window is
actually made visible on the screen with the command:window.setVisible(true);.
It might look as if the program ends at that point, and, in fact, the main() method does end.
However, the the window is still on the screen and the program as a whole does not end until the
user clicks the OK button.
The content that is displayed in a JFrame is called its content pane. (In addition to its
content pane, a JFrame can also have a menu bar, which is a separate thing that I will talk
about later.) A basic JFrame already has a blank content pane; you can either add things to
that pane or you can replace the basic content pane entirely. In my sample program, the line
window.setContentPane(content) replaces the original blank content pane with a different
component. (Remember that a “component” is just a visual element of a graphical user interface).
In this case, the new content is a component of type JPanel.
JPanel is another of the fundamental classes in Swing. The basic JPanel is, again, just a
blank rectangle. There are two ways to make a useful JPanel: The first is to add other compo-
nents to the panel; the second is to draw something in the panel. Both of these techniques are
illustrated in the sample program. In fact, you will find two JPanels in the program: content,
which is used to contain other components, and displayPanel, which is used as a drawing
surface.

105
 Let’s look more closely at displayPanel. displayPanel is a variable of type HelloWorldDisplay,
which is a nested static class inside the HelloWorldGUI2 class. This class defines just one in-
stance method, paintComponent(), which overrides a method of the same name in the JPanel
class:

106
 private static class HelloWorldDisplay extends JPanel {
public void paintComponent(Graphics g) {
super.paintComponent(g);
g.drawString( "Hello World!", 20, 30 );
}
}
The paintComponent() method is called by the system when a component needs to be painted
on the screen. In the JPanel class, the paintComponent method simply fills the panel with the
panel’s background color. The paintComponent() method in HelloWorldDisplay begins
by calling super.paintComponent(g). This calls the version of paintComponent() that is
defined in the superclass, JPanel; that is, it fills the panel with the background color. Then it
calls g.drawString() to paint the string “Hello World!” onto the panel. The net result is that
whenever a HelloWorldDisplay is shown on the screen, it displays the string “Hello World!”.
We will often use JPanels in this way, as drawing surfaces. Usually, when we do this, we will
define a nested class that is a subclass of JPanel and we will write a paintComponent method
in that class to draw the desired content in the panel.

Components and Layout

Another way of using a JPanel is as a container to hold other components. JAVA has many
classes that define GUI components. Before these components can appear on the screen, they must
be added to a container. In this program, the variable named content refers to a JPanel that
is used as a container, and two other components are added to that container. This is done in the
statements:
content.add(displayPanel, BorderLayout.CENTER);
content.add(okButton, BorderLayout.SOUTH);
Here, content refers to an object of type JPanel; later in the program, this panel becomes
the content pane of the window. The first component that is added to content is displayPanel
which, as discussed above, displays the message, “Hello World!”. The second is okButton which
represents the button that the user clicks to close the window. The variable okButton is of type
JButton, the JAVA class that represents push buttons.
The “BorderLayout” stuff in these statements has to do with how the two components are
arranged in the container. When components are added to a container, there has to be some way
of deciding how those components are arranged inside the container. This is called “laying out”
the components in the container, and the most common technique for laying out components is
to use a layout manager. A layout manager is an object that implements some policy for how
to arrange the components in a container; different types of layout manager implement different
policies. One type of layout manager is defined by the BorderLayout class. In the program, the
statement
content.setLayout(new BorderLayout());
creates a new BorderLayout object and tells the content panel to use the new object as its
layout manager. Essentially, this line determines how components that are added to the content
panel will be arranged inside the panel. We will cover layout managers in much more detail
later, but for now all you need to know is that adding okButton in the BorderLayout.SOUTH
position puts the button at the bottom of the panel, and putting the component displayPanel in
the BorderLayout.CENTER position makes it fill any space that is not taken up by the button.
This example shows a general technique for setting up a GUI: Create a container and assign a
layout manager to it, create components and add them to the container, and use the container as the
content pane of a window or applet. A container is itself a component, so it is possible that some

107
of the components that are added to the top-level container are themselves containers, with their
own layout managers and components. This makes it possible to build up complex user interfaces
in a hierarchical fashion, with containers inside containers inside containers...

Events and Listeners

The structure of containers and components sets up the physical appearance of a GUI, but it doesn’t
say anything about how the GUI behaves. That is, what can the user do to the GUI and how will it
respond? GUIs are largely event−driven; that is, the program waits for events that are generated
by the user’s actions (or by some other cause). When an event occurs, the program responds by
executing an event−handling method. In order to program the behavior of a GUI, you have
to write event-handling methods to respond to the events that you are interested in.
Event listeners are the most common technique for handling events in JAVA. A listener is an
object that includes one or more event-handling methods. When an event is detected by another
object, such as a button or menu, the listener object is notified and it responds by running the
appropriate event-handling method. An event is detected or generated by an object. Another
object, the listener, has the responsibility of responding to the event. The event itself is actually
represented by a third object, which carries information about the type of event, when it occurred,
and so on. This division of responsibilities makes it easier to organize large programs.
As an example, consider the OK button in the sample program. When the user clicks the
button, an event is generated. This event is represented by an object belonging to the class
ActionEvent. The event that is generated is associated with the button; we say that the but-
ton is the source of the event. The listener object in this case is an object belonging to the class
ButtonHandler, which is defined as a nested class inside HelloWorldGUI2:
private static class ButtonHandler implements ActionListener {
public void actionPerformed(ActionEvent e) {
System.exit(0);
}
}
This class implements the ActionListener interface – a requirement for listener objects that
handle events from buttons. The event-handling method is named
actionPerformed, as specified by the ActionListener interface. This method contains
the code that is executed when the user clicks the button; in this case, the code is a call to
System.exit(), which will terminate the program.
There is one more ingredient that is necessary to get the event from the button to the listener
object: The listener object must register itself with the button as an event listener. This is done
with the statement:
okButton.addActionListener(listener);
This statement tells okButton that when the user clicks the button, the ActionEvent that is gener-
ated should be sent to listener. Without this statement, the button has no way of knowing that
some other object would like to listen for events from the button.
This example shows a general technique for programming the behavior of a GUI: Write classes
that include event-handling methods. Create objects that belong to these classes and register them
as listeners with the objects that will actually detect or generate the events. When an event occurs,
the listener is notified, and the code that you wrote in one of its event-handling methods is exe-
cuted. At first, this might seem like a very roundabout and complicated way to get things done,
but as you gain experience with it, you will find that it is very flexible and that it goes together
very well with object oriented programming. (We will return to events and listeners in much more
detail in later sections.)

108
6.3 Applets and HTML
A LTHOUGH STAND - ALONE APPLICATIONS are probably more important than applets at this
point in the history of JAVA, applets are still widely used. They can do things on Web pages that
can’t easily be done with other technologies. It is easy to distribute applets to users: The user just
has to open a Web page, and the applet is there, with no special installation required (although the
user must have an appropriate version of JAVA installed on their computer). And of course, applets
are fun; now that the Web has become such a common part of life, it’s nice to be able to see your
work running on a web page.
The good news is that writing applets is not much different from writing stand-alone applica-
tions. The structure of an applet is essentially the same as the structure of the JFrames that were
introduced in the previously, and events are handled in the same way in both types of program.
So, most of what you learn about applications applies to applets, and vice versa.
Of course, one difference is that an applet is dependent on a Web page, so to use applets
effectively, you have to learn at least a little about creating Web pages. Web pages are written
using a language called HTML (HyperText Markup Language).

JApplet
The JApplet class (in package javax.swing) can be used as a basis for writing applets in the
same way that JFrame is used for writing stand-alone applications. The basic JApplet class
represents a blank rectangular area. Since an applet is not a stand-alone application, this area must
appear on a Web page, or in some other environment that knows how to display an applet. Like a
JFrame, a JApplet contains a content pane (and can contain a menu bar). You can add content
to an applet either by adding content to its content pane or by replacing the content pane with
another component. In my examples, I will generally create a JPanel and use it as a replacement
for the applet’s content pane.
To create an applet, you will write a subclass of JApplet. The JApplet class defines several
instance methods that are unique to applets. These methods are called by the applet’s environment
at certain points during the applet’s “life cycle.” In the JApplet class itself, these methods do
nothing; you can override these methods in a subclass. The most important of these special applet
methods is public void init().
An applet’s init() method is called when the applet is created. You can use the init()
method as a place where you can set up the physical structure of the applet and the event handling
that will determine its behavior. (You can also do some initialization in the constructor for your
class, but there are certain aspects of the applet’s environment that are set up after its constructor
is called but before the init() method is called, so there are a few operations that will work in
the init() method but will not work in the constructor.) The other applet life-cycle methods are
start(), stop(), and destroy(). I will not use these methods for the time being and will not
discuss them here except to mention that destroy() is called at the end of the applet’s lifetime
and can be used as a place to do any necessary cleanup, such as closing any windows that were
opened by the applet.
With this in mind, we can look at our first example of a JApplet. It is, of course, an applet
that says “Hello World!”. To make it a little more interesting, I have added a button that changes
the text of the message, and a state variable, currentMessage that holds the text of the current
message. This example is very similar to the stand-alone application HelloWorldGUI2 from the
previous section. It uses an event-handling class to respond when the user clicks the button, a
panel to display the message, and another panel that serves as a container for the message panel
and the button. The second panel becomes the content pane of the applet. Here is the source code
for the applet; again, you are not expected to understand all the details at this time:

109
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

/**
* A simple applet that can display the messages "Hello World"
* and "Goodbye World". The applet contains a button, and it
* switches from one message to the other when the button is
* clicked.
*/
public class HelloWorldApplet extends JApplet {

private String currentMessage = "Hello World!";

private MessageDisplay displayPanel;

private class MessageDisplay extends JPanel {//Defines the display panel.

public void paintComponent(Graphics g) {
super.paintComponent(g);
g.drawString(currentMessage, 20, 30);
}
}

private class ButtonHandler implements ActionListener {//The event listener.

public void actionPerformed(ActionEvent e) {
if (currentMessage.equals("Hello World!"))
currentMessage = "Goodbye World!";
else
currentMessage = "Hello World!";
displayPanel.repaint(); // Paint display panel with new message.
}
}

/**
* The applet’s init() method creates the button and display panel and
* adds them to the applet, and it sets up a listener to respond to
* clicks on the button.
*/
public void init() {

displayPanel = new MessageDisplay();

JButton changeMessageButton = new JButton("Change Message");
ButtonHandler listener = new ButtonHandler();
changeMessageButton.addActionListener(listener);

JPanel content = new JPanel();

content.setLayout(new BorderLayout());
content.add(displayPanel, BorderLayout.CENTER);
content.add(changeMessageButton, BorderLayout.SOUTH);

setContentPane(content);
}

110
You should compare this class with HelloWorldGUI2.java from the previous section. One
subtle difference that you will notice is that the member variables and nested classes in this ex-
ample are non-static. Remember that an applet is an object. A single class can be used to make
several applets, and each of those applets will need its own copy of the applet data, so the member
variables in which the data is stored must be non-static instance variables. Since the variables
are non-static, the two nested classes, which use those variables, must also be non-static. (Static
nested classes cannot access non-static member variables in the containing class) Remember the
basic rule for deciding whether to make a nested class static: If it needs access to any instance
variable or instance method in the containing class, the nested class must be non-static; otherwise,
it can be declared to be static.
You can try out the applet itself. Click the “Change Message” button to switch the message
back and forth between “Hello World!” and “Goodbye World!”:

Reusing Your JPanels

Both applets and frames can be programmed in the same way: Design a JPanel, and use it to
replace the default content pane in the applet or frame. This makes it very easy to write two
versions of a program, one which runs as an applet and one which runs as a frame. The idea is
to create a subclass of JPanel that represents the content pane for your program; all the hard
programming work is done in this panel class. An object of this class can then be used as the
content pane either in a frame or in an applet. Only a very simple main() program is needed to
show your panel in a frame, and only a very simple applet class is needed to show your panel in
an applet, so it’s easy to make both versions.
As an example, we can rewrite HelloWorldApplet by writing a subclass of JPanel. That
class can then be reused to make a frame in a standalone application. This class is very similar to
HelloWorldApplet, but now the initialization is done in a constructor instead of in an init()
method:

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

public class HelloWorldPanel extends JPanel {

private String currentMessage = "Hello World!";

private MessageDisplay displayPanel;

private class MessageDisplay extends JPanel {//Defines the display panel.

public void paintComponent(Graphics g) {
super.paintComponent(g);
g.drawString(currentMessage, 20, 30);
}
}

private class ButtonHandler implements ActionListener {//The event listener.

public void actionPerformed(ActionEvent e) {
if (currentMessage.equals("Hello World!"))
currentMessage = "Goodbye World!";
else
currentMessage = "Hello World!";
displayPanel.repaint(); // Paint display panel with new message.

111
 }
}

/**
* The constructor creates the components that will be contained inside this
* panel, and then adds those components to this panel.
*/
public HelloWorldPanel() {

displayPanel = new MessageDisplay(); // Create the display subpanel.

JButton changeMessageButton = new JButton("Change Message"); // The button.

ButtonHandler listener = new ButtonHandler();
changeMessageButton.addActionListener(listener);

setLayout(new BorderLayout()); // Set the layout manager for this panel.

add(displayPanel, BorderLayout.CENTER); // Add the display panel.
add(changeMessageButton, BorderLayout.SOUTH); // Add the button.

Once this class exists, it can be used in an applet. The applet class only has to create an object
of type HelloWorldPanel and use that object as its content pane:
import javax.swing.JApplet;

public class HelloWorldApplet2 extends JApplet {

public void init() {
HelloWorldPanel content = new HelloWorldPanel();
setContentPane(content);
}
}

Similarly, its easy to make a frame that uses an object of type HelloWorldPanel as its
content pane:
import javax.swing.JFrame;

public class HelloWorldGUI3 {

public static void main(String[] args) {

JFrame window = new JFrame("GUI Test");
HelloWorldPanel content = new HelloWorldPanel();
window.setContentPane(content);
window.setSize(250,100);
window.setLocation(100,100);
window.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
window.setVisible(true);
}

One new feature of this example is the line

window.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );

112
This says that when the user closes the window by clicking the close box in the title bar of the
window, the program should be terminated. This is necessary because no other way is provided to
end the program. Without this line, the default close operation of the window would simply hide
the window when the user clicks the close box, leaving the program running. This brings up one
of the difficulties of reusing the same panel class both in an applet and in a frame: There are some
things that a stand-alone application can do that an applet can’t do. Terminating the program is
one of those things. If an applet calls System.exit() , it has no effect except to generate an
error.
Nevertheless, in spite of occasional minor difficulties, many of the GUI examples in this book
will be written as subclasses of JPanel that can be used either in an applet or in a frame.

Applets on Web Pages

The <applet> tag can be used to add a JAVA applet to a Web page. This tag must have a match-
ing </applet>. A required modifier named code gives the name of the compiled class file that
contains the applet class. The modifiers height and width are required to specify the size of the
applet, in pixels. If you want the applet to be centered on the page, you can put the applet in a para-
graph with center alignment So, an applet tag to display an applet named HelloWorldApplet
centered on a Web page would look like this:
<p align=center>
<applet code="HelloWorldApplet.class" height=100 width=250>
</applet>
</p>

This assumes that the file HelloWorldApplet.class is located in the same directory with
the HTML document. If this is not the case, you can use another modifier, codebase, to give the
URL of the directory that contains the class file. The value of code itself is always just a class,
not a URL.
If the applet uses other classes in addition to the applet class itself, then those class files must
be in the same directory as the applet class (always assuming that your classes are all in the “default
package”; see Subectionă2.6.4). If an applet requires more than one or two class files, it’s a good
idea to collect all the class files into a single jar file. Jar files are “archive files” which hold a
number of smaller files. If your class files are in a jar archive, then you have to specify the name
of the jar file in an archive modifier in the <applet> tag, as in
<applet code="HelloWorldApplet.class" archive="HelloWorld.jar"
height=50...

Applets can use applet parameters to customize their behavior. Applet parameters are
specified by using <param> tags, which can only occur between an <applet> tag and the closing
</applet>. The param tag has required modifiers named name and value, and it takes the form
<param name= ‘‘param−name’’ value=‘‘param−value’’>

The parameters are available to the applet when it runs. An applet can use the predefined
method getParameter() to check for parameters specified in param tags. The getParameter()
method has the following interface:
String getParameter(String paramName)

The parameter paramName corresponds to the param−name in a param tag. If the specified
paramName occurs in one of the param tags, then getParameter(paramName) returns the
associated param−value. If the specified paramName does not occur in any param tag, then
getParameter(paramName) returns the value null. Parameter names are case-sensitive, so

113
you cannot use “size” in the param tag and ask for “Size” in getParameter. The getParameter()
method is often called in the applet’s init() method. It will not work correctly in the applet’s
constructor, since it depends on information about the applet’s environment that is not available
when the constructor is called.
Here is an example of an applet tag with several params:
<applet code="ShowMessage.class" width=200 height=50>
<param name="message" value="Goodbye World!">
<param name="font" value="Serif">
<param name="size" value="36">
</applet>
The ShowMessage applet would presumably read these parameters in its init() method,
which could go something like this:

114
 String message; // Instance variable: message to be displayed.
String fontName; // Instance variable: font to use for display.
int fontSize; // Instance variable: size of the display font.

public void init() {

String value;
value = getParameter("message"); // Get message param, if any.
if (value == null)
message = "Hello World!"; // Default value, if no param is present.
else
message = value; // Value from PARAM tag.
value = getParameter("font");
if (value == null)
fontName = "SansSerif"; // Default value, if no param is present.
else
fontName = value;
value = getParameter("size");
try {
fontSize = Integer.parseInt(value); // Convert string to number.
}
catch (NumberFormatException e) {
fontSize = 20; // Default value, if no param is present, or if
} // the parameter value is not a legal integer.
.
.
.
Elsewhere in the applet, the instance variables message, fontName, and fontSize would be
used to determine the message displayed by the applet and the appearance of that message. Note
that the value returned by getParameter() is always a String. If the param represents a nu-
merical value, the string must be converted into a number, as is done here for the size parameter.

6.4 Graphics and Painting

E VERTHING YOU SEE ON A COMPUTER SCREEN has to be drawn there, even the text. The
JAVA API includes a range of classes and methods that are devoted to drawing. In this section, I’ll
look at some of the most basic of these.
The physical structure of a GUI is built of components. The term component refers to a vi-
sual element in a GUI, including buttons, menus, text-input boxes, scroll bars, check boxes, and
so on. In JAVA, GUI components are represented by objects belonging to subclasses of the class
java.awt.Component. Most components in the Swing GUI – although not top-level compo-
nents like JApplet and JFrame – belong to subclasses of the class javax.swing.JComponent,
which is itself a subclass of java.awt.Component. Every component is responsible for drawing
itself. If you want to use a standard component, you only have to add it to your applet or frame.
You don’t have to worry about painting it on the screen. That will happen automatically, since it
already knows how to draw itself.
Sometimes, however, you do want to draw on a component. You will have to do this whenever
you want to display something that is not included among the standard, pre-defined component
classes. When you want to do this, you have to define your own component class and provide a
method in that class for drawing the component. I will always use a subclass of JPanel when
I need a drawing surface of this kind, as I did for the MessageDisplay class in the example
HelloWorldApplet.java in the previous section. A JPanel, like any JComponent, draws its
content in the method

115
 public void paintComponent(Graphics g)
To create a drawing surface, you should define a subclass of JPanel and provide a custom
paintComponent() method. Create an object belonging to this class and use it in your ap-
plet or frame. When the time comes for your component to be drawn on the screen, the sys-
tem will call its paintComponent() to do the drawing. That is, the code that you put into
the paintComponent() method will be executed whenever the panel needs to be drawn on the
screen; by writing this method, you determine the picture that will be displayed in the panel.
Note that the paintComponent() method has a parameter of type Graphics. The Graphics
object will be provided by the system when it calls your method. You need this object to do the
actual drawing. To do any drawing at all in JAVA, you need a graphics context. A graphics
context is an object belonging to the class java.awt.Graphics. Instance methods are provided
in this class for drawing shapes, text, and images. Any given Graphics object can draw to only
one location. In this chapter, that location will always be a GUI component belonging to some
subclass of JPanel. The Graphics class is an abstract class, which means that it is impossible to
create a graphics context directly, with a constructor. There are actually two ways to get a graph-
ics context for drawing on a component: First of all, of course, when the paintComponent()
method of a component is called by the system, the parameter to that method is a graphics con-
text for drawing on the component. Second, every component has an instance method called
getGraphics(). This method returns a graphics context that can be used for drawing on the
component outside its paintComponent() method. The official line is that you should not do
this, and I will avoid it for the most part. But I have found it convenient to use getGraphics()
in a few cases.
The paintComponent() method in the JPanel class simply fills the panel with the panel’s
background color. When defining a subclass of JPanel for use as a drawing surface, you will
almost always want to fill the panel with the background color before drawing other content
onto the panel (although it is not necessary to do this if the drawing commands in the method
cover the background of the component completely.) This is traditionally done with a call to
super.paintComponent(g), so most paintComponent() methods that you write will have
the form:
public void paintComponent(g) {
super.paintComponent(g); . . .
// Draw the content of the component.
}
Most components do, in fact, do all drawing operations in their paintComponent() meth-
ods. What happens if, in the middle of some other method, you realize that the content of the
component needs to be changed? You should not call paintComponent() directly to make
the change; this method is meant to be called only by the system. Instead, you have to inform
the system that the component needs to be redrawn, and let the system do its job by calling
paintComponent(). You do this by calling the component’s repaint() method. The method
public void repaint(); is defined in the Component class, and so can be used with any
component. You should call repaint() to inform the system that the component needs to be
redrawn. The repaint() method returns immediately, without doing any painting itself. The
system will call the component’s paintComponent() method later, as soon as it gets a chance
to do so, after processing other pending events if there are any.
Note that the system can also call paintComponent() for other reasons. It is called when
the component first appears on the screen. It will also be called if the component is resized or if
it is covered up by another window and then uncovered. The system does not save a copy of the
component’s contents when it is covered. When it is uncovered, the component is responsible for
redrawing itself. (As you will see, some of our early examples will not be able to do this correctly.)

116
 This means that, to work properly, the paintComponent() method must be smart enough to
correctly redraw the component at any time. To make this possible, a program should store data
about the state of the component in its instance variables. These variables should contain all the
information necessary to redraw the component completely. The paintComponent() method
should use the data in these variables to decide what to draw. When the program wants to change
the content of the component, it should not simply draw the new content. It should change the val-
ues of the relevant variables and call repaint(). When the system calls paintComponent(),
that method will use the new values of the variables and will draw the component with the desired
modifications. This might seem a roundabout way of doing things. Why not just draw the modifi-
cations directly? There are at least two reasons. First of all, it really does turn out to be easier to
get things right if all drawing is done in one method. Second, even if you did make modifications
directly, you would still have to make the paintComponent() method aware of them in some
way so that it will be able to redraw the component correctly on demand.
You will see how all this works in practice as we work through examples in the rest of this
chapter. For now, we will spend the rest of this section looking at how to get some actual drawing
done.

Coordinates
The screen of a computer is a grid of little squares called pixels. The color of each pixel can be
set individually, and drawing on the screen just means setting the colors of individual pixels.

A graphics context draws in a rectangle made up of pixels. A position in the rectangle is spec-
ified by a pair of integer coordinates, (x,y). The upper left corner has coordinates (0,0). The
x coordinate increases from left to right, and the y coordinate increases from top to bottom. The
illustration shows a 16-by-10 pixel component (with very large pixels). A small line, rectangle,
and oval are shown as they would be drawn by coloring individual pixels. (Note that, properly
speaking, the coordinates don’t belong to the pixels but to the grid lines between them.)
For any component, you can find out the size of the rectangle that it occupies by calling the
instance methods getWidth() and getHeight(), which return the number of pixels in the
horizontal and vertical directions, respectively. In general, it’s not a good idea to assume that you
know the size of a component, since the size is often set by a layout manager and can even change
if the component is in a window and that window is resized by the user. This means that it’s good
form to check the size of a component before doing any drawing on that component. For example,
you can use a paintComponent() method that looks like:
public void paintComponent(Graphics g) {
super.paintComponent(g);

117
 int width = getWidth(); // Find out the width of this component.
int height = getHeight(); // Find out its height.
. . . // Draw the content of the component.
}

Of course, your drawing commands will have to take the size into account. That is, they will
have to use (x,y) coordinates that are calculated based on the actual height and width of the
component.

Colors
You will probably want to use some color when you draw. JAVA is designed to work with the
RGB color system. An RGB color is specified by three numbers that give the level of red,
green, and blue, respectively, in the color. A color in JAVA is an object of the class, java.awt.Color.
You can construct a new color by specifying its red, blue, and green components. For example,
Color myColor = new Color(r,g,b);

There are two constructors that you can call in this way. In the one that I almost always use,
r, g, and b are integers in the range 0 to 255. In the other, they are numbers of type float in the
range 0.0F to 1.0F. (Recall that a literal of type float is written with an “F” to distinguish it from a
double number.) Often, you can avoid constructing new colors altogether, since the Color class
defines several named constants representing common colors: Color.WHITE, Color.BLACK,
Color.RED, Color.GREEN, Color.BLUE, Color.CYAN, Color.MAGENTA, Color.YELLOW,
Color.PINK, Color.ORANGE, Color.LIGHT_GRAY, Color.GRAY, and Color.DARK_GRAY.
(There are older, alternative names for these constants that use lower case rather than upper case
constants, such as Color.red instead of Color.RED, but the upper case versions are preferred
because they follow the convention that constant names should be upper case.)
An alternative to RGB is the HSB color system. In the HSB system, a color is specified
by three numbers called the hue, the saturation, and the brightness. The hue is the basic
color, ranging from red through orange through all the other colors of the rainbow. The brightness
is pretty much what it sounds like. A fully saturated color is a pure color tone. Decreasing the
saturation is like mixing white or gray paint into the pure color. In JAVA, the hue, saturation and
brightness are always specified by values of type float in the range from 0.0F to 1.0F. The Color
class has a static member method named getHSBColor for creating HSB colors. To create the
color with HSB values given by h, s, and b, you can say:
Color myColor = Color.getHSBColor(h,s,b);

For example, to make a color with a random hue that is as bright and as saturated as possible,
you could use:
Color randomColor = Color.getHSBColor(
(float)Math.random(), 1.0F, 1.0F );

The type cast is necessary because the value returned by Math.random() is of type double,
and Color.getHSBColor() requires values of type float. (By the way, you might ask why
RGB colors are created using a constructor while HSB colors are created using a static member
method. The problem is that we would need two different constructors, both of them with three
parameters of type float. Unfortunately, this is impossible. You can have two constructors only
if the number of parameters or the parameter types differ.)
The RGB system and the HSB system are just different ways of describing the same set of
colors. It is possible to translate between one system and the other. The best way to understand
the color systems is to experiment with them. In the following applet, you can use the scroll bars

118
to control the RGB and HSB values of a color. A sample of the color is shown on the right side of
the applet.
One of the properties of a Graphics object is the current drawing color, which is used for
all drawing of shapes and text. If g is a graphics context, you can change the current draw-
ing color for g using the method g.setColor(c), where c is a Color. For example, if you
want to draw in green, you would just say g.setColor(Color.GREEN) before doing the draw-
ing. The graphics context continues to use the color until you explicitly change it with another
setColor() command. If you want to know what the current drawing color is, you can call the
method g.getColor(), which returns an object of type Color. This can be useful if you want
to change to another drawing color temporarily and then restore the previous drawing color.
Every component has an associated foreground color and background color. Gener-
ally, the component is filled with the background color before anything else is drawn (although
some components are “transparent,” meaning that the background color is ignored). When a new
graphics context is created for a component, the current drawing color is set to the foreground
color. Note that the foreground color and background color are properties of the component, not
of a graphics context.
Foreground and background colors can be set by the instance methods
setForeground(c) and setBackground(c), which are defined in the Component class and
therefore are available for use with any component. This can be useful even for standard compo-
nents, if you want them to use colors that are different from the defaults.

Fonts
A font represents a particular size and style of text. The same character will appear different in
different fonts. In JAVA, a font is characterized by a font name, a style, and a size. The available
font names are system dependent, but you can always use the following four strings as font names:
“Serif”, “SansSerif”, “Monospaced”, and “Dialog”. (A “serif” is a little decoration on a character,
such as a short horizontal line at the bottom of the letter i. “SansSerif” means “without serifs.”
“Monospaced” means that all the characters in the font have the same width. The “Dialog” font is
the one that is typically used in dialog boxes.)
The style of a font is specified using named constants that are defined in the Font class. You
can specify the style as one of the four values:

• Font.PLAIN,

• Font.ITALIC,

• Font.BOLD, or

• Font.BOLD + Font.ITALIC.

The size of a font is an integer. Size typically ranges from about 10 to 36, although larger sizes
can also be used. The size of a font is usually about equal to the height of the largest characters in
the font, in pixels, but this is not an exact rule. The size of the default font is 12.
JAVA uses the class named java.awt.Font for representing fonts. You can construct a new
font by specifying its font name, style, and size in a constructor:
Font plainFont = new Font("Serif", Font.PLAIN, 12);
Font bigBoldFont = new Font("SansSerif", Font.BOLD, 24);
Every graphics context has a current font, which is used for drawing text. You can change the
current font with the setFont() method. For example, if g is a graphics context and bigBoldFont
is a font, then the command g.setFont(bigBoldFont) will set the current font of g to bigBoldFont.

119
The new font will be used for any text that is drawn after the setFont() command is given. You
can find out the current font of g by calling the method g.getFont(), which returns an object of
type Font.
Every component has an associated font that can be set with the setFont(font) instance
method, which is defined in the Component class. When a graphics context is created for drawing
on a component, the graphic context’s current font is set equal to the font of the component.

Shapes
The Graphics class includes a large number of instance methods for drawing various shapes,
such as lines, rectangles, and ovals. The shapes are specified using the (x,y) coordinate system
described above. They are drawn in the current drawing color of the graphics context. The current
drawing color is set to the foreground color of the component when the graphics context is created,
but it can be changed at any time using the setColor() method.
Here is a list of some of the most important drawing methods. With all these commands, any
drawing that is done outside the boundaries of the component is ignored. Note that all these meth-
ods are in the Graphics class, so they all must be called through an object of type Graphics.
• drawString(String str, int x, int y)
Draws the text given by the string str. The string is drawn using the current color and
font of the graphics context. x specifies the position of the left end of the string. y is the
y-coordinate of the baseline of the string. The baseline is a horizontal line on which the
characters rest. Some parts of the characters, such as the tail on a y or g, extend below the
baseline.

• drawLine(int x1, int y1, int x2, int y2)

Draws a line from the point (x1,y1) to the point (x2,y2). The line is drawn as if with
a pen that hangs one pixel to the right and one pixel down from the (x,y) point where the
pen is located. For example, if g refers to an object of type Graphics, then the command
g.drawLine(x,y,x,y), which corresponds to putting the pen down at a point, colors the
single pixel with upper left corner at the point (x,y).

• drawRect(int x, int y, int width, int height)

Draws the outline of a rectangle. The upper left corner is at (x,y), and the width and height
of the rectangle are as specified. If width equals height, then the rectangle is a square. If
the width or the height is negative, then nothing is drawn. The rectangle is drawn with
the same pen that is used for drawLine(). This means that the actual width of the rectangle
as drawn is width+1, and similarly for the height. There is an extra pixel along the right
edge and the bottom edge. For example, if you want to draw a rectangle around the edges
of the component, you can say
“g.drawRect(0, 0, getWidth()−1,getHeight()−1);”, where g is a graphics con-
text for the component. If you use
“g.drawRect(0, 0, getWidth(), getHeight());”, then the right and bottom edges
of the rectangle will be drawn outside the component.

• drawOval(int x, int y, int width, int height)

Draws the outline of an oval. The oval is one that just fits inside the rectangle specified by
x, y, width, and height. If width equals height, the oval is a circle.

• drawRoundRect(int x, int y, int width, int height, int xdiam, int ydiam)
Draws the outline of a rectangle with rounded corners. The basic rectangle is specified by
x, y, width, and height, but the corners are rounded. The degree of rounding is given by

120
 xdiam and ydiam. The corners are arcs of an ellipse with horizontal diameter xdiam and
vertical diameter ydiam. A typical value for xdiam and ydiam is 16, but the value used
should really depend on how big the rectangle is.

• draw3DRect(int x, int y, int width, int height, boolean raised)

Draws the outline of a rectangle that is supposed to have a three-dimensional effect, as if it
is raised from the screen or pushed into the screen. The basic rectangle is specified by x, y,
width, and height. The raised parameter tells whether the rectangle seems to be raised
from the screen or pushed into it. The 3D effect is achieved by using brighter and darker
versions of the drawing color for different edges of the rectangle. The documentation rec-
ommends setting the drawing color equal to the background color before using this method.
The effect won’t work well for some colors.

• drawArc(int x, int y, int width, int height, int startAngle, int arcAngle)
Draws part of the oval that just fits inside the rectangle specified by x, y, width, and
height. The part drawn is an arc that extends arcAngle degrees from a starting angle
at startAngle degrees. Angles are measured with 0 degrees at the 3 o’clock position (the
positive direction of the horizontal axis). Positive angles are measured counterclockwise
from zero, and negative angles are measured clockwise. To get an arc of a circle, make sure
that width is equal to height.

• fillRect(int x, int y, int width, int height)

Draws a filled-in rectangle. This fills in the interior of the rectangle that would be drawn
by drawRect(x,y,width,height). The extra pixel along the bottom and right edges is
not included. The width and height parameters give the exact width and height of the
rectangle. For example, if you wanted to fill in the entire component, you could say
“g.fillRect(0, 0, getWidth(), getHeight());”

• fillOval(int x, int y, int width, int height)

Draws a filled-in oval.

• fillRoundRect(int x, int y, int width, int height, int xdiam, int ydiam)
Draws a filled-in rounded rectangle.

• fill3DRect(int x, int y, int width, int height, boolean raised)

Draws a filled-in three-dimensional rectangle.

• fillArc(int x, int y, int width, int height, int startAngle, int arcAngle)
Draw a filled-in arc. This looks like a wedge of pie, whose crust is the arc that would be
drawn by the drawArc method.

An Example
Let’s use some of the material covered in this section to write a subclass of JPanel for use as a
drawing surface. The panel can then be used in either an applet or a frame. All the drawing will be
done in the paintComponent() method of the panel class. The panel will draw multiple copies
of a message on a black background. Each copy of the message is in a random color. Five different
fonts are used, with different sizes and styles. The message can be specified in the constructor; if
the default constructor is used, the message is the string “Java!”. The panel works OK no matter
what its size. Here’s an applet that uses the panel as its content pane:
The source for the panel class is shown below. I use an instance variable called message to
hold the message that the panel will display. There are five instance variables of type Font that

121
represent different sizes and styles of text. These variables are initialized in the constructor and
are used in the paintComponent() method.
The paintComponent() method for the panel simply draws 25 copies of the message. For
each copy, it chooses one of the five fonts at random, and it calls g.setFont() to select that font
for drawing the text. It creates a random HSB color and uses g.setColor() to select that color
for drawing. It then chooses random (x,y) coordinates for the location of the message. The x
coordinate gives the horizontal position of the left end of the string. The formula used for the x
coordinate,
“−50 + (int)(Math.random() * (width+40))” gives a random integer in the range from
−50 to width−10. This makes it possible for the string to extend beyond the left edge or the
right edge of the panel. Similarly, the formula for y allows the string to extend beyond the top and
bottom of the applet.
Here is the complete source code for the RandomStringsPanel
import java.awt.Color;
import java.awt.Font;
import java.awt.Graphics;
import javax.swing.JPanel;

/*
* This panel displays 25 copies of a message. The color and
* position of each message is selected at random. The font
* of each message is randomly chosen from among five possible
* fonts. The messages are displayed on a black background.
* <p>This panel is meant to be used as the content pane in
* either an applet or a frame.
*/
public class RandomStringsPanel extends JPanel {

private String message; // The message to be displayed. This can be set in

// the constructor. If no value is provided in the
// constructor, then the string "Java!" is used.

private Font font1, font2, font3, font4, font5; // The five fonts.

/**
* Default constructor creates a panel that displays the message "Java!".
*
*/
public RandomStringsPanel() {
this(null); // Call the other constructor, with parameter null.
}

/**
* Constructor creates a panel to display 25 copies of a specified message.
* @param messageString The message to be displayed. If this is null,
* then the default message "Java!" is displayed.
*/
public RandomStringsPanel(String messageString) {

message = messageString;
if (message == null)
message = "Java!";

122
 font1 = new Font("Serif", Font.BOLD, 14);
font2 = new Font("SansSerif", Font.BOLD + Font.ITALIC, 24);
font3 = new Font("Monospaced", Font.PLAIN, 30);
font4 = new Font("Dialog", Font.PLAIN, 36);
font5 = new Font("Serif", Font.ITALIC, 48);

setBackground(Color.BLACK);

/** The paintComponent method is responsible for drawing the content

* of the panel.It draws 25 copies of the message string, using a
* random color, font, and position for each string.
*/

public void paintComponent(Graphics g) {

super.paintComponent(g); // Call the paintComponent method from the

// superclass, JPanel. This simply fills the
// entire panel with the background color, black.

int width = getWidth();

int height = getHeight();

for (int i = 0; i < 25; i++) {

// Draw one string. First, set the font to be one of the five
// available fonts, at random.

int fontNum = (int)(5*Math.random()) + 1;

switch (fontNum) {
case 1:
g.setFont(font1);
break;
case 2:
g.setFont(font2);
break;
case 3:
g.setFont(font3);
break;
case 4:
g.setFont(font4);
break;
case 5:
g.setFont(font5);
break;
} // end switch

// Set the color to a bright, saturated color, with random hue.

float hue = (float)Math.random();

123
 g.setColor( Color.getHSBColor(hue, 1.0F, 1.0F) );

// Select the position of the string, at random.

int x,y;
x = −50 + (int)(Math.random()*(width+40));
y = (int)(Math.random()*(height+20));

// Draw the message.

g.drawString(message,x,y);

} // end for

} // end paintComponent()

} // end class RandomStringsPanel

This class defines a panel, which is not something that can stand on its own. To see it on
the screen, we have to use it in an applet or a frame. Here is a simple applet class that uses a
RandomStringsPanel as its content pane:
import javax.swing.JApplet;

/**
* A RandomStringsApplet displays 25 copies of a string, using random colors,
* fonts, and positions for the copies. The message can be specified as the
* value of an applet param with name "message." If no param with name
* "message" is present, then the default message "Java!" is displayed.
* The actual content of the applet is an object of type RandomStringsPanel.
*/
public class RandomStringsApplet extends JApplet {

public void init() {

String message = getParameter("message");
RandomStringsPanel content = new RandomStringsPanel(message);
setContentPane(content);
}

Note that the message to be displayed in the applet can be set using an applet parameter
when the applet is added to an HTML document. Remember that to use the applet on a Web
page, include both the panel class file, RandomStringsPanel.class, and the applet class file,
RandomStringsApplet.class, in the same directory as the HTML document (or, alternatively,
bundle the two class files into a jar file, and put the jar file in the document directory).
Instead of writing an applet, of course, we could use the panel in the window of a stand-
alone application. You can find the source code for a main program that does this in the file
RandomStringsApp.java.

6.5 Mouse Events

E VENTS ARE CENTRAL TO PROGRAMMING for a graphical user interface. A GUI program
doesn’t have a main() method that outlines what will happen when the program is run, in a

124
step-by-step process from beginning to end. Instead, the program must be prepared to respond to
various kinds of events that can happen at unpredictable times and in an order that the program
doesn’t control. The most basic kinds of events are generated by the mouse and keyboard. The
user can press any key on the keyboard, move the mouse, or press a button on the mouse. The user
can do any of these things at any time, and the computer has to respond appropriately.
In JAVA, events are represented by objects. When an event occurs, the system collects all the
information relevant to the event and constructs an object to contain that information. Different
types of events are represented by objects belonging to different classes. For example, when the
user presses one of the buttons on a mouse, an object belonging to a class called MouseEvent is
constructed. The object contains information such as the source of the event (that is, the compo-
nent on which the user clicked), the (x,y) coordinates of the point in the component where the
click occurred, and which button on the mouse was pressed. When the user presses a key on the
keyboard, a KeyEvent is created. After the event object is constructed, it is passed as a parameter
to a designated method. By writing that method, the programmer says what should happen when
the event occurs.
As a JAVA programmer, you get a fairly high-level view of events. There is a lot of process-
ing that goes on between the time that the user presses a key or moves the mouse and the time
that a method in your program is called to respond to the event. Fortunately, you don’t need to
know much about that processing. But you should understand this much: Even though your GUI
program doesn’t have a main() method, there is a sort of main method running somewhere that
executes a loop of the form
while the program is still running:
Wait for the next event to occur
Call a method to handle the event
This loop is called an event loop. Every GUI program has an event loop. In JAVA, you
don’t have to write the loop. It’s part of “the system.” If you write a GUI program in some other
language, you might have to provide a main method that runs an event loop.
In this section, we’ll look at handling mouse events in JAVA, and we’ll cover the framework for
handling events in general. The next section will cover keyboard-related events and timer events.
JAVA also has other types of events, which are produced by GUI components.

Event Handling
For an event to have any effect, a program must detect the event and react to it. In order to detect
an event, the program must “listen” for it. Listening for events is something that is done by an
object called an event listener. An event listener object must contain instance methods for
handling the events for which it listens. For example, if an object is to serve as a listener for events
of type MouseEvent, then it must contain the following method (among several others):
public void mousePressed(MouseEvent evt) {
. . .
}
The body of the method defines how the object responds when it is notified that a mouse button
has been pressed. The parameter, evt, contains information about the event. This information can
be used by the listener object to determine its response.
The methods that are required in a mouse event listener are specified in an interface named
MouseListener. To be used as a listener for mouse events, an object must implement this
MouseListener interface. JAVA interfaces were covered previously. (To review briefly: An
interface in JAVA is just a list of instance methods. A class can “implement” an interface by
doing two things. First, the class must be declared to implement the interface, as in

125
 class MyListener implements MouseListener
OR
class MyApplet extends JApplet implements MouseListener
Second, the class must include a definition for each instance method specified in the interface.
An interface can be used as the type for a variable or formal parameter. We say that an
object implements the MouseListener interface if it belongs to a class that implements the
MouseListener interface. Note that it is not enough for the object to include the specified meth-
ods. It must also belong to a class that is specifically declared to implement the interface.)
Many events in JAVA are associated with GUI components. For example, when the user presses
a button on the mouse, the associated component is the one that the user clicked on. Before a lis-
tener object can “hear” events associated with a given component, the listener object must be regis-
tered with the component. If a MouseListener object, mListener, needs to hear mouse events
associated with a Component object, comp, the listener must be registered with the component
by calling “comp.addMouseListener(mListener);”. The addMouseListener() method
is an instance method in class Component, and so can be used with any GUI component object.
In our first few examples, we will listen for events on a JPanel that is being used as a drawing
surface.
The event classes, such as MouseEvent, and the listener interfaces, for example MouseListener,
are defined in the package java.awt.event. This means that if you want to work with events,
you either include the line “import java.awt.event.*;” at the beginning of your source code
file or import the individual classes and interfaces.
Admittedly, there is a large number of details to tend to when you want to use events. To
summarize, you must

1. Put the import specification “import java.awt.event.*;” (or individual imports) at

the beginning of your source code;

2. Declare that some class implements the appropriate listener interface, such as
MouseListener;

3. Provide definitions in that class for the methods from the interface;

4. Register the listener object with the component that will generate the events by calling a
method such as addMouseListener() in the component.

Any object can act as an event listener, provided that it implements the appropriate interface.
A component can listen for the events that it itself generates. A panel can listen for events from
components that are contained in the panel. A special class can be created just for the purpose
of defining a listening object. Many people consider it to be good form to use anonymous inner
classes to define listening objects. You will see all of these patterns in examples in this textbook.

MouseEvent and MouseListener

The MouseListener interface specifies five different instance methods:
public void mousePressed(MouseEvent evt);
public void mouseReleased(MouseEvent evt);
public void mouseClicked(MouseEvent evt);
public void mouseEntered(MouseEvent evt);
public void mouseExited(MouseEvent evt);
The mousePressed method is called as soon as the user presses down on one of the mouse
buttons, and mouseReleased is called when the user releases a button. These are the two methods

126
that are most commonly used, but any mouse listener object must define all five methods; you can
leave the body of a method empty if you don’t want to define a response. The mouseClicked
method is called if the user presses a mouse button and then releases it quickly, without moving
the mouse. (When the user does this, all three methods – mousePressed, mouseReleased, and
mouseClicked – will be called in that order.) In most cases, you should define mousePressed
instead of mouseClicked. The mouseEntered and mouseExited methods are called when the
mouse cursor enters or leaves the component. For example, if you want the component to change
appearance whenever the user moves the mouse over the component, you could define these two
methods.
As an example, we will look at a small addition to the RandomStringsPanel example from
the previous section. In the new version, the panel will repaint itself when the user clicks on it. In
order for this to happen, a mouse listener should listen for mouse events on the panel, and when
the listener detects a mousePressed event, it should respond by calling the repaint() method
of the panel. Here is an applet version of the ClickableRandomStrings program for you to
try; when you click the applet, a new set of random strings is displayed:
For the new version of the program, we need an object that implements the MouseListener
interface. One way to create the object is to define a separate class, such as:
import java.awt.Component;
import java.awt.event.*;

/**
* An object of type RepaintOnClick is a MouseListener that
* will respond to a mousePressed event by calling the repaint()
* method of the source of the event. That is, a RepaintOnClick
* object can be added as a mouse listener to any Component;
* when the user clicks that component, the component will be
* repainted.
*/
public class RepaintOnClick implements MouseListener {

public void mousePressed(MouseEvent evt) {

Component source = (Component)evt.getSource();
source.repaint(); // Call repaint() on the Component that was clicked.
}

public void mouseClicked(MouseEvent evt) { }

public void mouseReleased(MouseEvent evt) { }
public void mouseEntered(MouseEvent evt) { }
public void mouseExited(MouseEvent evt) { }

}
This class does three of the four things that we need to do in order to handle mouse events:
First, it imports java.awt.event.* for easy access to event-related classes. Second, it is de-
clared that the class “implements MouseListener”. And third, it provides definitions for
the five methods that are specified in the MouseListener interface. (Note that four of the
five event-handling methods have empty defintions. We really only want to define a response
to mousePressed events, but in order to implement the MouseListener interface, a class must
define all five methods.)
We must do one more thing to set up the event handling for this example: We must reg-
ister an event-handling object as a listener with the component that will generate the events.
In this case, the mouse events that we are interested in will be generated by an object of type
RandomStringsPanel. If panel is a variable that refers to the panel object, we can create a

127
mouse listener object and register it with the panel with the statements:
// Create MouseListener object.
RepaintOnClick listener = new RepaintOnClick();

// Create MouseListener object.

panel.addMouseListener(listener);
Once this is done, the listener object will be notified of mouse events on the panel. When-
ever a mousePressed event occurs, the mousePressed() method in the listener will be
called. The code in this method calls the repaint() method in the component that is the source
of the event, that is, in the panel. The result is that the RandomStringsPanel is repainted with
its strings in new random colors, fonts, and positions.
Although the RepaintOnClick class was written for use with the
RandomStringsPanel example, the event-handling class contains no reference at all to the
RandomStringsPanel class. How can this be? The mousePressed() method in class RepaintOnClick
looks at the source of the event, and calls its repaint() method. If we have registered the
RepaintOnClick object as a listener on a
RandomStringsPanel, then it is that panel that is repainted. But the listener object could be
used with any type of component, and it would work in the same way.
Similarly, RandomStringsPanel contains no reference to the RepaintOnClick class–in
fact, RandomStringsPanel was written before we even knew anything about mouse events!
The panel will send mouse events to any object that has registered with it as a mouse listener.
It does not need to know anything about that object except that it is capable of receiving mouse
events.
The relationship between an object that generates an event and an object that responds to that
event is rather loose. The relationship is set up by registering one object to listen for events from
the other object. This is something that can potentially be done from outside both objects. Each
object can be developed independently, with no knowledge of the internal operation of the other
object. This is the essence of modular design: Build a complex system out of modules that
interact only in straightforward, easy to understand ways. Then each module is a separate design
problem that can be tackled independently.
To make this clearer, consider the application version of ClickableRandomStrings. I have
included RepaintOnClick as a nested subclass, although it could just as easily be a separate
class. The main point is that this program uses the same
RandomStringsPanel class that was used in the original program, which did not respond to
mouse clicks. The mouse handling has been “bolted on” to an existing class, without having to
make any changes at all to that class:
import java.awt.Component;
import java.awt.event.MouseEvent;
import java.awt.event.MouseListener;
import javax.swing.JFrame;

/**

128
 * Displays a window that shows 25 copies of the string "Java!" in
* random colors, fonts, and positions. The content of the window
* is an object of type RandomStringsPanel. When the user clicks
* the window, the content of the window is repainted, with the
* strings in newly selected random colors, fonts, and positions.
*/
public class ClickableRandomStringsApp {

public static void main(String[] args) {

JFrame window = new JFrame("Random Strings");
RandomStringsPanel content = new RandomStringsPanel();
content.addMouseListener( new RepaintOnClick() );//Register mouse listener.
window.setContentPane(content);
window.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
window.setLocation(100,75);
window.setSize(300,240);
window.setVisible(true);
}

private static class RepaintOnClick implements MouseListener {

public void mousePressed(MouseEvent evt) {

Component source = (Component)evt.getSource();
source.repaint();
}

public void mouseClicked(MouseEvent evt) { }

public void mouseReleased(MouseEvent evt) { }
public void mouseEntered(MouseEvent evt) { }
public void mouseExited(MouseEvent evt) { }

}
}
Often, when a mouse event occurs, you want to know the location of the mouse cursor. This
information is available from the MouseEvent parameter to the event-handling method, which
contains instance methods that return information about the event. If evt is the parameter, then
you can find out the coordinates of the mouse cursor by calling evt.getX() and evt.getY().
These methods return integers which give the x and y coordinates where the mouse cursor was
positioned at the time when the event occurred. The coordinates are expressed in the coordinate
system of the component that generated the event, where the top left corner of the component is
(0,0).

Anonymous Event Handlers

As I mentioned above, it is a fairly common practice to use anonymous nested classes to define
listener objects. A special form of the new operator is used to create an object that belongs to an
anonymous class. For example, a mouse listener object can be created with an expression of the
form:

129
 new MouseListener() {
public void mousePressed(MouseEvent evt) { . . . }
public void mouseReleased(MouseEvent evt) { . . . }
public void mouseClicked(MouseEvent evt) { . . . }
public void mouseEntered(MouseEvent evt) { . . . }
public void mouseExited(MouseEvent evt) { . . . }
}

This is all just one long expression that both defines an un-named class and creates an object
that belongs to that class. To use the object as a mouse listener, it should be passed as the parameter
to some component’s addMouseListener() method in a command of the form:

component.addMouseListener( new MouseListener() {

public void mousePressed(MouseEvent evt) { . . . }
public void mouseReleased(MouseEvent evt) { . . . }
public void mouseClicked(MouseEvent evt) { . . . }
public void mouseEntered(MouseEvent evt) { . . . }
public void mouseExited(MouseEvent evt) { . . . }
} );

Now, in a typical application, most of the method definitions in this class will be empty. A class
that implements an interface must provide definitions for all the methods in that interface, even
if the definitions are empty. To avoid the tedium of writing empty method definitions in cases like
this, JAVA provides adapter classes. An adapter class implements a listener interface by providing
empty definitions for all the methods in the interface. An adapter class is useful only as a basis
for making subclasses. In the subclass, you can define just those methods that you actually want
to use. For the remaining methods, the empty definitions that are provided by the adapter class
will be used. The adapter class for the MouseListener interface is named MouseAdapter. For
example, if you want a mouse listener that only responds to mouse-pressed events, you can use a
command of the form:
component.addMouseListener( new MouseAdapter() {
public void mousePressed(MouseEvent evt) { . . . }
} );

To see how this works in a real example, let’s write another version of the application: ClickableRandomString
This version uses an anonymous class based on MouseAdapter to handle mouse events:
import java.awt.Component;
import java.awt.event.MouseEvent;
import java.awt.event.MouseListener;
import javax.swing.JFrame;

public class ClickableRandomStringsApp {

public static void main(String[] args) {

130
 JFrame window = new JFrame("Random Strings");
RandomStringsPanel content = new RandomStringsPanel();

content.addMouseListener( new MouseAdapter() {

// Register a mouse listener that is defined by an anonymous subclass
// of MouseAdapter. This replaces the RepaintOnClick class that was
// used in the original version.
public void mousePressed(MouseEvent evt) {
Component source = (Component)evt.getSource();
source.repaint();
}
} );

window.setContentPane(content);
window.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
window.setLocation(100,75);
window.setSize(300,240);
window.setVisible(true);
}
}

Anonymous inner classes can be used for other purposes besides event handling. For ex-
ample, suppose that you want to define a subclass of JPanel to represent a drawing surface.
The subclass will only be used once. It will redefine the paintComponent() method, but will
make no other changes to JPanel. It might make sense to define the subclass as an anonymous
nested class. As an example, I present HelloWorldGUI4.java. This version is a variation of
HelloWorldGUI2.java that uses anonymous nested classes where the original program uses
ordinary, named nested classes:
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

/**
* A simple GUI program that creates and opens a JFrame containing
* the message "Hello World" and an "OK" button. When the user clicks
* the OK button, the program ends. This version uses anonymous
* classes to define the message display panel and the action listener
* object. Compare to HelloWorldGUI2, which uses nested classes.
*/
public class HelloWorldGUI4 {
/**
* The main program creates a window containing a HelloWorldDisplay
* and a button that will end the program when the user clicks it.
*/

public static void main(String[] args) {

JPanel displayPanel = new JPanel() {

131
 // An anonymous subclass of JPanel that displays "Hello World!".
public void paintComponent(Graphics g) {
super.paintComponent(g);
g.drawString( "Hello World!", 20, 30 );
}
};

JButton okButton = new JButton("OK");

okButton.addActionListener( new ActionListener() {

// An anonymous class that defines the listener object.
public void actionPerformed(ActionEvent e) {
System.exit(0);
}
} );

JPanel content = new JPanel();

content.setLayout(new BorderLayout());
content.add(displayPanel, BorderLayout.CENTER);
content.add(okButton, BorderLayout.SOUTH);

JFrame window = new JFrame("GUI Test");

window.setContentPane(content);
window.setSize(250,100);
window.setLocation(100,100);
window.setVisible(true);
}
}

6.6 Basic Components

I N PRECEDING SECTIONS, you’ve seen how to use a graphics context to draw on the screen
and how to handle mouse events and keyboard events. In one sense, that’s all there is to GUI
programming. If you’re willing to program all the drawing and handle all the mouse and keyboard
events, you have nothing more to learn. However, you would either be doing a lot more work
than you need to do, or you would be limiting yourself to very simple user interfaces. A typical
user interface uses standard GUI components such as buttons, scroll bars, text-input boxes, and
menus. These components have already been written for you, so you don’t have to duplicate the
work involved in developing them. They know how to draw themselves, and they can handle the
details of processing the mouse and keyboard events that concern them.
Consider one of the simplest user interface components, a push button. The button has a
border, and it displays some text. This text can be changed. Sometimes the button is disabled, so
that clicking on it doesn’t have any effect. When it is disabled, its appearance changes. When the
user clicks on the push button, the button changes appearance while the mouse button is pressed
and changes back when the mouse button is released. In fact, it’s more complicated than that. If
the user moves the mouse outside the push button before releasing the mouse button, the button
changes to its regular appearance. To implement this, it is necessary to respond to mouse exit or
mouse drag events. Furthermore, on many platforms, a button can receive the input focus. The
button changes appearance when it has the focus. If the button has the focus and the user presses
the space bar, the button is triggered. This means that the button must respond to keyboard and
focus events as well.

132
 Fortunately, you don’t have to program any of this, provided you use an object belonging to the
standard class javax.swing.JButton. A JButton object draws itself and processes mouse,
keyboard, and focus events on its own. You only hear from the Button when the user triggers it by
clicking on it or pressing the space bar while the button has the input focus. When this happens, the
JButton object creates an event object belonging to the class java.awt.event.ActionEvent.
The event object is sent to any registered listeners to tell them that the button has been pushed.
Your program gets only the information it needs – the fact that a button was pushed.
The standard components that are defined as part of the Swing graphical user interface API are
defined by subclasses of the class JComponent, which is itself a subclass of Component. (Note
that this includes the JPanel class that we have already been working with extensively.) Many
useful methods are defined in the Component and JComponent classes and so can be used with
any Swing component. We begin by looking at a few of these methods. Suppose that comp is a
variable that refers to some JComponent. Then the following methods can be used:
• comp.getWidth() and comp.getHeight() are methods that give the current size of the
component, in pixels. One warning: When a component is first created, its size is zero. The
size will be set later, probably by a layout manager. A common mistake is to check the size
of a component before that size has been set, such as in a constructor.
• comp.setEnabled(true) and comp.setEnabled(false) can be used to enable and
disable the component. When a component is disabled, its appearance might change, and
the user cannot do anything with it. The boolean-valued method, comp.isEnabled() can
be called to discover whether the component is enabled.
• comp.setVisible(true) and comp.setVisible(false) can be called to hide or
show the component.
• comp.setFont(font) sets the font that is used for text displayed on the component. See
Subectionă6.3.3 for a discussion of fonts.
• comp.setBackground(color) and comp.setForeground(color) set the background
and foreground colors for the component.
• comp.setOpaque(true) tells the component that the area occupied by the component
should be filled with the component’s background color before the content of the component
is painted. By default, only JLabels are non-opaque. A non-opaque, or “transparent”,
component ignores its background color and simply paints its content over the content of its
container. This usually means that it inherits the background color from its container.
• comp.setToolTipText(string) sets the specified string as a “tool tip” for the compo-
nent. The tool tip is displayed if the mouse cursor is in the component and the mouse is not
moved for a few seconds. The tool tip should give some information about the meaning of
the component or how to use it.
• comp.setPreferredSize(size) sets the size at which the component should be dis-
played, if possible. The parameter is of type java.awt.Dimension, where an object of
type Dimension has two public integer-valued instance variables, width and height. A
call to this method usually looks something like
“setPreferredSize( new Dimension(100,50))”.
The preferred size is used as a hint by layout managers, but will not be respected in all cases.
Standard components generally compute a correct preferred size automatically, but it can be
useful to set it in some cases. For example, if you use a JPanel as a drawing surface, it
might be a good idea to set a preferred size for it.

133
Note that using any component is a multi-step process. The component object must be created
with a constructor. It must be added to a container. In many cases, a listener must be registered
to respond to events from the component. And in some cases, a reference to the component must
be saved in an instance variable so that the component can be manipulated by the program after it
has been created. In this section, we will look at a few of the basic standard components that are
available in Swing. In the next section we will consider the problem of laying out components in
containers.

JButton
An object of class JButton is a push button that the user can click to trigger some action. You’ve
already seen buttons, but we consider them in much more detail here. To use any component
effectively, there are several aspects of the corresponding class that you should be familiar with.
For JButton, as an example, I list these aspects explicitly:
• Constructors: The JButton class has a constructor that takes a string as a parameter. This
string becomes the text displayed on the button. For example constructing the JButton
with stopGoButton = new JButton(‘‘Go’’) creates a button object that will display
the text, “Go” (but remember that the button must still be added to a container before it can
appear on the screen).
• Events: When the user clicks on a button, the button generates an event of type ActionEvent.
This event is sent to any listener that has been registered with the button as an ActionListener.
• Listeners: An object that wants to handle events generated by buttons must implement the
ActionListener interface. This interface defines just one method,
“pubic void actionPerformed(ActionEvent evt)”,
which is called to notify the object of an action event.
• Registration of Listeners: In order to actually receive notification of an event from a button,
an ActionListener must be registered with the button. This is done with the button’s
addActionListener() method. For example:
stopGoButton.addActionListener( buttonHandler);

• Event methods: When actionPerformed(evt) is called by the button, the parame-

ter, evt, contains information about the event. This information can be retrieved by calling
methods in the ActionEvent class. In particular,
evt.getActionCommand() returns a String giving the command associated with the
button. By default, this command is the text that is displayed on the button, but it is pos-
sible to set it to some other string. The method evt.getSource() returns a reference to
the Object that produced the event, that is, to the JButton that was pressed. The return
value is of type Object, not JButton, because other types of components can also produce
ActionEvents.

• Component methods: Several useful methods are defined in the JButton class. For ex-
ample, stopGoButton.setText(‘‘Stop’’) changes the text displayed on the button to
“Stop”. And stopGoButton.setActionCommand(‘‘sgb’’) changes the action com-
mand associated to this button for action events.
Of course, JButtons have all the general Component methods, such as setEnabled() and
setFont(). The setEnabled() and setText() methods of a button are particularly useful
for giving the user information about what is going on in the program. A disabled button is better
than a button that gives an obnoxious error message such as “Sorry, you can’t click on me now!”

134
JLabel
JLabel is certainly the simplest type of component. An object of type JLabel exists just to
display a line of text. The text cannot be edited by the user, although it can be changed by your
program. The constructor for a JLabel specifies the text to be displayed:
JLabel message = new JLabel("Hello World!");
There is another constructor that specifies where in the label the text is located, if there is extra
space. The possible alignments are given by the constants JLabel.LEFT, JLabel.CENTER, and
JLabel.RIGHT. For example,
JLabel message = new JLabel("Hello World!", JLabel.CENTER);
creates a label whose text is centered in the available space. You can change the text displayed in
a label by calling the label’s setText() method:
message.setText("Goodby World!");
Since JLabel is a subclass of JComponent, you can use JComponent methods such as
setForeground() with labels. If you want the background color to have any effect, call setOpaque(true)
on the label, since otherwise the JLabel might not fill in its background. For example:
JLabel message = new JLabel("Hello World!", JLabel.CENTER);
message.setForeground(Color.red); // Display red text...
message.setBackground(Color.black); // on a black background...
message.setFont(new Font("Serif",Font.BOLD,18)); // in a big bold font.
message.setOpaque(true); // Make sure background is filled in.

JCheckBox
A JCheckBox is a component that has two states: selected or unselected. The user can change the
state of a check box by clicking on it. The state of a checkbox is represented by a boolean value
that is true if the box is selected and false if the box is unselected. A checkbox has a label,
which is specified when the box is constructed:
JCheckBox showTime = new JCheckBox("Show Current Time");
Usually, it’s the user who sets the state of a JCheckBox, but you can also set the state in
your program using its setSelected(boolean) method. If you want the checkbox showTime
to be checked, you would say “showTime.setSelected(true)’’. To uncheck the box, say
“showTime.setSelected(false)’’. You can determine the current state of a checkbox by
calling its isSelected() method, which returns a boolean value.
In many cases, you don’t need to worry about events from checkboxes. Your program can just
check the state whenever it needs to know it by calling the isSelected() method. However, a
checkbox does generate an event when its state is changed by the user, and you can detect this event
and respond to it if you want something to happen at the moment the state changes. When the state
of a checkbox is changed by the user, it generates an event of type ActionEvent. If you want
something to happen when the user changes the state, you must register an ActionListener
with the checkbox by calling its addActionListener() method. (Note that if you change the
state by calling the setSelected() method, no ActionEvent is generated. However, there
is another method in the JCheckBox class, doClick(), which simulates a user click on the
checkbox and does generate an ActionEvent.)
When handling an ActionEvent, call evt.getSource() in the actionPerformed()
method to find out which object generated the event. (Of course, if you are only listening for events
from one component, you don’t even have to do this.) The returned value is of type Object, but

135
you can type-cast it to another type if you want. Once you know the object that generated the
event, you can ask the object to tell you its current state. For example, if you know that the event
had to come from one of two checkboxes, cb1 or cb2, then your actionPerformed() method
might look like this:
public void actionPerformed(ActionEvent evt) {
Object source = evt.getSource();
if (source == cb1) {
boolean newState = ((JCheckBox)cb1).isSelected();
... // respond to the change of state
}
else if (source == cb2) {
boolean newState = ((JCheckBox)cb2).isSelected();
... // respond to the change of state
}
}

Alternatively, you can use evt.getActionCommand() to retrieve the action command as-
sociated with the source. For a JCheckBox, the action command is, by default, the label of the
checkbox.

JTextField and JTextArea

The JTextField and JTextArea classes represent components that contain text that can be
edited by the user. A JTextField holds a single line of text, while a JTextArea can hold
multiple lines. It is also possible to set a JTextField or JTextArea to be read-only so that the
user can read the text that it contains but cannot edit the text. Both classes are subclasses of an
abstract class, JTextComponent, which defines their common properties.
JTextField and JTextArea have many methods in common. The setText() instance
method, which takes a parameter of type String, can be used to change the text that is displayed
in an input component. The contents of the component can be retrieved by calling its getText()
instance method, which returns a value of type String. If you want to stop the user from mod-
ifying the text, you can call setEditable(false). Call the same method with a parameter of
true to make the input component user-editable again.
The user can only type into a text component when it has the input focus. The user can give
the input focus to a text component by clicking it with the mouse, but sometimes it is useful to give
the input focus to a text field programmatically. You can do this by calling its requestFocus()
method. For example, when I discover an error in the user’s input, I usually call requestFocus()
on the text field that contains the error. This helps the user see where the error occurred and let’s
the user start typing the correction immediately.
The JTextField class has a constructor public JTextField(int columns) where columns
is an integer that specifies the number of characters that should be visible in the text field. This is
used to determine the preferred width of the text field. (Because characters can be of different sizes
and because the preferred width is not always respected, the actual number of characters visible in
the text field might not be equal to columns.) You don’t have to specify the number of columns;
for example, you might use the text field in a context where it will expand to fill whatever space is
available. In that case, you can use the constructor JTextField(), with no parameters. You can
also use the following constructors, which specify the initial contents of the text field:
public JTextField(String contents);
public JTextField(String contents, int columns);

The constructors for a JTextArea are

136
 public JTextArea()
public JTextArea(int rows, int columns)
public JTextArea(String contents)
public JTextArea(String contents, int rows, int columns)

The parameter rows specifies how many lines of text should be visible in the text area. This
determines the preferred height of the text area, just as columns determines the preferred width.
However, the text area can actually contain any number of lines; the text area can be scrolled
to reveal lines that are not currently visible. It is common to use a JTextArea as the CENTER
component of a BorderLayout. In that case, it isn’t useful to specify the number of lines and
columns, since the TextArea will expand to fill all the space available in the center area of the
container.
The JTextArea class adds a few useful methods to those already inherited from JTextComponent
e.g. the instance method append(moreText), where moreText is of type String, adds the
specified text at the end of the current content of the text area. (When using append() or
setText() to add text to a JTextArea, line breaks can be inserted in the text by using the
newline character, ’\n’.) And setLineWrap(wrap), where wrap is of type boolean, tells
what should happen when a line of text is too long to be displayed in the text area. If wrap is true,
then any line that is too long will be “wrapped” onto the next line; if wrap is false, the line will
simply extend outside the text area, and the user will have to scroll the text area horizontally to see
the entire line. The default value of wrap is false.
When the user is typing in a JTextField and presses return, an ActionEvent is generated.
If you want to respond to such events, you can register an ActionListener with the text field,
using the text field’s addActionListener() method. (Since a JTextArea can contain multiple
lines of text, pressing return in a text area does not generate an event; is simply begins a new line
of text.)

6.7 Basic Layout

C OMPONENTS ARE THE FUNDAMENTAL BUILDING BLOCKS of a graphical user interface. But
you have to do more with components besides create them. Another aspect of GUI programming is
laying out components on the screen, that is, deciding where they are drawn and how big they
are. You have probably noticed that computing coordinates can be a difficult problem, especially
if you don’t assume a fixed size for the drawing area. JAVA has a solution for this, as well.
Components are the visible objects that make up a GUI. Some components are containers,
which can hold other components. Containers in JAVA are objects that belong to some subclass of
java.awt.Container. The content pane of a JApplet or JFrame is an example of a container.
The standard class JPanel, which we have mostly used as a drawing surface up till now, is another
example of a container.
Because a JPanel object is a container, it can hold other components. Because a JPanel is
itself a component, you can add a JPanel to another JPanel. This makes complex nesting of
components possible. JPanels can be used to organize complicated user interfaces, as shown in
this illustration:

137
 The components in a container must be “laid out,” which means setting their sizes and posi-
tions. It’s possible to program the layout yourself, but ordinarily layout is done by a layout manager.
A layout manager is an object associated with a container that implements some policy for laying
out the components in that container. Different types of layout manager implement different poli-
cies. In this section, we will cover the three most common types of layout manager, and then we
will look at several programming examples that use components and layout.
Every container has an instance method, setLayout(), that takes a parameter of type LayoutManager
and that is used to specify the layout manager that will be responsible for laying out any compo-
nents that are added to the container. Components are added to a container by calling an instance
method named add() in the container object. There are actually several versions of the add()
method, with different parameter lists. Different versions of add() are appropriate for different
layout managers, as we will see below.

Basic Layout Managers

JAVA has a variety of standard layout managers that can be used as parameters in the setLayout()
method. They are defined by classes in the package java.awt. Here, we will look at just three of
these layout manager classes: FlowLayout, BorderLayout, and GridLayout.
A FlowLayout simply lines up components in a row across the container. The size of each
component is equal to that component’s “preferred size.” After laying out as many items as will
fit in a row across the container, the layout manager will move on to the next row. The default
layout for a JPanel is a FlowLayout; that is, a JPanel uses a FlowLayout unless you specify
a different layout manager by calling the panel’s setLayout() method.
The components in a given row can be either left-aligned, right-aligned, or centered within that
row, and there can be horizontal and vertical gaps between components. If the default constructor,
“new FlowLayout()”, is used, then the components on each row will be centered and both the
horizontal and the vertical gaps will be five pixels. The constructor
public FlowLayout(int align, int hgap, int vgap)

can be used to specify alternative alignment and gaps. The possible values of align are FlowLayout.LEFT,
FlowLayout.RIGHT, and FlowLayout.CENTER.
Suppose that cntr is a container object that is using a FlowLayout as its layout manager.
Then, a component, comp, can be added to the container with the statement cntr.add(comp);
The FlowLayout will line up all the components that have been added to the container in this
way. They will be lined up in the order in which they were added. For example, this picture shows
five buttons in a panel that uses a FlowLayout:

138
 Note that since the five buttons will not fit in a single row across the panel, they are arranged in
two rows. In each row, the buttons are grouped together and are centered in the row. The buttons
were added to the panel using the statements:
panel.add(button1);
panel.add(button2);
panel.add(button3);
panel.add(button4);
panel.add(button5);
When a container uses a layout manager, the layout manager is ordinarily responsible for com-
puting the preferred size of the container (although a different preferred size could be set by calling
the container’s setPreferredSize method). A FlowLayout prefers to put its components in a
single row, so the preferred width is the total of the preferred widths of all the components, plus the
horizontal gaps between the components. The preferred height is the maximum preferred height
of all the components.
A BorderLayout layout manager is designed to display one large, central component, with
up to four smaller components arranged along the edges of the central component. If a container,
cntr, is using a BorderLayout, then a component, comp, should be added to the container using
a statement of the form
cntr.add( comp, borderLayoutPosition );
where borderLayoutPosition specifies what position the component should occupy in the
layout and is given as one of the constants
BorderLayout.CENTER, BorderLayout.NORTH, BorderLayout.SOUTH,
BorderLayout.EAST, or BorderLayout.WEST. The meaning of the five positions is shown in
this diagram:

Note that a border layout can contain fewer than five compompontnts, so that not all five of
the possible positions need to be filled.
A BorderLayout selects the sizes of its components as follows: The NORTH and SOUTH
components (if present) are shown at their preferred heights, but their width is set equal to the full
width of the container. The EAST and WEST components are shown at their preferred widths, but
their height is set to the height of the container, minus the space occupied by the NORTH and SOUTH
components. Finally, the CENTER component takes up any remaining space; the preferred size of
the CENTER component is completely ignored. You should make sure that the components that

139
you put into a BorderLayout are suitable for the positions that they will occupy. A horizontal
slider or text field, for example, would work well in the NORTH or SOUTH position, but wouldn’t
make much sense in the EAST or WEST position.
The default constructor, new BorderLayout(), leaves no space between components. If
you would like to leave some space, you can specify horizontal and vertical gaps in the constructor
of the BorderLayout object. For example, if you say
panel.setLayout(new BorderLayout(5,7));
then the layout manager will insert horizontal gaps of 5 pixels between components and vertical
gaps of 7 pixels between components. The background color of the container will show through in
these gaps. The default layout for the original content pane that comes with a JFrame or JApplet
is a BorderLayout with no horizontal or vertical gap.
Finally, we consider the GridLayout layout manager. A grid layout lays out components in
a grid of equal sized rectangles. This illustration shows how the components would be arranged
in a grid layout with 3 rows and 2 columns:

If a container uses a GridLayout, the appropriate add method for the container takes a single
parameter of type Component (for example: cntr.add(comp)). Components are added to the
grid in the order shown; that is, each row is filled from left to right before going on the next row.
The constructor for a GridLayout takes the form “new GridLayout(R,C)”, where R is
the number of rows and C is the number of columns. If you want to leave horizontal gaps of
H pixels between columns and vertical gaps of V pixels between rows, then you need to use
“new GridLayout(R,C,H,V)” instead.
When you use a GridLayout, it’s probably good form to add just enough components to fill
the grid. However, this is not required. In fact, as long as you specify a non-zero value for the
number of rows, then the number of columns is essentially ignored. The system will use just as
many columns as are necessary to hold all the components that you add to the container. If you
want to depend on this behavior, you should probably specify zero as the number of columns.
You can also specify the number of rows as zero. In that case, you must give a non-zero number
of columns. The system will use the specified number of columns, with just as many rows as
necessary to hold the components that are added to the container.
Horizontal grids, with a single row, and vertical grids, with a single column, are very common.
For example, suppose that button1, button2, and button3 are buttons and that you’d like to
display them in a horizontal row in a panel. If you use a horizontal grid for the panel, then the
buttons will completely fill that panel and will all be the same size. The panel can be created as
follows:
JPanel buttonBar = new JPanel();
buttonBar.setLayout( new GridLayout(1,3) );
// (Note: The "3" here is pretty much ignored, and
// you could also say "new GridLayout(1,0)".

140
 // To leave gaps between the buttons, you could use
// ‘‘new GridLayout(1,0,5,5)’’.)
buttonBar.add(button1);
buttonBar.add(button2);
buttonBar.add(button3);
You might find this button bar to be more attractive than the one that uses the default FlowLayout
layout manager.

A Simple Calculator
As our next example, we look briefly at an example that uses nested subpanels to build a more
complex user interface. The program has two JTextFields where the user can enter two num-
bers, four JButtons that the user can click to add, subtract, multiply, or divide the two numbers,
and a JLabel that displays the result of the operation:
Like the previous example, this example uses a main panel with a GridLayout that has four
rows and one column. In this case, the layout is created with the statement: “setLayout(new GridLayout(4,1,3,
which allows a 3-pixel gap between the rows where the gray background color of the panel is visi-
ble. The gray border around the edges of the panel is added with the statement
setBorder( BorderFactory.createEmptyBorder(5,5,5,5) );.
The first row of the grid layout actually contains two components, a JLabel displaying the
text “x =” and a JTextField. A grid layout can only only have one component in each position.
In this case, that component is a JPanel, a subpanel that is nested inside the main panel. This
subpanel in turn contains the label and text field. This can be programmed as follows:
xInput = new JTextField("0", 10); // Create a text field to hold 10 chars.
JPanel xPanel = new JPanel(); // Create the subpanel.
xPanel.add( new JLabel(" x = ")); // Add a label to the subpanel.
xPanel.add(xInput); // Add the text field to the subpanel
mainPanel.add(xPanel); // Add the subpanel to the main panel.
The subpanel uses the default FlowLayout layout manager, so the label and text field are
simply placed next to each other in the subpanel at their preferred size, and are centered in the
subpanel.
Similarly, the third row of the grid layout is a subpanel that contains four buttons. In this case,
the subpanel uses a GridLayout with one row and four columns, so that the buttons are all the
same size and completely fill the subpanel.
One other point of interest in this example is the actionPerformed() method that responds
when the user clicks one of the buttons. This method must retrieve the user’s numbers from the
text field, perform the appropriate arithmetic operation on them (depending on which button was
clicked), and set the text of the label to represent the result. However, the contents of the text
fields can only be retrieved as strings, and these strings must be converted into numbers. If the
conversion fails, the label is set to display an error message:
public void actionPerformed(ActionEvent evt) {

double x, y; // The numbers from the input boxes.

try {
String xStr = xInput.getText();
x = Double.parseDouble(xStr);
}
catch (NumberFormatException e) {
// The string xStr is not a legal number.
answer.setText("Illegal data for x.");

141
 xInput.requestFocus();
return;
}

try {
String yStr = yInput.getText();
y = Double.parseDouble(yStr);
}
catch (NumberFormatException e) {
// The string xStr is not a legal number.
answer.setText("Illegal data for y.");
yInput.requestFocus();
return;
}

/* Perfrom the operation based on the action command from the

button. The action command is the text displayed on the button.
Note that division by zero produces an error message. */
String op = evt.getActionCommand();
if (op.equals("+"))
answer.setText( "x + y = " + (x+y) );
else if (op.equals("−"))
answer.setText( "x − y = " + (x−y) );
else if (op.equals("*"))
answer.setText( "x * y = " + (x*y) );
else if (op.equals("/")) {
if (y == 0)
answer.setText("Can’t divide by zero!");
else
answer.setText( "x / y = " + (x/y) );
}
} // end actionPerformed()

(The complete source code for this example can be found in SimpleCalc.java.)

A Little Card Game

For a final example, let’s look at something a little more interesting as a program. The example
is a simple card game in which you look at a playing card and try to predict whether the next
card will be higher or lower in value. (Aces have the lowest value in this game.) You’ve seen a
text-oriented version of the same game previously have also seen Deck, Hand, and Card classes
that are used in the game program. In this GUI version of the game, you click on a button to make
your prediction. If you predict wrong, you lose. If you make three correct predictions, you win.
After completing one game, you can click the “New Game” button to start a new game. Try it!
See what happens if you click on one of the buttons at a time when it doesn’t make sense to do so.
The complete source code for this example is in the file HighLowGUI.java.
The overall structure of the main panel in this example should be clear: It has three buttons in
a subpanel at the bottom of the main panel and a large drawing surface that displays the cards and
a message. The main panel uses a BorderLayout. The drawing surface occupies the CENTER
position of the border layout. The subpanel that contains the buttons occupies the SOUTH position
of the border layout, and the other three positions of the layout are empty.
The drawing surface is defined by a nested class named CardPanel, which is a subclass of
JPanel. I have chosen to let the drawing surface object do most of the work of the game: It

142
listens for events from the three buttons and responds by taking the appropriate actions. The main
panel is defined by HighLowGUI itself, which is another subclass of JPanel. The constructor of
the HighLowGUI class creates all the other components, sets up event handling, and lays out the
components:

public HighLowGUI() { // The constructor.

setBackground( new Color(130,50,40) );

setLayout( new BorderLayout(3,3) ); // BorderLayout with 3−pixel gaps.

CardPanel board = new CardPanel(); // Where the cards are drawn.

add(board, BorderLayout.CENTER);

JPanel buttonPanel = new JPanel(); // The subpanel that holds the buttons.
buttonPanel.setBackground( new Color(220,200,180) );
add(buttonPanel, BorderLayout.SOUTH);

JButton higher = new JButton( "Higher" );

higher.addActionListener(board); // The CardPanel listens for events.
buttonPanel.add(higher);

JButton lower = new JButton( "Lower" );

lower.addActionListener(board);
buttonPanel.add(lower);

JButton newGame = new JButton( "New Game" );

newGame.addActionListener(board);
buttonPanel.add(newGame);

setBorder(BorderFactory.createLineBorder( new Color(130,50,40), 3) );

} // end constructor

The programming of the drawing surface class, CardPanel, is a nice example of thinking in
terms of a state machine. (See Subectionă6.5.4.) It is important to think in terms of the states
that the game can be in, how the state can change, and how the response to events can depend on
the state. The approach that produced the original, text-oriented game in Subectionă5.4.3 is not
appropriate here. Trying to think about the game in terms of a process that goes step-by-step from
beginning to end is more likely to confuse you than to help you.
The state of the game includes the cards and the message. The cards are stored in an object
of type Hand. The message is a String. These values are stored in instance variables. There
is also another, less obvious aspect of the state: Sometimes a game is in progress, and the user is
supposed to make a prediction about the next card. Sometimes we are between games, and the user
is supposed to click the “New Game” button. It’s a good idea to keep track of this basic difference
in state. The CardPanel class uses a boolean instance variable named gameInProgress for this
purpose.
The state of the game can change whenever the user clicks on a button. CardPanel im-
plements the ActionListener interface and defines an actionPerformed() method to re-
spond to the user’s clicks. This method simply calls one of three other methods, doHigher(),
doLower(), or newGame(), depending on which button was pressed. It’s in these three event-
handling methods that the action of the game takes place.
We don’t want to let the user start a new game if a game is currently in progress. That would be

143
cheating. So, the response in the newGame() method is different depending on whether the state
variable gameInProgress is true or false. If a game is in progress, the message instance variable
should be set to show an error message. If a game is not in progress, then all the state variables
should be set to appropriate values for the beginning of a new game. In any case, the board must
be repainted so that the user can see that the state has changed. The complete newGame() method
is as follows:
/**
* Called by the CardPanel constructor, and called by actionPerformed() if
* the user clicks the "New Game" button. Start a new game.
*/
void doNewGame() {
if (gameInProgress) {
// If the current game is not over, it is an error to try
// to start a new game.
message = "You still have to finish this game!";
repaint();
return;
}
deck = new Deck(); // Create the deck and hand to use for this game.
hand = new Hand();
deck.shuffle();
hand.addCard( deck.dealCard() ); // Deal the first card into the hand.
message = "Is the next card higher or lower?";
gameInProgress = true;
repaint();
} // end doNewGame()
The doHigher() and doLower() methods are almost identical to each other (and could
probably have been combined into one method with a parameter, if I were more clever). Let’s
look at the doHigher() method. This is called when the user clicks the “Higher” button. This
only makes sense if a game is in progress, so the first thing doHigher() should do is check the
value of the state variable gameInProgress. If the value is false, then doHigher() should
just set up an error message. If a game is in progress, a new card should be added to the hand and
the user’s prediction should be tested. The user might win or lose at this time. If so, the value of
the state variable gameInProgress must be set to false because the game is over. In any case,
the board is repainted to show the new state. Here is the doHigher() method:
/**
* Called by actionPerformmed() when user clicks "Higher" button.
* Check the user’s prediction. Game ends if user guessed
* wrong or if the user has made three correct predictions.
*/
void doHigher() {
if (gameInProgress == false) {
// If the game has ended, it was an error to click "Higher",
// So set up an error message and abort processing.
message = "Click \"New Game\" to start a new game!";
repaint();
return;
}
hand.addCard( deck.dealCard() ); // Deal a card to the hand.
int cardCt = hand.getCardCount();
Card thisCard = hand.getCard( cardCt − 1 ); // Card just dealt.
Card prevCard = hand.getCard( cardCt − 2 ); // The previous card.

144
 if ( thisCard.getValue() < prevCard.getValue() ) {
gameInProgress = false;
message = "Too bad! You lose.";
}
else if ( thisCard.getValue() == prevCard.getValue() ) {
gameInProgress = false;
message = "Too bad! You lose on ties.";
}
else if ( cardCt == 4) {
gameInProgress = false;
message = "You win! You made three correct guesses.";
}
else {
message = "Got it right! Try for " + cardCt + ".";
}
repaint();
} // end doHigher()

The paintComponent() method of the CardPanel class uses the values in the state vari-
ables to decide what to show. It displays the string stored in the message variable. It draws each of
the cards in the hand. There is one little tricky bit: If a game is in progress, it draws an extra face-
down card, which is not in the hand, to represent the next card in the deck. Drawing the cards re-
quires some care and computation. I wrote a method, “void drawCard(Graphics g, Card card, int x, in
which draws a card with its upper left corner at the point (x,y). The paintComponent()
method decides where to draw each card and calls this method to do the drawing. You can check
out all the details in the source code, HighLowGUI.java.
One further note on the programming of this example: The source code defines HighLowGUI
as a subclass of JPanel. The class contains a main() method so that it can be run as a stand-alone
application; the main() method simply opens a window that uses a panel of type JPanel as its
content pane. In addition, I decided to write an applet version of the program as a static nested
class named Applet inside the HighLowGUI class. Since this is a nested class, its full name is
HighLowGUI.Applet and the class file produced when the code is compiled is HighLowGUI\$Applet.class.
This class is used for the applet version of the program shown above. The <applet> tag lists the
class file for the applet as code=’’HighLowGUI\$Applet.class’’. This is admittedly an un-
usual way to organize the program, and it is probably more natural to have the panel, applet, and
stand-alone program defined in separate classes. However, writing the program in this way does
show the flexibility of JAVA classes.
Simple dialogs are created by static methods in the class JOptionPane. This class includes
many methods for making dialog boxes, but they are all variations on the three basic types shown
here: a “message” dialog, a “confirm” dialog, and an “input” dialog. (The variations allow you to
provide a title for the dialog box, to specify the icon that appears in the dialog, and to add other
components to the dialog box. I will only cover the most basic forms here.)
A message dialog simply displays a message string to the user. The user (hopefully) reads the
message and dismisses the dialog by clicking the “OK” button. A message dialog can be shown
by calling the static method:
void JOptionPane.showMessageDialog(Component parentComp, String message)

The message can be more than one line long. Lines in the message should be separated by
newline characters, \n. New lines will not be inserted automatically, even if the message is very
long.

145
 An input dialog displays a question or request and lets the user type in a string as a response.
You can show an input dialog by calling:
String JOptionPane.showInputDialog(Component parentComp, String question)
Again, the question can include newline characters. The dialog box will contain an input box,
an “OK” button, and a “Cancel” button. If the user clicks “Cancel”, or closes the dialog box in
some other way, then the return value of the method is null. If the user clicks “OK”, then the
return value is the string that was entered by the user. Note that the return value can be an empty
string (which is not the same as a null value), if the user clicks “OK” without typing anything in
the input box. If you want to use an input dialog to get a numerical value from the user, you will
have to convert the return value into a number.
Finally, a confirm dialog presents a question and three response buttons: “Yes”, “No”, and
“Cancel”. A confirm dialog can be shown by calling:
int JOptionPane.showConfirmDialog(Component parentComp, String question)
The return value tells you the user’s response. It is one of the following constants:
• JOptionPane.YES_OPTION–the user clicked the “Yes” button
• JOptionPane.NO_OPTION–the user clicked the “No” button
• JOptionPane.CANCEL_OPTION–the user clicked the “Cancel” button
• JOptionPane.CLOSE_OPTION–the dialog was closed in some other way.
By the way, it is possible to omit the Cancel button from a confirm dialog by calling one of the
other methods in the JOptionPane class. Just call:
title, JOptionPane.YES_NO_OPTION )
The final parameter is a constant which specifies that only a “Yes” button and a “No” button
should be used. The third parameter is a string that will be displayed as the title of the dialog box
window.
If you would like to see how dialogs are created and used in the sample applet, you can find
the source code in the file SimpleDialogDemo.java.

6.8 Images and Resources

W E HAVE SEEN HOW TO USE THE G RAPHICS class to draw on a GUI component that is visible
on the computer’s screen. Often, however, it is useful to be able to create a drawing off-screen , in
the computer’s memory. It is also important to be able to work with images that are stored in files.
To a computer, an image is just a set of numbers. The numbers specify the color of each pixel
in the image. The numbers that represent the image on the computer’s screen are stored in a part
of memory called a frame buffer. Many times each second, the computer’s video card reads the
data in the frame buffer and colors each pixel on the screen according to that data. Whenever
the computer needs to make some change to the screen, it writes some new numbers to the frame
buffer, and the change appears on the screen a fraction of a second later, the next time the screen
is redrawn by the video card.
Since it’s just a set of numbers, the data for an image doesn’t have to be stored in a frame
buffer. It can be stored elsewhere in the computer’s memory. It can be stored in a file on the
computer’s hard disk. Just like any other data file, an image file can be downloaded over the
Internet. Java includes standard classes and methods that can be used to copy image data from one
part of memory to another and to get data from an image file and use it to display the image on the
screen.

146
Images

The class java.awt.Image represents an image stored in the computer’s memory. There are two
fundamentally different types of Image. One kind represents an image read from a source outside
the program, such as from a file on the computer’s hard disk or over a network connection. The
second type is an image created by the program. I refer to this second type as an off-screen canvas.
An off-screen canvas is region of the computer’s memory that can be used as a drawing surface.
It is possible to draw to an offscreen image using the same Graphics class that is used for drawing
on the screen.
An Image of either type can be copied onto the screen (or onto an off-screen canvas) using
methods that are defined in the Graphics class. This is most commonly done in the paintCom-
ponent() method of a JComponent. Suppose that g is the Graphics object that is provided as a
parameter to the paintComponent() method, and that img is of type Image. Then the statement
“g.drawImage(img, x, y, this);” will draw the image img in a rectangular area in the
component. The integer-valued parameters x and y give the position of the upper-left corner of the
rectangle in which the image is displayed, and the rectangle is just large enough to hold the image.
The fourth parameter, this, is the special variable that refers to the JComponent itself. This param-
eter is there for technical reasons having to do with the funny way Java treats image files. For most
applications, you don’t need to understand this, but here is how it works: g.drawImage() does not
actually draw the image in all cases. It is possible that the complete image is not available when
this method is called; this can happen, for example, if the image has to be read from a file. In that
case, g.drawImage() merely initiates the drawing of the image and returns immediately. Pieces
of the image are drawn later, asynchronously, as they become available. The question is, how do
they get drawn? That’s where the fourth parameter to the drawImage method comes in. The fourth
parameter is something called an ImageObserver. When a piece of the image becomes available
to be drawn, the system will inform the ImageObserver, and that piece of the image will appear on
the screen. Any JComponent object can act as an ImageObserver. The drawImage method returns
a boolean value to indicate whether the image has actually been drawn or not when the method
returns. When drawing an image that you have created in the computer’s memory, or one that you
are sure has already been completely loaded, you can set the ImageObserver parameter to null.
There are a few useful variations of the drawImage() method. For example, it is possible to
scale the image as it is drawn to a specified width and height. This is done with the command

g.drawImage(img, x, y, width, height, imageObserver);

The parameters width and height give the size of the rectangle in which the image is displayed.
Another version makes it possible to draw just part of the image. In the command:

g.drawImage(img, dest_x1, dest_y1, dest_x2, dest_y2,

source x1, source y1, source x2, source_y2, imageObserver);
_ _ _

the integers source_x1, source_y1, source_x2, and source_y2 specify the top-left and bottom-right
corners of a rectangular region in the source image. The integers dest_x1, dest_y1, dest_x2, and
dest_y2 specify the corners of a region in the destination graphics context. The specified rectangle
in the image is drawn, with scaling if necessary, to the specified rectangle in the graphics context.
For an example in which this is useful, consider a card game that needs to display 52 different
cards. Dealing with 52 image files can be cumbersome and inefficient, especially for downloading
over the Internet. So, all the cards might be put into a single image:

147
 (This image is from the Gnome desktop project, http://www.gnome.org, and is shown
here much smaller than its actual size.) Now, only one Image object is needed. Drawing one card
means drawing a rectangular region from the image. This technique is used in a variation of the
sample program HighLowGUI.java. In the original version, the cards are represented by textual
descriptions such as “King of Hearts.” In the new version, HighLowWithImages.java, the cards
are shown as images. Here is an applet version of the program:
In the program, the cards are drawn using the following method. The instance variable cardIm-
ages is a variable of type Image that represents the image that is shown above, containing 52 cards,
plus two Jokers and a face-down card. Each card is 79 by 123 pixels. These numbers are used,
together with the suit and value of the card, to compute the corners of the source rectangle for the
drawImage() command:

148
 /**
* Draws a card in a 79x123 pixel rectangle with its
* upper left corner at a specified point (x,y). Drawing the card
* requires the image file "cards.png".
* @param g The graphics context used for drawing the card.
* @param card The card that is to be drawn. If the value is null, then a
* face−down card is drawn.
* @param x the x−coord of the upper left corner of the card
* @param y the y−coord of the upper left corner of the card
*/
public void drawCard(Graphics g, Card card, int x, int y) {
int cx; // x−coord of upper left corner of the card inside cardsImage
int cy; // y−coord of upper left corner of the card inside cardsImage
if (card == null) {
cy = 4*123; // coords for a face−down card.
cx = 2*79;
}
else {
cx = (card.getValue()−1)*79;
switch (card.getSuit()) {
case Card.CLUBS:
cy = 0;
break;
case Card.DIAMONDS:
cy = 123;
break;
case Card.HEARTS:
cy = 2*123;
break;
default: // spades
cy = 3*123;
break;
}
}
g.drawImage(cardImages,x,y,x+79,y+123,cx,cy,cx+79,cy+123,this);
}

I will tell you later in this section how the image file, cards.png, can be loaded into the program.

Image File I/O

The class javax.imageio.ImageIO makes it easy to save images from a program into files and to
read images from files into a program. This would be useful in a program such as PaintWithOff-
ScreenCanvas, so that the users would be able to save their work and to open and edit existing
images. (See Exerciseă12.1.)
There are many ways that the data for an image could be stored in a file. Many standard formats
have been created for doing this. Java supports at least three standard image formats: PNG, JPEG,
and GIF. (Individual implementations of Java might support more.) The JPEG format is “lossy,”
which means that the picture that you get when you read a JPEG file is only an approximation
of the picture that was saved. Some information in the picture has been lost. Allowing some
information to be lost makes it possible to compress the image into a lot fewer bits than would
otherwise be necessary. Usually, the approximation is quite good. It works best for photographic
images and worst for simple line drawings. The PNG format, on the other hand is “lossless,”
meaning that the picture in the file is an exact duplicate of the picture that was saved. A PNG file

149
is compressed, but not in a way that loses information. The compression works best for images
made up mostly of large blocks of uniform color; it works worst for photographic images. GIF
is an older format that is limited to just 256 colors in an image; it has mostly been superseded by
PNG.
Suppose that image is a BufferedImage. The image can be saved to a file simply by calling
ImageIO.write( image, format, file ) where format is a String that specifies the image
format of the file and file is a File that specifies the file that is to be written. The format string
should ordinarily be either “PNG” or “JPEG”, although other formats might be supported.
ImageIO.write() is a static method in the ImageIO class. It returns a boolean value that is
false if the image format is not supported. That is, if the specified image format is not supported,
then the image is not saved, but no exception is thrown. This means that you should always check
the return value! For example:
boolean hasFormat = ImageIO.write(OSC,format,selectedFile);
if ( ! hasFormat )
throw new Exception(format + " format is not available.");
If the image format is recognized, it is still possible that that an IOExcption might be thrown
when the attempt is made to send the data to the file.
The ImageIO class also has a static read() method for reading an image from a file into
a program. The method ImageIO.read( inputFile ) takes a variable of type File as a
parameter and returns a BufferedImage. The return value is null if the file does not contain
an image that is stored in a supported format. Again, no exception is thrown in this case, so you
should always be careful to check the return value. It is also possible for an IOException to occur
when the attempt is made to read the file. There is another version of the read() method that
takes an InputStream instead of a file as its parameter, and a third version that takes a URL.
Earlier in this section, we encountered another method for reading an image from a URL,
the createImage() method from the Toolkit class. The difference is that ImageIO.read()
reads the image data completely and stores the result in a BufferedImage. On the other hand,
createImage() does not actually read the data; it really just stores the image location and
the data won’t be read until later, when the image is used. This has the advantage that the
createImage() method itself can complete very quickly. ImageIO.read(), on the other hand,
can take some time to execute.

150
 CHAPTER 7
A S OLITAIRE G AME - K LONDIKE
In this chapter will build a version of the Solitaire game. We’ll use the case study investigate the
object-oriented concepts of encapsulation, inheritance, and polymorphism. The game is inspired
by Timothy Budd’s version in his book A N I NTRODUCTION TO O BJECT-O RIENTED P ROGRAM -
MING .

7.1 Klondike Solitaire

The most popular solitare game is called klondike. It can be described as follows:
The layout of the game is shown in the figure below. A single standard pack of 52 cards is
used. (i.e. 4 suits (spades ♠, diamonds ♦, hearts ♥, clubs ♣) and 13 cards (13 ranks) in each suit.).
The tableau, or playing table, consists of 28 cards in 7 piles. The first pile has 1 card, the
second 2, the third 3, and so on up to 7. The top card of each pile is initially face up; all other
cards are face down.
The suit piles (sometimes called foundations) are built up from aces to kings in suits. They are
constructed above the tableau as the cards become available. The object of the game is to build all
52 cards into the suit piles.
The cards that are not part of the tableau are initially all in the deck. Cards in the deck are
face down, and are drawn one by one from the deck and placed, face up, on the discard pile. From
there, they can be moved onto either a tableau pile or a foundation. Cards are drawn from the deck
until the pile is empty; at this point, the game is over if no further moves can be made.
Cards can be placed on a tableau pile only on a card of next-higher rank and opposite color.
They can be placed on a foundation only if they are the same suit and next higher card or if the
foundation is empty and the card is an ace. Spaces in the tableau that arise during play can be
filled only by kings.
The topmost card of each tableau pile and the topmost card of the discard pile are always
available for play. The only time more than one card is moved is when an entire collection of
face-up cards from a tableau (called a build) is moved to another tableau pile. This can be done if
the bottommost card of the build can be legally played on the topmost card of the destination. Our
initial game will not support the transfer of a build. The topmost card of a tableau is always face

151
 Figure 7.1: Layout of the Solitaire Game

up. If a card is moved from a tableau, leaving a face-down card on the top, the latter card can be
turned face up.

7.2 Card Games

In this section and the next we will explore games that employ playing cards, and use them to
build our simplified game of Klondike Solitaire.
To start off we will program two classes, a Card class and a Deck class. These two classes will
be useful in almost all card games. Create and new project (CardGames is good name) and write
these classes in a package called cardGames.

The Card class

The aim is to build an ABSTRACTION of a playing card. Objects of type Card represent a single
playing card. The class has the following responsibilites:

Know its suit, rank and whether it is black or red

Create a card specified by rank and suit

Know if it is face down or up

Display itself (face up or down)

Flip itself (change from face down to face up and vice versa)

Your tasks is to design the Card class and program it. It is also necessary to test your class.

152
Using Images
In order to program the class, we need to use images of cards.
There are several ways to work with images. Heres a quick how-to describing one way...

(a) Copy the images folder into the project folder. It should be copied into the top level of the
CardGames folder.

(b) Using an image is a three step process:

* Declare a variable of type Image e.g. Image backImage;

* Read an image into this variable: (This must be done within a try/catch block and
assumes the images are stored in the images folder in the project.)
try{
backImage = ImageIO.read(new File("images/b1fv.gif"));

}
catch (IOException i){
System.err.println("Image load error");
}

* Draw the image (Off course, you draw method will be different since you have to worry
about whether the card is face up and face down and the image you draw depends on
the particular card.):
public void draw(Graphics g, int x, int y) {
g.drawImage(backImage,x,y,null); }

(c) The naming convention of the image files is straight forward: ’xnn.gif’ is the format were
’x’ is a letter of the suit (s=spades ♠, d=diamonds ♦, h=hearts ♥, c=clubs ♣) and ’nn’ is a
one or two digit number representing the card’s rank (1=ACE, 2-10=cards 2 to 10, 11=JACK,
12=Q UEEN, 13=K ING). e.g. c12 is the Queen of clubs; d1 is the Ace of Diamonds; h8=8
of hearts. There are two images of the back of a card (b1fv.gif and b2fv.gif).

The testing of the Card class can be done by setting up a test harness. This could simply be a
main method in the Card class like this one. You will off course make changes to this to do various
tests.:
public static void main(String[] args) {

class Panel extends JPanel { //a method local inner class

Card c;
Panel(){ c = new Card(1,13); }

public void PanelTest(){ //method to test Cards

repaint(); c.flip(); repaint();
}
public void paintComponent(Graphics g){
super.paintComponent(g);
c.draw(g,20,10);
}
} \\end of class Panel

JFrame frame = new JFrame();

frame.setSize(new Dimension(500,500));

153
 frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
Panel p = new Panel();
frame.setContentPane(p);
frame.show();
p.PanelTest();
}\\end of main method

The CardNames Interface

The CardNames class is an interface defining names.
public interface CardNames {
public static final int heart = 0;
public static final int diamond = 1;
public static final int club = 2;
public static final int spade = 3;
public static final int ace = 1;
public static final int jack = 11;
public static final int queen = 12;
public static final int king = 13;
public static final int red = 0;
public static final int black = 1;
}

Its a convenience class that allows us to use these names in a consistent manner. Thus, we can
use the name CardNames.ace throughout the program consistently (i. e. Different parts of the
program will mean the same thing when they say CardNames.ace).

The Deck class

This class is meant to represent a deck of 52 cards. (A Deck is composed of 52 Cards). Its
responsibilities are:

Create a deck of 52 cards

Know the cards in the deck

Shuffle a deck

Deal a card from the deck

Know how many cards are in the deck

Design, write and test the Deck class.

7.3 Implementation of Klondike

To program the game, we notice that we basically need to keep track of several piles of cards. The
piles have similar functionality, so inheritance is strongly suggested. What we do is write all the
common functionality in a base class called CardPile. We then specialise this class to create the
concrete classes for each pile.
A class diagram for this application is shown above:

154
 Figure 7.2: Class diagram for the Solitaire app

The CardPile class (the base class)

package solitaire;

import java.awt.Graphics;
import java.util.LinkedList;
import java.util.List;

public abstract class CardPile {

protected List pile;

protected int x;
protected int y;

/** * Make an Empty Pile */

public CardPile(int x, int y) {
pile = new LinkedList();
this.x = x;
this.y = y;
}

public boolean empty(){

return pile.isEmpty();
}

155
 public Card topCard() {
if (!empty())
return (Card)pile.get(pile.size()−1);
else
return null;
}

public Card pop() {

if (!empty())
return (Card)pile.remove(pile.size()−1);
else
return null;
}

public boolean includes(int tx, int ty) {

return x<=tx && tx <= x + Card.width
&& y <= ty && ty <= y + Card.height;
}

public void addCard(Card aCard){

pile.add(aCard);
}

public void draw (Graphics g){

if (empty()) {
g.drawRect(x,y,Card.width,Card.height);
}
else
topCard().draw(g,x,y);
}

public abstract boolean canTake(Card aCard);

public abstract void select ();

}

Notice that this class is abstract. It has three protected attributes (What does protected mean?).
The x and y are coordinates of this pile on some drawing surface and the pile attribute is Collection
of Cards. Most of the methods are self explanatory ;).
* The includes method is given a point (a coordinate) and returns true if this point is con-
tained within the space occupied by the cards in the pile. We intend to use this method to tell
us if the user has clicked on this particular pile of cards. The idea is to get the coordinates
of the point the user has clicked on and then ask each pile if this coordinate falls within the
space it occupies.

* The canTake abstract method should tell us whether a particular pile of cards can accept a
card. Different piles will have different criteria for accepting a Card. For example, suit piles
will accept a card if it is the same suit as all others in the pile and if its rank is one more that
its topCard. The table piles will accept a card if its suit is opposite in color and its rank is
one less than the pile’s topCard.

* The select abstract method is the action this pile takes if it can accept a Card. Usually, this
means adding it to its pile and making the new Card the topCard.

156
The Solitaire class
The Solitaire class is the one that runs. It creates and maintains the different piles of cards. Notice
that most of its attributes are static and visible to other classes in the package. Study it carefully
and make sure you understand it fully (FULLY!) before you continue.

package solitaire;

import javax.swing.*;
import java.awt.*;

public class Solitaire extends JPanel implements MouseListener {

static DeckPile deckPile;

static DiscardPile discardPile;
static TablePile tableau[];
static SuitPile suitPile[];
static CardPile allPiles[];

public Solitaire(){
setBackground(Color.green);
addMouseListener(this);
allPiles = new CardPile[13];
suitPile = new SuitPile[4];
tableau = new TablePile[7];

int deckPos = 600;

int suitPos = 15;
allPiles[0] = deckPile = new DeckPile(deckPos, 5);
allPiles[1] = discardPile =
new DiscardPile(deckPos − Card.width − 10, 5);
for (int i = 0; i < 4; i++)
allPiles[2+i] = suitPile[i] =
new SuitPile(suitPos + (Card.width + 10) * i, 5);
for (int i = 0; i < 7; i++)
allPiles[6+i] = tableau[i] =
new TablePile(suitPos + (Card.width + 10) * i,
Card.height + 20, i+1);
repaint();
}

public void paintComponent(Graphics g) {

super.paintComponent(g);
for (int i = 0; i < 13; i++)
allPiles[i].draw(g);
}

public static void main(String[] args) {

157
 JFrame frame = new JFrame();
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
frame.setVisible(true);
frame.setSize(800,600);
frame.setTitle("Solitaire");

Solitaire s = new Solitaire();

frame.add(s);
frame.validate();
s.repaint();
}

public void mouseClicked(MouseEvent e) {

int x = e.getX();
int y = e.getY();
for (int i = 0; i < 12; i++)
if (allPiles[i].includes(x, y)) {
allPiles[i].select();
repaint();
}
}

public void mousePressed(MouseEvent e) { }

public void mouseReleased(MouseEvent e) { }

public void mouseEntered(MouseEvent e) { }

public void mouseExited(MouseEvent e) { }

}

Completing the Implementation

Write the classes TablePile, SuitPile, DiscardPile, DeckPile. I suggest that you create all the classes
first and then work with them one at a time. They all extend the CardPile class. You must take
care to consider situations when the pile is empty. The following will guide you in writing these
classes:

* the DeckPile Class This class extends the CardPile class. It must create a full deck of cards
(stored in its super class’s pile attribute.) The cards should be shuffled after creation (use
Collections.shuffle(...) ). You never add cards to the DeckPile so its canTake method always
returns false. The select method removes a card from the deckPile and adds it to the
discardPile (In the Solitaire class).

* The DiscardPile Class This maintains a pile of cards that do not go into any of the other
piles. Override the addCard method to check first if the card is faceUp and flip it if its
not. Then add the card to the pile. You never add cards to the DiscardPile so its canTake
method always returns false. The select method requires careful thought. Remember that
this method runs when the user selects this pile. Now, what happens when the user clicks on
the topCard in the discardPile? We must check if any SuitPile (4 of them) or any TablePile
(7 of them) (all in the Solitaire class) can take the card. If any of these piles can take the
card we add the Card to that pile. If not, we leave it on the discardPile.

158
* The SuitPile Class The select method is empty (Cards are never removed from this pile).
The canTake method should return true if the Card is the same suit as all others in the pile
and if its rank is one more that its topCard.

* The TablePile Class Write the constructor to initialize the table pile. The constructor accepts
three parameters, the x and y coordinates of the pile, and an integer that tell it how many
cards it contains. (remember that the first tablePile contains 1 card, the second 2 Cards etc.).
It takes Cards from the deckPile. The table pile is displayed differently from the other piles
(the cards overlap). We thus need to override the includes the method and the draw method.
The canTake method is also different. The table piles will accept a card if its suit is opposite
in color and its rank is one less than the pile’s topCard. The select method is similar to the
one in DiscardPile. We must check if any SuitPile (4 of them) or any TablePile (7 of them)
(all in the Solitaire class) can take the card. If any of these piles can take the card we add
the Card to that pile otherwise we leave it in this tabePile.

159
 CHAPTER 8
G ENERIC P ROGRAMMING

Contents
7.1 Klondike Solitaire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.2 Card Games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
The CardNames Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
The Deck class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.3 Implementation of Klondike . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
The CardPile class (the base class) . . . . . . . . . . . . . . . . . . . . . . . . . 155
The Solitaire class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Completing the Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

A DATA STRUCTURE IS A COLLECTION OF DATA ITEMS, considered as a unit. For example,

a list is a data structure that consists simply of a sequence of items. Data structures play an
important part in programming. Various standard data structures have been developed including
lists, sets, and trees. Most programming libraries provide built-in data structures that may be used
with very little effort from the programmer. Java has the Collection Framework that provides
standard data structures for use by programmers.
Generic programming refers to writing code that will work for many types of data. The source
code presented there for working with dynamic arrays of integers works only for data of type int.
But the source code for dynamic arrays of double, String, JButton, or any other type would be
almost identical, except for the substitution of one type name for another. It seems silly to write
essentially the same code over and over. Java goes some distance towards solving this problem
by providing the ArrayList class. An ArrayList is essentially a dynamic array of values of
type Object. Since every class is a subclass of Object, objects of any type can be stored in an
ArrayList. Java goes even further by providing “parameterized types.” The ArrayList type
can be parameterized, as in “ArrayList<String>”, to limit the values that can be stored in the
list to objects of a specified type. Parameterized types extend Java’s basic philosophy of type-safe
programming to generic programming.

161
8.1 Generic Programming in Java
J AVA ’ S GENERIC PROGRAMMING FEATURES are represented by group of generic classes and
interfaces as a group are known as the Java Collection Framework. These classes represents
various data structure designed to hold Objects can be used with objects of any type. Unfortunately
the result is a category of errors that show up only at run time, rather than at compile time. If a
programmer assumes that all the items in a data structure are strings and tries to process those
items as strings, a run-time error will occur if other types of data have inadvertently been added to
the data structure. In JAVA, the error will most likely occur when the program retrieves an Object
from the data structure and tries to type-cast it to type String. If the object is not actually of type
String, the illegal type-cast will throw an error of type ClassCastException.
JAVA 5.0 introduced parameterized types, such as ArrayList<String>. This made it pos-
sible to create generic data structures that can be type-checked at compile time rather than at run
time. With these data structures, type-casting is not necessary, so ClassCastExceptions are
avoided. The compiler will detect any attempt to add an object of the wrong type to the data
structure; it will report a syntax error and will refuse to compile the program. In Java 5.0, all of
the classes and interfaces in the Collection Framework, and even some classes that are not part
of that framework, have been parameterized. In this chapter, I will use the parameterized types
almost exclusively, but you should remember that their use is not mandatory. It is still legal to use
a parameterized class as a non-parameterized type, such as a plain ArrayList.
With a Java parameterized class, there is only one compiled class file. For example, there
is only one compiled class file, ArrayList.class, for the parameterized class ArrayList. The
parameterized types ArrayList<String> and ArrayList<Integer> both use the some com-
piled class file, as does the plain ArrayList type. The type parameter—String or Integer—
just tells the compiler to limit the type of object that can be stored in the data structure. The type
parameter has no effect at run time and is not even known at run time. The type information
is said to be “erased” at run time. This type erasure introduces a certain amount of weirdness.
For example, you can’t test “if (list instanceof {ArrayList<String>)” because the
instanceof operator is evaluated at run time, and at run time only the plain ArrayList ex-
ists. Even worse, you can’t create an array that has base type ArrayList<String> using the
new operator, as in “new ArrayList<String>(N)”. This is because the new operator is eval-
uated at run time, and at run time there is no such thing as “ArrayList<String>”; only the
non-parameterized type ArrayList exists at run time.
Fortunately, most programmers don’t have to deal with such problems, since they turn up only
in fairly advanced programming. Most people who use the Java Collection Framework will
not encounter them, and they will get the benefits of type-safe generic programming with little
difficulty.

8.2 ArrayLists
I N THIS SECTION we discuss ArrayLists that are part of the Collection Framework.
Arrays in JAVA have two disadvantages: they have a fixed size and their type must be must be
specified when they are created.
The size of an array is fixed when it is created. In many cases, however, the number of data
items that are actually stored in the array varies with time. Consider the following examples: An
array that stores the lines of text in a word-processing program. An array that holds the list of
computers that are currently downloading a page from a Web site. An array that contains the
shapes that have been added to the screen by the user of a drawing program. Clearly, we need
some way to deal with cases where the number of data items in an array is not fixed.

162
 Specifying the type when arrays are created means that one can only put primitives or objects
of the specified into the array—for example, an array of int can only hold integers. One way to
work around this is to declare Object as the type of an array. In this case one can place anything
into the array because, in JAVA, every class is a subclass of the class named Object. This means
that every object can be assigned to a variable of type Object. Any object can be put into an array
of type Object[ ].
An ArrayList serves much the same pupose as arrays do. It allows you to store objects
of any type. The ArrayList class is in the package java.util, so if you want to use it in a
program, you should put the directive “import java.util.ArrayList;” at the beginning of
your source code file.
The ArrayList class always has a definite size, and it is illegal to refer to a position in the
ArrayList that lies outside its size. In this, an ArrayList is more like a regular array. However,
the size of an ArrayList can be increased at will. The ArrayList class defines many instance
methods. I’ll describe some of the most useful. Suppose that list is a variable of type ArrayList.
Then we have:

• list.size()–This method returns the current size of the ArrayList. The only valid
positions in the list are numbers in the range 0 to list.size()−1. Note that the size can
be zero. A call to the default constructor new ArrayList() creates an ArrayList of size
zero.

• list.add(obj)–Adds an object onto the end of the list, increasing the size by 1. The
parameter, obj, can refer to an object of any type, or it can be null.

• list.get(N)–returns the value stored at position N in the ArrayList. N must be an

integer in the range 0 to list.size()−1. If N is outside this range, an error of type
IndexOutOfBoundsException occurs. Calling this method is similar to referring to
A[N] for an array, A, except you can’t use list.get(N) on the left side of an assignment
statement.

• list.set(N, obj)–Assigns the object, obj, to position N in the ArrayList, replacing

the item previously stored at position N. The integer N must be in the range from 0 to
list.size()−1. A call to this method is equivalent to the command A[N] = obj for an
array A.

• list.remove(obj)–If the specified object occurs somewhere in the ArrayList, it is

removed from the list. Any items in the list that come after the removed item are moved
down one position. The size of the ArrayList decreases by 1. If obj occurs more than
once in the list, only the first copy is removed.

• list.remove(N)–For an integer, N, this removes the N-th item in the ArrayList. N

must be in the range 0 to list.size()−1. Any items in the list that come after the removed
item are moved down one position. The size of the ArrayList decreases by 1.

• list.indexOf(obj)–A method that searches for the object, obj, in the ArrayList. If
the object is found in the list, then the position number where it is found is returned. If the
object is not found, then −1 is returned.

For example, suppose that players in a game are represented by objects of type Player.
The players currently in the game could be stored in an ArrayList named players. This
variable would be declared as ArrayList players; and initialized to refer to a new, empty
ArrayList object with players = new ArrayList();. If newPlayer is a variable that

163
refers to a Player object, the new player would be added to the ArrayList and to the game by
saying players.add(newPlayer); and if player number i leaves the game, it is only necessary
to say players.remove(i);. Or, if player is a variable that refers to the Player that is to be
removed, you could say players.remove(player);.
All this works very nicely. The only slight difficulty arises when you use the method players.get(i)
to get the value stored at position i in the ArrayList. The return type of this method is Object.
In this case the object that is returned by the method is actually of type Player. In order to do
anything useful with the returned value, it’s usually necessary to type-cast it to type Player by
saying:
Player plr = (Player)players.get(i);.
For example, if the Player class includes an instance method makeMove() that is called to
allow a player to make a move in the game, then the code for letting every player make a move is
for (int i = 0; i < players.size(); i++) {
Player plr = (Player)players.get(i);
plr.makeMove();
}
The two lines inside the for loop can be combined to a single line:
((Player)players.get(i)).makeMove();.
This gets an item from the list, type-casts it, and then calls the makeMove() method on the result-
ing Player. The parentheses around “(Player)players.get(i)” are required because of Java’s
precedence rules. The parentheses force the type-cast to be performed before the makeMove()
method is called.
for−each loops work for ArrayLists just as they do for arrays. But note that since the
items in an ArrayList are only known to be Objects, the type of the loop control variable must
be Object. For example, the for loop used above to let each Player make a move could be
written as the for−each loop
for ( Object plrObj : players ) {
Player plr = (Player)plrObj;
plr.makeMove();
}
In the body of the loop, the value of the loop control variable, plrObj, is one of the objects
from the list, players. This object must be type-cast to type Player before it can be used.

8.3 Parameterized Types

T HE MAIN DIFFERENCE BETWEEN true generic programming and the ArrayList examples in
the previous subsection is the use of the type Object as the basic type for objects that are stored
in a list. This has at least two unfortunate consequences: First, it makes it necessary to use type-
casting in almost every case when an element is retrieved from that list. Second, since any type
of object can legally be added to the list, there is no way for the compiler to detect an attempt to
add the wrong type of object to the list; the error will be detected only at run time when the object
is retrieved from the list and the attempt to type-cast the object fails. Compare this to arrays. An
array of type BaseType[ ] can only hold objects of type BaseType. An attempt to store an
object of the wrong type in the array will be detected by the compiler, and there is no need to
type-cast items that are retrieved from the array back to type BaseType.
To address this problem, Java 5.0 introduced parameterized types. ArrayList is an example:
Instead of using the plain “ArrayList” type, it is possible to use ArrayList<BaseType>,
where BaseType is any object type, that is, the name of a class or of an interface. (BaseType
cannot be one of the primitive types.)

164
 ArrayList<BaseType> can be used to create lists that can hold only objects of type BaseType.
For example, ArrayList<ColoredRect> rects;. declares a variable named rects of type
ArrayList<ColoredRect>, and
rects = new ArrayList<ColoredRect>();
sets rects to refer to a newly created list that can only hold objects belonging to the class
ColoredRect (or to a subclass). The funny-looking “ArrayList<ColoredRect>” is being
used here in the same way as an ordinary class name–don’t let the
“<ColoredRect>” confuse you; it’s just part of the name of the type. When a statements such
as rects.add(x); occurs in the program, the compiler can check whether x is in fact of type
ColoredRect. If not, the compiler will report a syntax error. When an object is retrieved from
the list, the compiler knows that the object must be of type ColoredRect, so no type-cast is nec-
essary. You can say simply:
ColoredRect rect = rects.get(i).
You can even refer directly to an instance variable in the object, such as
rects.get(i).color. This makes using ArrayList<ColoredRect> very similar to using
ColoredRect[ ] with the added advantage that the list can grow to any size. Note that if a
for-each loop is used to process the items in rects, the type of the loop control variable can be
ColoredRect, and no type-cast is necessary. For example, when using ArrayList<ColoredRect>
as the type for the list rects, the code for drawing all the rectangles in the list could be rewritten
as:

for ( ColoredRect rect : rects ) {

g.setColor( rect.color );
g.fillRect( rect.x, rect.y, rect.width, rect.height);
g.setColor( Color.BLACK );
g.drawRect( rect.x, rect.y, rect.width − 1, rect.height − 1);
}

You can use ArrayList<ColoredRect> anyplace where you could use a normal type: to
declare variables, as the type of a formal parameter in a method, or as the return type of a method.
ArrayList<ColoredRect> is not considered to be a separate class from ArrayList. An object
of type ArrayList<ColoredRect> actually belongs to the class ArrayList, but the compiler
restricts the type of objects that can be added to the list.)
The only drawback to using parameterized types is that the base type cannot be a primitive
type. For example, there is no such thing as “ArrayList<int>”. However, this is not such a big
drawback as it might seem at first, because of the “wrapper types” and “autoboxing”. A wrapper
type such as Double or Integer can be used as a base type for a parameterized type. An object of
type ArrayList<Double> can hold objects of type Double. Since each object of type Double
holds a value of type double, it’s almost like having a list of doubles. If numlist is declared to be
of type ArrayList<Double> and if x is of type double, then the value of x can be added to the
list by saying: numlist.add( new Double(x) );.
Furthermore, because of autoboxing, the compiler will automatically do double-to-Double
and Double-to-double type conversions when necessary. This means that the compiler will treat
“numlist.add(x)” as begin equivalent to the statement
“numlist.add( new Double(x))”. So, behind the scenes, “numlist.add(x)” is actually
adding an object to the list, but it looks a lot as if you are working with a list of doubles.
The ArrayList class is just one of several standard classes that are used for generic pro-
gramming in Java. We will spend the next few sections looking at these classes and how they
are used, and we’ll see that there are also generic methods and generic interfaces. All the classes
and interfaces discussed in these sections are defined in the package java.util, and you will
need an import statement at the beginning of your program to get access to them. (Before you

165
start putting “importăjava.util.*” at the beginning of every program, you should know that
some things in java.util have names that are the same as things in other packages. For example,
both java.util.List and java.awt.List exist, so it is often better to import the individual
classes that you need.)

8.4 The Java Collection Framework

J AVA ’ S GENERIC DATA STRUCTURES can be divided into two categories: collections and maps.
A collection is more or less what it sound like: a collection of objects. An ArrayList is an ex-
ample of a collection. A map associates objects in one set with objects in another set in the
way that a dictionary associates definitions with words or a phone book associates phone num-
bers with names. In Java, collections and maps are represented by the parameterized interfaces
Collection<T> and Map<T,S>. Here, “T” and “S” stand for any type except for the primitive
types.
We will discuss only collections in this course.
There are two types of collections: lists and sets. A list is a collection in which the objects are
arranged in a linear sequence. A list has a first item, a second item, and so on. For any item in the
list, except the last, there is an item that directly follows it. The defining property of a set is that
no object can occur more than once in a set; the elements of a set are not necessarily thought of
as being in any particular order. The ideas of lists and sets are represented as parameterized inter-
faces List<T> and Set<T>. These are sub−interfaces of \code{Collection<T>.
That is, any object that implements the interface List<T> or Set<T> automatically implements
Collection<T> as well. The interface Collection<T> specifies general operations that can
be applied to any collection at all. List<T> and Set<T> add additional operations that are ap-
propriate for lists and sets respectively.
Of course, any actual object that is a collection, list, or set must belong to a concrete class that
implements the corresponding interface. For example, the class ArrayList<T> implements the
interface List<T> and therefore also implements
Collection<T>. This means that all the methods that are defined in the list and collection
interfaces can be used with, for example, an ArrayList<String> object. We will look at var-
ious classes that implement the list and set interfaces in the next section. But before we do that,
we’ll look briefly at some of the general operations that are available for all collections.
The interface Collection<T> specifies methods for performing some basic operations on
any collection of objects. Since “collection” is a very general concept, operations that can be
applied to all collections are also very general. They are generic operations in the sense that they
can be applied to various types of collections containing various types of objects. Suppose that
coll is an object that implements the interface Collection<T> (for some specific non-primitive
type T). Then the following operations, which are specified in the interface Collection<T>, are
defined for coll:

• coll.size()–returns an int that gives the number of objects in the collection.

• coll.isEmpty()–returns a boolean value which is true if the size of the collection is 0.

• coll.clear()–removes all objects from the collection.

• coll.add(tobject)–adds tobject to the collection. The parameter must be of type T;

if not, a syntax error occurs at compile time. This method returns a boolean value which
tells you whether the operation actually modified the collection. For example, adding an
object to a Set has no effect if that object was already in the set.

166
 • coll.contains(object)–returns a boolean value that is true if object is in the collec-
tion. Note that object is not required to be of type T, since it makes sense to check whether
object is in the collection, no matter what type object has. (For testing equality, null is con-
sidered to be equal to itself. The criterion for testing non-null objects for equality can differ
from one kind of collection to another.)

• coll.remove(object)–removes object from the collection, if it occurs in the collec-

tion, and returns a boolean value that tells you whether the object was found. Again, object
is not required to be of type T.

• coll.containsAll(coll2)–returns a boolean value that is true if every object in coll2

is also in the coll. The parameter can be any collection.

• coll.addAll(coll2)–adds all the objects in coll2 to coll. The parameter, coll2,

can be any collection of type Collection<T>. However, it can also be more general. For
example, if T is a class and S is a sub-class of T, then coll2 can be of type Collection<S>.
This makes sense because any object of type S is automatically of type T and so can legally
be added to coll.

• coll.removeAll(coll2)–removes every object from coll that also occurs in the col-
lection coll2. coll2 can be any collection.

• coll.retainAll(coll2)–removes every object from coll that does not occur in the
collection coll2. It “retains” only the objects that do occur in coll2. coll2 can be any
collection.

• coll.toArray()–returns an array of type Object[ ] that contains all the items in the
collection. The return value can be type-cast to another array type, if appropriate. Note that
the return type is Object[ ], not T[ ]! However, you can type-cast the return value to a
more specific type. For example, if you know that all the items in coll are of type String,
then String[])coll.toArray() gives you an array of Strings containing all the strings
in the collection.

Since these methods are part of the Collection<T> interface, they must be defined for every
object that implements that interface. There is a problem with this, however. For example, the size
of some kinds of collection cannot be changed after they are created. Methods that add or remove
objects don’t make sense for these collections. While it is still legal to call the methods, an ex-
ception will be thrown when the call is evaluated at run time. The type of the exception thrown is
UnsupportedOperationException. Furthermore, since Collection<T> is only an inter-
face, not a concrete class, the actual implementation of the method is left to the classes that im-
plement the interface. This means that the semantics of the methods, as described above, are not
guaranteed to be valid for all collection objects; they are valid, however, for classes in the Java
Collection Framework.
There is also the question of efficiency. Even when an operation is defined for several types of
collections, it might not be equally efficient in all cases. Even a method as simple as size() can
vary greatly in efficiency. For some collections, computing the size() might involve counting
the items in the collection. The number of steps in this process is equal to the number of items.
Other collections might have instance variables to keep track of the size, so evaluating size()
just means returning the value of a variable. In this case, the computation takes only one step, no
matter how many items there are. When working with collections, it’s good to have some idea of
how efficient operations are and to choose a collection for which the operations that you need can
be implemented most efficiently. We’ll see specific examples of this in the next two sections.

167
8.5 Iterators and for-each Loops
T HE INTERFACE Collection<T> defines a few basic generic algorithms, but suppose you want
to write your own generic algorithms. Suppose, for example, you want to do something as simple
as printing out every item in a collection. To do this in a generic way, you need some way of
going through an arbitrary collection, accessing each item in turn. We have seen how to do this
for specific data structures: For an array, you can use a for loop to iterate through all the array
indices. For a linked list, you can use a while loop in which you advance a pointer along the list.
Collections can be represented in any of these forms and many others besides. With such a
variety of traversal mechanisms, how can we even hope to come up with a single generic method
that will work for collections that are stored in wildly different forms? This problem is solved
by iterators. An iterator is an object that can be used to traverse a collection. Different types of
collections have iterators that are implemented in different ways, but all iterators are used in the
same way. An algorithm that uses an iterator to traverse a collection is generic, because the same
technique can be applied to any type of collection. Iterators can seem rather strange to someone
who is encountering generic programming for the first time, but you should understand that they
solve a difficult problem in an elegant way.
The interface Collection<T> defines a method that can be used to obtain an iterator for any
collection. If coll is a collection, then coll.iterator() returns an iterator that can be used to
traverse the collection. You should think of the iterator as a kind of generalized pointer that starts
at the beginning of the collection and can move along the collection from one item to the next.
Iterators are defined by a parameterized interface named Iterator<T>. If coll implements the
interface Collection<T> for some specific type T, then coll.iterator() returns an iterator
of type Iterator<T> , with the same type T as its type parameter. The interface Iterator<T>
defines just three methods. If iter refers to an object that implements Iterator<T>, then we
have:
• iter.next()–returns the next item, and advances the iterator. The return value is of type
T. This method lets you look at one of the items in the collection. Note that there is no way
to look at an item without advancing the iterator past that item. If this method is called when
no items remain, it will throw a NoSuchElementException.
• iter.hasNext()–returns a boolean value telling you whether there are more items to be
processed. In general, you should test this before calling iter.next().
• iter.remove()–if you call this after calling iter.next(), it will remove the item that
you just saw from the collection. Note that this method has no parameter . It removes the
item that was most recently returned by iter.next(). This might produce an UnsupportedOperationExce
if the collection does not support removal of items.
Using iterators, we can write code for printing all the items in any collection. Suppose,
for example, that coll is of type Collection<String>. In that case, the value returned by
coll.iterator() is of type Iterator<String>, and we can say:
Iterator<String> iter; // Declare the iterater variable.
iter = coll.iterator(); // Get an iterator for the collection.
while ( iter.hasNext() ) {
String item = iter.next(); // Get the next item.
System.out.println(item);
}
The same general form will work for other types of processing. For example, the following
code will remove all null values from any collection of type
Collection<JButton> (as long as that collection supports removal of values):

168
 Iterator<JButton> iter = coll.iterator():
while ( iter.hasNext() ) {
JButton item = iter.next();
if (item == null)
iter.remove();
}
(Note, by the way, that when Collection<T>, Iterator<T>, or any other parameterized
type is used in actual code, they are always used with actual types such as String or JButton in
place of the “formal type parameter” T. An iterator of type Iterator<String> is used to iterate
through a collection of Strings; an iterator of type Iterator<JButton> is used to iterate through
a collection of JButtons; and so on.)
An iterator is often used to apply the same operation to all the elements in a collection. In
many cases, it’s possible to avoid the use of iterators for this purpose by using a for−each loop.
A for−each loop can also be used to iterate through any collection. For a collection coll of
type Collection<T>, a for−each loop takes the form:
for ( T x : coll ) { // "for each object x, of type T, in coll"
// process x
}
Here, x is the loop control variable. Each object in coll will be assigned to x in turn, and the body
of the loop will be executed for each object. Since objects in coll are of type T, x is declared to
be of type T. For example, if namelist is of type Collection<String>, we can print out all
the names in the collection with:
for ( String name : namelist ) {
System.out.println( name );
}
This for-each loop could, of course, be written as a while loop using an iterator, but the for-each
loop is much easier to follow.

8.6 Equality and Comparison

T HERE ARE SEVERAL METHODS in the collection interface that test objects for equality. For ex-
ample, the methods coll.contains(object) and coll.remove(object) look for an item
in the collection that is equal to object. However, equality is not such a simple matter. The obvi-
ous technique for testing equality–using the == operator–does not usually give a reasonable answer
when applied to objects. The == operator tests whether two objects are identical in the sense that
they share the same location in memory. Usually, however, we want to consider two objects to
be equal if they represent the same value, which is a very different thing. Two values of type
String should be considered equal if they contain the same sequence of characters. The question
of whether those characters are stored in the same location in memory is irrelevant. Two values of
type Date should be considered equal if they represent the same time.
The Object class defines the boolean-valued method equals(Object) for testing whether
one object is equal to another. This method is used by many, but not by all, collection classes for
deciding whether two objects are to be considered the same. In the Object class, obj1.equals(obj2)
is defined to be the same as obj1 == obj2. However, for most sub-classes of Object, this def-
inition is not reasonable, and it should be overridden. The String class, for example, overrides
equals() so that for a String str, str.equals(obj) if obj is also a String and obj
contains the same sequence of characters as str.
If you write your own class, you might want to define an equals() method in that class to
get the correct behavior when objects are tested for equality. For example, a Card class that

169
will work correctly when used in collections could be defined as shown below. Without the
equals() method in this class, methods such as contains() and remove() in the interface
Collection<Card> will not work as expected.

public class Card { // Class to represent playing cards.

int suit; // Number from 0 to 3 that codes for the suit −−

// spades, diamonds, clubs or hearts.
int value; // Number from 1 to 13 that represents the value.

public boolean equals(Object obj) {

try {
Card other = (Card)obj; // Type−cast obj to a Card.
if (suit == other.suit && value == other.value) {
// The other card has the same suit and value as
// this card, so they should be considered equal.
return true;
}
else
return false;
}
catch (Exception e) {
// This will catch the NullPointerException that occurs if obj
// is null and the ClassCastException that occurs if obj is
// not of type Card. In these cases, obj is not equal to
// this Card, so return false.
return false;
}
}

.
. // other methods and constructors
.
}
A similar concern arises when items in a collection are sorted. Sorting refers to arranging a
sequence of items in ascending order, according to some criterion. The problem is that there is no
natural notion of ascending order for arbitrary objects. Before objects can be sorted, some method
must be defined for comparing them. Objects that are meant to be compared should implement the
interface java.lang.Comparable. In fact, Comparable is defined as a parameterized interface,
Comparable<T>, which represents the ability to be compared to an object of type T. The interface
Comparable<T> defines one method: public int compareTo( T obj ).
The value returned by obj1.compareTo(obj2) should be negative if and only if obj1

170
comes before obj2, when the objects are arranged in ascending order. It should be positive if
and only if obj1 comes after obj2. A return value of zero means that the objects are considered
to be the same for the purposes of this comparison. This does not necessarily mean that the objects
are equal in the sense that obj1.equals(obj2) is true. For example, if the objects are of type
Address, representing mailing addresses, it might be useful to sort the objects by zip code. Two
Addresses are considered the same for the purposes of the sort if they have the same zip code–but
clearly that would not mean that they are the same address.
The String class implements the interface Comparable<String> and define compareTo
in a reasonable way (and in this case, the return value of compareTo is zero if and only if the two
strings that are being compared are equal). If you define your own class and want to be able to
sort objects belonging to that class, you should do the same. For example:

/**
* Represents a full name consisting of a first name and a last name.
*/
public class FullName implements Comparable<FullName> {

private String firstName, lastName; // Non−null first and last names.

public FullName(String first, String last) { // Constructor.

if (first == null || last == null)
throw new IllegalArgumentException("Names must be non−null.");
firstName = first;
lastName = last;
}

public boolean equals(Object obj) {

try {
FullName other = (FullName)obj; // Type−cast obj to type FullName
return firstName.equals(other.firstName)
&& lastName.equals(other.lastName);
}
catch (Exception e) {
return false; // if obj is null or is not of type FirstName
}
}

public int compareTo( FullName other ) {

if ( lastName.compareTo(other.lastName) < 0 ) {
// If lastName comes before the last name of
// the other object, then this FullName comes
// before the other FullName. Return a negative
// value to indicate this.
return −1;
}
if ( lastName.compareTo(other.lastName) > 0 ) {
// If lastName comes after the last name of
// the other object, then this FullName comes
// after the other FullName. Return a positive
// value to indicate this.
return 1;
}
else {
// Last names are the same, so base the comparison on
// the first names, using compareTo from class String.

171
 return firstName.compareTo(other.firstName);
}
}

.
. // other methods
.
}

(Its odd to declare the class as “classFullName implements Comparable<FullName>”,

with “FullName” repeated as a type parameter in the name of the interface. However, it does make
sense. It means that we are going to compare objects that belong to the class FullName to other
objects of the same type. Even though this is the only reasonable thing to do, that fact is not
obvious to the Java compiler – and the type parameter in Comparable<FullName> is there for
the compiler.)
There is another way to allow for comparison of objects in Java, and that is to provide a
separate object that is capable of making the comparison. The object must implement the interface
Comparator<T>, where T is the type of the objects that are to be compared. The interface
Comparator<T> defines the method: public int compare( T obj1, T obj2 ).
This method compares two objects of type T and returns a value that is negative, or positive, or
zero, depending on whether obj1 comes before obj2, or comes after obj2, or is considered to be
the same as obj2 for the purposes of this comparison. Comparators are useful for comparing ob-
jects that do not implement the Comparable interface and for defining several different orderings
on the same collection of objects.
In the next two sections, we’ll see how Comparable and Comparator are used in the context of
collections and maps.

8.7 Generics and Wrapper Classes

A S NOTED ABOVE , J AVA ’ S GENERIC PROGRAMMING does not apply to the primitive types,
since generic data structures can only hold objects, while values of primitive type are not objects.
However, the “wrapper classes” make it possible to get around this restriction to a great extent.
Recall that each primitive type has an associated wrapper class: class Integer for type int,
class Boolean for type boolean, class Character for type char, and so on.
An object of type Integer contains a value of type int. The object serves as a “wrapper” for
the primitive type value, which allows it to be used in contexts where objects are required, such
as in generic data structures. For example, a list of Integers can be stored in a variable of type
ArrayList<Integer>, and interfaces such as Collection<Integer> and Set<Integer>
are defined. Furthermore, class Integer defines equals(), compareTo(), and toString()
methods that do what you would expect (that is, that compare and write out the corresponding
primitive type values in the usual way). Similar remarks apply for all the wrapper classes.
Recall also that Java does automatic conversions between a primitive type and the corre-
sponding wrapper type. (These conversions, are called autoboxing and unboxing) This means
that once you have created a generic data structure to hold objects belonging to one of the wrap-
per classes, you can use the data structure pretty much as if it actually contained primitive type
values. For example, if numbers is a variable of type Collection<Integer>, it is legal to
call numbers.add(17) or numbers.remove(42). You can’t literally add the primitive type
value 17 to numbers, but Java will automatically convert the 17 to the corresponding wrapper ob-
ject, new Integer(17), and the wrapper object will be added to the collection. (The creation
of the object does add some time and memory overhead to the operation, and you should keep

172
that in mind in situations where efficiency is important. An array of int is more efficient than an
ArrayList<Integer>)

8.8 Lists
I N THE PREVIOUS SECTION , we looked at the general properties of collection classes in Java. In
this section, we look at a few specific collection classes (lists in particular) and how to use them.
A list consists of a sequence of items arranged in a linear order. A list has a definite order, but is
not necessarily sorted into ascending order.

ArrayList and LinkedList

There are two obvious ways to represent a list: as a dynamic array and as a linked list. Both
of these options are available in generic form as the collection classes java.util.ArrayList
and java.util.LinkedList. These classes are part of the Java Collection Framework. Each
implements the interface List<T>, and therefor the interface Collection<T>. An object of
type ArrayList<T> represents an ordered sequence of objects of type T, stored in an array that
will grow in size whenever necessary as new items are added. An object of type LinkedList<T>
also represents an ordered sequence of objects of type T, but the objects are stored in nodes that
are linked together with pointers.
Both list classes support the basic list operations that are defined in the interface List<T>, and
an abstract data type is defined by its operations, not by its representation. So why two classes?
Why not a single List class with a single representation? The problem is that there is no single
representation of lists for which all list operations are efficient. For some operations, linked lists
are more efficient than arrays. For others, arrays are more efficient. In a particular application
of lists, it’s likely that only a few operations will be used frequently. You want to choose the
representation for which the frequently used operations will be as efficient as possible.
Broadly speaking, the LinkedList class is more efficient in applications where items will
often be added or removed at the beginning of the list or in the middle of the list. In an array, these
operations require moving a large number of items up or down one position in the array, to make
a space for a new item or to fill in the hole left by the removal of an item.
On the other hand, the ArrayList class is more efficient when random access to items is re-
quired. Random access means accessing the k-th item in the list, for any integer k. Random access
is used when you get or change the value stored at a specified position in the list. This is trivial for
an array. But for a linked list it means starting at the beginning of the list and moving from node
to node along the list for k steps.
Operations that can be done efficiently for both types of lists include sorting and adding an
item at the end of the list.
All lists implement the methods from interface Collection<T> that were discussed in previ-
ously. These methods include size(), isEmpty(), remove(Object),
add(T), and clear(). The add(T) method adds the object at the end of the list. The remove(Object)
method involves first finding the object, which is not very efficient for any list since it involves
going through the items in the list from beginning to end until the object is found. The interface
List<T> adds some methods for accessing list items according to their numerical positions in the
list. Suppose that list is an object of type List<T>. Then we have the methods:

• list.get(index)–returns the object of type T that is at position index in the list, where
index is an integer. Items are numbered 0, 1, 2, ..., list.size()−1. The parameter must
be in this range, or an IndexOutOfBoundsException is thrown.

173
 • list.set(index,obj)–stores the object obj at position number index in the list, replac-
ing the object that was there previously. The object obj must be of type T. This does not
change the number of elements in the list or move any of the other elements.

• list.add(index,obj)–inserts an object obj into the list at position number index,

where obj must be of type T. The number of items in the list increases by one, and items
that come after position index move up one position to make room for the new item. The
value of index must be in the range 0 to list.size(), inclusive. If index is equal to
list.size(), then obj is added at the end of the list.

• list.remove(index)–removes the object at position number index, and returns that ob-
ject as the return value of the method. Items after this position move up one space in the list
to fill the hole, and the size of the list decreases by one. The value of index must be in the
range 0 to list.size()−1.

• list.indexOf(obj)–returns an int that gives the position of obj in the list, if it occurs.
If it does not occur, the return value is −1. The object obj can be of any type, not just of
type T. If obj occurs more than once in the list, the index of the first occurrence is returned.

These methods are defined both in class ArrayList<T> and in class LinkedList<T>, al-
though some of them–get and set–are only efficient for ArrayLists. The class
LinkedList<T> adds a few additional methods, which are not defined for an ArrayList. If
linkedlist is an object of type LinkedList<T>, then we have

• linkedlist.getFirst()–returns the object of type T that is the first item in the list.
The list is not modified. If the list is empty when the method is called, an exception of
type NoSuchElementException is thrown (the same is true for the next three methods as
well).

• linkedlist.getLast()–returns the object of type T that is the last item in the list. The
list is not modified.

• linkedlist.removeFirst()–removes the first item from the list, and returns that object
of type T as its return value.

• linkedlist.removeLast()–removes the last item from the list, and returns that object of type
T as its return value.

• linkedlist.addFirst(obj)–adds the obj, which must be of type T, to the beginning

of the list.

• linkedlist.addLast(obj)–adds the object obj, which must be of type T, to the end

of the list. (This is exactly the same as linkedlist.add(obj) and is apparently defined
just to keep the naming consistent.)

If list is an object of type List<T>, then the method list.iterator(), defined in the
interface Collection<T>, returns an Iterator that can be used to traverse the list from be-
ginning to end. However, for Lists, there is a special type of Iterator, called a ListIterator,
which offers additional capabilities. ListIterator<T> is an interface that extends the interface
Iterator<T>. The method list.listIterator() returns an object of type ListIterator<T>.
A ListIterator has the usual Iterator methods, hasNext(), next(), and
remove(), but it also has methods hasPrevious(), previous(), and add(obj) that make it
possible to move backwards in the list and to add an item at the current position of the iterator.

174
To understand how these work, its best to think of an iterator as pointing to a position between
two list elements, or at the beginning or end of the list. In this diagram, the items in a list are
represented by squares, and arrows indicate the possible positions of an iterator:

If iter is of type ListIterator<T>, then iter.next() moves the iterator one space
to the right along the list and returns the item that the iterator passes as it moves. The method
iter.previous() moves the iterator one space to the left along the list and returns the item
that it passes. The method iter.remove() removes an item from the list; the item that is
removed is the item that the iterator passed most recently in a call to either iter.next() or
iter.previous(). There is also a method iter.add(obj) that adds the specified object to
the list at the current position of the iterator (where obj must be of type T). This can be between
two existing items or at the beginning of the list or at the end of the list.
As an example of using a ListIterator, suppose that we want to maintain a list of items that
is always sorted into increasing order. When adding an item to the list, we can use a ListIterator
to find the position in the list where the item should be added. Once the position has been found,
we use the same list iterator to place the item in that position. The idea is to start at the beginning
of the list and to move the iterator forward past all the items that are smaller than the item that is
being inserted. At that point, the iterator’s add() method can be used to insert the item. To be
more definite, suppose that stringList is a variable of type List<String>. Assume that that
the strings that are already in the list are stored in ascending order and that newItem is a string
that we would like to insert into the list. The following code will place newItem in the list in its
correct position, so that the modified list is still in ascending order:
ListIterator<String> iter = stringList.listIterator();
// Move the iterator so that it points to the position where
// newItem should be inserted into the list. If newItem is
// bigger than all the items in the list, then the while loop
// will end when iter.hasNext() becomes false, that is, when
// the iterator has reached the end of the list.
while (iter.hasNext()) {
String item = iter.next();
if (newItem.compareTo(item) <= 0) {
// newItem should come BEFORE item in the list.
// Move the iterator back one space so that
// it points to the correct insertion point,
// and end the loop.
iter.previous();
break;
}
}
iter.add(newItem);
Here, stringList may be of type ArrayList<String> or of type LinkedList<String>.
The algorithm that is used to insert newItem into the list will be about equally efficient for both
types of lists, and it will even work for other classes that implement the interface List<String>.
You would probably find it easier to design an insertion algorithm that uses array-like indexing
with the methods get(index) and add(index,obj). However, that algorithm would be inef-

175
ficient for LinkedLists because random access is so inefficient for linked lists. (By the way, the
insertion algorithm works when the list is empty. It might be useful for you to think about why
this is true.)

Sorting
Sorting a list is a fairly common operation, and there should really be a sorting method in the List
interface. There is not, presumably because it only makes sense to sort lists of certain types of ob-
jects, but methods for sorting lists are available as static methods in the class java.util.Collections.
This class contains a variety of static utility methods for working with collections. The methods
are generic; that is, they will work for collections of objects of various types. Suppose that list
is of type List<T>. The command Collections.sort(list); can be used to sort the list
into ascending order. The items in the list should implement the interface Comparable<T>. The
method Collections.sort() will work, for example, for lists of String and for lists of any
of the wrapper classes such as Integer and Double. There is also a sorting method that takes a
Comparator as its second argument: Collections.sort(list,comparator);.
In this method, the comparator will be used to compare the items in the list. As mentioned in
the previous section, a Comparator is an object that defines a compare() method that can be
used to compare two objects.
The sorting method that is used by Collections.sort() is the so-called “merge sort” al-
gorithm.
The Collections class has at least two other useful methods for modifying lists. Collections.shuffle(list)
will rearrange the elements of the list into a random order. Collections.reverse(list) will
reverse the order of the elements, so that the last element is moved to the beginning of the list, the
next-to-last element to the second position, and so on.
Since an efficient sorting method is provided for Lists, there is no need to write one your-
self. You might be wondering whether there is an equally convenient method for standard ar-
rays. The answer is yes. Array-sorting methods are available as static methods in the class
java.util.Arrays. The statement Arrays.sort(A); will sort an array, A, provided either
that the base type of A is one of the primitive types (except boolean) or that A is an array of Ob-
jects that implement the Comparable interface. You can also sort part of an array. This is important
since arrays are often only “partially filled.” The command: Arrays.sort(A,fromIndex,toIndex);
sorts the elements A[fromIndex], A[fromIndex+1], ..., A[toIndex−1] into ascend-
ing order. You can use Arrays.sort(A,0,N−1) to sort a partially filled array which has ele-
ments in the first N positions.
Java does not support generic programming for primitive types. In order to implement the
command Arrays.sort(A), the Arrays class contains eight methods: one method for arrays
of Objects and one method for each of the primitive types byte, short, int, long, float,
double, and char.

176
 CHAPTER 9
C ORRECTNESS AND ROBUSTNESS

Contents
8.1 Generic Programming in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8.2 ArrayLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8.3 Parameterized Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
8.4 The Java Collection Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.5 Iterators and for-each Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
8.6 Equality and Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
8.7 Generics and Wrapper Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.8 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

A PROGRAM IS CORRECT if it accomplishes the task that it was designed to perform. It

is robust if it can handle illegal inputs and other unexpected situations in a reasonable way. For
example, consider a program that is designed to read some numbers from the user and then print
the same numbers in sorted order. The program is correct if it works for any set of input numbers.
It is robust if it can also deal with non-numeric input by, for example, printing an error message
and ignoring the bad input. A non-robust program might crash or give nonsensical output in the
same circumstance.
Every program should be correct. (A sorting program that doesn’t sort correctly is pretty
useless.) It’s not the case that every program needs to be completely robust. It depends on who
will use it and how it will be used. For example, a small utility program that you write for your
own use doesn’t have to be particularly robust.
The question of correctness is actually more subtle than it might appear. A programmer works
from a specification of what the program is supposed to do. The programmer’s work is correct if
the program meets its specification. But does that mean that the program itself is correct? What
if the specification is incorrect or incomplete? A correct program should be a correct implemen-
tation of a complete and correct specification. The question is whether the specification correctly
expresses the intention and desires of the people for whom the program is being written. This is a
question that lies largely outside the domain of computer science.

177
9.1 Introduction
Horror Stories
M OST COMPUTER USERS HAVE PERSONAL EXPERIENCE with programs that don’t work or
that crash. In many cases, such problems are just annoyances, but even on a personal computer
there can be more serious consequences, such as lost work or lost money. When computers are
given more important tasks, the consequences of failure can be proportionately more serious.
Just a few years ago, the failure of two multi-million space missions to Mars was prominent in
the news. Both failures were probably due to software problems, but in both cases the problem was
not with an incorrect program as such. In September 1999, the Mars Climate Orbiter burned up in
the Martian atmosphere because data that was expressed in English units of measurement (such as
feet and pounds) was entered into a computer program that was designed to use metric units (such
as centimeters and grams). A few months later, the Mars Polar Lander probably crashed because
its software turned off its landing engines too soon. The program was supposed to detect the bump
when the spacecraft landed and turn off the engines then. It has been determined that deployment
of the landing gear might have jarred the spacecraft enough to activate the program, causing it to
turn off the engines when the spacecraft was still in the air. The unpowered spacecraft would then
have fallen to the Martian surface. A more robust system would have checked the altitude before
turning off the engines!
There are many equally dramatic stories of problems caused by incorrect or poorly written
software. Let’s look at a few incidents recounted in the book Computer Ethics by Tom Forester
and Perry Morrison. (This book covers various ethical issues in computing. It, or something like
it, is essential reading for any student of computer science.)
In 1985 and 1986, one person was killed and several were injured by excess radiation, while
undergoing radiation treatments by a mis-programmed computerized radiation machine. In an-
other case, over a ten-year period ending in 1992, almost 1,000 cancer patients received radiation
dosages that were 30% less than prescribed because of a programming error.
In 1985, a computer at the Bank of New York started destroying records of on-going security
transactions because of an error in a program. It took less than 24 hours to fix the program, but
by that time, the bank was out $5,000,000 in overnight interest payments on funds that it had to
borrow to cover the problem.
The programming of the inertial guidance system of the F-16 fighter plane would have turned
the plane upside-down when it crossed the equator, if the problem had not been discovered in
simulation. The Mariner 18 space probe was lost because of an error in one line of a program.
The Gemini V space capsule missed its scheduled landing target by a hundred miles, because a
programmer forgot to take into account the rotation of the Earth.
In 1990, AT&T’s long-distance telephone service was disrupted throughout the United States
when a newly loaded computer program proved to contain a bug.
These are just a few examples. Software problems are all too common. As programmers, we
need to understand why that is true and what can be done about it.

Java to the Rescue

Part of the problem, according to the inventors of Java, can be traced to programming languages
themselves. Java was designed to provide some protection against certain types of errors. How
can a language feature help prevent errors? Let’s look at a few examples.
Early programming languages did not require variables to be declared. In such languages,
when a variable name is used in a program, the variable is created automatically. You might
consider this more convenient than having to declare every variable explicitly. But there is an

178
unfortunate consequence: An inadvertent spelling error might introduce an extra variable that you
had no intention of creating. This type of error was responsible, according to one famous story,
for yet another lost spacecraft. In the FORTRAN programming language, the command “DO 20
I = 1,5” is the first statement of a counting loop. Now, spaces are insignificant in FORTRAN, so
this is equivalent to “DO20I=1,5”. On the other hand, the command “DO20I=1.5”, with a period
instead of a comma, is an assignment statement that assigns the value 1.5 to the variable DO20I.
Supposedly, the inadvertent substitution of a period for a comma in a statement of this type caused
a rocket to blow up on take-off. Because FORTRAN doesn’t require variables to be declared,
the compiler would be happy to accept the statement “DO20I=1.5.” It would just create a new
variable named DO20I. If FORTRAN required variables to be declared, the compiler would have
complained that the variable DO20I was undeclared.
While most programming languages today do require variables to be declared, there are other
features in common programming languages that can cause problems. Java has eliminated some
of these features. Some people complain that this makes Java less efficient and less powerful.
While there is some justice in this criticism, the increase in security and robustness is probably
worth the cost in most circumstances. The best defense against some types of errors is to design
a programming language in which the errors are impossible. In other cases, where the error can’t
be completely eliminated, the language can be designed so that when the error does occur, it will
automatically be detected. This will at least prevent the error from causing further harm, and it
will alert the programmer that there is a bug that needs fixing. Let’s look at a few cases where the
designers of Java have taken these approaches.
An array is created with a certain number of locations, numbered from zero up to some spec-
ified maximum index. It is an error to try to use an array location that is outside of the specified
range. In Java, any attempt to do so is detected automatically by the system. In some other lan-
guages, such as C and C++, it’s up to the programmer to make sure that the index is within the
legal range. Suppose that an array, A, has three locations, A[0], A[1], and A[2]. Then A[3], A[4],
and so on refer to memory locations beyond the end of the array. In Java, an attempt to store data in
A[3] will be detected. The program will be terminated (unless the error is “caught”. In C or C++,
the computer will just go ahead and store the data in memory that is not part of the array. Since
there is no telling what that memory location is being used for, the result will be unpredictable.
The consequences could be much more serious than a terminated program. (See, for example, the
discussion of buffer overflow errors later in this section.)
Pointers are a notorious source of programming errors. In Java, a variable of object type holds
either a pointer to an object or the special value null. Any attempt to use a null value as if it were a
pointer to an actual object will be detected by the system. In some other languages, again, it’s up
to the programmer to avoid such null pointer errors. In my old Macintosh computer, a null pointer
was actually implemented as if it were a pointer to memory location zero. A program could use a
null pointer to change values stored in memory near location zero. Unfortunately, the Macintosh
stored important system data in those locations. Changing that data could cause the whole system
to crash, a consequence more severe than a single failed program.
Another type of pointer error occurs when a pointer value is pointing to an object of the wrong
type or to a segment of memory that does not even hold a valid object at all. These types of errors
are impossible in Java, which does not allow programmers to manipulate pointers directly. In other
languages, it is possible to set a pointer to point, essentially, to any location in memory. If this is
done incorrectly, then using the pointer can have unpredictable results.
Another type of error that cannot occur in Java is a memory leak. In Java, once there are no
longer any pointers that refer to an object, that object is “garbage collected” so that the memory
that it occupied can be reused. In other languages, it is the programmer’s responsibility to return
unused memory to the system. If the programmer fails to do this, unused memory can build up,

179
leaving less memory for programs and data. There is a story that many common programs for older
Windows computers had so many memory leaks that the computer would run out of memory after
a few days of use and would have to be restarted.
Many programs have been found to suffer from buffer overflow errors. Buffer overflow errors
often make the news because they are responsible for many network security problems. When
one computer receives data from another computer over a network, that data is stored in a buffer.
The buffer is just a segment of memory that has been allocated by a program to hold data that it
expects to receive. A buffer overflow occurs when more data is received than will fit in the buffer.
The question is, what happens then? If the error is detected by the program or by the networking
software, then the only thing that has happened is a failed network data transmission. The real
problem occurs when the software does not properly detect buffer overflows. In that case, the
software continues to store data in memory even after the buffer is filled, and the extra data goes
into some part of memory that was not allocated by the program as part of the buffer. That memory
might be in use for some other purpose. It might contain important data. It might even contain
part of the program itself. This is where the real security issues come in. Suppose that a buffer
overflow causes part of a program to be replaced with extra data received over a network. When
the computer goes to execute the part of the program that was replaced, it’s actually executing
data that was received from another computer. That data could be anything. It could be a program
that crashes the computer or takes it over. A malicious programmer who finds a convenient buffer
overflow error in networking software can try to exploit that error to trick other computers into
executing his programs.
For software written completely in Java, buffer overflow errors are impossible. The language
simply does not provide any way to store data into memory that has not been properly allocated.
To do that, you would need a pointer that points to unallocated memory or you would have to refer
to an array location that lies outside the range allocated for the array. As explained above, neither
of these is possible in Java. (However, there could conceivably still be errors in Java’s standard
classes, since some of the methods in these classes are actually written in the C programming
language rather than in Java.)
It’s clear that language design can help prevent errors or detect them when they occur. Doing
so involves restricting what a programmer is allowed to do. Or it requires tests, such as checking
whether a pointer is null, that take some extra processing time. Some programmers feel that
the sacrifice of power and efficiency is too high a price to pay for the extra security. In some
applications, this is true. However, there are many situations where safety and security are primary
considerations. Java is designed for such situations.

Problems Remain in Java

There is one area where the designers of Java chose not to detect errors automatically: numerical
computations. In Java, a value of type int is represented as a 32-bit binary number. With 32
bits, it’s possible to represent a little over four billion different values. The values of type int
range from −2147483648 to 2147483647. What happens when the result of a computation lies
outside this range? For example, what is 2147483647 + 1? And what is 2000000000 ∗ 2? The
mathematically correct result in each case cannot be represented as a value of type int. These
are examples of integer overflow. In most cases, integer overflow should be considered an error.
However, Java does not automatically detect such errors. For example, it will compute the value
of 2147483647 + 1 to be the negative number, −2147483648. (What happens is that any extra bits
beyond the 32-nd bit in the correct answer are discarded. Values greater than 2147483647 will
“wrap around” to negative values. Mathematically speaking, the result is always “correct modulo
232”.)

180
 For example, consider the 3N + 1 program. Starting from a positive integer N, the program
computes a certain sequence of integers:
while ( N != 1 ) {
if ( N % 2 == 0 ) // If N is even...
N = N / 2;
else
N = 3 * N + 1;
System.out.println(N);
}

But there is a problem here: If N is too large, then the value of 3∗N +1 will not be mathematically
correct because of integer overflow. The problem arises whenever 3∗ N +1 > 2147483647, that is
when N > 2147483646/3. For a completely correct program, we should check for this possibility
before computing 3 ∗ N + 1:
while ( N != 1 ) {
if ( N % 2 == 0 ) // If N is even...
N = N / 2;
else {
if (N > 2147483646/3) {
System.out.println("Sorry, value of N has become too large!");
break;
}
N = 3 * N + 1;
}
System.out.println(N); }

The problem here is not that the original algorithm for computing 3N +1 sequences was wrong.
The problem is that it just can’t be correctly implemented using 32-bit integers. Many programs
ignore this type of problem. But integer overflow errors have been responsible for their share of
serious computer failures, and a completely robust program should take the possibility of integer
overflow into account. (The infamous “Y2K” bug was, in fact, just this sort of error.)
For numbers of type double, there are even more problems. There are still overflow errors,
which occur when the result of a computation is outside the range of values that can be repre-
sented as a value of type double. This range extends up to about 1.7 × 10308 . Numbers beyond
this range do not “wrap around” to negative values. Instead, they are represented by special values
that have no real numerical equivalent. The special values Double.POSITIVE_INFINITY and
Double.NEGATIVE_INFINITY represent numbers outside the range of legal values. For exam-
ple, 20 × 10308 is computed to be Double.POSITIVE_INFINITY. Another special value of type
double, Double.NaN, represents an illegal or undefined result. (“NaN” stands for “Not a Num-
ber”.) For example, the result of dividing by zero or taking the square root of a negative number is
Double.NaN. You can test whether a number x is this special non-a-number value by calling the
boolean-valued method Double.isNaN(x).
For real numbers, there is the added complication that most real numbers can only be repre-
sented approximately on a computer. A real number can have an infinite number of digits after
the decimal point. A value of type double is only accurate to about 15 digits. The real number
1/3, for example, is the repeating decimal 0.333333333333..., and there is no way to represent it
exactly using a finite number of digits. Computations with real numbers generally involve a loss of
accuracy. In fact, if care is not exercised, the result of a large number of such computations might
be completely wrong! There is a whole field of computer science, known as numerical analysis,
which is devoted to studying algorithms that manipulate real numbers.
So you see that not all possible errors are avoided or detected automatically in Java. Further-
more, even when an error is detected automatically, the system’s default response is to report the

181
error and terminate the program. This is hardly robust behavior! So, a Java programmer still needs
to learn techniques for avoiding and dealing with errors. These are the main topics of the rest of
this chapter.

9.2 Writing Correct Programs

C ORRECT PROGRAMS DON ’ T JUST HAPPEN . It takes planning and attention to detail to avoid
errors in programs. There are some techniques that programmers can use to increase the likelihood
that their programs are correct.

Provably Correct Programs

In some cases, it is possible to prove that a program is correct. That is, it is possible to demonstrate
mathematically that the sequence of computations represented by the program will always produce
the correct result. Rigorous proof is difficult enough that in practice it can only be applied to fairly
small programs. Furthermore, it depends on the fact that the “correct result” has been specified
correctly and completely. As I’ve already pointed out, a program that correctly meets its specifi-
cation is not useful if its specification was wrong. Nevertheless, even in everyday programming,
we can apply the ideas and techniques that are used in proving that programs are correct.
The fundamental ideas are process and state. A state consists of all the information relevant
to the execution of a program at a given moment during its execution. The state includes, for
example, the values of all the variables in the program, the output that has been produced, any
input that is waiting to be read, and a record of the position in the program where the computer
is working. A process is the sequence of states that the computer goes through as it executes the
program. From this point of view, the meaning of a statement in a program can be expressed in
terms of the effect that the execution of that statement has on the computer’s state. As a simple
example, the meaning of the assignment statement “x = 7;” is that after this statement is executed,
the value of the variable x will be 7. We can be absolutely sure of this fact, so it is something upon
which we can build part of a mathematical proof.
In fact, it is often possible to look at a program and deduce that some fact must be true at a
given point during the execution of a program. For example, consider the do loop:
do {
Scanner keyboard = new Scanner(System.in);
System.out.prinln("Enter a positive integer: ");
N = keyboard.nextInt();
} while (N <= 0);

After this loop ends, we can be absolutely sure that the value of the variable N is greater than
zero. The loop cannot end until this condition is satisfied. This fact is part of the meaning of the
while loop. More generally, if a while loop uses the test “while (condition)”, then after the
loop ends, we can be sure that the condition is false. We can then use this fact to draw further
deductions about what happens as the execution of the program continues. (With a loop, by the
way, we also have to worry about the question of whether the loop will ever end. This is something
that has to be verified separately.)
A fact that can be proven to be true after a given program segment has been executed is called
a postcondition of that program segment. Postconditions are known facts upon which we can build
further deductions about the behavior of the program. A postcondition of a program as a whole is
simply a fact that can be proven to be true after the program has finished executing. A program
can be proven to be correct by showing that the postconditions of the program meet the program’s
specification.

182
 Consider the following program segment, where all the variables are of type double:
disc = B*B − 4*A*C;
x = (−B + Math.sqrt(disc)) / (2*A);

The quadratic formula (from high-school mathematics) assures us that the value assigned to x
is a solution of the equation Ax 2 +B x+C = 0, provided that the value of disc is greater than or equal
to zero and the value of A is not zero. If we can assume or guarantee that B ∗ B − 4 ∗ A ∗C > = 0
and that A! = 0, then the fact that x is a solution of the equation becomes a postcondition of the
program segment. We say that the condition, B ∗ B − 4 ∗ A ∗ C > = 0 is a precondition of the
program segment. The condition that A ! = 0 is another precondition. A precondition is defined
to be condition that must be true at a given point in the execution of a program in order for the
program to continue correctly. A precondition is something that you want to be true. It’s something
that you have to check or force to be true, if you want your program to be correct.
We’ve encountered preconditions and postconditions once before. That section introduced
preconditions and postconditions as a way of specifying the contract of a method. As the terms
are being used here, a precondition of a method is just a precondition of the code that makes up the
definition of the method, and the postcondition of a method is a postcondition of the same code. In
this section, we have generalized these terms to make them more useful in talking about program
correctness.
Let’s see how this works by considering a longer program segment:
do {
Scanner keyboard = new Scanner(System.in);
System.out.println("Enter A, B, and C. B*B−4*A*C must be >= 0.");
System.out.print("A = ");
A = keyboard.nextDouble();
System.out.print("B = ");
B = keyboard.nextDouble();
System.out.print("C = ");
C = keyboard.nextDouble();
if (A == 0 || B*B − 4*A*C < 0)
System.out.println("Your input is illegal. Try again.");
} while (A == 0 || B*B − 4*A*C < 0);

disc = B*B − 4*A*C;

x = (−B + Math.sqrt(disc)) / (2*A);

After the loop ends, we can be sure that B ∗ B − 4 ∗ A ∗ C >= 0 and that A ! = 0. The precon-
ditions for the last two lines are fulfilled, so the postcondition that x is a solution of the equation
A ∗ x2 + B ∗ x + C = 0 is also valid. This program segment correctly and provably computes a
solution to the equation. (Actually, because of problems with representing numbers on computers,
this is not 100% true. The algorithm is correct, but the program is not a perfect implementation
of the algorithm.
Here is another variation, in which the precondition is checked by an if statement. In the first
part of the if statement, where a solution is computed and printed, we know that the preconditions
are fulfilled. In the other parts, we know that one of the preconditions fails to hold. In any case,
the program is correct.
Scanner keyboard = new Scanner(System.in);
System.out.println("Enter your values for A, B, and C.");
System.out.print("A = ");
A = keyboard.nextDouble();
System.out.print("B = ");
B = keyboard.nextDouble();

183
 System.out.print("C = ");
C = keyboard.nextDouble();

if (A != 0 && B*B − 4*A*C >= 0) {

disc = B*B − 4*A*C;
x = (−B + Math.sqrt(disc)) / (2*A);
System.out.println("A solution of A*X*X + B*X + C = 0 is " + x);
}
else if (A == 0) {
System.out.println("The value of A cannot be zero.");
}
else {
System.out.println("Since B*B − 4*A*C is less than zero, the");
System.out.println("equation A*X*X + B*X + C = 0 has no solution.");
}
Whenever you write a program, it’s a good idea to watch out for preconditions and think about
how your program handles them. Often, a precondition can offer a clue about how to write the
program.
For example, every array reference, such as A[i], has a precondition: The index must be
within the range of legal indices for the array. For A[i], the precondition is that 0 <= i <
A .length. The computer will check this condition when it evaluates A[i], and if the condition is
not satisfied, the program will be terminated. In order to avoid this, you need to make sure that the
index has a legal value. (There is actually another precondition, namely that A is not null, but let’s
leave that aside for the moment.) Consider the following code, which searches for the number x
in the array A and sets the value of i to be the index of the array element that contains x :
i = 0;
while (A[i] != x) {
i++;
}
As this program segment stands, it has a precondition, namely that x is actually in the array.
If this precondition is satisfied, then the loop will end when A[i] == x. That is, the value of i
when the loop ends will be the position of x in the array. However, if x is not in the array, then
the value of i will just keep increasing until it is equal to A.length. At that time, the reference to
A[i] is illegal and the program will be terminated. To avoid this, we can add a test to make sure
that the precondition for referring to A[i] is satisfied:
i = 0;
while (i < A.length && A[i] != x) {
i++;
}
Now, the loop will definitely end. After it ends, i will satisfy either i == A.length or
A[i] == x. An if statement can be used after the loop to test which of these conditions caused
the loop to end:
i = 0;
while (i < A.length && A[i] != x) {
i++;
}

if (i == A.length)
System.out.println("x is not in the array");
else
System.out.println("x is in position " + i);

184
Robust Handling of Input
One place where correctness and robustness are important–and especially difficult–is in the pro-
cessing of input data, whether that data is typed in by the user, read from a file, or received over a
network.
Sometimes, it’s useful to be able to look ahead at what’s coming up in the input without actu-
ally reading it. For example, a program might need to know whether the next item in the input is
a number or a word. For this purpose, the Scanner class has various hasNext methods. These in-
cludes hasNextBoolean(); hasNextInteger(); hasNextLine() and hasNextDouble().
For example the hasNextInteger() method returns true if the input’s next token is an integer.
Thus, you can check if the expected input is available before actually reading it.

9.3 Exceptions and try..catch

G ETTING A PROGRAM TO WORK under ideal circumstances is usually a lot easier than making
the program robust. A robust program can survive unusual or “exceptional” circumstances without
crashing. One approach to writing robust programs is to anticipate the problems that might arise
and to include tests in the program for each possible problem. For example, a program will crash
if it tries to use an array element A[i], when i is not within the declared range of indices for the
array A. A robust program must anticipate the possibility of a bad index and guard against it. One
way to do this is to write the program in a way that ensures that the index is in the legal range.
Another way is to test whether the index value is legal before using it in the array. This could be
done with an if statement:
if (i < 0 || i >= A.length) {
... // Do something to handle the out−of−range index, i
}
else {
... // Process the array element, A[i]
}
There are some problems with this approach. It is difficult and sometimes impossible to an-
ticipate all the possible things that might go wrong. It’s not always clear what to do when an
error is detected. Furthermore, trying to anticipate all the possible problems can turn what would
otherwise be a straightforward program into a messy tangle of if statements.

Exceptions and Exception Classes

We have already seen that Java (like its cousin, C++) provides a neater, more structured alternative
method for dealing with errors that can occur while a program is running. The method is referred
to as exception handling. The word “exception” is meant to be more general than “error.” It
includes any circumstance that arises as the program is executed which is meant to be treated as
an exception to the normal flow of control of the program. An exception might be an error, or it
might just be a special case that you would rather not have clutter up your elegant algorithm.
When an exception occurs during the execution of a program, we say that the exception is
thrown. When this happens, the normal flow of the program is thrown off-track, and the program
is in danger of crashing. However, the crash can be avoided if the exception is caught and handled
in some way. An exception can be thrown in one part of a program and caught in a different part.
An exception that is not caught will generally cause the program to crash.
By the way, since Java programs are executed by a Java interpreter, having a program crash
simply means that it terminates abnormally and prematurely. It doesn’t mean that the Java in-
terpreter will crash. In effect, the interpreter catches any exceptions that are not caught by the

185
program. The interpreter responds by terminating the program. In many other programming lan-
guages, a crashed program will sometimes crash the entire system and freeze the computer until it
is restarted. With Java, such system crashes should be impossible – which means that when they
happen, you have the satisfaction of blaming the system rather than your own program.
When an exception occurs, the thing that is actually “thrown” is an object. This object can
carry information (in its instance variables) from the point where the exception occurs to the point
where it is caught and handled. This information always includes the method call stack, which
is a list of the methods that were being executed when the exception was thrown. (Since one
method can call another, several methods can be active at the same time.) Typically, an exception
object also includes an error message describing what happened to cause the exception, and it can
contain other data as well. All exception objects must belong to a subclass of the standard class
java.lang.Throwable. In general, each different type of exception is represented by its own
subclass of Throwable, and these subclasses are arranged in a fairly complex class hierarchy that
shows the relationship among various types of exceptions. Throwable has two direct subclasses,
Error and Exception. These two subclasses in turn have many other predefined subclasses. In
addition, a programmer can create new exception classes to represent new types of exceptions.
Most of the subclasses of the class Error represent serious errors within the Java virtual
machine that should ordinarily cause program termination because there is no reasonable way to
handle them. In general, you should not try to catch and handle such errors. An example is a
ClassFormatError, which occurs when the Java virtual machine finds some kind of illegal data
in a file that is supposed to contain a compiled Java class. If that class was being loaded as part of
the program, then there is really no way for the program to proceed.
On the other hand, subclasses of the class Exception represent exceptions that are meant to
be caught. In many cases, these are exceptions that might naturally be called “errors,” but they are
errors in the program or in input data that a programmer can anticipate and possibly respond to in
some reasonable way. (However, you should avoid the temptation of saying, “Well, I’ll just put a
thing here to catch all the errors that might occur, so my program won’t crash.” If you don’t have
a reasonable way to respond to the error, it’s best just to let the program crash, because trying to
go on will probably only lead to worse things down the road – in the worst case, a program that
gives an incorrect answer without giving you any indication that the answer might be wrong!)
The class Exception has its own subclass, RuntimeException. This class groups to-
gether many common exceptions, including all those that have been covered in previous sections.
For example, IllegalArgumentException and NullPointerException are subclasses of
RuntimeException. A RuntimeException generally indicates a bug in the program, which
the programmer should fix. RuntimeExceptions and Errors share the property that a program
can simply ignore the possibility that they might occur. (“Ignoring” here means that you are
content to let your program crash if the exception occurs.) For example, a program does this
every time it uses an array reference like A[i] without making arrangements to catch a possible
ArrayIndexOutOfBoundsException. For all other exception classes besides Error, RuntimeException,
and their subclasses, exception-handling is “mandatory” in a sense that I’ll discuss below.
The following diagram is a class hierarchy showing the class Throwable and just a few of its
subclasses. Classes that require mandatory exception-handling are shown in red:

186
 The class Throwable includes several instance methods that can be used with any exception
object. If e is of type Throwable (or one of its subclasses), then
e.getMessage() is a method that returns a String that describes the exception. The method
e.toString(), which is used by the system whenever it needs a string representation of the ob-
ject, returns a String that contains the name of the class to which the exception belongs as well
as the same string that would be returned by e.getMessage(). And e.printStackTrace()
writes a stack trace to standard output that tells which methods were active when the exception
occurred. A stack trace can be very useful when you are trying to determine the cause of the
problem. (Note that if an exception is not caught by the program, then the system automatically
prints the stack trace to standard output.)

The try Statement

To catch exceptions in a Java program, you need a try statement. The try statements that we have
used so far had a syntax similar to the following example:
try {
double determinant = M[0][0]*M[1][1] − M[0][1]*M[1][0];
System.out.println("The determinant of M is " + determinant);
}
catch ( ArrayIndexOutOfBoundsException e ) {
System.out.println("M is the wrong size to have a determinant.");
e.printStackTrace();
}

Here, the computer tries to execute the block of statements following the word “try”. If no ex-
ception occurs during the execution of this block, then the “catch” part of the statement is simply
ignored. However, if an exception of type
ArrayIndexOutOfBoundsException occurs, then the computer jumps immediately to the
catch clause of the try statement. This block of statements is said to be an exception handler
for ArrayIndexOutOfBoundsException. By handling the exception in this way, you prevent
it from crashing the program. Before the body of the catch clause is executed, the object that
represents the exception is assigned to the variable e, which is used in this example to print a stack
trace.

187
 However, the full syntax of the try statement allows more than one catch clause. This makes
it possible to catch several different types of exceptions with one try statement. In the example
above, in addition to the possibility of an
ArrayIndexOutOfBoundsException, there is a possible NullPointerException which
will occur if the value of M is null. We can handle both exceptions by adding a second catch
clause to the try statement:
try {
double determinant = M[0][0]*M[1][1] − M[0][1]*M[1][0];
System.out.println("The determinant of M is " + determinant);
}
catch ( ArrayIndexOutOfBoundsException e ) {
System.out.println("M is the wrong size to have a determinant.");
}
catch ( NullPointerException e ) {
System.out.print("Programming error! M doesn’t exist." + );
}

Here, the computer tries to execute the statements in the try clause. If no error occurs, both of
the catch clauses are skipped. If an ArrayIndexOutOfBoundsException occurs, the computer
executes the body of the first catch clause and skips the second one. If a NullPointerException
occurs, it jumps to the second catch clause and executes that.
Note that both ArrayIndexOutOfBoundsException and NullPointerException are
subclasses of RuntimeException. It’s possible to catch all RuntimeExceptions with a single
catch clause. For example:
try {
double determinant = M[0][0]*M[1][1] − M[0][1]*M[1][0];
System.out.println("The determinant of M is " + determinant);
}
catch ( RuntimeException err ) {
System.out.println("Sorry, an error has occurred.");
System.out.println("The error was: " + err);
}

The catch clause in this try statement will catch any exception belonging to class RuntimeException
or to any of its subclasses. This shows why exception classes are organized into a class hierarchy.
It allows you the option of casting your net narrowly to catch only a specific type of exception. Or
you can cast your net widely to catch a wide class of exceptions. Because of subclassing, when
there are multiple catch clauses in a try statement, it is possible that a given exception might match
several of those catch clauses. For example, an exception of type NullPointerException
would match catch clauses for NullPointerException, RuntimeException, Exception,
or Throwable. In this case, only the first catch clause that matches the exception is executed.
The example I’ve given here is not particularly realistic. You are not very likely to use
exception-handling to guard against null pointers and bad array indices. This is a case where
careful programming is better than exception handling: Just be sure that your program assigns a
reasonable, non-null value to the array M. You would certainly resent it if the designers of Java
forced you to set up a try..catch statement every time you wanted to use an array! This is why
handling of potential RuntimeExceptions is not mandatory. There are just too many things that
might go wrong! (This also shows that exception-handling does not solve the problem of program
robustness. It just gives you a tool that will in many cases let you approach the problem in a more
organized way.)
I have still not completely specified the syntax of the try statement. There is one additional
element: the possibility of a finally clause at the end of a try statement. The complete syntax of

188
the try statement can be described as:
try {
statements
}
optional−catch−clauses
optional−finally−clause

Note that the catch clauses are also listed as optional. The try statement can include zero or more
catch clauses and, optionally, a finally clause. The try statement must include one or the
other. That is, a try statement can have either a finally clause, or one or more catch clauses,
or both. The syntax for a catch clause is
catch ( exception−class−name variable−name ) {
statements
}

and the syntax for a finally clause is

finally {
statements
}

The semantics of the finally clause is that the block of statements in the finally clause
is guaranteed to be executed as the last step in the execution of the try statement, whether or not
any exception occurs and whether or not any exception that does occur is caught and handled.
The finally clause is meant for doing essential cleanup that under no circumstances should be
omitted. One example of this type of cleanup is closing a network connection. Although you
don’t yet know enough about networking to look at the actual programming in this case, we can
consider some pseudocode:
try {
open a network connection
}
catch ( IOException e ) {
report the error
return // Don’t continue if connection can’t be opened!
}

// At this point, we KNOW that the connection is open.

try {
communicate over the connection
}
catch ( IOException e ) {
handle the error
}
finally {
close the connection
}

The finally clause in the second try statement ensures that the network connection will
definitely be closed, whether or not an error occurs during the communication. The first try
statement is there to make sure that we don’t even try to communicate over the network unless we
have successfully opened a connection. The pseudocode in this example follows a general pattern
that can be used to robustly obtain a resource, use the resource, and then release the resource.

189
Throwing Exceptions
There are times when it makes sense for a program to deliberately throw an exception. This is
the case when the program discovers some sort of exceptional or error condition, but there is no
reasonable way to handle the error at the point where the problem is discovered. The program
can throw an exception in the hope that some other part of the program will catch and handle the
exception. This can be done with a throw statement. In this section, we cover the throw statement
more fully. The syntax of the throw statement is: throw exception−object ;
The exception-object must be an object belonging to one of the subclasses of
Throwable. Usually, it will in fact belong to one of the subclasses of Exception. In most cases,
it will be a newly constructed object created with the new operator. For example: throw new ArithmeticExceptio
The parameter in the constructor becomes the error message in the exception object; if e refers
to the object, the error message can be retrieved by calling
e.getMessage(). (You might find this example a bit odd, because you might expect the system
itself to throw an ArithmeticException when an attempt is made to divide by zero. So why
should a programmer bother to throw the exception? Recalls that if the numbers that are being
divided are of type int, then division by zero will indeed throw an ArithmeticException.
However, no arithmetic operations with floating-point numbers will ever produce an exception.
Instead, the special value Double.NaN is used to represent the result of an illegal operation. In
some situations, you might prefer to throw an ArithmeticException when a real number is
divided by zero.)
An exception can be thrown either by the system or by a throw statement. The exception is
processed in exactly the same way in either case. Suppose that the exception is thrown inside a
try statement. If that try statement has a catch clause that handles that type of exception, then
the computer jumps to the catch clause and executes it. The exception has been handled. After
handling the exception, the computer executes the finally clause of the try statement, if there is one.
It then continues normally with the rest of the program, which follows the try statement. If the
exception is not immediately caught and handled, the processing of the exception will continue.
When an exception is thrown during the execution of a method and the exception is not handled
in the same method, then that method is terminated (after the execution of any pending finally
clauses). Then the method that called that method gets a chance to handle the exception. That
is, if the method was called inside a try statement that has an appropriate catch clause, then that
catch clause will be executed and the program will continue on normally from there. Again, if
the second method does not handle the exception, then it also is terminated and the method that
called it (if any) gets the next shot at the exception. The exception will crash the program only if
it passes up through the entire chain of method calls without being handled.
A method that might generate an exception can announce this fact by adding a clause “throws
exception-class-name” to the header of the method. For example:
/**
* Returns the larger of the two roots of the quadratic equation
* A*x*x + B*x + C = 0, provided it has any roots. If A == 0 or
* if the discriminant, B*B − 4*A*C, is negative, then an exception
* of type IllegalArgumentException is thrown.
*/
static public double root( double A, double B, double C )
throws IllegalArgumentException {
if (A == 0) {
throw new IllegalArgumentException("A can’t be zero.");
}
else {
double disc = B*B − 4*A*C;

190
 if (disc < 0)
throw new IllegalArgumentException("Discriminant < zero.");
return (−B + Math.sqrt(disc)) / (2*A);
}
}

As discussed in the previous section, the computation in this method has the preconditions that
A! = 0 and B ∗B −4∗A∗C >= 0. The method throws an exception of type IllegalArgumentException
when either of these preconditions is violated. When an illegal condition is found in a method,
throwing an exception is often a reasonable response. If the program that called the method knows
some good way to handle the error, it can catch the exception. If not, the program will crash – and
the programmer will know that the program needs to be fixed.
A throws clause in a method heading can declare several different types of exceptions, sepa-
rated by commas. For example:
void processArray(int[] A) throws NullPointerException,
ArrayIndexOutOfBoundsException { ...

Mandatory Exception Handling

In the preceding example, declaring that the method root() can throw an
IllegalArgumentException is just a courtesy to potential readers of this method. This is
because handling of IllegalArgumentExceptions is not “mandatory”. A method can throw
an IllegalArgumentException without announcing the possibility. And a program that calls
that method is free either to catch or to ignore the exception, just as a programmer can choose
either to catch or to ignore an exception of type NullPointerException.
For those exception classes that require mandatory handling, the situation is different. If a
method can throw such an exception, that fact must be announced in a throws clause in the method
definition. Failing to do so is a syntax error that will be reported by the compiler.
On the other hand, suppose that some statement in the body of a method can generate an
exception of a type that requires mandatory handling. The statement could be a throw statement,
which throws the exception directly, or it could be a call to a method that can throw the exception.
In either case, the exception must be handled. This can be done in one of two ways: The first way
is to place the statement in a try statement that has a catch clause that handles the exception; in this
case, the exception is handled within the method, so that any caller of the method will never see
the exception. The second way is to declare that the method can throw the exception. This is done
by adding a “throws” clause to the method heading, which alerts any callers to the possibility that
an exception might be generated when the method is executed. The caller will, in turn, be forced
either to handle the exception in a try statement or to declare the exception in a throws clause in
its own header.
Exception-handling is mandatory for any exception class that is not a subclass of either Error
or RuntimeException. Exceptions that require mandatory handling generally represent condi-
tions that are outside the control of the programmer. For example, they might represent bad input
or an illegal action taken by the user. There is no way to avoid such errors, so a robust program
has to be prepared to handle them. The design of Java makes it impossible for programmers to
ignore the possibility of such errors.
Among the exceptions that require mandatory handling are several that can occur when us-
ing Java’s input/output methods. This means that you can’t even use these methods unless you
understand something about exception-handling.

191
Programming with Exceptions
Exceptions can be used to help write robust programs. They provide an organized and structured
approach to robustness. Without exceptions, a program can become cluttered with if statements
that test for various possible error conditions. With exceptions, it becomes possible to write a
clean implementation of an algorithm that will handle all the normal cases. The exceptional cases
can be handled elsewhere, in a catch clause of a try statement.
When a program encounters an exceptional condition and has no way of handling it imme-
diately, the program can throw an exception. In some cases, it makes sense to throw an excep-
tion belonging to one of Java’s predefined classes, such as IllegalArgumentException or
IOException. However, if there is no standard class that adequately represents the exceptional
condition, the programmer can define a new exception class. The new class must extend the stan-
dard class Throwable or one of its subclasses. In general, if the programmer does not want to
require mandatory exception handling, the new class will extend RuntimeException (or one of
its subclasses). To create a new exception class that does require mandatory handling, the pro-
grammer can extend one of the other subclasses of Exception or can extend Exception itself.
Here, for example, is a class that extends Exception, and therefore requires mandatory ex-
ception handling when it is used:
public class ParseError extends Exception {
public ParseError(String message) {
// Create a ParseError object containing
// the given message as its error message.
super(message);
}
}
The class contains only a constructor that makes it possible to create a ParseError object
containing a given error message. (The statement “super(message)” calls a constructor in
the superclass, Exception.) The class inherits the getMessage() and printStackTrace()
methods from its superclass, off course. If e refers to an object of type ParseError, then the
method call e.getMessage() will retrieve the error message that was specified in the construc-
tor. But the main point of the ParseError class is simply to exist. When an object of type
ParseError is thrown, it indicates that a certain type of error has occurred. (Parsing, by the way,
refers to figuring out the syntax of a string. A ParseError would indicate, presumably, that some
string that is being processed by the program does not have the expected form.)
A throw statement can be used in a program to throw an error of type ParseError. The
constructor for the ParseError object must specify an error message. For example:
throw new ParseError("Encountered an illegal negative number.");
or
throw new ParseError("The word ’" + word
+ "’ is not a valid file name.");
If the throw statement does not occur in a try statement that catches the error, then the method
that contains the throw statement must declare that it can throw a ParseError by adding the
clause “throws ParseError” to the method heading. For example,
void getUserData() throws ParseError {
. . .
}
This would not be required if ParseError were defined as a subclass of
RuntimeException instead of Exception, since in that case exception handling for ParseErrors
would not be mandatory.

192
 A method that wants to handle ParseErrors can use a try statement with a catch clause that
catches ParseErrors. For example:
try {
getUserData();
processUserData();
}
catch (ParseError pe) {
. . . // Handle the error
}

Note that since ParseError is a subclass of Exception, a catch clause of the form “catch (Exception e)”
would also catch ParseErrors, along with any other object of type Exception.
Sometimes, it’s useful to store extra data in an exception object. For example,
class ShipDestroyed extends RuntimeException {
Ship ship; // Which ship was destroyed.
int where_x, where_y; // Location where ship was destroyed.
ShipDestroyed(String message, Ship s, int x, int y) {
// Constructor creates a ShipDestroyed object
// carrying an error message plus the information
// that the ship s was destroyed at location (x,y)
// on the screen.
super(message);
ship = s;
where_x = x;
where_y = y;
}
}

Here, a ShipDestroyed object contains an error message and some information about a ship
that was destroyed. This could be used, for example, in a statement:
if ( userShip.isHit() )
throw new ShipDestroyed("You’ve been hit!", userShip, xPos, yPos);

Note that the condition represented by a ShipDestroyed object might not even be considered
an error. It could be just an expected interruption to the normal flow of a game. Exceptions can
sometimes be used to handle such interruptions neatly.
The ability to throw exceptions is particularly useful in writing general-purpose methods and
classes that are meant to be used in more than one program. In this case, the person writing
the method or class often has no reasonable way of handling the error, since that person has no
way of knowing exactly how the method or class will be used. In such circumstances, a novice
programmer is often tempted to print an error message and forge ahead, but this is almost never
satisfactory since it can lead to unpredictable results down the line. Printing an error message and
terminating the program is almost as bad, since it gives the program no chance to handle the error.
The program that calls the method or uses the class needs to know that the error has occurred.
In languages that do not support exceptions, the only alternative is to return some special value
or to set the value of some variable to indicate that an error has occurred. For example, a method
may return the value −1 if the user’s input is illegal. However, this only does any good if the
main program bothers to test the return value. It is very easy to be lazy about checking for special
return values every time a method is called. And in this case, using −1 as a signal that an error has
occurred makes it impossible to allow negative return values. Exceptions are a cleaner way for a
method to react when it encounters an error.

193
9.4 Assertions

W E END THIS CHAPTER WITH A SHORT SECTION ON ASSERTIONS, another feature of the
Java programming language that can be used to aid in the development of correct and robust
programs.
Recall that a precondition is a condition that must be true at a certain point in a program, for
the execution of the program to continue correctly from that point. In the case where there is a
chance that the precondition might not be satisfied – for example, if it depends on input from the
user – then it’s a good idea to insert an if statement to test it. But then the question arises, What
should be done if the precondition does not hold? One option is to throw an exception. This will
terminate the program, unless the exception is caught and handled elsewhere in the program.
In many cases, of course, instead of using an if statement to test whether a precondition holds,
a programmer tries to write the program in a way that will guarantee that the precondition holds.
In that case, the test should not be necessary, and the if statement can be avoided. The problem
is that programmers are not perfect. In spite of the programmer’s intention, the program might
contain a bug that screws up the precondition. So maybe it’s a good idea to check the precondition
– at least during the debugging phase of program development.
Similarly, a postcondition is a condition that is true at a certain point in the program as a
consequence of the code that has been executed before that point. Assuming that the code is
correctly written, a postcondition is guaranteed to be true, but here again testing whether a desired
postcondition is actually true is a way of checking for a bug that might have screwed up the
postcondition. This is somthing that might be desirable during debugging.
The programming languages C and C++ have always had a facility for adding what are called
assertions to a program. These assertions take the form
“assert(condition)”, where condition is a boolean-valued expression. This condition expresses
a precondition or postcondition that should hold at that point in the program. When the computer
encounters an assertion during the execution of the program, it evaluates the condition. If the con-
dition is false, the program is terminated. Otherwise, the program continues normally. This allows
the programmer’s belief that the condition is true to be tested; if if it not true, that indicates that the
part of the program that preceded the assertion contained a bug. One nice thing about assertions
in C and C++ is that they can be “turned off” at compile time. That is, if the program is compiled
in one way, then the assertions are included in the compiled code. If the program is compiled
in another way, the assertions are not included. During debugging, the first type of compilation
is used. The release version of the program is compiled with assertions turned off. The release
version will be more efficient, because the computer won’t have to evaluate all the assertions.
Although early versions of Java did not have assertions, an assertion facility similar to the
one in C/C++ has been available in Java since version 1.4. As with the C/C++ version, Java
assertions can be turned on during debugging and turned off during normal execution. In Java,
however, assertions are turned on and off at run time rather than at compile time. An assertion in
the Java source code is always included in the compiled class file. When the program is run in the
normal way, these assertions are ignored; since the condition in the assertion is not evaluated in
this case, there is little or no performance penalty for having the assertions in the program. When
the program is being debugged, it can be run with assertions enabled, as discussed below, and then
the assertions can be a great help in locating and identifying bugs.
An assertion statement in Java takes one of the following two forms:
assert condition ; or assert condition : error−message ; where condition is a
boolean-valued expression and error-message is a string or an expression of type String. The
word “assert” is a reserved word in Java, which cannot be used as an identifier. An assertion
statement can be used anyplace in Java where a statement is legal.

194
 If a program is run with assertions disabled, an assertion statement is equivalent to an empty
statement and has no effect. When assertions are enabled and an assertion statement is en-
countered in the program, the condition in the assertion is evaluated. If the value is true, the
program proceeds normally. If the value of the condition is false, then an exception of type
java.lang.AssertionError is thrown, and the program will crash (unless the error is caught
by a try statement). If the assert statement includes an error-message, then the error message string
becomes the message in the AssertionError.
So, the statement “assert condition : error-message;” is similar to
if ( condition == false )
throw new AssertionError( error−message );

except that the if statement is executed whenever the program is run, and the assert statement is
executed only when the program is run with assertions enabled.
The question is, when to use assertions instead of exceptions? The general rule is to use
assertions to test conditions that should definitely be true, if the program is written correctly.
Assertions are useful for testing a program to see whether or not it is correct and for finding the
errors in an incorrect program. After testing and debugging, when the program is used in the
normal way, the assertions in the program will be ignored. However, if a problem turns up later,
the assertions are still there in the program to be used to help locate the error. If someone writes to
you to say that your program doesn’t work when he does such-and-such, you can run the program
with assertions enabled, do such-and-such, and hope that the assertions in the program will help
you locate the point in the program where it goes wrong.
Consider, for example, the root() method that calculates a root of a quadratic equation. If
you believe that your program will always call this method with legal arguments, then it would
make sense to write the method using assertions instead of exceptions:
/**
* Returns the larger of the two roots of the quadratic equation
* A*x*x + B*x + C = 0, provided it has any roots.
* Precondition: A != 0 and B*B − 4*A*C >= 0.
*/
static public double root( double A, double B, double C ) {
assert A != 0 : "Leading coefficient of quadratic equation cannot be zero.";
double disc = B*B − 4*A*C;
assert disc >= 0 : "Discriminant of quadratic equation cannot be negative.";
return (−B + Math.sqrt(disc)) / (2*A);
}

The assertions are not checked when the program is run in the normal way. If you are correct
in your belief that the method is never called with illegal arguments, then checking the conditions
in the assertions would be unnecessary. If your belief is not correct, the problem should turn up
during testing or debugging, when the program is run with the assertions enabled.
If the root() method is part of a software library that you expect other people to use, then
the situation is less clear. Sun’s Java documentation advises that assertions should not be used for
checking the contract of public methods: If the caller of a method violates the contract by passing
illegal parameters, then an exception should be thrown. This will enforce the contract whether or
not assertions are enabled. (However, while it’s true that Java programmers expect the contract
of a method to be enforced with exceptions, there are reasonable arguments for using assertions
instead, in some cases.)
On the other hand, it never hurts to use an assertion to check a postcondition of a method. A
postcondition is something that is supposed to be true after the method has executed, and it can be
tested with an assert statement at the end of the method. If the postcodition is false, there is a bug

195
in the method itself, and that is something that needs to be found during the development of the
method.
To have any effect, assertions must be enabled when the program is run. How to do this de-
pends on what programming environment you are using. In the usual command line environment,
assertions are enabled by adding the −enableassertions option to the java command that is
used to run the program. For example, if the class that contains the main program is RootFinder,
then the command
java −enableassertions RootFinder
will run the program with assertions enabled. The −enableassertions option can be abbrevi-
ated to −ea, so the command can alternatively be written as
java −ea RootFinder.
In fact, it is possible to enable assertions in just part of a program. An option of the form
“-ea:class-name” enables only the assertions in the specified class. Note that there are no spaces
between the -ea, the “:”, and the name of the class. To enable all the assertions in a package and in
its sub-packages, you can use an option of the form “-ea:package-name...”. To enable assertions
in the “default package” (that is, classes that are not specified to belong to a package, like almost
all the classes in this book), use “-ea:...”. For example, to run a Java program named “MegaPaint”
with assertions enabled for every class in the packages named “paintutils” and “drawing”, you
would use the command:
java −ea:paintutils... −ea:drawing... MegaPaint
If you are using the Eclipse integrated development environment, you can specify the -ea
option by creating a run configuration. Right-click the name of the main program class in the
Package Explorer pane, and select “Run As” from the pop-up menu and then “Run...” from the
submenu. This will open a dialog box where you can manage run configurations. The name of the
project and of the main class will be already be filled in. Click the “Arguments” tab, and enter -ea
in the box under “VM Arguments”. The contents of this box are added to the java command that
is used to run the program. You can enter other options in this box, including more complicated
enableassertions options such as -ea:paintutils.... When you click the “Run” button, the options
will be applied. Furthermore, they will be applied whenever you run the program, unless you
change the run configuration or add a new configuration. Note that it is possible to make two run
configurations for the same class, one with assertions enabled and one with assertions disabled.

196
 CHAPTER

10
I NPUT AND O UTPUT

Contents
9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Horror Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Java to the Rescue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Problems Remain in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
9.2 Writing Correct Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Provably Correct Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Robust Handling of Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
9.3 Exceptions and try..catch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Exceptions and Exception Classes . . . . . . . . . . . . . . . . . . . . . . . . . . 185
The try Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Throwing Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Mandatory Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Programming with Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
9.4 Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

10.1 Streams, Readers, and Writers

Without the ability to interact with the rest of the world, a program would be useless. The interac-
tion of a program with the rest of the world is referred to as input/output or I/O. Historically, one
of the hardest parts of programming language design has been coming up with good facilities for
doing input and output. A computer can be connected to many different types of input and output
devices. If a programming language had to deal with each type of device as a special case, the
complexity would be overwhelming. One of the major achievements in the history of program-
ming has been to come up with good abstractions for representing I/O devices. In Java, the main
I/O abstractions are called streams. Other I/O abstractions, such as “files” and “channels” also
exist, but in this section we will look only at streams. Every stream represents either a source of
input or a destination to which output can be sent.

197
Character and Byte Streams

When dealing with input/output, you have to keep in mind that there are two broad categories of
data: machine-formatted data and human-readable data. Machine-formatted data is represented
in binary form, the same way that data is represented inside the computer, that is, as strings of
zeros and ones. Human-readable data is in the form of characters. When you read a number
such as 3.141592654, you are reading a sequence of characters and interpreting them as a num-
ber. The same number would be represented in the computer as a bit-string that you would find
unrecognizable.
To deal with the two broad categories of data representation, Java has two broad categories of
streams: byte streams for machine-formatted data and character streams for human-readable data.
There are many predefined classes that represent streams of each type.
An object that outputs data to a byte stream belongs to one of the subclasses of the abstract
class OutputStream. Objects that read data from a byte stream belong to subclasses of Input-
Stream. If you write numbers to an OutputStream, you won’t be able to read the resulting data
yourself. But the data can be read back into the computer with an InputStream. The writing
and reading of the data will be very efficient, since there is no translation involved: the bits that
are used to represent the data inside the computer are simply copied to and from the streams.
For reading and writing human-readable character data, the main classes are the abstract
classes Reader and Writer. All character stream classes are subclasses of one of these. If a
number is to be written to a Writer stream, the computer must translate it into a human-readable
sequence of characters that represents that number. Reading a number from a Reader stream into
a numeric variable also involves a translation, from a character sequence into the appropriate bit
string. (Even if the data you are working with consists of characters in the first place, such as words
from a text editor, there might still be some translation. Characters are stored in the computer as
16−bit Unicode values. For people who use Western alphabets, character data is generally stored
in files in ASCII code, which uses only 8 bits per character. The Reader and Writer classes take
care of this translation, and can also handle non-western alphabets in countries that use them.)
Byte streams can be useful for direct machine-to-machine communication, and they can some-
times be useful for storing data in files, especially when large amounts of data need to be stored
efficiently, such as in large databases. However, binary data is fragile in the sense that its mean-
ing is not self-evident. When faced with a long series of zeros and ones, you have to know what
information it is meant to represent and how that information is encoded before you will be able
to interpret it. Of course, the same is true to some extent for character data, which is itself coded
into binary form. But the binary encoding of character data has been standardized and is well
understood, and data expressed in character form can be made meaningful to human readers. The
current trend seems to be towards increased use of character data, represented in a way that will
make its meaning as self-evident as possible.
I should note that the original version of Java did not have character streams, and that for
ASCII-encoded character data, byte streams are largely interchangeable with character streams. In
fact, the standard input and output streams, System.in and System.out, are byte streams rather
than character streams. However, you should use Readers and Writers rather than InputStreams
and OutputStreams when working with character data.
The standard stream classes discussed in this section are defined in the package java.io,
along with several supporting classes. You must import the classes from this package if you want to
use them in your program. That means either importing individual classes or putting the directive
“import java.io.*;” at the beginning of your source file. Streams are necessary for working with
files and for doing communication over a network. They can be also used for communication
between two concurrently running threads, and there are stream classes for reading and writing
data stored in the computer’s memory.

198
 The beauty of the stream abstraction is that it is as easy to write data to a file or to send data
over a network as it is to print information on the screen.
The basic I/O classes Reader, Writer, InputStream, and OutputStream provide only
very primitive I/O operations. For example, the InputStream class declares the instance method
public int read() throws IOException for reading one byte of data, as a number in
the range 0 to 255, from an input stream. If the end of the input stream is encountered, the
read() method will return the value −1 instead. If some error occurs during the input attempt,
an exception of type IOException is thrown. Since IOException is an exception class that
requires mandatory exception-handling, this means that you can’t use the read() method except
inside a try statement or in a method that is itself declared with a “throws IOException”
clause.
The InputStream class also defines methods for reading several bytes of data in one step
into an array of bytes. However, InputStream provides no convenient methods for reading other
types of data, such as int or double, from a stream. This is not a problem because you’ll never use
an object of type InputStream itself. Instead, you’ll use subclasses of InputStream that add
more convenient input methods to InputStream’s rather primitive capabilities. Similarly, the
OutputStream class defines a primitive output method for writing one byte of data to an output
stream. The method is defined as:public void write(int b) throws IOException The
parameter is of type int rather than byte, but the parameter value is type-cast to type byte before it is
written; this effectively discards all but the eight low order bytes of b. Again, in practice, you will
almost always use higher-level output operations defined in some subclass of OutputStream.
The Reader and Writer classes provide identical low-level read and write methods. As
in the byte stream classes, the parameter of the write(c) method in Writer and the return value
of the read() method in Reader are of type int, but in these character-oriented classes, the I/O
operations read and write characters rather than bytes. The return value of read() is −1 if the end
of the input stream has been reached. Otherwise, the return value must be type-cast to type char to
obtain the character that was read. In practice, you will ordinarily use higher level I/O operations
provided by sub-classes of Reader and Writer, as discussed below.

PrintWriter
One of the neat things about Java’s I/O package is that it lets you add capabilities to a stream by
“wrapping” it in another stream object that provides those capabilities. The wrapper object is also
a stream, so you can read from or write to it–but you can do so using fancier operations than those
available for basic streams.
For example, PrintWriter is a subclass of Writer that provides convenient methods for
outputting human-readable character representations of all of Java’s basic data types. If you have
an object belonging to the Writer class, or any of its subclasses, and you would like to use
PrintWriter methods to output data to that Writer, all you have to do is wrap the Writer
in a PrintWriter object. You do this by constructing a new PrintWriter object, using the
Writer as input to the constructor. For example, if charSink is of type Writer, then you could
say
PrintWriter printableCharSink = new PrintWriter(charSink);

When you output data to printableCharSink, using the high-level output methods in
PrintWriter, that data will go to exactly the same place as data written directly to charSink.
You’ve just provided a better interface to the same output stream. For example, this allows you to
use PrintWriter methods to send data to a file or over a network connection.
For the record, if out is a variable of type PrintWriter, then the following methods are
defined:

199
 • out.print(x)–prints the value of x, represented in the form of a string of characters, to
the output stream; x can be an expression of any type, including both primitive types and
object types. An object is converted to string form using its toString() method. A null
value is represented by the string “null”.

• out.println()–outputs an end-of-line to the output stream.

• out.println(x)–outputs the value of x, followed by an end-of-line; this is equivalent to

out.print(x) followed by out.println().

• out.printf(formatString, x1, x2, ...)–does formated output of x1, x2, . . .

to the output stream. The first parameter is a string that specifies the format of the out-
put. There can be any number of additional parameters, of any type, but the types of the
parameters must match the formatting directives in the format string.

Note that none of these methods will ever throw an IOException. Instead, the PrintWriter
class includes the method public boolean checkError() which will return true if any er-
ror has been encountered while writing to the stream. The PrintWriter class catches any
IOExceptions internally, and sets the value of an internal error flag if one occurs. The checkError()
method can be used to check the error flag. This allows you to use PrintWriter methods with-
out worrying about catching exceptions. On the other hand, to write a fully robust program, you
should call checkError() to test for possible errors whenever you used a PrintWriter.

Data Streams
When you use a PrintWriter to output data to a stream, the data is converted into the sequence
of characters that represents the data in human-readable form. Suppose you want to output the
data in byte-oriented, machine-formatted form? The java.io package includes a byte-stream
class, DataOutputStream that can be used for writing data values to streams in internal, binary-
number format.
DataOutputStream bears the same relationship to OutputStream that PrintWriter bears to
Writer. That is, whereas OutputStream only has methods for outputting bytes, DataOutputStream
has methods writeDouble(double x) for outputting values of type double, writeInt(int x)
for outputting values of type int, and so on. Furthermore, you can wrap any OutputStream in a
DataOutputStream so that you can use the higher level output methods on it. For example, if
byteSink is of type classname, you could say
DataOutputStream dataSink = new DataOutputStream(byteSink);

to wrap byteSink in a DataOutputStream, dataSink.

For input of machine-readable data, such as that created by writing to a
DataOutputStream, java.io provides the class DataInputStream. You can wrap any InputStream
in aDataInputStream object to provide it with the ability to read data of various types from the
byte-stream. The methods in theDataInputStream for reading binary data are called readDou-
ble(), readInt(), and so on. Data written by a DataOutputStream is guaranteed to be in a format
that can be read by a DataInputStream. This is true even if the data stream is created on one
type of computer and read on another type of computer. The cross-platform compatibility of binary
data is a major aspect of Java’s platform independence.
In some circumstances, you might need to read character data from an
InputStream or write character data to an OutputStream. This is not a problem, since charac-
ters, like all data, are represented as binary numbers. However, for character data, it is convenient

200
to use Reader and Writer instead of InputStream and OutputStream. To make this pos-
sible, you can wrap a byte stream in a character stream. If byteSource is a variable of type
InputStream and byteSink is of type OutputStream, then the statements
Reader charSource = new InputStreamReader( byteSource );
Writer charSink = new OutputStreamWriter( byteSink );
create character streams that can be used to read character data from and write character data to the
byte streams. In particular, the standard input stream System.in, which is of type InputStream
for historical reasons, can be wrapped in a Reader to make it easier to read character data from
standard input:
Reader charIn = new InputStreamReader( System.in );
As another application, the input and output streams that are associated with a network con-
nection are byte streams rather than character streams, but the byte streams can be wrapped in
character streams to make it easy to send and receive character data over the network.

Reading Text
Still, the fact remains that much I/O is done in the form of human-readable characters. In view of
this, it is surprising that Java does not provide a standard character input class that can read charac-
ter data in a manner that is reasonably symmetrical with the character output capabilities of Print-
Writer. There is one basic case that is easily handled by a standard class. The BufferedReader
class has a method public String readLine() throws IOException that reads one line
of text from its input source. If the end of the stream has been reached, the return value is null.
When a line of text is read, the end-of-line marker is read from the input stream, but it is not part of
the string that is returned. Different input streams use different characters as end-of-line markers,
but the readLine method can deal with all the common cases.
Line-by-line processing is very common. Any Reader can be wrapped in a
BufferedReader to make it easy to read full lines of text. If reader is of type Reader, then a
BufferedReader wrapper can be created for reader with
BufferedReader in = new BufferedReader( reader );.
This can be combined with the InputStreamReader class that was mentioned above to read
lines of text from an InputStream. For example, we can apply this to System.in:
BufferedReader in; // BufferedReader for reading from standard input.
in = new BufferedReader( new InputStreamReader( System.in ) );
try {
String line = in.readLine();
while ( line != null && line.length() > 0 ) {
processOneLineOfInput( line );
line = in.readLine();
}
}
catch (IOException e) {
}
This code segment reads and processes lines from standard input until either an empty line or
an end-of-stream is encountered. (An end-of-stream is possible even for interactive input. For ex-
ample, on at least some computers, typing a Control-D generates an end-of-stream on the standard
input stream.) The try..catch statement is necessary because the readLine method can throw
an exception of type IOException, which requires mandatory exception handling; an alternative
to try..catch would be to declare that the method that contains the code “throws IOException”.
Also, remember that BufferedReader, InputStreamReader, and IOException must be im-
ported from the package java.io.

201
The Scanner Class
Since its introduction, Java has been notable for its lack of built-in support for basic input, and for
its reliance on fairly advanced techniques for the support that it does offer. (This is my opinion,
at least.) The Scanner class was introduced in Java 5.0 to make it easier to read basic data types
from a character input source. It does not (again, in my opinion) solve the problem completely,
but it is a big improvement. The Scanner class is in the package java.util.
Input methods are defined as instance methods in the Scanner class, so to use the class,
you need to create a Scanner object. The constructor specifies the source of the characters that
the Scanner will read. The scanner acts as a wrapper for the input source. The source can be
a Reader, an InputStream, a String, or a File. (If a String is used as the input source, the
Scanner will simply read the characters in the string from beginning to end, in the same way that
it would process the same sequence of characters from a stream. The File class will be covered in
the next section.) For example, you can use a Scanner to read from standard input by saying:
Scanner standardInputScanner = new Scanner( System.in );
and if charSource is of type Reader, you can create a Scanner for reading from charSource with:
Scanner scanner = new Scanner( charSource );
When processing input, a scanner usually works with tokens. A token is a meaningful string of
characters that cannot, for the purposes at hand, be further broken down into smaller meaningful
pieces. A token can, for example, be an individual word or a string of characters that represents
a value of type double. In the case of a scanner, tokens must be separated by “delimiters.” By
default, the delimiters are whitespace characters such as spaces and end-of-line markers. In normal
processing, whitespace characters serve simply to separate tokens and are discarded by the scanner.
A scanner has instance methods for reading tokens of various types. Suppose that scanner is an
object of type Scanner. Then we have:
• scanner.next()–reads the next token from the input source and returns it as a String.
• scanner.nextInt(), scanner.nextDouble(), and so on–reads the next token from
the input source and tries to convert it to a value of type int, double, and so on. There are
methods for reading values of any of the primitive types.
• scanner.nextLine()–reads an entire line from the input source, up to the next end-of-
line and returns the line as a value of type String. The end-of-line marker is read but is
not part of the return value. Note that this method is not based on tokens. An entire line is
read and returned, including any whitespace characters in the line.
All of these methods can generate exceptions. If an attempt is made to read past the end of in-
put, an exception of type NoSuchElementException is thrown. Methods such as scanner.getInt()
will throw an exception of type InputMismatchException if the next token in the input does
not represent a value of the requested type. The exceptions that can be generated do not require
mandatory exception handling.
The Scanner class has very nice look-ahead capabilities. You can query a scanner to deter-
mine whether more tokens are available and whether the next token is of a given type. If scanner
is of type Scanner:
• scanner.hasNext()–returns a boolean value that is true if there is at least one more token
in the input source.
• scanner.hasNextInt(), scanner.hasNextDouble(), and so on–returns a
boolean value that is true if there is at least one more token in the input source and that
token represents a value of the requested type.

202
 • scanner.hasNextLine()–returns a boolean value that is true if there is at least one more
line in the input source.
Although the insistence on defining tokens only in terms of delimiters limits the usability of
scanners to some extent, they are easy to use and are suitable for many applications.

10.2 Files
The data and programs in a computer’s main memory survive only as long as the power is on.
For more permanent storage, computers use files, which are collections of data stored on a hard
disk, on a USB memory stick, on a CD-ROM, or on some other type of storage device. Files are
organized into directories (sometimes called folders). A directory can hold other directories, as
well as files. Both directories and files have names that are used to identify them.
Programs can read data from existing files. They can create new files and can write data to files.
In Java, such input and output can be done using streams. Human-readable character data is read
from a file using an object belonging to the class FileReader, which is a subclass of Reader.
Similarly, data is written to a file in human-readable format through an object of type FileWriter,
a subclass of Writer. For files that store data in machine format, the appropriate I/O classes
are FileInputStream and FileOutputStream. In this section, I will only discuss character-
oriented file I/O using the FileReader and FileWriter classes. However, FileInputStream
and FileOutputStream are used in an exactly parallel fashion. All these classes are defined in
the java.io package.
It’s worth noting right at the start that applets which are downloaded over a network connection
are not allowed to access files (unless you have made a very foolish change to your web browser’s
configuration). This is a security consideration. You can download and run an applet just by
visiting a Web page with your browser. If downloaded applets had access to the files on your
computer, it would be easy to write an applet that would destroy all the data on a computer that
downloads it. To prevent such possibilities, there are a number of things that downloaded applets
are not allowed to do. Accessing files is one of those forbidden things. Standalone programs
written in Java, however, have the same access to your files as any other program. When you write
a standalone Java application, you can use all the file operations described in this section.

Reading and Writing Files

The FileReader class has a constructor which takes the name of a file as a parameter and creates
an input stream that can be used for reading from that file. This constructor will throw an exception
of type FileNotFoundException if the file doesn’t exist. It requires mandatory exception
handling, so you have to call the constructor in a try..catch statement (or inside a method that
is declared to throw the exception). For example, suppose you have a file named “data.txt”, and
you want your program to read data from that file. You could do the following to create an input
stream for the file:
FileReader data; // (Declare the variable before the
// try statement, or else the variable
// is local to the try block and you won’t
// be able to use it later in the program.)

try {
data = new FileReader("data.txt"); // create the stream
}
catch (FileNotFoundException e) {
... // do something to handle the error −− maybe, end the program

203
 }
The FileNotFoundException class is a subclass of IOException, so it would be accept-
able to catch IOExceptions in the above try...catch statement. More generally, just about
any error that can occur during input/output operations can be caught by a catch clause that handles
IOException.
Once you have successfully created a FileReader, you can start reading data from it. But
since FileReaders have only the primitive input methods inherited from the basic Reader class,
you will probably want to wrap your FileReader in a Scanner, or in some other wrapper class.
Working with output files is no more difficult than this. You simply create an object belonging
to the class FileWriter. You will probably want to wrap this output stream in an object of type
PrintWriter. For example, suppose you want to write data to a file named “result.dat”. Since
the constructor for FileWriter can throw an exception of type IOException, you should use
a try..catch statement:

PrintWriter result;

try {
result = new PrintWriter(new FileWriter("result.dat"));
}
catch (IOException e) {
... // handle the exception
}
If no file named result.dat exists, a new file will be created. If the file already exists, then the
current contents of the file will be erased and replaced with the data that your program writes to
the file. This will be done without any warning. To avoid overwriting a file that already exists,
you can check whether a file of the same name already exists before trying to create the stream, as
discussed later in this section. An IOException might occur in the PrintWriter constructor
if, for example, you are trying to create a file on a disk that is “write-protected,” meaning that it
cannot be modified.
After you are finished using a file, it’s a good idea to close the file, to tell the operating system
that you are finished using it. You can close a file by calling the close() method of the associated
stream. Once a file has been closed, it is no longer possible to read data from it or write data to it,
unless you open it again as a new stream. (Note that for most stream classes, the close() method
can throw an IOException, which must be handled; PrintWriter overrides this method so
that it cannot throw such exceptions.) If you forget to close a file, the file will ordinarily be closed
automatically when the program terminates or when the file object is garbage collected, but in the
case of an output file, some of the data that has been written to the file might be lost. This can
occur because data that is written to a file can be buffered; that is, the data is not sent immediately
to the file but is retained in main memory (in a “buffer”) until a larger chunk of data is ready to be
written. This is done for efficiency. The close() method of an output stream will cause all the
data in the buffer to be sent to the file. Every output stream also has a flush() method that can
be called to force any data in the buffer to be written to the file without closing the file.
As a complete example, here is a program that will read numbers from a file named data.dat,
and will then write out the same numbers in reverse order to another file named result.dat. It is
assumed that data.dat contains only one number on each line. Exception-handling is used to check
for problems along the way. Although the application is not a particularly useful one, this program
demonstrates the basics of working with files. (By the way, at the end of this program, you’ll
find our first example of a finally clause in a try statement. When the computer executes a try
statement, the commands in its finally clause are guaranteed to be executed, no matter what.)

204
import java.io.*;
import java.util.ArrayList;
/**
* Reads numbers from a file named data.dat and writes them to a file
* named result.dat in reverse order. The input file should contain
* exactly one real number per line.
*/
public class ReverseFile {

public static void main(String[] args) {

TextReader data; // Character input stream for reading data.
PrintWriter result; // Character output stream for writing data.
ArrayList<Double> numbers; // An ArrayList for holding the data.
numbers = new ArrayList<Double>();

try { // Create the input stream.

data = new TextReader(new FileReader("data.dat"));
}
catch (FileNotFoundException e) {
System.out.println("Can’t find file data.dat!");
return; // End the program by returning from main().
}

try { // Create the output stream.

result = new PrintWriter(new FileWriter("result.dat"));
}
catch (IOException e) {
System.out.println("Can’t open file result.dat!");
System.out.println("Error: " + e);
data.close(); // Close the input file.
return; // End the program.
}
try {

// Read numbers from the input file, adding them to the ArrayList.
while ( data.eof() == false ) { // Read until end−of−file.
double inputNumber = data.getlnDouble();
numbers.add( inputNumber );
}
// Output the numbers in reverse order.

for (int i = numbers.size()−1; i >= 0; i−−)

result.println(numbers.get(i));
System.out.println("Done!");
}
catch (IOException e) {
// Some problem reading the data from the input file.
System.out.println("Input Error: " + e.getMessage());
}
finally {
// Finish by closing the files, whatever else may have happened.
data.close();
result.close();
}
} // end of main()
} // end of class

205
Files and Directories
The subject of file names is actually more complicated than I’ve let on so far. To fully specify
a file, you have to give both the name of the file and the name of the directory where that file is
located. A simple file name like “data.dat” or “result.dat” is taken to refer to a file in a directory
that is called the current directory (also known as the “default directory” or “working directory”).
The current directory is not a permanent thing. It can be changed by the user or by a program.
Files not in the current directory must be referred to by a path name, which includes both the name
of the file and information about the directory where it can be found.
To complicate matters even further, there are two types of path names, absolute path names
and relative path names. An absolute path name uniquely identifies one file among all the files
available to the computer. It contains full information about which directory the file is in and what
the file’s name is. A relative path name tells the computer how to locate the file starting from the
current directory.
It’s reasonably safe to say, though, that if you stick to using simple file names only, and if the
files are stored in the same directory with the program that will use them, then you will be OK.
It is possible for a Java program to find out the absolute path names for two important directo-
ries, the current directory and the user’s home directory. The names of these directories are system
properties, and they can be read using the method calls:
• System.getProperty(‘‘user.dir’’)–returns the absolute path name of the current
directory as a String.

• System.getProperty(‘‘user.home’’)–returns the absolute path name of the user’s

home directory as a String.
To avoid some of the problems caused by differences in path names between platforms, Java
has the class java.io.File. An object belonging to this class represents a file. More precisely,
an object of type File represents a file name rather than a file as such. The file to which the name
refers might or might not exist. Directories are treated in the same way as files, so a File object
can represent a directory just as easily as it can represent a file.
A File object has a constructor, new File(String), that creates a File object from a path
name. The name can be a simple name, a relative path, or an absolute path. For example, new
File(“data.dat”) creates a File object that refers to a file named data.dat, in the current directory.
Another constructor has two parameters: new File(File, String). The first is a File object
that refers to the directory that contains the file. The second can be the name of the file or a relative
path from the directory to the file.
File objects contain several useful instance methods. Assuming that file is a variable of type
File, here are some of the methods that are available:

• file.exists()–This boolean-valued method returns true if the file named by the File
object already exists. You can use this method if you want to avoid overwriting the contents
of an existing file when you create a new FileWriter.

• file.isDirectory()–This boolean-valued method returns true if the File object refers

to a directory. It returns false if it refers to a regular file or if no file with the given name
exists.

• file.delete()–Deletes the file, if it exists. Returns a boolean value to indicate whether

the file was successfully deleted.

• file.list()–If the File object refers to a directory, this method returns an array of type
String[ ] containing the names of the files in that directory. Otherwise, it returns null.

206
 Here, for example, is a program that will list the names of all the files in a directory specified
by the user. Just for fun, I have used a Scanner to read the user’s input:
import java.io.File;
import java.util.Scanner;

/**
* This program lists the files in a directory specified by
* the user. The user is asked to type in a directory name.
* If the name entered by the user is not a directory, a
* message is printed and the program ends.
*/

public class DirectoryList {

public static void main(String[] args) {

String directoryName; // Directory name entered by the user.

File directory; // File object referring to the directory.
String[] files; // Array of file names in the directory.
Scanner scanner; // For reading a line of input from the user.

scanner = new Scanner(System.in); // scanner reads from standard input.

System.out.print("Enter a directory name: ");

directoryName = scanner.nextLine().trim();
directory = new File(directoryName);

if (directory.isDirectory() == false) {
if (directory.exists() == false)
System.out.println("There is no such directory!");
else
System.out.println("That file is not a directory.");
}
else {
files = directory.list();
System.out.println("Files in directory \"" + directory + "\":");
for (int i = 0; i < files.length; i++)
System.out.println(" " + files[i]);
}

} // end main()

} // end class DirectoryList

All the classes that are used for reading data from files and writing data to files have constructors
that take a File object as a parameter. For example, if file is a variable of type File, and you
want to read character data from that file, you can create a FileReader to do so by saying
new FileReader(file). If you want to use a TextReader to read from the file, you could
say:
TextReader data;

try {
data = new TextReader( new FileReader(file) );
}

207
 catch (FileNotFoundException e) {
... // handle the exception
}

10.3 Programming With Files

I N THIS SECTION, we look at several programming examples that work with files, using the
techniques that were introduced previously.

Copying a File
As a first example, we look at a simple command-line program that can make a copy of a file.
Copying a file is a pretty common operation, and every operating system already has a command
for doing it. However, it is still instructive to look at a Java program that does the same thing. Many
file operations are similar to copying a file, except that the data from the input file is processed in
some way before it is written to the output file. All such operations can be done by programs with
the same general form.
Since the program should be able to copy any file, we can’t assume that the data in the file
is in human-readable form. So, we have to use InputStream and OutputStream to operate
on the file rather than Reader and Writer. The program simply copies all the data from the
InputStream to the OutputStream, one byte at a time. If source is the variable that refers to the
InputStream, then the method source.read() can be used to read one byte. This method returns
the value −1 when all the bytes in the input file have been read. Similarly, if copy refers to the
OutputStream, then copy.write(b) writes one byte to the output file. So, the heart of the program
is a simple while loop. As usual, the I/O operations can throw exceptions, so this must be done in
a TRY.. CATCH statement:
while(true) {
int data = source.read();
if (data < 0)
break;
copy.write(data);
}

The file-copy command in an operating system such as UNIX uses command line arguments to
specify the names of the files. For example, the user might say “copy original.dat backup.dat”
to copy an existing file, original.dat, to a file named backup.dat. Command-line arguments
can also be used in Java programs. The command line arguments are stored in the array of strings,
args, which is a parameter to the main() method. The program can retrieve the command-line
arguments from this array. For example, if the program is named CopyFile and if the user runs
the program with the command “java CopyFile work.dat oldwork.dat”, then in the pro-
gram, args[0] will be the string “work.dat” and args[1] will be the string “oldwork.dat”.
The value of args.length tells the program how many command-line arguments were specified
by the user.
My CopyFile program gets the names of the files from the command-line arguments. It prints
an error message and exits if the file names are not specified. To add a little interest, there are two
ways to use the program. The command line can simply specify the two file names. In that case,
if the output file already exists, the program will print an error message and end. This is to make
sure that the user won’t accidently overwrite an important file. However, if the command line
has three arguments, then the first argument must be “-f” while the second and third arguments
are file names. The -f is a command-line option, which is meant to modify the behavior of the

208
program. The program interprets the -f to mean that it’s OK to overwrite an existing program.
(The “f” stands for “force,” since it forces the file to be copied in spite of what would otherwise
have been considered an error.) You can see in the source code how the command line arguments
are interpreted by the program:

import java.io.*;
/** Makes a copy of a file. The original file and the name of the
* copy must be given as command−line arguments. In addition, the
* first command−line argument can be "−f"; if present, the program
* will overwrite an existing file; if not, the program will report
* an error and end if the output file already exists. The number
* of bytes that are copied is reported. */
public class CopyFile {
public static void main(String[] args) {

String sourceName; //Name of the source file,specified on the command line.

String copyName; // Name of the copy specified on the command line.
InputStream source; // Stream for reading from the source file.
OutputStream copy; // Stream for writing the copy.
boolean force; // This is set to true if the "−f" option
// is specified on the command line.
int byteCount; // Number of bytes copied from the source file.

/* Get file names from the command line and check for the
presence of the −f option. If the command line is not one
of the two possible legal forms, print an error message and
end this program. */
if (args.length == 3 && args[0].equalsIgnoreCase("−f")) {
sourceName = args[1];
copyName = args[2];
force = true;
}
else if (args.length == 2) {
sourceName = args[0];
copyName = args[1];
force = false;
}
else {
System.out.println("Usage:java CopyFile <source−file> <copy−name>");
System.out.println("or java CopyFile −f <source−file> <copy−name>");
return;
}

/* Create the input stream. If an error occurs, end the program. */

try {
source = new FileInputStream(sourceName);
}
catch (FileNotFoundException e) {
System.out.println("Can’t find file \"" + sourceName + "\".");
return;
}
/* If the output file already exists and the −f option was not
specified, print an error message and end the program. */
File file = new File(copyName);
if (file.exists() && force == false) {
System.out.println(

209
 "Output file exists. Use the −f option to replace it.");
return;
}
/* Create the output stream. If an error occurs, end the program. */

try {
copy = new FileOutputStream(copyName);
}
catch (IOException e) {
System.out.println("Can’t open output file \"" + copyName + "\".");
return;
}

/* Copy one byte at a time from the input stream to the output
stream, ending when the read() method returns −1 (which is
the signal that the end of the stream has been reached). If any
error occurs, print an error message. Also print a message if
the file has been copied successfully. */
byteCount = 0;
try {
while (true) {
int data = source.read();
if (data < 0)
break;
copy.write(data);
byteCount++;
}
source.close();
copy.close();
System.out.println("Successfully copied " + byteCount + " bytes.");
}
catch (Exception e) {
System.out.println("Error occurred while copying. "
+ byteCount + " bytes copied.");
System.out.println("Error: " + e);
}
} // end main()
} // end class CopyFile

210