You have used a good number of classes in the preceding chapters and probably designed a few classes yourself as part of your programming assignments. Designing a class can be a challenge—it is not always easy to tell how to start or whether the result is of good quality.

What makes a good class? Most importantly, a class should represent a single conceptfrom a problem domain. Some of the classes that you have seen represent concepts from mathematics:

Other classes are abstractions of real-life entities:

For these classes, the properties of a typical object are easy to understand. A Rectangle object has a width and height. Given a BankAccount object, you can deposit and withdraw money. Generally, concepts from the part of the universe that a program concerns, such as science, business, or a game, make good classes. The name for such a class should be a noun that describes the concept. In fact, a simple rule of thumb for getting started with class design is to look for nouns in the problem description.

One useful category of classes can be described as actors. Objects of an actor class carry out certain tasks for you. Examples of actors are the Scanner class of Chapter 4 and the Random class in Chapter 6. A Scanner object scans a stream for numbers and strings. A Random object generates random numbers. It is a good idea to choose class names for actors that end in "-er" or "-or". (A better name for the Random class might be RandomNumberGenerator.)

Very occasionally, a class has no objects, but it contains a collection of related static methods and constants. The Math class is a typical example. Such a class is called a utility class.

Finally, you have seen classes with only a main method. Their sole purpose is to start a program. From a design perspective, these are somewhat degenerate examples of classes.

What might not be a good class? If you can't tell from the class name what an object of the class is supposed to do, then you are probably not on the right track. For example, your homework assignment might ask you to write a program that prints paychecks. Suppose you start by trying to design a class PaycheckProgram. What would an object of this class do? An object of this class would have to do everything that the homework needs to do. That doesn't simplify anything. A better class would be Paycheck. Then your program can manipulate one or more Paycheck objects.

Another common mistake is to turn a single operation into a class. For example, if your homework assignment is to compute a paycheck, you may consider writing a class ComputePaycheck. But can you visualize a "ComputePaycheck" object? The fact that "ComputePaycheck" isn't a noun tips you off that you are on the wrong track. On the other hand, a Paycheck class makes intuitive sense. The word "paycheck" is a noun. You can visualize a paycheck object. You can then think about useful methods of the Paycheck class, such as computeTaxes, that help you solve the assignment.

2. Your job is to write a program that plays chess. Might ChessBoard be an appropriate class? How about MovePiece?

In this section you will learn two useful criteria for analyzing the quality of a class—qualities of its public interface.

A class should represent a single concept. The public methods and constants that the public interface exposes should be cohesive. That is, all interface features should be closely related to the single concept that the class represents.

If you find that the public interface of a class refers to multiple concepts, then that is a good sign that it may be time to use separate classes instead. Consider, for example, the public interface of the CashRegister class in Chapter 4:

public class CashRegister
{
   public static final double NICKEL_VALUE = 0.05;
   public static final double DIME_VALUE = 0.1;
   public static final double QUARTER_VALUE = 0.25;
   ...

public void enterPayment(int dollars, int quarters,
         int dimes, int nickels, int pennies)
   ...
}

There are really two concepts here: a cash register that holds coins and computes their total, and the values of individual coins. (For simplicity, we assume that the cash register only holds coins, not bills. Exercise P8.1 discusses a more general solution.)

It makes sense to have a separate Coin class and have coins responsible for knowing their values.

public class Coin
{
    ...
   public Coin(double aValue, String aName) { ... }
   public double getValue() { ... }
    ...
}

Then the CashRegister class can be simplified:

public class CashRegister
{
    ...
   public void enterPayment(int coinCount, Coin coinType) { ... }
    ...
}

Now the CashRegister class no longer needs to know anything about coin values. The same class can equally well handle euros or zorkmids!

This is clearly a better solution, because it separates the responsibilities of the cash register and the coins. The only reason we didn't follow this approach in Chapter 4 was to keep the CashRegister example simple.

Many classes need other classes in order to do their jobs. For example, the restructured CashRegister class now depends on the Coin class to determine the value of the payment.

To visualize relationships, such as dependence between classes, programmers draw class diagrams. In this book, we use the UML ("Unified Modeling Language") notation for objects and classes. UML is a notation for object-oriented analysis and design invented by Grady Booch, Ivar Jacobson, and James Rumbaugh, three leading researchers in object-oriented software development. The UML notation distinguishes between object diagrams and class diagrams. In an object diagram the class names are underlined; in a class diagram the class names are not underlined. In a class diagram, you denote dependency by a dashed line with a →-shaped open arrow tip that points to the dependent class. Figure 1 shows a class diagram indicating that the CashRegister class depends on the Coin class.

Figure 8.1. Dependency Relationship Between the CashRegister and Coin Classes

Figure 8.2. High and Low Coupling Between Classes

Note that the Coin class does not depend on the CashRegister class. Coins have no idea that they are being collected in cash registers, and they can carry out their work without ever calling any method in the CashRegister class.

If many classes of a program depend on each other, then we say that the couplingbetween classes is high. Conversely, if there are few dependencies between classes, then we say that the coupling is low (see Figure 2).

Why does coupling matter? If the Coin class changes in the next release of the program, all the classes that depend on it may be affected. If the change is drastic, the coupled classes must all be updated. Furthermore, if we would like to use a class in another program, we have to take with it all the classes on which it depends. Thus, we want to remove unnecessary coupling between classes.

4. Why does the Coin class not depend on the CashRegister class?

5. Why should coupling be minimized between classes?

JOptionPane.showInputDialog(promptString)

JOptionPane.showMessageDialog(null, messageString)

When analyzing a program that consists of many classes, it is not only important to understand which parts of the program use a given class. We also want to understand who modifies objects of a class. The following sections are concerned with this aspect of class design.

Recall that a mutator method modifies the object on which it is invoked, whereas an accessor method merely accesses information without making any modifications. For example, in the BankAccount class, the deposit and withdraw methods are mutator methods. Calling

