Effective Java Tuesday! Obey the `equals` contract

Effective Java Review (90 Part Series)

Today we are starting a new chapter. This new chapter covers methods common to all objects. And what are methods that are common to all objects? Well since every object eventually inherits from Object it would be methods on that object. The method we have a pleasure to talk about today is the equals method.

The equals method seems simple to override but it is actually easy to get ourselves into trouble with it as Effective Java details. So why must we override the equals method? Well actually we don’t have to. If your class fulfills any of the following requirement there is no need to override the equals method:

Each instance of a class is inherently unique. Thread for example doesn’t make sense to have two instances be equals.
If there is no desire for two objects of the type to be compared. This does seem risky in that if others are consuming your class you can’t know for sure if they will ever want to compare two instances of the class.
The superclass implements an equals method that is appropriate for the class. Examples of this are the implementation of equals in AbstractList thus none needed in ArrayList.
If the class is private or package-private and you can be sure that equals will never be called on the class.
If the class uses instance control. This is something like the singleton model we talked about in a previous item or enums where there is only a single instance. In these cases logical equality is the same as instance equality.

So we have gone over times that we can avoid overriding the equals function. But what must we do if we do need to overwrite this function. Well we must meet the contract of the function. To meet this function’s contract we must meet the four properties for non-null objects:

Reflexive: An object should be equal to itself (x.equals(x) = true)
Symmetric: If x.equals(y) = true, then y.equals(x) must equal true as well. (And if the former returns false, the latter should as well)
Transitive: As an extension of the symmetric property. If x.equals(y) = true and y.equals(z) = true then x.equals(z) must equal true.
Consistent: Multiple invocations of x.equals(y) should consistently return the same result. Thus there shouldn’t be any side effects of the execution.
The final item, less so a property, is that for any non null x. x.equals(null) should equal false.

The above properties can appear pretty daunting and very mathematical when you first read them and they should be taken seriously. That being said it is fairly straightforward once you learn about them.

Reflexive – This first property is quite straightforward. Objects should be equal to themselves. This is usually quite easy to accomplish especially given not overriding the equals function we do get this property for free.

Symmetry – The next property is more meaty. This one says that if x says it is equals to y, y should also say it’s equal to x. Let’s look at an example of class that does not meet this property.

public final class CaseInsensitiveString {
  private final String value;

  public CaseInsensitiveString(String value) {
    this.value = Objects.requireNonNull(value);
  }

  @Override
  public boolean equals(Object o) {
    if (o instanceof CaseInsensitiveString) {
      return value.equalsIgnoreCase((CaseInsensitiveString)o);
    } else if (o instanceof String) {
      // This breaks symmetry.
      return value.equalsIgnoreCase(o);
    }
    return false;
  }
}