Programming to Interfaces

9.1 Why We Need Specifications

Say that you receive a portable disc player as a gift. When you try to operate the player, nothing happens --- the player requires batteries. What batteries fit into the player? Fortunately, on the back of the player is the specification, ``This player requires two AA batteries.'' With this information, you can obtain the correctly sized components (the batteries) and fit them into the player. The completed ``assembly'' operates.

The specification of the disc player's batteries served several useful purposes:

• The specification told the user which component must be fitted to the player to ensure correct operation.
• The specification told the manufacturer of the disc player what size to build the player's battery chamber and what voltage and amperage to use within the player's electronics.
• The specification told the battery manufacturer what size, voltage, and amperage to build batteries so that others can use them.

Without size specifications of items like batteries, clothing, and auto parts, everyday life would would be a disaster.

When we assemble a program from components, the components must fit together. When a class, A, invokes methods from an object constructed from class B, class A assumes that B possesses the methods invoked and that the methods behave in some expected way --- in the way they are specified. Just like batteries have specifications (e.g., sizes AAA, AA, C,...), classes have specifications also. This explains why we have been writing specifications for the Java classes we code.

For example, in Chapter 7, we encountered a case study of a simulation of a ball bouncing in a box. The specifications of the ball and the box proved crucial to both writing the simulation's classes and fitting the classes together in the program.

The Java language and the Java compiler can help us write specifications of classes and check that a class correctly matches (implements) its specification. In this chapter we study several Java constructions for designing programs in separate classes:

1. the interface construction, which lets us code in Java the information we specify in a class diagram;
2. the extends construction, which lets us code a class by adding methods to a class that already exists;
3. the abstract class construction, which lets us code an incomplete class that can be finished by another class.

We will study each of the constructions in turn in this chapter.

9.2 Java Interfaces

In the previous chapters, we used informal specifications to design classes and to connect them to their collaborator classes. But the Java language provides a construct, called an interface, that lets us include a specification as an actual Java component of an application---we type the interface into a file and compile it, just like a class. Then, we use the compiled interface in two ways:

• We write classes that match or implement the interface, and the Java compiler verifies this is so.
• We write classes that rely upon the interface, and the Java compiler verifies this is so.

FIGURE 1: Java interface===============================================

/** BankAccountSpecification specifies the behavior of a bank account.  */
public interface BankAccountSpecification
{ /** deposit adds money to the account
    * @param amount - the amount of the deposit, a nonnegative integer  */
  public void deposit(int amount);

  /** withdraw deducts money from the account, if possible
    * @param amount - the amount of the withdrawal, a nonnegative integer
    * @return true, if the the withdrawal was successful;
    *  return false, otherwise.  */
  public boolean withdraw(int amount);
}

ENDFIGURE==============================================================

A Java interface is a collection of header lines of methods for a class that is not yet written. The interface is not itself a class---it is a listing of methods that some class might have.

The syntax of a Java interface is simply

public interface NAME
{ METHOD_HEADER_LINES }

The BankAccountSpecification interface is placed in its own file, BankAccountSpecification.java, and is compiled like any other component. Once the interface is compiled, other classes can use it in their codings, as we now see.

Your friend starts work on the mortgage-payment class. Although your friend does not have the coding of the bank-account class, it does not matter --- whatever the coding will be, it will possess the methods listed in interface BankAccountSpecification. Therefore, your friend writes the class in Figure 2, which uses the BankAccountSpecification as the data type for the yet-to-be-written bank-account class.

FIGURE 2: class that references a Java interface=========================

/** MortgagePaymentCalculator makes mortgage payments */
public class MortgagePaymentCalculator
{ private BankAccountSpecification bank_account;  // holds the address of
                // an object that implements the BankAccountSpecification

  /** Constructor MortgagePaymentCalculator initializes the calculator.
    * @param account - the address of the bank account from which we
    *   make deposits and withdrawals  */
  public MortgagePaymentCalculator(BankAccountSpecification account)
  { bank_account = account; }

  /** makeMortgagePayment makes a mortgage payment from the bank account.
    * @param amount - the amount of the mortgage payment  */
  public void makeMortgagePayment(int amount)
  { boolean ok = bank_account.withdraw(amount);
    if ( ok )
       { System.out.println("Payment made: " + amount); }
    else { ... error ... }
  }

  ...
}

ENDFIGURE===============================================================

Class MortgagePaymentCalculator can now be compiled; the Java compiler validates that the class is using correctly the methods listed in interface BankAccountSpecification. (That is, the methods are spelled correctly and are receiving the correct forms of arguments, and the results that the methods return are used correctly.) In this way, your friend completes the class that makes mortgage payments.

Meanwhile, you are writing the class that implements interface BankAccountSpecification; this might look like Figure 3.

FIGURE 3: a class that implements a Java interface=======================

/** BankAccount manages a single bank account; as stated in its
  * header line, it _implements_ the BankAccountSpecification:  */
public class BankAccount implements BankAccountSpecification
{ private int balance;  // the account's balance

  /** Constructor BankAccount initializes the account */
  public BankAccount()
  { balance = 0; }

  // notice that methods  deposit  and  withdraw  match the same-named
  //  methods in interface  BankAccountSpecification:

  public void deposit(int amount)
  { balance = balance + amount; }

  public boolean withdraw(int amount)
  { boolean result = false;
    if ( amount <= balance )
       { balance = balance - amount;
         result = true;
       }
    return result;
  }

  /** getBalance reports the current account balance
    * @return the balance */
  public int getBalance()
  { return balance; }
}

ENDFIGURE===============================================================

Notice that class BankAccount has an additional method that is not mentioned in the interface; this is acceptable.

To connect together the two classes, we write a start-up method with statements like the following:

BankAccount my_account = new BankAccount();
MortgageCalculator calc = new MortgageCalculator(my_account);
  ...
calc.makeMortgagePayment(500);

A major advantage of using Java interfaces is this:

Class MortgageCalculator is not rewritten or changed to refer to BankAccount --- once class MortgageCalculator is correctly compiled with interface BankAccountSpecification, it is ready for use.

In this way, components can be separately designed, written, compiled, and later connected together into an application, just like the disc player and batteries were separately manufactured and later connected together.

Figure 4 shows the class diagram for the example in Figures 1 to 3.

FIGURE 4: class diagram of Java interface=================================



ENDFIGURE============================================================

The class diagram in Figure 4 shows that MortgageCalculator and BankAccount do not couple-to/depend-on each other (in the sense of Chapter 6)---they both depend on interface BankAccountSpecification, which is the ``connection point'' for the two classes. Indeed, MortgageCalculator and BankAccount are simple examples of ``subassemblies'' that connect together through the BankAccountSpecification interface. This makes it easy to remove BankAccount from the picture and readily replace it by some other class that also implements BankAccountSpecification. (See the Exercises that follow this section.)

It is exactly this use of Java interfaces that allows teams of programmers build large applications: Say that a team of programmers must design and build a complex application, which will require dozens of classes. Perhaps the programmers are divided into three groups, each group agrees to write one-third of the application, and the three subassemblies will be connected together. If all the programmers first agree on the interfaces where the three subassemblies connect, then each group can independently develop their own subassembly so that it properly fits into the final product

Exercises

1. Given this interface,

   public interface Convertable
   { public double convert(int i); }
   

   which of the following classes will the Java compiler accept as correctly implementing the interface? Justify your answers.

   1. public class C1 implements Convertable
      { private int x;
        public C1(int a) { x = a; }
        public double convert(int j)
        { return x + j; }
      }
      

   2. public class C2 implements Convertable
      { private int x;
        public C1(int a) { x = a; }
        public int convert(int i)
        { return i; }
      }
      

   3. public class C3
      { private int x;
        public C3(int a) { x = a; }
        public double convert(int i)
        { return (double)x; }
      }
      