account.deposit(1000);

modifies the state of the account object, but calling

double balance = account.getBalance();

does not modify the state of account.

You can call an accessor method as many times as you like—you always get the same answer, and the method does not change the state of your object. That is clearly a desirable property, because it makes the behavior of such a method very predictable.

Some classes have been designed to have only accessor methods and no mutator methods at all. Such classes are called immutable. An example is the String class. Once a string has been constructed, its content never changes. No method in the String class can modify the contents of a string. For example, the toUpperCase method does not change characters from the original string. Instead, it constructs a newstring that contains the uppercase characters:

String name = "John Q. Public";
String uppercased = name.toUpperCase(); // name is not changed

An immutable class has a major advantage: It is safe to give out references to its objects freely. If no method can change the object's value, then no code can modify the object at an unexpected time. In contrast, if you give out a BankAccount reference to any other method, you have to be aware that the state of your object may change—the other method can call the deposit and withdraw methods on the reference that you gave it.

7. Is the Rectangle class immutable?

A side effectof a method is any kind of modification of data that is observable outside the method. Mutator methods have a side effect, namely the modification of the implicit parameter. For example, when you call

harrysChecking.deposit(1000);

you can tell that something changed by calling harrysChecking.getBalance().

Now consider the explicit parameter of a method, such as studentNames here:

public class GradeBook
{
   ...
   /**

*/
   public void addStudents(ArrayList<String> studentNames)
   {
      while (studentNames.size() > 0)
      {
         String name = studentNames.remove(0); // Not recommended
         Add name to gradebook
      }
   }
}

This method removes all names from the studentNames parameter as it adds them to the grade book. That too is a side effect. After a call

book.addStudents(listOfNames);

the call listOfNames.size() returns 0. Such a side effect would not be what most programmers expect. It is better if the method reads the names from the list without modifying it.

Now consider the following method:

public class BankAccount
{
   ...
   /**

*/
   public void transfer(double amount, BankAccount other)
   {
      balance = balance - amount;
      other.deposit(amount);
   }
}

This method modifies both the implicit parameter and the explicit parameter other. Neither side effect is surprising for a transfer method, and there is no reason to avoid them.

Another example of a side effect is output. Consider how we have always printed a bank balance:

System.out.println("The balance is now $" + momsSavings.getBalance());

Why don't we simply have a printBalance method?

public void printBalance() // Not recommended
{
   System.out.println("The balance is now $" + balance);
}

That would be more convenient when you actually want to print the value. But, of course, there are cases when you want the value for some other purpose. Thus, you can't simply drop the getBalance method in favor of printBalance.

More importantly, the printBalance method forces strong assumptions on the BankAccount class.

In other words, this design violates the rule of minimizing the coupling of the classes. The printBalance method couples the BankAccount class with the System and PrintStream classes. It is best to decouple input/output from the actual work of your classes.

9. Consider the DataSet class of Chapter 6. Suppose we add a method

void read(Scanner in)
{
   while (in.hasNextDouble())
      add(in.nextDouble());
}

Does this method have a side effect other than mutating the data set?

Common Error 8.1: Trying to Modify Primitive Type Parameters

Methods can't update parameters of primitive type (numbers, char, and boolean). To illustrate this point, let's try to write a method that updates a number parameter:

public class BankAccount
{
  . . .
  /**
     Transfers money from this account and tries to add it to a balance.
     @param amount the amount of money to transfer
     @param otherBalance balance to add the amount to
  */
  void transfer(double amount, double otherBalance)

  {
     balance = balance - amount;
     otherBalance = otherBalance + amount;
        // Won't work
  }

}

This doesn't work. Let's consider a method call.

double savingsBalance = 1000;
harrysChecking.transfer(500, savingsBalance);

System.out.println(savingsBalance);

As the method starts, the parameter variable otherBalance is set to the same value as savingsBalance (see Figure 3). Then the value of the otherBalance value is modified, but that modification has no effect on savingsBalance, because otherBalance is a separate variable. When the method terminates, the otherBalance variable dies, and savingsBalance isn't increased.

Figure 8.3. Modifying a Numeric Parameter Has No Effect on Caller

Why did the example at the beginning of Section 8.4 work, where the second explicit parameter was a BankAccount reference? Then the parameter variable contained a copy of the object reference. Through that reference, the method is able to modify the object.

You already saw this difference between objects and primitive types in Chapter 2. As a consequence, a Java method can never modify numbers that are passed to it.

Note

In Java, a method can never change parameters of primitive type.

public void deposit(double amount)
{
   // Using the parameter variable to hold an intermediate value
   amount = balance + amount; // Poor style
   ...
}

public void deposit(double amount)
{
   double newBalance = balance + amount;
   ...
}

Special Topic 8.1: Call by Value and Call by Reference

In Java, parameter variables are initialized with the values that are supplied in the method call when a method starts. Computer scientists refer to this call mechanism as "call by value". There are some limitations to the "call by value" mechanism. As you saw in Common Error 8.1 on page 334, it is not possible to implement methods that modify the contents of number variables. Other programming languages such as C++ support an alternate mechanism, called "call by reference". For example, in C++ it would be an easy matter to write a method that modifies a number, by using a so-called reference parameter. Here is the C++ code, for those of you who know C++:

// This is C++
class BankAccount
{
public:
   void transfer(double amount, double& otherBalance)
      // otherBalance is a double&, a reference to a double
   {
      balance = balance - amount;
      otherBalance = otherBalance + amount; // Works in C++
   }
   ...
};

You will sometimes read in Java books that "numbers are passed by value, objects are passed by reference". That is technically not quite correct. In Java, objects themselves are never passed as parameters; instead, both numbers and object references are passed by value. To see this clearly, let us consider another scenario. This method tries to set the otherAccount parameter to a new object:

