Design of classes

2.1. The need to provide equals with an Object parameter

• Many Java books do not teach that a class should provide ability to find out whether two objects have the same value.
• If a book mention equals, often it will declared with a parameter of type Date:

  public boolean equals(final Date pDate)
  {
     return iYear==pDate.iYear && iMonth==pDate.iMonth && iDay==pDate.iDay;
  }
  

• If a client attempts to add objects of this class to an object of the Collections API (or Hashtable or Vector), they are in for a shock ...
• None of the following methods will work:

  Hashtable	contains, containsKey, get, put, remove
  Vector	contains, indexOf
  List	contains, remove, indexOf
  Map	containsKey, containsValue, get, put, remove
  Set	add, contains, remove

• Instead, equals requires a parameter of type Object.

2.2. Using getClass in the code of equals

• For example:

  public boolean equals(final Object pObject)
  {
     if ( pObject==null || getClass()!=pObject.getClass() )
     {
        return false;
     }
     final Date tDate = (Date)pObject;
     return iYear==tDate.iYear && iMonth==tDate.iMonth && iDay==tDate.iDay;
  }
  

• getClass (which is declared in the class java.lang.Object) returns a value of type java.lang.Class, a value that describes the class of its target.

Since the equals method appears in a class called Date, you would think that the target of the equals method must be an object of class Date, and so this kind of call of getClass will always return the class Date. However, suppose we derive a class called NamedDate from Date:

public class NamedDate extends Date
{
   private String iName:
   ...
}

Suppose that NamedDate does not override equals. If we write:

tFirstNamedDate.equals(tSecondNamedDate)

then this will be a call of Date's equals method and both calls of getClass will return the class NamedDate. So, even though this code appears in the class declaration for Date, in some circumstances the first call of getClass will return a value that is a subclass of the class Date.

2.3. Using getClass in preference to instanceof

• When providing a proper version of equals, many authors use code like:

  public boolean equals(final Object pObject)
  {
     if ( ! (pObject instanceof Date) )
     {
        return false;
     }
     final Date tDate = (Date)pObject;
     return iYear==tDate.iYear && iMonth==tDate.iMonth && iDay==tDate.iDay;
  }
  

• This code causes problems if later inheritance is used to subclass this class and you want the subclass to override the Date's equals.
• The problem is that this equals does not satisfy a rule of the contract of equals mentioned in Object's WWW pages.
• For more information about this, see:
  • Pages 44 to 59 of the book 'Practical Java' by Peter Haggar.
  • Mark Roulo's article at http://www.javaworld.com/javaworld/jw-01-1999/jw-01-object.html.
• Peter Haggar says: ‘A quick glance through the source code of the Java libraries shows the use of instanceof in equals method implementations is common. You also find the use of getClass. The Java libraries are not consistent in how they implement the equals methods of their classes, thereby making consistent equality comparisons difficult’.

3.1. The need to provide hashCode

• If you declare equals properly, you need also to declare hashCode.
• java.util.Hashtable's WWW pages state that: ‘to successfully store and retrieve objects from a hashtable, the objects used as keys must implement the hashCode method and the equals method’.
• So a class should override the following methods from java.lang.Object:

  public int hashCode();
  public boolean equals(Object pObject);
  

• hashCode method is used by the following methods:

  Hashtable	contains, containsKey, get, put, remove
  HashMap	containsKey, containsValue, get, put, remove
  HashSet	add, contains, remove

3.2. The contract that hashCode should satisfy

• Here is the contract that hashCode needs to satisfy:
  • ‘Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.’
  • ‘If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.’
  • ‘It is not required that if two objects are unequal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.’

3.3. Providing a hashCode method that returns the value 0

• The implications of these rules are not easy to understand.
• To begin with, I find it easier to advise students to provide:

  public int hashCode()
  {
     return 0;
  }
  

• When this function is called, it always returns the same value, and so this hashCode satisfies the first two rules.
• The third rule says we will get poor execution speeds using this hashCode.

3.4. Providing other code for the hashCode function

• For Date, another possibility for hashCode is:

  public int hashCode()
  {
     return iMonth;
  }
  