2. Given this interface,

   public interface Convertable
   { public double convert(int i); }
   

   which of the following classes use the interface correctly? Justify your answers.

   1. public class Compute1
      { private Convertable convertor;
      
        public Compute1(Convertable c)
        { convertor = c; }
      
        public void printConversion(int x)
        { System.out.println(convertor.convert(x)); }
      }
      

   2. public class Compute2 uses Convertable
      { public Compute2() { }
      
        public void printIt(double x)
        { System.out.println(Convertable.convert(x)); }
      }
      

   3. public class Compute3
      { Convertable c;
      
        public Compute3()
        { c = new Convertable(); }
      
        public void printIt(int v)
        { System.out.println(c.compute(v)); }
      }
      

3. After you have answered the previous two questions, do the following:
   • Place interface Convertable in the file, Convertable.java, and compile it. Next, copy class C1 to the file, C1.java, in the same folder as Convertable.java, and compile it.
   • Place class Compute1 in the file, Compute1.java, in the same folder as Convertable.java, and compile it.
   • Now, place the following code in the file, Start.java, in the same folder as Convertable.java, and compile it:

     public class Start
     { public static void main(String[] args)
       { C1 c = new C1(1);
         Compute1 computer = new Computer(c);
         computer.printConversion(3);
       }
     }
     

     Execute Start.
   Notice that both C1.java as well as Compute1.java use the same compiled instance of Convertable.java. This arrangement is a bit awkward when two different people write the two classes --- they must share the same folder. We will repair this difficulty when we study Java packages later in this chapter.
4. Reconsider interface BankAccountSpecification from Figure 1. We will use it to improve the bank-accounts manager program from Section 8 of Chapter 6.
   1. Revise class BankAccount from Figure 11 of Chapter 6 so that it implements BankAccountSpecification. Next, revise class BankWriter (Figure 15, Chapter 6) and class AccountController (Figure 16, Chapter 6) so that they invoke the methods of an object of type BankAccountSpecification (and not BankAccount). Why does AccountController compile correctly but BankWriter does not?

      Repair interface BankAccountSpecification so that class BankWriter compiles without errors. Does class AccountManager of Figure 16 require any changes?

   2. Next, discard class BankAccount from Figure 11 of Chapter 6 and replace it by this class:

      public class SillyAccount implements BankAccountSpecification
      { public SillyAccount() { }
        public void deposit(int amount) { }
        public boolean withdraw(int amount) { return true; }
        public int getBalance() { return 0; }
      }
      

      Change class AccountManager in Figure 16 so that it declares,

      BankAccountSpecification account = new SillyAccount();
      

      Does AccountManager compile without error? Do any of the other classes require changes to compile?

      This exercise demonstrates that Java interfaces make it simple to replace one class in an assembly without rewriting the other classes.

5. Review the moving-ball animation in Chapter 7, Section 9.
   1. First, write a Java interface that describes MovingObjectBehavior as defined in Table 10 of Chapter 7. Then make class MovingBall in Figure 12, Chapter 7, implement MovingObjectBehavior, and change classes BounceController and BallWriter so that they mention only MovingObjectBehavior (and not MovingBall).
   2. Based on the changes you made, redraw the class diagram in Figure 9, Chapter 7.
   3. Next, replace class MovingBall by this class:

      /** ThrobbingBall models a stationary ball that changes size */
      public class ThrobbingBall implements MovingObjectBehavior
      { private int max_radius = 60;
        private int increment = 10;
        private int current_radius; // invariant: 0 <= current_radius < max_radius
        private int position = 100;
      
        public ThrobbingBall() { current_radius = 0; }
        public int xPosition() { return position; }
        public int yPosition() { return position; }
        public int radiusOf() { return current_radius; }
        public void move() 
        { current_radius = (current_radius + increment) % max_radius; }
      }
      

      and in Figure 16, Chapter 7, replace the MovingBall object constructed within class BounceTheBall by

      ThrobbingBall ball = new ThrobbingBall();
      

      Recompile class BounceTheBall and execute the animation.

9.2.1 Case Study: Databases

In Chapter 8, Section 6, we designed a database, named class Database, to hold a collection of ``record'' objects, each of which possessed a unique ``key'' object to identify it. The database was designed to be general purpose, in the sense that records might be library-book objects or bank-account objects, or tax records. As stated in Chapter 8, the crucial behaviors were

1. The Database holds a collection of Record objects, where each Record holds a Key object. The remaining structure of the Records is unimportant and unknown to the database.
2. The Database will possess insert, find, and delete methods.
3. Records, regardless of their internal structure, will possess a getKey method that returns the Record's Key object when asked.
4. Key objects, regardless of their internal structure, will have an equals method that compares two Keys for equality and returns true or false as the answer.

Clearly, the types Record and Key are not meant to be specific classes; they should be the names of two Java interfaces, so that we can compile class Database now and decide later how to implement the two interfaces.

Figure 5 shows how to transform the informal specifications of Record and Key from Table 3 of Chapter 8 into interfaces.

FIGURE 5: interfaces for Record and Key===============================

/** Record is a data item that can be stored in a database  */
public interface Record
{ /** getKey  returns the key that uniquely identifies the record
    * @return the key  */
  public Key getKey();
}

/** Key is an identification, or ``key,'' value   */
public interface Key
{ /** equals  compares itself to another key, m, for equality
    * @param m - the other key
    * @return true, if this key and  m  have the same key value;
    *  return false, otherwise  */
  public boolean equals(Key m);
}

ENDFIGURE=============================================================

As noted in Section 8.6.5, we might use the database to hold information about bank accounts that are identified by integer keys. Figure 5 of Chapter 8, which defines bank accounts and integer keys, should be rewritten --- Figure 6 shows these two classes revised so that they implement the Record and Key interfaces, respectively. Note that both classes are properly named and implement their respective interfaces.

FIGURE 6: implementing the database interfaces==========================

/** BankAccount  models a bank account with an identification key */
public class BankAccount implements Record
{ private int balance;  // the account's balance
  private Key id;       // the identification key

  /** Constructor  BankAccount  initializes the account
    * @param initial_amount - the starting account balance, a nonnegative.
    * @param id - the account's identification key  */
  public BankAccount(int initial_amount, Key id)
  { balance = initial_amount;
    key = id;
  }

  /** deposit adds money to the account.
    * @param amount - the amount of money to be added, a nonnegative int */
  public void deposit(int amount)
  { balance = balance + amount; }

  /** getBalance reports the current account balance
    * @return the balance */
  public int getBalance() { return balance; }

  /** getKey returns the account's key
    * @return the key */
  public int getKey() { return key; }
}


/** IntegerKey models an integer key */
public class IntegerKey implements Key
{ private int k;  // the integer key

  /** Constructor  IntegerKey  constructs the key
    * @param i - the integer that uniquely defines the key */
  public IntegerKey(int i) {  k = i; }

  /** equals  compares this Key to another for equality
    * @param c - the other key
    * @return true, if this key equals k's; return false, otherwise */
  public boolean equals(Key c)
  { return  ( k == ((IntegerKey)c).getInt() ); }

  /** getInt returns the integer value held within this key */
  public int getInt() { return k; }
}

ENDFIGURE============================================================

The first class, BankAccount, keeps its key as an attribute and gives it away with its getKeyOf method; the class knows nothing about its key's implementation. The second class, IntegerKey, uses an integer attribute as its internal state. Its equals method must compare its internal integer to the integer held in its argument, c. To do this, object c must be cast into its underlying type, IntegerKey, so that the getInt method can be queried for c's integer. (From the perspective of the Java compiler, an object whose data type is Key does not necessarily possess a getInt method; the cast is necessary to tell the compiler that c is actually an IntegerKey, which does possess a getInt method.)

Unfortunately, we cannot avoid the cast by writing equals's header line as

public boolean equals(IntegerKey c)

Now, we can build a database that holds BankAccount records; study carefully the following, which shows how to insert and retrieve bank acccounts:

Database db = new Database(4);  // see Figure 4, Chapter 8

BankAccount a = new BankAccount(500, new IntegerKey(1234));
boolean result1 = db.insert(a);

IntegerKey k = new IntegerKey(567);
BankAccount b = new BankAccount(1000, k);
boolean result2 = db.insert(b);