public class BankAccount
{
   public void transfer(double amount, BankAccount otherAccount)
    {
      balance = balance - amount;
      double newBalance = otherAccount.balance + amount;
      otherAccount = new BankAccount(newBalance); // Won't work
    }
}

In this situation, we are not trying to change the state of the object to which the parameter variable otherAccount refers; instead, we are trying to replace the object with a different one (see the figure on page 338). Now the parameter variable otherAccount is replaced with a reference to a new account. But if you call the method with

harrysChecking.transfer(500, savingsAccount);

then that change does not affect the savingsAccount variable that is supplied in the call.

Note

In Java, a method can change the state of an object reference parameter, but it cannot replace the object reference with another.

As you can see, a Java method can update an object's state, but it cannot replace the contents of an object reference. This shows that object references are passed by value in Java.

Modifying an Object Reference Parameter Has No Effect on the Caller

A precondition is a requirement that the caller of a method must obey. For example, the deposit method of the BankAccount class has a precondition that the amount to be deposited should not be negative. It is the responsibility of the caller never to call a method if one of its preconditions is violated. If the method is called anyway, it is not responsible for producing a correct result.

Therefore, a precondition is an important part of the method, and you must document it. Here we document the precondition that the amount parameter must not be negative.

/**
   Deposits money into this account.
   @param amount the amount of money to deposit
   (Precondition: amount >= 0)
*/

Some javadoc extensions support a @precondition or @requires tag, but it is not a part of the standard javadoc program. Because the standard javadoc tool skips all unknown tags, we simply add the precondition to the method explanation or the appropriate @param tag.

Preconditions are typically provided for one of two reasons:

For example, once a Scanner has run out of input, it is no longer legal to call the next method. Thus, a precondition for the next method is that the hasNext method returns true.

A method is responsible for operating correctly only when its caller has fulfilled all preconditions. The method is free to do anything if a precondition is not fulfilled. What should a method actually do when it is called with inappropriate inputs? For example, what should account.deposit(-1000) do? There are two choices.

The first approach can be inefficient, particularly if the same check is carried out many times by several methods. The second approach can be dangerous. The assertion mechanism was invented to give you the best of both approaches.

An assertion is a condition that you believe to be true at all times in a particular program location. An assertion check tests whether an assertion is true. Here is a typical assertion check that tests a precondition:

public double deposit (double amount)
{
   assert amount >= 0;
   balance = balance + amount;
}

In this method, the programmer expects that the quantity amount can never be negative. When the assertion is correct, no harm is done, and the program works in the normal way. If, for some reason, the assertion fails, and assertion checking is enabled, then the program terminates with an AssertionError.

However, if assertion checking is disabled, then the assertion is never checked, and the program runs at full speed. By default, assertion checking is disabled when you execute a program. To execute a program with assertion checking turned on, use this command:

java -enableassertions MainClass

Assertion

You can also use the shortcut -ea instead of -enableassertions. You definitely want to turn assertion checking on during program development and testing.

You don't have to use assertions for checking preconditions—throwing an exception is another reasonable option. But assertions have one advantage: You can turn them off after you have tested your program, so that it runs at maximum speed. That way, you never have to feel bad about putting lots of assertions into your code. You can also use assertions for checking conditions other than preconditions.

Many beginning programmers think that it isn't "nice" to abort the program when a precondition is violated. Why not simply return to the caller instead?

public void deposit(double amount)
{
   if (amount < 0)
      return; // Not recommended
   balance = balance + amount;
}

That is legal—after all, a method can do anything if its preconditions are violated. But it is not as good as an assertion check. If the program calling the deposit method has a few bugs that cause it to pass a negative amount as an input value, then the version that generates an assertion failure will make the bugs very obvious during test-ing—it is hard to ignore when the program aborts. The quiet version, on the other hand, will not alert you, and you may not notice that it performs some wrong calculations as a consequence. Think of assertions as the "tough love" approach to precondition checking.

When a method is called in accordance with its preconditions, then the method promises to do its job correctly. A different kind of promise that the method makes is called a postcondition. There are two kinds of postconditions:

Here is a postcondition that makes a statement about the object state after the deposit method is called.

/**
   Deposits money into this account.
   (Postcondition: getBalance() >= 0)
   @param amount the amount of money to deposit
   (Precondition: amount >= 0)
*/

As long as the precondition is fulfilled, this method guarantees that the balance after the deposit is not negative.

Some javadoc extensions support a @postcondition or @ensures tag. However, just as with preconditions, we simply add postconditions to the method explanation or the @return tag, because the standard javadoc program skips all tags that it doesn't know.

Some programmers feel that they must specify a postcondition for every method. When you use javadoc, however, you already specify a part of the postcondition in the @return tag, and you shouldn't repeat it in a postcondition.

// This postcondition statement is overly repetitive.
/**
   Returns the current balance of this account.
   @return the account balance
   (Postcondition: The return value equals the account balance.)
*/

Note that we formulate pre- and postconditions only in terms of the interface of the class. Thus, we state the precondition of the withdraw method as amount <= getBalance(), not amount <= balance. After all, the caller, which needs to check the precondition, has access only to the public interface, not the private implementation.

Preconditions and postconditions are often compared to contracts. In real life, contracts spell out the obligations of the contracting parties. For example, a car dealer may promise you a car in good working order, and you promise in turn to pay a certain amount of money. If either party breaks the promise, then the other is not bound by the terms of the contract. In the same fashion, pre- and postconditions are contractual terms between a method and its caller. The method promises to fulfill the postcondition for all inputs that fulfill the precondition. The caller promises never to call the method with illegal inputs. If the caller fulfills its promise and gets a wrong answer, it can take the method to "programmer's court". If the caller doesn't fulfill its promise and something terrible happens as a consequence, it has no recourse.

11. When you implement a method with a precondition and you notice that the caller did not fulfill the precondition, do you have to notify the caller?

