Obey the general contract when overriding equals in Java

Special notes about overriding equals

• Overriding the equals method seems simple, but there are many ways to get it wrong, and consequences can be dire.
• Always override hashCode when you override equals
• Don’t try to be too clever. For example, the File class shouldn’t attempt to equate symbolic links referring to the same file. Thankfully, it doesn’t.
• Don’t substitute another type for Object in the equals declaration.

This is the right thing to do if any of the following conditions apply:

• Each instance of the class is inherently unique.
  This is true for classes such as Thread that represent active entities rather than values.
• You don’t care whether the class provides a “logical equality” test.
  For example, java.util.Random could have overridden equals to check whether two Random instances would produce the same sequence of random numbers going forward
• A superclass has already overridden equals, and the superclass behavior is appropriate for this class.
  For example, most Set implementations inherit their equals implementation from AbstractSet, List implementations from AbstractList, and Map implementations from AbstractMap.
• The class is private or package-private, and you are certain that its equals method will never be invoked.
  Arguably, the equals method should be overridden under these circumstances, in case it is accidentally invoked:

  	@Override public boolean equals(Object o) {
  	   throw new AssertionError(); // Method is never called
  	}
          

So when is it appropriate to override Object.equals?

When a class has a notion of logical equality that differs from mere object identity, and a superclass has not already overridden equals to implement the desired behavior. This is generally the case for value classes. A value class is simply a class that represents a value, such as an Integer or Date.

One kind of value class that does not require the equals method to be overridden and Enum types fall into this category.

The equals method implements an equivalence relation. (specification for Object [JavaSE6])

Reflexive: For any non-null reference value x, x.equals(x) must return true.
An object must be equal to itself.

Symmetric: For any non-null reference values x and y, x.equals(y) must return true if and only if y.equals(x) returns true.

Any two objects must agree on whether they are equal.

    // Broken - violates symmetry!
    public final class CaseInsensitiveString {
        private final String s;

        public CaseInsensitiveString(String s) {
            if (s == null)
                throw new NullPointerException();

            this.s = s;
        }
    }

   // Broken - violates symmetry!
    @Override public boolean equals(Object o) {
        if (o instanceof CaseInsensitiveString)
            return s.equalsIgnoreCase(
                    ((CaseInsensitiveString) o).s);
        if (o instanceof String) // One-way interoperability!
            return s.equalsIgnoreCase((String) o);
        return false;
    }
    
    CaseInsensitiveString cis = new CaseInsensitiveString("Polish");
    String s = "polish";

As expected, cis.equals(s) returns true. The problem is that while the equals method in CaseInsensitiveString knows about ordinary strings, the equals method in String is oblivious to case- insensitive strings. Therefore s.equals(cis) return false, a clear violation of symmetry. Suppose you put a case-insensitive string into a collection:

    List list = new ArrayList();
    list.add(cis);

What does list.contains(s) return at this point? Who knows? In Sun’s current implementation, it happens to return false.

Once you’ve violated the equals contract, you simply don’t know how other objects will behave when confronted with your object.

To eliminate the problem:

    @Override public boolean equals(Object o) {
        return o instanceof CaseInsensitiveString && 
                ((CaseInsensitiveString) o).s.equalsIgnoreCase(s);
    }

Transitive: For any non-null reference values x, y, z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) must return true.
If one object is equal to a second and the second object is equal to a third, then the first
the object must be equal to the third.

    public class Point {
        private final int x;
        private final int y;
        public Point(int x, int y) {
            this.x = x;
            this.y = y;
        }
        @Override public boolean equals(Object o) {
            if (!(o instanceof Point))
                return false;
            Point p = (Point)o;
            return p.x == x && p.y == y;
        }
    }

Suppose you want to extend this class, adding the notion of color to a point:

    public class ColorPoint extends Point {
        private final Color color;
        public ColorPoint(int x, int y, Color color) {
            super(x, y);
            this.color = color;
        }
    }

How should the equals method look?

    // Broken - violates symmetry!
    @Override public boolean equals(Object o) {
        if (!(o instanceof ColorPoint))
            return false;
        return super.equals(o) && ((ColorPoint) o).color == color;
    }