Record r = db.find(k);  // retrieve object indexed by Key  k
System.out.println(((BankAccount)r).getBalance());  // why is the cast needed?

Figure 7 shows the database example's class diagram.

FIGURE 7: class diagram with interfaces==================================



ENDFIGURE================================================================

Also, note how BankAccount and IntegerKey are not coupled to each other, making it easy to ``unplug'' and replace both classes. Finally, by transitivity, the dotted arrows from BankAccount to Record to Key let us infer correctly that BankAccount depends on interface Key as well as interface Record.

Exercises

9.3 Inheritance

import java.awt.*;
import javax.swing.*;
public class MyPanel extends JPanel
{  ...

  public void paintComponent(Graphics g)
  { ...  instructions for painting on a panel ... }
}

• writing a new class that extends JPanel
• writing a method, paintComponent, that contains instructions for painting on the panel.

MyPanel p = new MyPanel(...);

This style of ``connecting'' to an already written class and adding new methods is called inheritance. We say that MyPanel is a subclass of JPanel (and JPanel is a superclass of MyPanel).

To understand inheritance further, study this small example developed from scratch: Say that a friend has written class Person:

public class Person
{ private String name;

  public Person(String n)
  { name = n; }

  public String getName()
  { return name; }
 
  ... // Other clever methods are here.
}

Next, say that you must write a new application that models persons with their addresses. You would like to ``connect'' an address to a person and reuse the coding within class Person to save you time writing your new class. You can use inheritance to do this:

public class PersonAddress extends Person
{ private String address;

  public PersonAddress(String the_name, String the_addr)
  { super(the_name);  // this gives  the_name  to  Person's  constructor
    address = the_addr;
  }

  public String getAddress()
  { return address; }

  ...
}

PersonAddress x = new PersonAddress("fred", "new york");

super(the_name);

When we use the object we constructed, e.g.,

System.out.println("Name: " + x.getName());
System.out.println("Address: " + x.getAddress());

We use a large arrowhead in class-diagram notation to denote inheritance:

FIGURE HERE:   PersonAddress  ---|>  Person

Inheritance is fundamentally different from Java interfaces, because inheritance builds upon classes that are already written, whereas interfaces specify classes that are not yet written (or unavailable). Inheritance is often used when someone has written a basic class that contains clever methods, and other people wish to use the clever methods in their own classes without copying the code --- they write subclasses. A good example is our extension of class JPanel, at the beginning of this section.

Here is another situation where inheritance can be useful: Again, say that class Person has proved popular, and someone has written a useful class that writes information about persons:

public class WritePerson
{ ...

  public void writeName(Person p)
  { ... clever instructions to write  p's  name ... }
}

If we write an application that manages persons plus their addresses, we can exploit both class Person and class WritePerson by writing class PersonAddress extends Person as shown above. Then, we can do this:

PersonAddress x = new PersonAddress("fred", "new york");
WritePerson writer = new WritePerson(...);
writer.writeName(x);  
System.out.println("Address: " + x.getAddress());

Exercises

1. Given these classes,

   public class Person
   { private String name;
   
     public Person(String n) { name = n; }
   
     public String getName() { return name; }
   
     public boolean sameName(Person other)
     { return  getName().equals(other.getName(); }
   }
   
   public class PersonAddress extends Person
   { private String address;
   
     public PersonAddress(String the_name, String the_addr)
     { super(the_name);
       address = the_addr;
     }
   
     public String getAddress() { return address; }
   
     public boolean same(PersonAddress other)
     { return   sameName(other) && address.equals(other.getAddress()); }
   }
   

   and these declarations:

   Person p = new Person("fred");
   Person q = new PersonAddress("ethel", "new york");
   

   Which of the following statement sequences are acceptable to the Java compiler? If a statement sequence is acceptable, what does it print when executed?
   1. System.out.println(p.getAddress());
   2. System.out.println(q.getName());
   3. System.out.println(p.sameName(p));
   4. System.out.println(q.sameName(p));
   5. System.out.println(q.same(p));
   This example is studied further in the next Section.

9.4 Reference Types, Subtypes, and instanceof

When we first encountered data types in Chapter 3, we treated them as ``species'' of values---int, double, and boolean were examples of such species. The classifying values into species prevents inappropriate combinations of values, such as true && 3 --- the Java compiler does data-type checking to spot such errors. Data-type checking also spots bad actual-formal parameter combinations, such as Math.sqrt(true).

Numerical, boolean, and character values are primitive (non-object), and their data types are called primitive types. The numeric primitive types are related by subtyping: int is a subtype of double, written int <= double, because an integer can be used in any situation where a double is required. For example, the integer 2 can be used within

double d = 4.5 / 2;

public double inverseOf(double d)
{ return  1.0 / d; }

Subtyping relationships simplify our programming; in particular, cumbersome cast expressions are not required. For example, it is technically correct but ugly to write double d = 4.5 / ((double)2), and thanks to subtyping, we can omit the cast.

Begin footnote: Here is a listing of the subtyping relationships between the numeric types:

byte  <=  int  <=  long  <=  float  <=  double

In addition to the primitive data types, there are object or reference data types: Every class C defines a reference data type, named C --- its values are the objects constructed from the class. This explains why we write declarations like

Person p = new Person("fred");

Java interfaces and inheritance generate subtyping relationships between reference types as well. If we write the class,

public class MyPanel extends JPanel
{ ... }

// This example comes from Figure 12, Chapter 4:
import java.awt.*;
import javax.swing.*;
public class MyPanel extends JPanel
{ ... }

public class FrameTest3 
{ public static void main(String[] args)
  { JFrame my_frame = new JFrame();
    // insert a new panel into the frame:
    my_frame.getContentPane().add(new MyPanel());
    ...
  }
}

This same phenomenon appeared at the end of the previous section when we used a PersonAddress object as an argument to the writeName method of PersonWriter.

Similar subtyping principles also apply to Java interfaces: The Java compiler uses interface names as data type names, and the compiler enforces a subtyping relationship when an interface is implemented: if class C implements I, then C <= I. This proves crucial when connecting together classes: Reconsider the database example in Figures 5-7; we might write

Database db = new Database(4);
IntegerKey k = new IntegerKey(1234);
BankAccount b = new BankAccount(500, k);
boolean success = db.insert(b);

If we peek inside computer storage, we see that the above statements constructed these objects:

Consider the following statements, which build on the above:

Record r = db.find(k);
System.out.println( ((BankAccount)r).getBalance() );

If we try to repair the situation with the assignment, BankAccount r = db.find(k), the Java compiler complains again, because the find method was declared to return a result of data type Record, and Record is not a subtype of BankAccount!

This is frustrating to the programmer, who knows that db is holding BankAccount objects, but Java's compiler and interpreter are not intelligent enough to deduce this fact. Therefore, the programmer must write an explicit cast upon r, namely, (BankAccount)r, to tell the Java compiler that r holds an address of an object whose run-time type is BankAccount. Only then, can the getBalance message be sent.

If the programmer encounters a situation where she is not certain herself what is extracted from the database, then the instanceof operation can be used to ask the extracted record its data type, e.g.,

Record mystery_record = db.find(mystery_key);
if ( mystery_record instanceof BankAccount)
     { System.out.println( ((BankAccount)mystery_record).getBalance() ); }
else { System.out.println("unknown record type"); }

We can use the instanceof method to repair a small problem in the database example in the previous section. In addition to class IntegerKey implements Key, say that the programmer writes this new class:

/** StringKey models a key that is a string */
public class StringKey implements Key
{ private String s;

  public StringKey(String j)
  { s = j; }

  public String getString()
  { return s; }