public class BankAccount
{
      ...
   /**
      Constructs a bank account with a given balance.
      @param initialBalance the initial balance
      (Precondition: initialBalance >= 0)
   */
   public BankAccount(double initialBalance) { ... }
   {
      balance = initialBalance;

}

   /**
      Deposits money into the bank account.
      @param amount the amount to deposit
      (Precondition: amount >= 0)
   */
   public void deposit(double amount) { ... }

   /**
      Withdraws money from the bank account.
      @param amount   the amount to withdraw
      (Precondition: amount <= getBalance() )
   */
   public void withdraw(double amount) { ... }
}

getBalance() >= 0

initialBalance >= 0

amount >= 0

/**
   A bank account has a balance that can be changed by
   deposits and withdrawals.
   (Invariant: getBalance() >= 0)
*/
public class BankAccount
{
   ...
}

Sometimes you need a method that is not invoked on an object. Such a method is called a static method or a class method. In contrast, the methods that you have written up to now are often called instance methods because they operate on a particular instance of an object.

A typical example of a static method is the sqrt method in the Math class. When you call Math.sqrt(x), you don't supply any implicit parameter. (Recall that Math is the name of a class, not an object.)

Why would you want to write a method that does not operate on an object? The most common reason is that you want to encapsulate some computation that involves only numbers. Because numbers aren't objects, you can't invoke methods on them. For example, the call x.sqrt() can never be legal in Java.

Here is a typical example of a static method that carries out some simple algebra: to compute p percent of the amount a. Because the parameters are numbers, the method doesn't operate on any objects at all, so we make it into a static method:

/**
   Computes a percentage of an amount.
   @param p the percentage to apply
   @param a the amount to which the percentage is applied
   @return p percent of  a
*/
public static double percentOf(double p, double a)
{
    return (p / 100) * a;
}

You need to find a home for this method. Let us come up with a new class (similar to the Math class of the standard Java library). Because the percentOf method has to do with financial calculations, we'll design a class Financial to hold it. Here is the class:

public class Financial
{
   public static double percentOf(double p, double a)
   {
      return (p / 100) * a;
   }
   // More financial methods can be added here.
}

When calling a static method, you supply the name of the class containing the method so that the compiler can find it. For example,

double tax = Financial.percentOf(taxRate, total);

Note that you do not supply an object of type Financial when you call the method.

There is another reason why static methods are sometimes necessary. If a method manipulates a class that you do not own, you cannot add it to that class. Consider a method that computes the area of a rectangle. The Rectangle class in the standard library has no such feature, and we cannot modify that class. A static method solves this problem:

public class Geometry
{
   public static double area(Rectangle rect)
    {
      return rect.getWidth() * rect.getHeight();
    }
   // More geometry methods can be added here.
}

Now we can tell you why the main method is static. When the program starts, there aren't any objects. Therefore, the first method in the program must be a static method.

You may well wonder why these methods are called static. The normal meaning of the word static ("staying fixed at one place") does not seem to have anything to do with what static methods do. Indeed, it's used by accident. Java uses the static reserved word because C++ uses it in the same context. C++ uses static to denote class methods because the inventors of C++ did not want to invent another reserved word. Someone noted that there was a relatively rarely used reserved word, static, that denotes certain variables that stay in a fixed location for multiple method calls. (Java does not have this feature, nor does it need it.) It turned out that the reserved word could be reused to denote class methods without confusing the compiler. The fact that it can confuse humans was apparently not a big concern. You'll just have to live with the fact that "static method" means "class method": a method that has only explicit parameters.

13. The following method computes the average of an array list of numbers:

public static double average(ArrayList<Double> values)

Why must it be a static method?

public class ScoreAnalyzer
{
   public static double[] readInputs() { ... }
   public static double sum(double[] values) { ... }
   public static double minimum(double[] values) { ... }
   public static double finalScore(double[] values)
   {
      if (values.length == 0) return 0;
      else if (values.length == 1) return 1;
      else return sum(values) - minimum(values);
   }

   public static void main(String[] args)
   {
      System.out.println(finalScore(readInputs()));
   }
}

Sometimes, a value properly belongs to a class, not to any object of the class. You use a static variable for this purpose. Here is a typical example. We want to assign bank account numbers sequentially. That is, we want the bank account constructor to construct the first account with number 1001, the next with number 1002, and so on. Therefore, we must store the last assigned account number somewhere.

Of course, it makes no sense to make this value into an instance variable:

public class BankAccount
{
   private double balance;
   private int accountNumber;
   private int lastAssignedNumber = 1000; // NO--won't work
   ...
}

In that case each instance of the BankAccount class would have its own value of last-AssignedNumber.

Instead, we need to have a single value of lastAssignedNumber that is the same for the entire class. Such a variable is called a static variable, because you declare it using the static reserved word.

public class BankAccount
{
   private double balance;
   private int accountNumber;
   private static int lastAssignedNumber = 1000;
   ...
}

Every BankAccount object has its own balance and accountNumber instance variables, but there is only a single copy of the lastAssignedNumber variable (see Figure 4). That variable is stored in a separate location, outside any BankAccount objects.

Figure 8.4. A Static Variable and Instance Variables

A static variable is sometimes called a class variable because there is a single variable for the entire class.

Every method of a class can access its static variables. Here is the constructor of the BankAccount class, which increments the last assigned number and then uses it to initialize the account number of the object to be constructed:

public class BankAccount
{
   ...
   public BankAccount()
   {
      lastAssignedNumber++; // Updates the static variable
      accountNumber = lastAssignedNumber; // Sets the instance variable
   }
}

There are three ways to initialize a static variable:

Like instance variables, static variables should always be declared as private to ensure that methods of other classes do not change their values. The exception to this rule are static constants, which may be either private or public. For example, the BankAccount class may want to declare a public constant value, such as

public class BankAccount
{
   public static final double OVERDRAFT_FEE = 29.95;
   ...
}