• If we use this hashCode function, an integer in the range 1 to 12 is associated with each of the values of the class Date.
• For example:

  final Date tNoelDate = new Date(2000, 12, 25);
  final int tValue = tNoelDate.hashCode();
  

  will assign the value 12 to tValue.
• So, if objects of this class are stored in a collection, the designer of the collection class could arrange for the objects to be stored in 12 buckets.
• When we later call the contains method, the code of contains can find the hashcode of its Date argument and then it need only look at the values in the appropriate bucket.

For example, suppose we want to set up a HashSet containing the dates when various composers died:

Suppose we add each of these dates to a HashSet, e.g. for Bach:

final Date tDeathOfBach = new Date(1750, 8, 28);
tHashSet.add(tDeathOfBach); 

The add method could use Date's hashCode function to store the values in 12 buckets:

2. 1934-02-23
3. 1924-03-29, 1827-03-26, 1983-03-08
4. 1759-04-14
8. 1750-08-28, 1992-08-12, 1958-08-26
9. 1957-09-20
10. 1849-10-17
11. 1847-11-04, 1695-11-21, 1893-11-06, 1585-11-23
12. 1990-12-02

Then, when later we ask the collection class whether it has the value 1893-11-06 (the date when Tchaikovsky died), the contains method can call hashCode on this value and, because this produces the value 11, the contains method need only check the values in the 11th bucket. The code of the contains method uses equals on each of these values in turn returning the value true if and only if it finds the value (in this case, the value 1893-11-06).

• Besides the above hashCode, there are many other possibilities:

  public int hashCode()
  {
     return iYear+10000 + iMonth*100 + iDay;
  }
  

• If we were to use this, each value would have its own unique hashcode.

3.5. The reason for using a zero-returning hashCode

• There is one problem which we have not yet considered.
• If a client chooses to change a value after it has been put in a collection, the value will no longer be in the right bucket.
• So it will not be found if we later search for it.

• Rule 1: a hashCode function should not be written in terms of fields that can be altered.
• So, if Date provides setYear, setMonth and setDay, we ought not to provide a hashCode written in terms of the iYear, iMonth and/or iDay.
• This is the reason why we might want to use:

  public int hashCode()
  {
     return 0;
  }
  

• A collection class will use one bucket for all the objects we put into the collection.
• This means that a method like contains will execute more slowly.
• It means we can change values after they have been added to a collection.

3.6. It is not a problem for immutable classes

• Not a problem for an immutable class.
• In such circumstances, you will be able to choose a hashCode function that helps to speed up searching.
• So if we removed setYear, setMonth and setDay, we could then use either of the two hashCode given earlier.
• This would speed up the searching for dates when they have been stored in a Hashtable, a HashSet or a HashMap.

3.7. Another rule

• Rule 2: the same hashcode values must be produced for any two objects that are equal (according to the equals method).
• In practice, this means that hashCode must always return the same value (e.g., 0) or it must (at least) be dependent on the values of the fields used in the definition of equals.

3.8. What is the effect on performance?

• The effect on performance was measured by timing the execution of a program.
• The program creates a HashSet that contains 10000 elements that are objects of the Date class.
• The program times the execution of 10000 calls of contains.
• The following times (milliseconds) were obtained:

  the code of the hashCode method	time taken
  return 0;	14826
  return iMonth;	1235
  return iYear*10000 + iMonth*100 + iDay;	36

• Results demonstrate how a carefully chosen hashCode method can affect the performance of some programs.

4.1. The need to provide compareTo

• If a class is for a type where there is a natural order for the values, you ought to provide a method to find out whether one value is less than another.
• Some parts of the Collections API (e.g., TreeSet and TreeMap) work better if your class implements the Comparable interface,
• This interface is simply:

  public interface Comparable
  {
     public int compareTo(Object pObject);
  }
  

• To implement Comparable, Date can be changed to:

  public class Date implements Comparable
  {
     ...
     public int compareTo(final Object pObject)
     {
        final Date tDate = (Date)pObject;
        int tResult = iYear - tDate.iYear;
        if (tResult==0)
        {
           tResult = iMonth - tDate.iMonth;
           if (tResult==0)
           {
              tResult = iDay - tDate.iDay;
           }
        }
        return tResult;
     }
  }
  

