hashCode() and equals()

The behavior of hashCode and equals methods

Sometimes, you need to compare objects of your custom class between each other. The java.lang.Object class, which is the superclass for any class, provides two methods to do that: equals(Object obj) and hashCode(). Their default behavior is the following:

• boolean equals(Object obj) checks whether this and some other object are stored in the same memory address;
• int hashCode() returns an integer hash code that is unique for each object (object's identity).

Let's look at how they behave on the simple Person class with three fields.

class Person {

    private String firstName;
    private String lastName;
    private int age;

    // constructor, getters and setters
}

There are two objects that actually represent the same person (i.e., the objects are logically equivalent):

Person p1 = new Person("John", "Smith", 31);
Person p2 = new Person("John", "Smith", 31);

But the equals method considers them to be different persons since it compares references rather than the values of their fields:

System.out.println(p1.equals(p2)); // false

The hashCode method also says nothing about their equality:

System.out.println(p1.hashCode()); // 242131142
System.out.println(p2.hashCode()); // 1782113663

String person1 = new String("John Smith");
String person2 = new String("John Smith");

System.out.println(person1.equals(person2)); // true

System.out.println(person1.hashCode()); // 2314539
System.out.println(person2.hashCode()); // 2314539

Overriding equals

To have the logical equality of objects, we should override the equals method of the class. It is not as trivial as it may sound.

There are some math restrictions placed on the behavior of equals, which are listed in the documentation for Object.

• Reflexivity: for any non-null reference value x, x.equals(x) should return true.
  
• Symmetry: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• Transitivity: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• Consistency: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided that no information used in equals comparisons on the objects is modified.
• Non-nullity: for any non-null reference value x, x.equals(null) should return false.

To create a method that satisfies the listed restrictions, first, select some fields to use them in comparison and then perform three tests inside the equals method:

1. if this and other object have the same reference, the objects are equal, otherwise - go to step 2;
2. if the other object is null or has an unsuitable type, the objects are not equal, otherwise - go to step 3;
3. if all selected fields are equal, the objects are equal, otherwise, they are not equal.

class Person {

    private String firstName;
    private String lastName;
    private int age;

    // constructor, getters and setters

    @Override
    public boolean equals(Object other) {
        /* Check this and other refer to the same object */
        if (this == other) {
            return true;
        }

        /* Check other is Person and not null */
        if (!(other instanceof Person)) {
            return false;
        }

        Person person = (Person) other;

        /* Compare all required fields */
        return age == person.age && 
                Objects.equals(firstName, person.firstName) &&
                Objects.equals(lastName, person.lastName);
    }
}

Person p1 = new Person("John", "Smith", 31); // a person
Person p2 = new Person("John", "Smith", 31); // the same person
Person p3 = new Person("Marry", "Smith", 30); // another person

System.out.println(p1.equals(p2)); // true
System.out.println(p2.equals(p3)); // false
System.out.println(p3.equals(p3)); // true (reflexivity)

Overriding hashCode

If you override equals, the good practice is to override hashCode as well. Otherwise, your class cannot be used correctly in any collection that applies hashing mechanism (such as HashMap, HashSet or HashTable).

Below we give the general contract which consists of thee conditions (taken from the doc).

person1.hashCode(); // 400000 - ok
person1.hashCode(); // 400000 - ok
person1.hashCode(); // 500000 - not ok

person1.equals(person2); // true
person1.hashCode() == person2.hashCode(); // false - not ok, it must be true

person1.equals(person3); // false
person1.hashCode() == person3.hashCode(); // true - will work

@Override
public int hashCode() {
    return 42;
}

class Person {

    private String firstName;
    private String lastName;
    private int age;

    // constructor, getters and setters

    // overridden equals method

    @Override
    public int hashCode() {
        int result = 17;
        result = 31 * result + (firstName == null ? 0 : firstName.hashCode());
        result = 31 * result + (lastName == null ? 0 : lastName.hashCode());
        result = 31 * result + age;
        return result;
    }
}

Person p1 = new Person("John", "Smith", 31);  // a person
Person p2 = new Person("John", "Smith", 31);  // the same person
Person p3 = new Person("Marry", "Smith", 30); // another person

System.out.println(p1.hashCode()); // 409937238
System.out.println(p2.hashCode()); // 409937238
System.out.println(p3.hashCode()); // 689793455

Objects.hash(firstName, secondName, age);

Summary

The default behavior of the equals method provided by the java.lang.Object class checks whether objects references are equal. This is not enough if you would like to compare objects by the values of their fields. In this case, you should override the equals method in your class.

The correct implementation should satisfy the following restrictions: reflexivity, symmetry, transitivity, consistency, and non-nullity. You also should override the hashCode method, taking into account that:

• if two objects are equal, they MUST also have the same hash code;
  
• if two objects have the same hash code, they do NOT have to be equal too.