Methods from any class can refer to such a constant as BankAccount.OVERDRAFT_FEE.

It makes sense to declare constants as static—you wouldn't want every object of the BankAccount class to have its own set of variables with these constant values. It is sufficient to have one set of them for the class.

Why are class variables called static? As with static methods, the static reserved word itself is just a meaningless holdover from C++. But static variables and static methods have much in common: They apply to the entire class, not to specific instances of the class.

In general, you want to minimize the use of static methods and variables. If you find yourself using lots of static methods that access static variables, then that's an indication that you have not found the right classes to solve your problem in an object-oriented way.

15. Harry tells you that he has found a great way to avoid those pesky objects: Put all code into a single class and declare all methods and variables static. Then main can call the other static methods, and all of them can access the static variables. Will Harry's plan work? Is it a good idea?

import static java.lang.System.*;
import static java.lang.Math.*;

public class RootTester
{
   public static void main(String[] args)
   {
      double r = sqrt(PI);  // Instead of Math.sqrt(Math.PI)
      out.println(r);          // Instead of System.out
   }
}

public class Coin
{
   private double value = 1;
   private String name = "Dollar";
   ...
}

public class Coin
{
   private double value;

private String name;
      {
      value = 1;
      name = "Dollar";
     }
   ...
}

public class BankAccount
{
   private static int lastAssignedNumber;
   static
   {
      lastAssignedNumber = 1000;
   }
   ...
}

The scope of a variable is the part of the program in which the variable can be accessed. It is considered good design to minimize the scope of a variable. This reduces the possibility of accidental modification and name conflicts.

In the following sections, you will learn how to determine the scopes of local and instance variables, and how to resolve name conflicts if the scopes overlap.

public static void process(double[] values) // values  is a parameter variable
{
   for (int i = 0; i < 10; i++) // i is a local variable declared in a for loop
   {
      if (values[i] == 0)
      {
         double r = Math.random(); // r i s a local variable declared in a block
         values[i] = r;
      } // Scope of r ends here
   } // Scope of i ends here
} // Scope of values ends here

public static void main(String[] args)
{
   double r = Math.random();
   if (r > 0.5)
    {
      Rectangle r = new Rectangle(5, 10, 20, 30);
      // Error--can't declare another variable called r here
      ...
    }
}

if (Math.random() > 0.5)
{
   Rectangle r = new Rectangle(5, 10, 20, 30);
    ...
} // Scope of r ends here
else
{
   int r = 5;
   // OK--it is legal to declare another r here
    ...
}

Overlapping Scope

Problems arise if you have two identical variable names with overlapping scope. This can never occur with local variables, but the scopes of identically named local variables and instance variables can overlap. Here is a purposefully bad example.

public class Coin
{
   private String name;
   private double value; // Instance variable
   ...
   public double getExchangeValue(double exchangeRate)
   {
         double value; // Local variable with the same name
      ...
      return value;
   }
}

Inside the getExchangeValue method, the variable name value could potentially have two meanings: the local variable or the instance variable. The Java language specifies that in this situation the local variable wins out. It shadows the instance variable.

This sounds pretty arbitrary, but there is actually a good reason: You can still refer to the instance variable as this.value.

value = this.value * exchangeRate;

Of course, it is not a good idea to write code like this. You can easily change the name of the local variable to something else, such as result.

Note

A local variable can shadow an instance variable with the same name. You can access the shadowed variable name through the this reference.

However, there is one situation where overlapping scope is acceptable. When implementing constructors or setter methods, it can be awkward to come up with different names for instance variables and parameters. Here is how you can use the same name for both:

public Coin(double value, String name)
{
   this.value = value;
   this.name = name;
}

The expression this.value refers to the instance variable, and value is the parameter.

public class RectangleTester
{
   public static double area(Rectangle rect)
   {
      double r = rect.getWidth() * rect.getHeight();
      return r;
   }

   public static void main(String[] args)
   {
      Rectangle r = new Rectangle(5, 10, 20, 30);
      double a = area(r);
      System.out.println(r);
   }
}

What is the scope of the balance variable of the BankAccount class?

Common Error 8.2: Shadowing

Accidentally using the same name for a local variable and an instance variable is a surprisingly common error. As you saw in the preceding section, the local variable then shadowsthe instance variable. Even though you may have meant to access the instance variable, the local variable is quietly accessed. Look at this example of an incorrect constructor:

public class Coin
{
   private double value;
   private String name;
   ...

public Coin(double aValue, String aName)
   {
      value = aValue;
      String name = aName; // Oops  ...
   }
}

The programmer declared a local variable name in the constructor. In all likelihood, that was just a typo—the programmer's fingers were on autopilot and typed the reserved word String, even though the programmer all the time intended to access the instance variable. Unfortunately, the compiler gives no warning in this situation and quietly sets the local variable to the value of aName. The instance variable of the object that is being constructed is never touched, and remains null.

Some programmers give all instance variable names a special prefix to distinguish them from other variables. A common convention is to prefix all instance variable names with the prefix my, such as myValue or myName.

Another way of avoiding this problem is to use the this parameter when accessing an instance variable:

this.name = aName;

Quality Tip 8.5: Minimize Variable Scope

When you make the scope of a variable as small as possible, it becomes less likely that the variable is accidentally corrupted. It also becomes easier to modify or eliminate the variable as you reorganize your code.

As already mentioned, don't make an instance variable public. (The Java library has a few classes with public instance variables, but their creators later regretted their decision when they were unable to make optimizations later.)

Note

You should give each variable the smallest scope that it needs.

When you have a constant, ask yourself who needs it. Everybody (public static final)? Only the class (private static final)? Only a single method (a final local variable)? Choose the smallest scope.

Beware of unnecessary instance variables. For example, consider the Pyramid class in Worked Example 4.1. You would not want an instance variable for the volume:

public class Pyramid
{
   private double height;
   private double baseLength;
   private double volume; // Not a good idea to use class scope for this variable
   ...
}