  public boolean equals(Key m) { ... }
}

IntegerKey k1 = new IntegerKey(2);
StringKey k2 = new StringKey("two");
boolean answer = k1.equals(k2);

Exception in thread "main" java.lang.ClassCastException: StringKey
        at IntegerKey.equals(...)

If an application will be constructing both IntegerKeys and StringKeys, then we should improve IntegerKey's equals method to protect itself against alien keys. We use the instanceof operation:

public boolean equals(Key another_key)
{ boolean answer;
  // ask if  another_key's  run-time data type is  IntegerKey:
  if ( another_key instanceof IntegerKey ) 
       { int m = ((IntegerKey)another_key).getInt(); 
         answer = (id == m); 
       }
  else // another_key  is not an  IntegerKey, so don't compare:
       { answer = false; }
  return answer;
}

if ( another_key instanceof IntegerKey )

Exercises

1. Given these classes,

   public class Person
   { private String name;
   
     public Person(String n) { name = n; }
   
     public String getName() { return name; }
   
     public boolean sameName(Person other)
     { return  getName().equals(other.getName(); }
   }
   
   public class PersonAddress extends Person
   { private String address;
   
     public PersonAddress(String the_name, String the_addr)
     { super(the_name); 
       address = the_addr;
     }
   
     public String getAddress() { return address; }
   
     public boolean same(PersonAddress other)
     { return   sameName(other) && address.equals(other.getAddress()); }
   }
   

   and these declarations:

   Person p = new Person("fred");
   Person q = new PersonAddress("ethel", "new york");
   

   Which of the following statement sequences are acceptable to the Java compiler? If a statement sequence is acceptable, what does it print when executed?
   1. System.out.println(p.sameName(q));
   2. Person x = q; System.out.println(x.getName());
   3. PersonAddress x = p; System.out.println(x.getAddress());
   4. Person x = q; System.out.println(x.getAddress());
   5. System.out.println(q.same(p));
2. Explain why this example fails to compile:

   public class C
   { private int x;
     public C() { x = 0; }
   }
   
   public class D extends C
   { public D() { super(); }
     public void increment() { x = x + 1; }
   }
   

   If you are interested in repairing the example, read the section, ``Subclasses and Method Overriding,'' at the end of the Chapter.
3. Use the instanceof operation to improve the existing implementations of interface Key:
   1. Insert the above coding of equals into class IntegerKey in Figure 6.
   2. Finish writing class StringKey so that it has equals method like the one you wrote in the previous exercise. (Hint: Use the compareTo method, in Table 5, Chapter 3, to write the lessthan method.)
   3. Write a test class that executes these statements:

      Database db = new Database(4);  // see Figure 3, Chapter 8
      
      BankAccount b = new BankAccount(500, new IntegerKey(1234));
      IntegerKey k = new StringKey("lucy");
      BankAccount lucy = new BankAccount(1000, k);
      boolean result1 = db.insert(b);
      boolean result2 = db.insert(lucy);
      
      Record p = db.find(k);
      BankAccount q = (BankAccount)p;
      System.out.println(q.getBalance());
      
      Key k = q.getKey();
      if ( k instanceof IntegerKey )
           { System.out.println( ((IntegerKey)k).getInt() ); }
      else if ( k instance of StringKey )
           { System.out.println( ((StringKey)k).getString() ); }
      else { System.out.println("unknown key value"); }
      

      What appears on the display?
4. Given these interfaces and classes,

   public interface I
   { public int f(int i); }
   
   public class C implements I
   { public C() { }
     public int f(int i) { return i + 1; }
     public void g() { }
   }
   
   public class D
   { public D() { }
     public int f(int i) { return i + 1; }
   }
   

   1. Which of the following subtyping relations hold true? C <= I; D <= I; C <= D.
   2. Given these initializations,

      I x = new C();
      C y = new C();
      C z = (C)x;
      

      Which of the following expressions evaluate to true? x instanceof I; x instanceof C; x instanceof D; y instanceof I; y instanceof C; y instanceof D; z instanceof I; z instanceof C.
   3. Add casts, where necessary, so that the following statement sequence passes the scrutiny of the Java compiler:

      I x = new C();
      x.f(21);
      x.g();
      C y = x;
      y.g();
      if ( x instanceof C )
         { x.g(); }
      

   4. Explain why the Java compiler complains about these statements:

      D a = new D();
      I b = a;
      if ( a instanceof C )
         { System.out.println("!");
      

9.5 Abstract Classes

In the previous section, we pretended that a class Person was an important component of many programs. Perhaps the author of class Person intended that Person objects must have addresses, but the author did not wish to code the address part. (The address might be a string or an integer or a color or ....) An abstract class can state exactly the author's wishes:

public abstract class Person  // note the keyword,  abstract
{ private String name;

  public Person(String n)
  { name = n; }

  public String getName()
  { return name; }

  public abstract String getAddress();  // method will be written later

  ...
}

1. In the title line, the keyword, abstract, announces that we cannot construct Person objects, because there are missing method bodies.
2. The title line for method getAddress contains the keyword, abstract, and the method is missing its body. The title line is terminated by a semicolon.

public class PersonAddress extends Person
{ private String address;

  public PersonAddress(String the_name, String the_addr)
  { super(the_name);  // this gives  the_name  to  Person's  constructor
    address = the_addr;
  }

  public String getAddress()
  { return address; }

  ...
}

public class PersonWithInt extends Person
{ private int address;

  public PersonWithInt(String the_name, int the_addr)
  { super(the_name); 
    address = the_addr;
  }

  public String getAddress()
  { return  "" + address; }  // make the int into a string

  ...
}

9.5.1 Case Study: Card Players

An abstract class is ``half interface'' and ``half superclass,'' and it is most useful for grouping, under a single data type name, classes that share methods.

Here is an example that illustrates good use of interfaces with abstract classes: In Chapter 8, we saw how to design cards and card decks for a card game. (See Tables 7 and 8 and Figures 9 and 10 from that Chapter.) If we continue developing the card game, we will design a class Dealer, which collaborates with cards and card decks as well as with objects that are card players. At this point, we do not know exactly how the card players will behave (this is dependent on the rules of the card game), but class Dealer would expect that a card player has a method to receive a card and has a method that replies whether a player wants to receive additional cards. The obvious step is to write an interface; Figure 8 shows it.

FIGURE 8: interface for card playing=====================================

/** CardPlayerBehavior defines expected behaviors of card players */
public interface CardPlayerBehavior
{ /** wantsACard replies whether the player wants one more new card
    * @return whether a card is wanted */
  public boolean wantsACard();

  /** receiveCard accepts a card and adds it to the player's hand 
    * @param c - the card  */
  public void receiveCard(Card c);
}

ENDFIGURE=================================================================

Next, we consider implementations of the CardPlayerBehavior interface. Perhaps there are two formats of card players---computerized players and human players. (A computerized player is an object that does card playing all by itself; a human player is an object that helps the human user join in the play.) The two classes of player receive cards in the same way, but when a human-player object is asked if it wants a card, it asks the user for a decision. In contrast, a computerized-player object will make the decision based on an algorithm --- that is, the two players share the same implementation of the receiveCard method but use different implementations of the wantsACard method.

To accommodate the situation, we invent the abstract class, CardPlayer, that acts as the superclass of both computerized and human card players. Figure 9 shows abstract class CardPlayer; its subclasses, ComputerPlayer and HumanPlayer, appear in Figure 10.

FIGURE 9: abstract class for card players================================

/** CardPlayer models an abstract form of card player */
public abstract class CardPlayer implements CardPlayerBehavior
{ private Card[] my_hand;  // the player's cards
  private int card_count;  // how many cards are held in the hand

  /** CardPlayer builds the player
    * @param max_cards - the maximum cards the player can hold.  */
  public CardPlayer(int max_cards)
  { my_hand = new Card[max_cards];
    card_count = 0;
  }

  /** wantsACard replies whether the player wants one more new card
    * @return whether a card is wanted */
  public abstract boolean wantsACard();    // method will be written later

  public void receiveCard(Card c)
  { my_hand[card_count] = c;
    card_count = card_count + 1;
  }

  /** showCards displays the player's hand
    * @return an array holding the cards in the hand  */
  public Card[] showCards()
  { Card[] answer = new Card[card_count];
    for ( int i = 0;  i != card_count;  i = i + 1 )
        { answer[i] = my_hand[i]; }
    return answer;
  }
}

ENDFIGURE=================================================================

CardPlayer is labelled abstract because it is incomplete: It is missing its wantsACard method (which it needs to implement CardPlayerBehavior). Only the header line for wantsACard appears; it contains the keyword, abstract, and is terminated by a semicolon. In contrast, receiveCard and another method, showCards, are written in entirety.

FIGURE 10: subclasses of CardPlayer=============================

/** HumanPlayer models a human who plays cards */
public class HumanPlayer extends CardPlayer
{ /** HumanPlayer builds the player
    * @param max_cards - the maximum cards the player can hold  */
  public HumanPlayer(int max_cards)
  { super(max_cards); }   // invoke constructor in superclass

  public boolean wantsACard()
  { String response = JOptionPane.showInputDialog
                        ("Do you want another card (Y or N)?");
    return  response.equals("Y");
  }
}


/** ComputerPlayer  models a computerized card player  */
public class ComputerPlayer extends CardPlayer
{ /** ComputerPlayer builds the player
    * @param max_cards - the maximum cards the player can hold.  */
  public ComputerPlayer(int max_cards)
  { super(max_cards); }  // invoke constructor in superclass

  public boolean wantsACard()
  { boolean decision;
    Card[] what_i_have = showCards();
    ... statements go here that examine  what_i_have  and
            calculate a decision ...
    return decision;
  }
}

ENDFIGURE================================================================

The two classes in Figure 8, HumanPlayer and ComputerPlayer, extend the abstract class, meaning the classes get the attributes and methods of a CardPlayer. The two classes also supply their own versions of the missing wantsACard method.

At this point, there are no more missing methods, and we say that the classes HumanPlayer and ComputerPlayer are concrete classes. Objects can be constructed from concrete classes. (Recall that they cannot be constructed from abstract classes.) Say that we construct two players:

ComputerPlayer p = new ComputerPlayer(3);
HumanPlayer h = new HumanPlayer(3);
CardPlayer someone = p;
CardPlayerBehavior another = someone;

The assignment, CardPlayer someone = p, reminds us that the data types ComputerPlayer and HumanPlayer are subtypes of CardPlayer; objects of either of the first two types can be used in situations where a CardPlayer object is required. This means we can send the message, boolean ask = someone.wantsACard(), because this is a behavior expected of a CardPlayer (even though no method was written for wantsACard in the abstract class!).

The last assignment, CardPlayerBehavior another = someone, is also acceptable, because interface names are data types. Although it is legal to say, boolean b = another.wantsACard(), the Java compiler will complain about another.showCards(), because the showCards method is not listed in interface CardPlayerBehavior; a cast would be necessary: e.g.,

if ( another instanceof CardPlayer )
   { ((CardPlayer)another).showCards(); }

The above example has created these subtyping relationships:

  ComputerPlayer <=
                    CardPlayer  <=  CardPlayerBehavior
  HumanPlayer    <=

Although the assignment, CardPlayer someone = p, was legal, this initialization is not---CardPlayer someone = new CardPlayer(3)---because objects cannot be constructed from abstract classes.

Figure 11 shows the architecture we have assembled with the example.

FIGURE 11: architecture of dealer and card players======================



ENDFIGURE==========================================================

Exercises

1. Write class Dealer based on this specification:

   class Dealer	models a dealer of cards
   Responsibilities (methods)
   dealTo(CardPlayerBehavior p)	gives cards, one by one, to player p, until p no longer wants a card
   Collaborators:	CardPlayerBehavior, CardDeck, Card

2. In the above specification, replace all occurrences of CardPlayerBehavior by CardPlayer. Rewrite class Dealer accordingly. Compare the advantages and disadvantages of the two variants of class Dealer.
3. One abstract class can extend another; here is an example:

   /** Point models a geometric point */
   public class Point
   { private int x;
     private int y;
   
     public Point(int a, int b)
     { x = a;
       y = b;
     }
     
     public int xPosition() { return x; }
     public int yPosition() { return y; }
   }
   
   /** Shape models a two-dimensional geometric shape */
   public abstract class Shape
   { private Point upper_left_corner;
   
     public Shape(Point location)
     { upper_left_corner = location; }
   
     /** locationOf returns the location of the shape's upper left corner */
     public Point locationOf()
     { return upper_left_corner; }
   
     /** widthOf returns the width of the shape, starting from its left corner */
     public abstract int widthOf();
   
     /** depthOf returns the depth of the shape, starting from its left corner */
     public abstract int depthOf();
   }
   
   /** Polygon models a polygon shape */
   public abstract class Polygon extends Shape
   { private Point[] end_points;  // the nodes (corners) of the polygon
   
     public Polygon(Point upper_left_corner)
     { super(upper_left_corner); }
   
     /** setCorners remembers the nodes (corners) of the polygon */
     public void setCorners(Point[] corners)
     { end_points = corners; }
   }
   

   Now, write a concrete class, Rectangle, that extends Polygon. The constructor method for class Rectangle can look like this:

   public Rectangle(Point location, int width, int height)
   

   Next, write a concrete class, Circle, that extends Shape.

9.5.2 Class Hierarchies

This approach comes from real-life taxonomies, like the one in Figure 12, which simplistically models the zoology of part of the animal kingdom.

FIGURE 12: hierarchy of animals==========================================



ENDFIGURE=========================================================

The characteristics of animals appear at the internal positions of the hierarchy, and actual animals appear at the end positions---the ``leaves'' of the ``tree.'' (Animal is the ``root'' of the ``tree.'') When one characteristic is listed beneath another, it means that the first is more specific or a ``customization'' of the second, in the sense that the first has all the behaviors and characteristics of the second. For example, being Equine means having all the characteristics of a WarmBlooded entity.

The zoological taxonomy helps us make sense of the variety of animals and reduces the amount of analysis we apply to the animal kingdom. In a similar way, in a taxonomy of classes, when a class, A is a superclass of class B, we place B underneath A in the hierarchy.

For example, if we designed a computer program that worked with the animal-kingdom taxonomy, the program would create objects for the classes at the leaves, for example,

Horse black_beauty = new Horse(...);

Equine a_good_specimen = black_beauty;

This example suggests that the non-leaf entries of a class hierarchy represent typically (but not always!) abstract classes, and the leaves must be concrete classes from which objects are constructed. The hierarchy can be converted into a collection of classes, that extend one another, e.g.,

public abstract class Animal
{
  // fields and methods that describe an animal
}

public abstract class WarmBlooded extends Animal
{
  // additional fields and methods specific to warm-blooded animals
}

public abstract class Equine extends WarmBlooded
{
  // fields and methods specific to equines
}

public class Horse extends Equine
{
  // fields and completed methods specific to horses
}

Here is a more computing-oriented example: Figure 13 shows a hierarchy that might arise from listing the forms one would draw in a graphics window.

FIGURE 13: hierarchy of forms for drawing===============================



ENDFIGURE==============================================================

The primary benefit of working with class hierarchies is that a hierarchy collects together related classes, meaning that commonly used attributes and methods can be written within abstract classes and shared by concrete classes. The major negative aspect of a class hierarchy is its size---one actual object might be constructed by extending many classes, which might be located in many different files. For example, a Triangle object constructed from Figure 13 is a composite of classes Triangle, Polygon, Shape, and Form; a programmer will quickly grow weary from reading four (or more) distinct classes to understand the interface and internal structure of just one object! If possible, limit the hierarchies you write to a depth of two or three classes.

A documentation tool, like javadoc, can generate helpful interface documentation for a class hierarchy; see the section, ``Generating Package APIs with javadoc,'' which follows.

Exercises

1. Reread the Exercise from the section, ``Abstract Classes,'' that displayed several geometric forms. Use the classes in that exercise to write classes for the hierarchy in Figure 13. Say that class Form goes as follows:

   /** Form  is the root of the geometric forms hierarchy */
   public abstract class Form { }
   

   Alter classes Point and Shape so that they fit into the hierarchy. Next, write the classes for Line and Straight. (Remember that a line has two end points. A straight line has no additional points, whereas jagged lines require additional points and curves require additional information.)
2. Write taxonomies of the following:
   1. the people---teachers, students, and staff---who work in a school;
   2. the different forms of motorized vehicles (cars, trucks, cycles);
   3. forms of fruits and vegetables;
   4. forms of music;
   5. forms of dance;
   6. computer input/output devices;
   7. people who work for a candy company (managers, chefs, assembly-line workers, tasters, salespeople)

9.5.3 Frameworks and Abstract Classes

A framework is such an incomplete program---it is a collection of classes and interfaces organized into an architecture for a particular application area, such as building graphics windows, or generating animations, or building spreadsheets, or writing music, or creating card games. Some of the framework's classes are left abstract---incomplete. This is deliberate---a programmer uses the framework to build a specific graphics window (or a specific animation, or spreadsheet, or song, or game) by writing concrete classes that extend the abstract ones. The result is a complete application that creates what the programmer desires with little effort.

For example, say that someone wrote for us a framework for building graphics windows. Such a framework would contain classes that do the hard work of calculating colors, shapes, and sizes and displaying them on the computer console. Most importantly, the framework would also contain an abstract class, say, by the name of class GraphicsWindow, that already contains methods like setSize, and setVisible but lacks a paint method. A programmer would use the framework and class GraphicsWindow in particular to write concrete classes that extend GraphicsWindow with paint methods. By using the framework, the programmer generates graphics windows with minimal effort.

We have been doing something similar, of course, when we used Java's Abstract Window Toolkit (java.awt) and Swing (javax.swing) packages to build graphics windows. These two packages form a framework for a range of graphics applications, and by extending class JPanel, we ``complete'' the framework and create graphics windows with little effort on our own part.

The next chapter surveys the AWT/Swing framework.

9.6 Subtypes versus Subclasses

• An interface defines a behavioral specification or ``connection point'' between classes or subassemblies that are developed separately. When a class implements an interface, the class provides, with its methods, the behavior promised by the interface.
• A subclass provides codings---implementations---of some methods that are omitted from the superclass. When a class extends another, it inherits the existing coded methods and provides codings for additional ones.

Interfaces list behaviors, subclasses list codings.

• Use an abstract class or a superclass when you are building a ``family'' of related classes whose internal structures are similar; the superclass holds the coding common to all the subclasses.
• Use an interface when you are connecting classes together, and you do not know or care how the classes will be coded.

Because interfaces and abstract classes have different purposes, it is acceptable to use both when a subassembly, as we saw in the case study with the varieties of card players.

One reason why interfaces and subclasses are confused is because both of them define subtype relationships. As noted earlier in the Chapter, if class C implements I, then data type C is a subtype of I written, C <= I. Similarly, if class B extends A, then B <= A. But remember that ``subtype'' is different from ``subclass'' --- if C <= D, it does not mean that C and D are classes and C is a subclass of D. Indeed, D and even C might be interfaces.

9.7 class Object and Wrappers

For example, if we wrote

public class A {...}

public class B extends A {...}

public class A extends Object {...}

The practical upshot of this transformation is C <= Object, for every class, C. In this way, class Object defines a type Object which is the ``data type of all objects.''

Some programmers exploit the situation by writing methods whose arguments use type Object, e.g., here is a class that can hold any two objects whatsoever:

public class Pair
{ Object[] r = new Object[2];

  public Pair(Object ob1, Object ob2)
  { r[0] = ob1;
    r[1] = ob2;
  }

  public Object getFirst()
  { return r[0]; }

  public Object getSecond()
  { return r[1]; }
}

Pair p = new Pair(new JPanel(), new int[3]);
Object item = p.getFirst();
if ( item instanceof JPanel )
   { (JPanel)item.setVisible(true); }

Of course, primitive values like integers, booleans, and doubles are not objects, so they cannot be used with class Pair. But it is possible to use class Integer, class Boolean, and class Double as so-called wrappers and embed primitive values into objects. For example, if we write

Integer wrapped_int = new Integer(3);

Pair p = new Pair(wrapped_int, new int[3]);
Object item = p.getFirst();
if ( item instanceof Integer )
   { System.out.println( ((Integer)item).intValue() + 4 ); }

Finally, since every object is built from a class that extends Object, every object inherits from class Object a method, toString, that returns a string representation of an object's ``identity.'' For example, if we write

Integer wrapped_int = new Integer(3);
String s = "abc";
Pair p = new Pair(wrapped_int, s);
  System.out.println(wrapped_int.toString());
  System.out.println(s.toString());
  System.out.println(p.toString());
}

3
abc
Pair@1f14c60

9.8 Packages

A Java package is a folder of classes where the classes in the folder are marked as belonging together. We have used several Java packages already, such as java.util, java.awt, and javax.swing. When you write a program that requires components from a package named P, you must insert an import P.* statement at the beginning of your program. The import statement alerts the Java compiler to search inside package P for the classes your program requires.

We can make our own packages. Say that we wish to group the components written for bank accounting, listed in Figures 1 and 3, into a package named Bank. We do the following:

• Create a folder (called a ``project package,'' if you are using an IDE) with the name Bank, and move the classes into this folder.
• Insert, as the first line of each class, the statement package Bank. For example, Figure 1 is revised to read,