The problem with this method is that you might get different results when comparing a point to a color point and vice versa.

To make this concrete, let’s create one point and one color point:

Point p = new Point(1, 2);
ColorPoint cp = new ColorPoint(1, 2, Color.RED);

Then p.equals(cp) returns true, while cp.equals(p) returns false. You might try to fix the problem by having ColorPoint.equals ignore color when doing “mixed comparisons”:

    // Broken - violates transitivity!
    @Override public boolean equals(Object o) {
        if (!(o instanceof Point))
            return false;
        // If o is a normal Point, do a color-blind comparison
        if (!(o instanceof ColorPoint))
            return o.equals(this);
        // o is a ColorPoint; do a full comparison
        return super.equals(o) && ((ColorPoint)o).color == color;
    }

This approach does provide symmetry, but at the expense of transitivity:

ColorPoint p1 = new ColorPoint(1, 2, Color.RED);
Point p2 = new Point(1, 2);
ColorPoint p3 = new ColorPoint(1, 2, Color.BLUE);

Now p1.equals(p2) and p2.equals(p3) return true, while p1.equals(p3) returns false, a clear violation of transitivity. The first two comparisons are “color-blind,” while the third take color into account. So what’s the solution?

There is no way to extend an instantiable class and add a value component while preserving the equals contract.

    // Broken - violates Liskov substitution principle
    @Override public boolean equals(Object o) {
        if (o == null || o.getClass() != getClass())
            return false;
        Point p = (Point) o;
        return p.x == x && p.y == y;
    }

The Liskov substitution principle says that any important property of a type should also hold for its subtypes so that any method written for the type should work equally well on its subtypes [Liskov87].

There are some classes in the Java platform libraries that do extend an instantiable class and add a value component. For example, java.sql.Timestamp extends java.util.Date and adds a nanoseconds field. The equals implementation for Timestamp does violate symmetry and can cause erratic behavior if Timestamp and Date objects are used in the same collection or are otherwise intermixed.

Consistent: For any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.

If two objects are equal, they must remain equal for all time unless one (or both) of them
is modified. In other words, mutable objects can be equal to different objects at different times while immutable objects can’t.

Whether or not a class is immutable, do not write an equals method that depends on unreliable resources.

For any non-null reference value x, x.equals(null) must return false.

“Non-nullity”—The final requirement, which in the absence of a name I have taken the liberty of calling “non-nullity,” says that all objects must be unequal to null.

Many classes have equals methods that guard against this with an explicit test for null:

    @Override public boolean equals(Object o) {
        if (o == null)
            return false;

    }

This test is unnecessary. To test its argument for equality, the equals method must first cast its argument to an appropriate type so its accessors may be invoked or its fields accessed. Before doing the cast, the method must use the instanceof operator to check that its argument is of the correct type:

    @Override public boolean equals(Object o) {
        if (!(o instanceof MyType))
            return false;
        MyType mt = (MyType) o;
    }

Putting it all together, here’s a recipe for a high-quality equals method:

• Use the == operator to check if the argument is a reference to this object. If so, return true. This is just a performance optimization, but one that is worth doing if the comparison is potentially expensive.
• Use the instanceof operator to check if the argument has the correct type. If not, return false. Typically, the correct type is the class in which the method occurs. Occasionally, it is some interface implemented by this class. Use an interface if the class implements an interface that refines the equals contract to permit comparisons across classes that implement the interface. Collection interfaces such as Set, List, Map, and Map. The entry has this property.
• Cast the argument to the correct type. Because this cast was preceded by an instanceof test, it is guaranteed to succeed.
• For each “significant” field in the class, check if that field of the argument matches the corresponding field of this object. If all these tests succeed, return true; otherwise, return false. If the type in step 2 is an interface, you must access the argument’s fields via interface methods; if the type is a class, you may be able to access the fields directly, depending on their accessibility.
• When you are finished writing your equals method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent? And don’t just ask yourself; write unit tests to check that these properties hold! If they don’t, figure out why not, and modify the equals method accordingly. Of course, your equals method also has to satisfy the other two properties (reflexivity and “non-nullity”), but these two usually take care of themselves.