Instead, compute the volume when it is needed in the getVolume method. That way, no other method can accidentally modify the volume variable, or forget to modify it when changing the height or base length.

Finally, with local variables, declare them only when you need them.

A Java program consists of a collection of classes. So far, most of your programs have consisted of a small number of classes. As programs get larger, however, simply distributing the classes over multiple files isn't enough. An additional structuring mechanism is needed.

In Java, packages provide this structuring mechanism. A Java package is a set of related classes. For example, the Java library consists of several hundred packages, some of which are listed in Table 1.

Organizing Related Classes into Packages

To put one of your classes in a package, you must place a line

package packageName;

as the first instruction in the source file containing the class. A package name consists of one or more identifiers separated by periods. (See Section 8.9.3 for tips on constructing package names.)

For example, let's put the Financial class introduced in this chapter into a package named com.horstmann.bigjava. The Financial.java file must start as follows:

package com.horstmann.bigjava;
public class Financial
{
   ...
}

In addition to the named packages (such as java.util or com.horstmann.bigjava), there is a special package, called the default package, which has no name. If you did not include any package statement at the top of your source file, its classes are placed in the default package.

Package Specification

java.util.Scanner in = new java.util.Scanner(System.in);

import java.util.Scanner;

import java.util.*;

Packages and Source Files

A source file must be located in a subdirectory that matches the package name. The parts of the name between periods represent successively nested directories. For example, the source files for classes in the package com.horstmann.bigjava would be placed in a subdirectory com/horstmann/bigjava. You place the subdirectory inside the base directory holding your program's files. For example, if you do your homework assignment in a directory /home/britney/hw8/problem1, then you can place the class files for the com.horstmann.bigjava package into the directory /home/britney/hw8/problem1/com/horstmann/bigjava, as shown in Figure 5. (Here, we are using UNIX-style file names. Under Windows, you might use c:UsersBritneyhw8problem1 comhorstmannigjava.)

Note

The path of a class file must match its package name.

Figure 8.5. Base Directories and Subdirectories for Packages

1. java

2. java.lang

3. java.util

4. java.lang.Math

19. Is a Java program without import statements limited to using the default and java.lang packages?

20. Suppose your homework assignments are located in the directory /home/me/cs101 (c:UsersMecs101 on Windows). Your instructor tells you to place your homework into packages. In which directory do you place the class hw1.problem1.TicTacToeTester?

Common Error 8.3: Confusing Dots

In Java, the dot symbol (.) is used as a separator in the following situations:

• Between package names (java.util)

• Between package and class names (homework1.Bank)

• Between class and inner class names (Ellipse2D.Double)

• Between class and instance variable names (Math.PI)

• Between objects and methods (account.getBalance())

When you see a long chain of dot-separated names, it can be a challenge to find out which part is the package name, which part is the class name, which part is an instance variable name, and which part is a method name. Consider

java.lang.System.out.println(x);

Because println is followed by an opening parenthesis, it must be a method name. Therefore, out must be either an object or a class with a static println method. (Of course, we know that out is an object reference of type PrintStream.) Again, it is not at all clear, without context, whether System is another object, with a public variable out, or a class with a static variable. Judging from the number of pages that the Java language specification devotes to this issue, even the compiler has trouble interpreting these dot-separated sequences of strings.

To avoid problems, it is helpful to adopt a strict coding style. If class names always start with an uppercase letter, and variable, method, and package names always start with a lower-case letter, then confusion can be avoided.

Special Topic 8.5: Package Access

If a class, field, or method has no public or private modifier, then all methods of classes in the same package can access the feature. For example, if a class is declared as public, then all other classes in all packages can use it. But if a class is declared without an access modifier, then only the other classes in the same package can use it. Package access is a reasonable default for classes, but it is extremely unfortunate for instance variables.

It is a common error to forget the reserved word private, thereby opening up a potential security hole. For example, at the time of this writing, the Window class in the java.awt package contained the following declaration:

public class Window extends Container
{
   String warningString;
   ...
}

Note

A field or method that is not declared as public or private can be accessed by all classes in the same package, which is usually not desirable.

There actually was no good reason to grant package access to the warningString instance variable—no other class accesses it.

Package access for instance variables is rarely useful and always a potential security risk. Most instance variables are given package access by accident because the programmer simply forgot the private reserved word. It is a good idea to get into the habit of scanning your instance variable declarations for missing private modifiers.

How To 8.1: Programming with Packages

This How To explains in detail how to place your programs into packages. For example, your instructor may ask you to place each homework assignment into a separate package. That way, you can have classes with the same name but different implementations in separate packages (such as homework1.problem1.Bank and homework1.problem2.Bank).

• Step 1 Come up with a package name.

  Your instructor may give you a package name to use, such as homework1.problem2. Or, perhaps you want to use a package name that is unique to you. Start with your e-mail address, written backwards. For example, [email protected] becomes edu.sjsu.cs.walters. Then add a subpackage that describes your project, such as edu.sjsu.cs.walters.cs1project.

• Step 2 Pick a base directory.

  The base directory is the directory that contains the directories for your various packages, for example, /home/britney or c:UsersBritney.

• Step 3 Make a subdirectory from the base directory that matches your package name.

  The subdirectory must be contained in your base directory. Each segment must match a segment of the package name. For example,

  mkdir -p/home/britney/homework1/problem2 (in UNIX)

  or

  mkdir/s c:UsersBritneyhomework1problem2 (in Windows)

• Step 4 Place your source files into the package subdirectory.

  For example, if your homework consists of the files Tester.java and Bank.java, then you place them into

  /home/britney/homework1/problem2/Tester.java
  /home/britney/homework1/problem2/Bank.java

  or

  c:UsersBritneyhomework1problem2Tester.java
  c:UsersBritneyhomework1problem2Bank.java