  package Bank;
  /** BankAccountSpecification specifies the expected behavior of a
    *  bank account.   */
  public interface BankAccountSpecification
  {
    ... // the body of the interface remains the same
  }
  

  and Figure 3 is revised as follows:

  package Bank;
  /** BankAccount manages a single bank account; as stated in its
    * header line, it _implements_ the BankAccountSpecification:  */
  public class BankAccount implements BankAccountSpecification
  {
    ... // the body of the class remains the same
  }
  

• Compile each of the classes. If you are using an IDE, this step is the usual one. If you are using the JDK, you must first close the folder, and then you compile each class by mentioning both its folder and file names, e.g., javac Bank\BankAccount.java
• Say that the package you assembled contained a class that has a main method, and you wish to execute that class. To execute an application that is contained in a package, you may proceed as usual when you use an IDE.

  If you are using the JDK, then you must state both the package name and the class name to execute. For example, pretend that the Bank package contained a file, MortgagePaymentApplication.java, that has a main method. We compile this file like the others, e.g., javac Bank\MortgagePaymentApplication.java. We execute the class by typing java Bank.MortgagePaymentApplication. Note the dot rather than the slash.

Once a collection of classes is grouped in a package, other applications can import the package, just like you have imported javax.swing to use its graphics classes. For example, perhaps we write a new application, class MyCheckingAccount, so that it uses classes in package Bank. to do this, insert import Bank.* at the beginning of the class. This makes the components in package Bank immediately available, e.g.,

import Bank.*;
/** MyCheckingAccount contains methods for managing my account */
public class MyCheckingAccount
{ private BankAccount my_account = new BankAccount(); 
  private MortgagePaymentCalculator calculator
                         = new MortgagePaymentCalculator(my_account);
  ...
}

If other applications will import the Bank package, then the package must be placed where the applications can find it. You do this by adding Bank's directory path to the Java compiler's classpath.

(Begin Footnote: A classpath is a list of paths to folders that hold packages. Whenever you compile and execute a Java program, a classpath is automatically used to locate the needed classes. The usual classpath includes paths to the standard packages, java.lang, java.util, etc. If you use an IDE, you can read and update the classpath by selecting the appropriate menu item. (Usually, you ``Edit'' the ``Project Preferences'' to see and change the classpath.) If you use the JDK, you must edit the environment variable, CLASSPATH, to change the path. End Footnote)

For example, if you created the package, Bank, as a folder within the folder, C:\JavaPgms, then add C:\JavaPgms to the Java compiler's classpath. If you do not wish to fight classpaths but wish to experiment with packages nonetheless, you can move the Bank folder into the folder where you develop your programs. (For example, if you do your development work in the folder, A:\MyWork\JavaExperiments, move Bank into that folder.) This also works when one package contains classes that use classes from another package---keep both packages within the same folder.

Exercise

9.8.1 Generating Package APIs with javadoc

javadoc P

For example, here is the page created for the Bank package:

Exercise

9.9 Case Study: An Adventure Game

We finish the chapter by applying interfaces and inheritance to design a complex model whose components connect together in multiple, unpredictable ways: We are building an ``adventure game,'' where players can enter and exit rooms. A player enters an unoccupied room by speaking the ``secret word'' that opens the room's door. A player exits a room whenever she chooses.

We want the adventure game to be as general as possible, so we retrict as little as possible the notions of ``player'' and ``room.'' To start, we write specifications (Java interfaces) that state the minimal expected behaviors of rooms and players. The interfaces might appear as in Figure 14.

FIGURE 14: Interfaces for an adventure game======================

/** RoomBehavior  defines the behavior of a room  */
public interface RoomBehavior
{ /** enter lets a player enter a room
    * @param p - the player who wishes to enter
    * @return whether the player sucessfully opened the door and entered. */
  public boolean enter(PlayerBehavior p);