• Comparable became part of Java when the Java 2 platform was released in December 1998.

4.2. Using the Comparator interface

If a class such as Date fails to implement the Comparable interface, or its implementation of compareTo provides inappropriate code, a client class can still store Date objects in a TreeSet or a TreeMap provided it creates the TreeSet/TreeMap using a constructor that is passed an object that implements the Comparator interface ([7]). This interface requires the object to provide the method:

public int compare(Object pObject1, Object pObject2);

This method returns a negative integer, zero, or a positive integer depending on whether the value of pObject1 is less than, equal to, or greater than that of pObject2.

If, bizarrely, we chose to compare dates only on the year field, we could provide:

public class MyDateComparator implements java.util.Comparator
{
   public int compare(final Object pObject1, final Object pObject2)
   {
      return ((Date)pObject1).getYear() - ((Date)pObject2).getYear();
   }
}

and then use:

MyDateComparator tMyDateComparator = new MyDateComparator();
final Set tOccurrences = new TreeSet(tMyDateComparator):
tOccurrences.add(tDeathOfBach);

5.1. The need to provide a cloning operation

• Few books explain that it is desirable to provide a cloning operation.
• When creating a Person, we might let a client supply a Date that is the person's date-of-birth:

  Date tBirthDate = new Date(2000, 1, 24);
  Person tSomePerson = new Person("Joe", tBirthDate);
  

  where Person is as follows:

  public class Person
  {
     private String iName;
     private Date iDateOfBirth;
     public Person(final String pName, final Date pDateOfBirth)
     {
        iName = pName;
        iDateOfBirth = pDateOfBirth;                // share
        ...
  

• Here the Person object is sharing the Date supplied by the client.
• If Date provides mutable objects, this may be undesirable.

• Instead of sharing the Date with the client, the Person object may prefer to have its own copy.
• Java's Core APIs use two ways of producing a copy of an object:
  • a class sometimes provides a method called clone;
  • a class sometimes provides a suitable constructor.
• So, if Date provided clone, the Person constructor could use:

        iDateOfBirth = (Date)pDateOfBirth.clone();  // clone
  

• Or, if Date provided a cloning constructor, the Person constructor could use:

        iDateOfBirth = new Date(pDateOfBirth);      // clone
  

• It is best to provide a method called clone as this can be used when inheritance is involved. However, getting the code of a clone method completely right is difficult.

5.2. Providing a constructor for cloning

• Because it is difficult to get right, it is also difficult to teach.
• So, to begin with, I cheat by teaching students to provide a constructor that can be used for cloning:

  public Date(final Date pDate)
  {
     iYear = pDate.iYear;
     iMonth = pDate.iMonth;
     iDay = pDate.iDay; 
  }
  

5.3. Providing a method called clone

• The class java.lang.Object provides a method called clone.
• The header of this method is:

  public Object clone();
  

• When it is used on an object, it returns a new instance which contains a copy of all the fields of the object.

• public class Date implements Cloneable
  {
     ...
     public Object clone()
     {
        try
        {
           return super.clone();
        }
        catch(final CloneNotSupportedException pCloneNotSupportedException)
        {
           throw new InternalError();
        }
     }
  } 
  

Object's clone method only produces a shallow copy. So, if a class has one or more fields that are of a reference type, we may want to provide a deep copy by cloning these fields. For example, for the Person class, we may want to provide:

public class Person implements Cloneable
{
   ...
   public Object clone()
   {
      try
      {
         final Person tPerson = (Person)super.clone();
         if (iDateOfBirth!=null)
         {
            tPerson.iDateOfBirth = (Date)iDateOfBirth.clone();
         }
         return tPerson;
      }
      catch(final CloneNotSupportedException pCloneNotSupportedException)
      {
         throw new InternalError();
      }
   }
} 

5.4. Other information about cloning

For more information about how to clone objects, look at the canonical object article by Bill Venners ([11]).