• Step 5 Use the package statement in each source file.

  The first noncomment line of each file must be a package statement that lists the name of the package, such as

  package homework1.problem2;

• Step 6 Compile your source files from the base directory.

  Change to the base directory (from Step 2) to compile your files. For example,

  cd /home/britney
  javac homework1/problem2/Tester.java

  or

  c:
  cd UsersBritney
  javac homework1problem2Tester.java

  Note that the Java compiler needs the source file name and not the class name. That is, you need to supply file separators(/ on UNIX, on Windows) and a file extension (.java).

• Step 7 Run your program from the base directory.

  Unlike the Java compiler, the Java interpreter needs the class name (and not a file name) of the class containing themain method. That is, use periods as package separators, and don't use a file extension. For example,

  cd /home/britney
  java homework1.problem2.Tester

  or

  c:
  cd UsersBritney
  java homework1.problem2.Tester

Random Fact 8.1: The Explosive Growth of Personal Computers

In 1971, Marcian E. "Ted" Hoff, an engineer at Intel Corporation, was working on a chip for a manufacturer of electronic calculators. He realized that it would be a better idea to develop a general-purposechip that could be programmed to interface with the keys and display of a calculator, rather than to do yet another custom design. Thus, the microprocessor was born. At the time, its primary application was as a controller for calculators, washing machines, and the like. It took years for the computer industry to notice that a genuine central processing unit was now available as a single chip.

Hobbyists were the first to catch on. In 1974 the first computer kit, the Altair 8800, was available from MITS Electronics for about $350. The kit consisted of the microprocessor, a circuit board, a very small amount of memory, toggle switches, and a row of display lights. Purchasers had to solder and assemble it, then program it in machine language through the toggle switches. It was not a big hit.

The first big hit was the Apple II. It was a real computer with a keyboard, a monitor, and a floppy disk drive. When it was first released, users had a $3000 machine that could play Space Invaders, run a primitive bookkeeping program, or let users program it in BASIC. The original Apple II did not even support lowercase letters, making it worthless for word processing. The breakthrough came in 1979 with a new spreadsheet program, VisiCalc. In a spreadsheet, you enter data and their relationships into a grid of rows and columns (see the figure). Then you modify some of the data and watch in real time how the others change. For example, you can see how changing the mix of widgets in a manufacturing plant might affect estimated costs and profits. Middle managers in companies, who understood computers and were fed up with having to wait for hours or days to get their data runs back from the computing center, snapped up VisiCalc and the computer that was needed to run it. For them, the computer was a spreadsheet machine.

The VisiCalc Spreadsheet Running on an Apple II

The next big hit was the IBM Personal Computer, ever after known as the PC. It was the first widely available personal computer that used Intel's 16-bit processor, the 8086, whose successors are still being used in personal computers today. The success of the PC was based not on any engineering breakthroughs but on the fact that it was easy to clone. IBM published specifications for plug-in cards, and it went one step further. It published the exact source code of the so-called BIOS (Basic Input/Output System), which controls the keyboard, monitor, ports, and disk drives and must be installed in ROM form in every PC. This allowed third-party vendors of plug-in cards to ensure that the BIOS code, and third-party extensions of it, interacted correctly with the equipment. Of course, the code itself was the property of IBM and could not be copied legally. Perhaps IBM did not foresee that functionally equivalent versions of the BIOS nevertheless could be recreated by others. Compaq, one of the first clone vendors, had fifteen engineers, who certified that they had never seen the original IBM code, write a new version that conformed precisely to the IBM specifications. Other companies did the same, and soon a variety of vendors were selling computers that ran the same software as IBM's PC but distinguished themselves by a lower price, increased portability, or better performance. In time, IBM lost its dominant position in the PC market, and it sold its personal computer division to the Chinese manufacturer Lenovo in 2005.

IBM never produced an operating system for its PCs—that is, the software that organizes the interaction between the user and the computer, starts application programs, and manages disk storage and other resources. Instead, IBM offered customers the option of three separate operating systems for its original PC. Most customers couldn't care less about the operating system. They chose the system that was able to launch most of the few applications that existed at the time. It happened to be DOS (Disk Operating System) by Microsoft. Microsoft cheerfully licensed the same operating system to other hardware vendors and encouraged software companies to write DOS applications. A huge number of useful application programs for PC-compatible machines was the result.

PC applications were certainly useful, but they were not easy to learn. Every vendor developed a different user interface: the collection of keystrokes, menu options, and settings that a user needed to master to use a software package effectively. Data exchange between applications was difficult, because each program used a different data format. The Apple Macintosh changed all that in 1984. The designers of the Macintosh had the vision to supply an intuitive user interface with the computer and to force software developers to adhere to it. It took Microsoft and PC-compatible manufacturers years to catch up.

Today, most personal computers are used for accessing information from online sources, entertainment, word processing, and home finance (banking, budgeting, taxes). Some analysts predict that the personal computer will merge with the television set and cable network into an entertainment and information appliance.

Up to now, we have used a very simple approach to testing. We provided tester classes whose main method computes values and prints actual and expected values. However, that approach has limitations. The main method gets messy if it contains many tests. And if an exception occurs during one of the tests, the remaining tests are not executed.

Unit testing frameworks were designed to quickly execute and evaluate test suites, and to make it easy to incrementally add test cases. One of the most popular testing frameworks is JUnit. It is freely available at http://junit.org, and it is also built into a number of development environments, including BlueJ and Eclipse. Here we describe JUnit 4, the most current version of the library as this book is written.

When you use JUnit, you design a companion test class for each class that you develop. You provide a method for each test case that you want to have executed. You use "annotations" to mark the test methods. An annotation is an advanced Java feature that places a marker into the code that is interpreted by another tool. In the case of JUnit, the @Test annotation is used to mark test methods.