  /** exit ejects a player from the room.
    * @param p - the player who wishes to leave the room  */
  public void exit(PlayerBehavior p);

  /** occupantOf  returns the identity of the room's occupant
    * @return the address of the occupant object;
    *   if room unoccupied, return null  */
  public PlayerBehavior occupantOf();
}

/** PlayerBehavior  defines the behavior of a player of an adventure game */
public interface PlayerBehavior
{ /** speak lets the player say one word
    * @return the word  */
  public String speak(); 

  /** explore attempts to enter a room and explore it
    * @param r - the room that will be explored
    * @return whether the room was successfully entered */
  public boolean explore(RoomBehavior r);
}

ENDFIGURE===============================================================

Although we know nothing about the kinds of players in the adventure game, we can use the interfaces to write a basic class of room for the game; see Figure 15.

FIGURE 15: room for an adventure game======================================

/** BasicRoom models a room that can have at most one resident at a time */
public class BasicRoom implements RoomBehavior
{ private PlayerBehavior occupant;  // who is inside the room at the moment
  private String rooms_name;   
  private String secret_word;  // the password for room entry

  /** Constructor BasicRoom builds the room.
    * @param name - the room's name
    * @param password - the secret word for entry into the room */
  public BasicRoom(String name, String password)
  { occupant = null;  // no one is in the room initially
    rooms_name = name;
    secret_word = password;
  }

  public boolean enter(PlayerBehavior p)
  { boolean result = false;
    if ( occupant == null  &&  secret_word.equals(p.speak())  )
       { occupant = p;
         result = true;
       }
    return result;
  }

  public void exit(PlayerBehavior p)
  { if ( occupant == p )  // is  p  indeed in this room at the moment?
       { occupant = null; }
  }

  public PlayerBehavior occupantOf()
  { return occupant; }
}

ENDFIGURE=============================================================

Next, we might write a class of player that remembers who it is and where it is. Figure 16 shows the class.

FIGURE 16: a player that can explore rooms===================

/** Explorer models a player who explores rooms */
public class Explorer implements PlayerBehavior
{ private String my_name;
  private String my_secret_word;  // a password for entering rooms
  private RoomBehavior where_I_am_now;  // the room this object occupies

  /** Constructor Explorer builds the Player
    * @param name - the player's name
    * @param word - the password the player can speak */
  public Explorer(String name, String word)
  { my_name = name;
    my_secret_word = word;
    where_I_am_now = null;  // player does not start inside any room
  }
  
  public String speak()
  { return my_secret_word; }

  /** exitRoom causes the player to leave the room it occupies, if any */
  public void exitRoom()
  { if ( where_I_am_now != null )
       { where_I_am_now.exit(this);   // exit the room
         where_I_am_now = null;
       }
  }

  public boolean explore(RoomBehavior r)
  { if ( where_I_am_now != null )
       { exitRoom(); }  // exit current room to go to room  r:
    boolean went_inside = r.enter(this);  // ``this'' means ``this object''
    if ( went_inside )
       { where_I_am_now = r; }
    return went_inside;
  }

  /** locationOf returns the room that is occupied by this player */
  public RoomBehavior locationOf()
  { return where_I_am_now; }
}

ENDFIGURE===============================================================

Method explore of class Explorer uses the enter method of interface RoomBehavior when it explores a room. The novelty within the method is the keyword, this. When we write,

boolean went_inside = r.enter(this);

To understand this, consider this example:

RoomBehavior[] ground_floor = new RoomBehavior[4];
ground_floor[0] = new BasicRoom("kitchen", "pasta");
ground_floor[3] = new BasicRoom("lounge", "swordfish");

Explorer harpo = new Explorer("Harpo Marx", "swordfish");
Explorer chico = new Explorer("Chico Marx", "tomato");
boolean success = harpo.explore(ground_floor[3]);

Exercises

1. Write this class:

   class Dungeon implements RoomBehavior
   

   so that any object with PlayerBehavior can enter the room; no object that enters the room can ever exit it; and when asked by means of its occupantOf method, the Dungeon replies that no one is in the room.
2. After working the previous exercise, construct an array of size 3, so that the first two rooms in the array are BasicRoom objects named "kitchen" and "lounge", respectively, and the third object is a Dungeon. Then, construct

   Explorer harpo = new Explorer("Harpo Marx", "swordfish");
   

   and write a for-loop that makes harpo systematically try to enter and then exit each room in the array.
3. A close examination of Figures 15 and 16 shows us that it is possible for one Explorer object to occupy simultaneously multiple BasicRooms. Write a sequence of Java statements that makes this happen. (Hint: in the example at the end of the section, make both rooms use the same password.)

   How can we make a BasicRoom object ``smart'' enough so that it refuses to let a player be its occupant when the player currently occupies another room? To do this, add this method to interface PlayerBehavior:

   /** locationOf returns the room that is occupied by this player */
   public RoomBehavior locationOf();
   

   Now, rewrite the enter method of BasicRoom.

9.9.1 Interfaces and Inheritance Together

Classes BasicRoom and Explorer are too simplistic for an interesting game. We might design rooms that contain ``treasures'' so that players can take the treasures from the rooms they enter.

Since a treasure might be a variety of things, it is simplest to define an interface that gives the basic property of being a treasure. See Figure 17.

FIGURE 17: interface for treasures======================================

/** TreasureProperty  defines a treasure object */
public interface TreasureProperty
{ /** contentsOf  explains what the treasure is
    * @return the explanation  */
  public String contentsOf();
}

ENDFIGURE================================================================

FIGURE 18: interface for a treasury====================================

/** Treasury describes the method an object has for yielding
  *  a treasure  */
public interface Treasury
{ /** yieldTreasure surrenders the room's treasure
    * @param p - the player who requests the treasure
    * @return the treasure (or null, if the treasure is already taken) */
  public TreasureProperty yieldTreasure(PlayerBehavior p);
}

ENDFIGURE===============================================================

A room that possesses an entry and exit as well as a treasure must implement both interface RoomBehavior as well as interface Treasury. It is indeed acceptable for one class to implement two interfaces, and it might look like this:

public class Vault implements RoomBehavior, Treasury
{ private PlayerBehavior occupant;  // who is inside the room at the moment
  private String rooms_name;   
  private String secret_word;  // the password for room entry

  private TreasureProperty valuable;  // the treasure item held in this room

  /** Constructor Vault builds the room.
    * @param name - the room's name
    * @param password - the secret word for entry into the room 
    * @param item - the treasure to be saved in the room  */
  public Vault(String name, String password, TreasureProperty item)
  { occupant = null;
    rooms_name = name;
    secret_word = password;
    valuable = item;
  }

  public boolean enter(PlayerBehavior p)
  { ... }  // insert coding from Figure 15

  public void exit(PlayerBehavor p)
  { ... }  // insert coding from Figure 15

  public PlayerBehavior occupantOf()
  { ... }  // insert coding from Figure 15