In each test case, you make some computations and then compute some condition that you believe to be true. You then pass the result to a method that communicates a test result to the framework, most commonly the assertEquals method. The assertEquals method takes as parameters the expected and actual values and, for floating-point numbers, a tolerance value.

Figure 8.6. Unit Testing with JUnit

It is also customary (but not required) that the name of the test class ends in Test, such as CashRegisterTest. Here is a typical example:

import org.junit.Test;
import org.junit.Assert;

public class CashRegisterTest
{
   @Test public void twoPurchases()
   {
      CashRegister register = new CashRegister();
      register.recordPurchase(0.75);
      register.recordPurchase(1.50);
      register.enterPayment(2, 0, 5, 0, 0);
      double expected = 0.25;
      Assert.assertEquals(expected, register.giveChange(), EPSILON);
   }
   // More test cases
   ...
}

If all test cases pass, the JUnit tool shows a green bar (see Figure 6). If any of the test cases fail, the JUnit tool shows a red bar and an error message.

Your test class can also have other methods (whose names should not be annotated with @Test). These methods typically carry out steps that you want to share among test methods.

The JUnit philosophy is simple. Whenever you implement a class, also make a companion test class. You design the tests as you design the program, one test method at a time. The test cases just keep accumulating in the test class. Whenever you have detected an actual failure, add a test case that flushes it out, so that you can be sure that you won't introduce that particular bug again. Whenever you modify your class, simply run the tests again.

If all tests pass, the user interface shows a green bar and you can relax. Otherwise, there is a red bar, but that's also good. It is much easier to fix a bug in isolation than inside a complex program.

22. What is the significance of the EPSILON parameter in the assertEquals method?

public class Coin
{
   ...
   public void print()
   {
      System.out.println(name + " " + value);
   }

   public void print(PrintStream stream)
   {
      stream.println(name + " " + value);
   }

   public String toString()
   {
      return name + " " + value;
   }
}

public static void falseSwap(double a, double b)
{
   double temp = a;
   a = b;
   b = temp;
}

public static void main(String[] args)
{
   double x = 3;
   double y = 4;
   falseSwap(x, y);
   System.out.println(x + " " + y);
}

public static void falseSwap(BankAccount a, BankAccount b)
{
   BankAccount temp = a;
   a = b;
   b = temp;
}

public class Die
{
   private int sides;
   private static Random generator = new Random();
    public Die(int s) { ... }
    public int cast() { ... }
}

Die d4 = new Die(4);
Die d6 = new Die(6);
Die d8 = new Die(8);

public class Print13
{
   public void print(int x)
   {
      System.out.println(x);
   }

   public static void main(String[] args)
   {
      int n = 13;
      print(n);
   }
}

public class X
{
   private int n;

   public int f()
    {
      int n = 1;
      return n;
   }

   public int g(int k)
   {
      int a;
      for (int n = 1; n <= k; n++)
         a = a + n;
      return a;
   }

public int h(int n)
    {
      int b;
      for (int n = 1; n <= 10; n++)
          b = b + n;
      return b + n;
    }

    public int k(int n)
    {
      if (n < 0)
      {
         int k = -n;
         int n = (int) (Math.sqrt(k));
         return n;
      }
      else return n;
   }

    public int m(int k)
    {
      int a;
      for (int n = 1; n <= k; n++)
          a = a + n;
      for (int n = k; n >= 1; n++)
          a = a + n;
      return a;
    }
}

void enterPayment(int coinCount, Coin coinType)

int giveChange(Coin coinType)

public static double perimeter(Ellipse2D.Double e);
public static double area(Ellipse2D.Double e);

public static double angle(Point2D.Double p, Point2D.Double q)
public static double slope(Point2D.Double p, Point2D.Double q)

public static boolean isInside(Point2D.Double p, Ellipse2D.Double e)
public static boolean isOnBoundary(Point2D.Double p, Ellipse2D.Double e)

public static int readInt(
      Scanner in, String prompt, String error, int min, int max)

Programming Projects

Project 8.1 Implement a program that prints paychecks for a group of student assistants. Deduct federal and Social Security taxes. (You may want to use the tax computation used in Chapter 5. Find out about Social Security taxes on the Internet.) Your program should prompt for the names, hourly wages, and hours worked of each student.

Project 8.2 For faster sorting of letters, the United States Postal Service encourages companies that send large volumes of mail to use a bar code denoting the ZIP code (see Figure 7).

The encoding scheme for a five-digit ZIP code is shown in Figure 8. There are full-height frame bars on each side. The five encoded digits are followed by a check digit, which is computed as follows: Add up all digits, and choose the check digit to make the sum a multiple of 10. For example, the sum of the digits in the ZIP code 95014 is 19, so the check digit is 1 to make the sum equal to 20.

Each digit of the ZIP code, and the check digit, is encoded according to the table at right, where 0 denotes a half bar and 1 a full bar. Note that they represent all combinations of two full and three half bars. The digit can be computed easily from the bar code using the column weights 7, 4, 2, 1, 0. For example, 01100 is

0 · 7 + 1 · 4 + 1 · 2 + 0 · 1 + 0 · 0 = 6

The only exception is 0, which would yield 11 according to the weight formula.

Write a program that asks the user for a ZIP code and prints the bar code. Use : for half bars, | for full bars. For example, 95014 becomes

||:|:::|:|:||::::::||:|::|:::|||

(Alternatively, write a graphical application that draws real bars.)

Your program should also be able to carry out the opposite conversion: Translate bars into their ZIP code, reporting any errors in the input format or a mismatch of the digits.

	7	4	2	1	0
1	0	0	0	1	1
2	0	0	1	0	1
3	0	0	1	1	1
4	0	1	0	0	0
5	0	1	0	1	1
6	0	1	1	0	0
7	1	0	0	0	0
8	1	0	0	1	1
9	1	0	1	0	0
0	1	1	0	0	0

Figure 8.7. A Postal Bar Code

Figure 8.8. Encoding for Five-Digit Bar Codes