  public TreasureProperty yieldTreasure(PlayerBehavior p)
  { TreasureProperty answer = null;
    if ( p == occupant )
       { answer = valuable;
         valuable = null;
       }
    return answer;
  }
}

The coding of class Vault possesses a major flaw: It copies the codings of methods already present in class BasicRoom. For this reason, we should rewrite the class so that it uses inheritance to use BasicRoom's methods. Figure 19 shows the corrected coding.

FIGURE 19: VaultRoom defined by inheritance==============================

/** VaultRoom is a room that holds a treasure---it is constructed from
  *   class BasicRoom, by means of inheritance, plus the structure below.  */
public class VaultRoom extends BasicRoom implements Treasury
   // because BasicRoom implements RoomBehavior, so does VaultRoom
{ private TreasureProperty valuable;  // the treasure item held in this room

  /** Constructor VaultRoom builds the room.
    * @param name - the room's name
    * @param password - the secret word for entry into the room
    * @param item - the treasure to be saved in the room  */
  public VaultRoom(String name, String password, TreasureProperty item)
  { // first, invoke class  BasicRoom's  constructor method:
    super(name, password);  // ``super'' means ``superclass''
    valuable = item;
  }

 public TreasureProperty yieldTreasure(PlayerBehavior p)
  { TreasureProperty answer = null;
    if ( p == occupantOf() ) // invokes the  occupantOf  method in  BasicRoom
                             // You can also state,  super.occupantOf()
                             // Another format is,   this.occupantOf()
       { answer = valuable;
         valuable = null;
       }
    return answer;
  }
}

ENDFIGURE===============================================================

The header line of class VaultRoom indicates that VaultRoom extends BasicRoom; this makes VaultRoom a subclass of the superclass BasicRoom. The class also implements the interface, Treasury, because it has a yieldTreasure method that matches the one in that interface. (Indeed, the class also implements interface RoomBehavior, because it extends BasicRoom and BasicRoom implements RoomBehavior.)

Within VaultRoom's constructor method, we see super(name, password), which invokes the constructor method of the superclass, ensuring that the private fields within BasicRoom are initialized. (Recall that when the super-constructor is invoked, it must be invoked as the first statement in the subclass's constructor.)

Within the yieldTreasure method, we see an invocation of the occupantOf method of BasicRoom:

if ( p == occupantOf() )

As the comment next to the invocation states, we can also invoke this particular method by

if ( p == super.occupantOf() )

if ( p == this.occupantOf() )

Using the above classes, say that we construct one BasicRoom object and one VaultRoom object:

BasicRoom a = new BasicRoom("The Lounge", "Hello");

TreasureProperty the_treasure = new Jewel("diamond");
VaultRoom b = new VaultRoom("The Vault", "Open, please!", the_treasure);

public class Jewel implements TreasureProperty
{ private String name;  // the name of the jewel

  public Jewel(String id)
  { name = id; }

  public String contentsOf()
  { return name; }
}

Because VaultRoom extends BasicRoom, the resulting data types are related by subtyping---data type VaultRoom is a subtype of data type BasicRoom. Further, since BasicRoom is a subtype of RoomBehavior, then by transitivity, VaultRoom is a subtype of RoomBehavior as well. Here is a drawing of the situation:

           <=  BasicRoom  <=  RoomBehavior
VaultRoom
           <=  Treasury

Finally, the diagram for the classes defined in this and the previous sections appears in Figure 20.

FIGURE 20: diagram for model of adventure game=============================



ENDFIGURE===========================================================

Exercises

1. Write a class that implements TreasureProperty:

   public class GoldCoin implements TreasureProperty
   

   and construct a Vault object with the name, "lounge" and the password, "swordfish", to hold an object constructed from class GoldCoin.
2. Modify the method, explore, in Figure 10 so that once the player successfully enters the room, it tries to extract the treasure from it. Note that not all rooms will implement interface Treasury, however. (Hint: use instanceof.) Then, construct an explorer named "Harpo Marx" that explores the "lounge".
3. Here is an interface:

   /** TreasureHunterBehavior describes the behavior of a player that tries
     *  to take treasures  */
   public interface TreasureHunterBehavior
   { /** takeTreasure  tries to extract the treasure from the current room
       *  that this player occupies.
       * @return true if the treasure was succesfully extracted from the
       *   room and saved by this player; return false otherwise */
     public boolean takeTreasure(); 
   
     /** getTreasures  returns an array of all the treasures located so far
       *  by this player
       * @return the array of treasures  */
     public TreasureProperty[] getTreasures();
   }
   

   Write this class:

   /** TreasureHunter explores rooms and saves all the treasures it extracts
     *  from the rooms.  */
   public class TreasureHunter extends Explorer implements TreasureHunterBehavior
   

4. The TreasureHunter defined in the previous exercise does not automatically try to take a treasure each time it successfully enter a room. (The TreasureHunter must be sent an enter message followed by a takeTreasure message.)

   We can create a treasure hunter that has more aggressive behavior: First write this method:

   /** explore  attempts to enter a room and explore it.  If the room is
     * successfully entered, then an attempt is made to take the treasure
     * from the room and keep it (if the room indeed holds a treasure).
     * @param r - the room that will be explored
     * @return whether the room was successfully entered */
   public boolean explore(RoomBehavior r)
   

   Now, insert your coding of the new explore into this class:

   public class RuthlessHunter extends TreasureHunter
   { ...
   
     public boolean explore(RoomBehavior r)
     { ... }
   }
   

   When we construct a RuthlessHunter, e.g.,

   VaultRoom bank = new VaultRoom("Bank", "bah!", new Jewel("ruby"));
   RuthlessHunter bart = new RuthlessHunter("Black Bart", "bah!");
   bart.explore(bank);
   

   The new explore method of the RuthlessHunter executes instead of the old, same-named method in the superclass, Explorer. We say that the new explore method overrides the old one.

   Construct this object:

   Explorer indiana = new Explorer("Indiana Jones", "hello");
   indiana.explore(bank);
   

   Which version of explore method executes? Method overriding is studied in the ``Beyond the Basics'' section at the end of this Chapter.

9.9.2 Inheritance of Interfaces

/** TreasuryBehavior describes a room that holds a treasure */
public interface TreasuryBehavior extends RoomBehavior
{ /** yieldTreasure surrenders the room's treasure
    * @param p - the player who requests the treasure
    * @return the treasure (or null, if the treasure is already taken) */
  public TreasureProperty yieldTreasure(PlayerBehavior p);
}

public class VaultRoom extends BasicRoom implements Treasury, TreasuryBehavior

public class VaultRoom extends BasicRoom implements TreasuryBehavior

Because TreasuryBehavior extends RoomBehavior, the expected subtyping relation is established: TreasuryBehavior <= RoomBehavior. The Java compiler uses the subtyping to check compatibility of classes to interfaces.

9.10 Summary

New Constructions

• interface (from Figure 1):

  public interface BankAccountSpecification
  { public void deposit(int amount);
    public boolean withdraw(int amount);
  }
  

• inheritance (from Figure 10):

  public class HumanPlayer extends CardPlayer
  { public HumanPlayer(int max_cards)
    { super(max_cards); } 
  
    public boolean wantsACard()
    { String response = JOptionPane.showInputDialog
                          ("Do you want another card (Y or N)?");
      return  response.equals("Y");
    }
  }
  

• abstract class (from Figure 9):

  public abstract class CardPlayer implements CardPlayerBehavior
  { private Card[] my_hand;
    private int card_count;
  
    public CardPlayer(int max_cards)
    { my_hand = new Card[max_cards];
      card_count = 0;
    }
  
    public abstract boolean wantsACard();  // method will be written later
  
    public void receiveCard(Card c)
    { my_hand[card_count] = c;
      card_count = card_count + 1;
    }
  }
  

• package:

  package Bank;
  /** BankAccount manages a single bank account; as stated in its
    * header line, it _implements_ the BankAccountSpecification:  */
  public class BankAccount implements BankAccountSpecification
  { ... }
  

• instanceof operation:

  Record mystery_record = db.find(mystery_key);
  if ( mystery_record instanceof BasicPerson )
       { Syst