Be careful to check that your objects are consistent with equals though.  I have mentioned this before.

In the following method I am using the Objects.equal with a BigDecimal class.  It does not work because BigDecimal equals treats 0 and 0.0 as not equal, which is probably not what you need.

public boolean equals(Object obj) {
    if (obj == null) {
      return false;
    }
    if (getClass() != obj.getClass()) {
      return false;
    }

    final TestEquals other = (TestEquals) obj;

    return Objects.equal(this.bigDecimal, other);
}

The common solution is to use the compareTo method instead like so.

  final TestEquals other = (TestEquals) obj;
  if (this.bigDecimal != other.bigDecimal &&
      (this.bigDecimal == null
      || this.bigDecimal.compareTo(other.bigDecimal) != 0)) {
    return false;
  }
  return true;

I will be using this technique, especially where the object has many attributes but I will be testing the equals method.

                          

But the devil is in the detail so here it is anyway.

I have this multi threaded application. One of the problems with integration testing it is, you can’t guarantee the order that messages will be written to a stream. So during the test I have to go to some trouble to split and order the lines written out. If I don’t do this the test fails sometimes. It depends on which thread writes first. The output though is correct, order is not important. Not exactly rocket science.

Here is the method I was using to massage the string.

 public List<String> getSortedLines(String expectedString) {

        String[] splitExpectedResultLines = expectedString.toString().split("\n");
        List<String> resultLines = new ArrayList<String>();
        for (String messageLine : resultLines) {
            resultLines.add(messageLine);
        }

        Collections.sort(resultLines);
        return resultLines;
    }

There is nothing particularly wrong with the method. It takes a string, splits it into lines, loads a List, sorts and returns it. Thus when its used in an assertion later the expected and actual lists are the same.

With google collections its just three lines! The HashMultiset is designed to be used in equals methods. Its equal even if the order of the elements in collections being compared is different. From the API documentation: An extension of Collection that may contain duplicate values like a List, yet has order-independent equality like a Set. One typical use for a multiset is to represent a histogram.

Its possible to use the HashMultiSet.create static factory method, passing in an Iterable. i.e a Collection. So from the original code, both the loop and the Collections.sort are no longer required.

   public HashMultiset<String> getOrderAgnosticCollection(String expectedString) {

        String[] splitExpectedResultLines = expectedString.toString().split("\n");
        Iterable<String> resultLines = Arrays.asList(splitExpectedResultLines);
        HashMultiset<String> orderAgnosticResultLines =
                                              HashMultiset.create(resultLines);

        return orderAgnosticResultLines;
    }

If there was something that performed the split, but returned an Iterable the method would be perfect!

                          

All good java programmers know the equals and hashcode methods are vitally important. I have seen some unpredictable behavior through bugs in these two methods.

If your about to click away to something more interesting fine, but first read my page with an example equals bug. See if you can spot the problem before I show the solution.

Writing a test for the equals method

Writing a test for equals is so easy its tedious. Which is perhaps why so much code gets written and not tested. First from the javadoc what are the specifications for a good equals and hashcode implementations?

Suns javadoc for the equals method

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: 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.
• It is 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.
• For any non-null reference value x, x.equals(null) should return false.

Suns javadoc for the hashcode method

• 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(java.lang.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.

Simple implementations for equals and hashcode

These two implementations were built using the generator in netbeans. Arguably some further optimisation could be done, especially if the class were made fully immutable. They are fine for the purpose of this blog.

public final class SimpleBean {
    private Integer goodInt = 0;

    public SimpleBean(final Integer goodInt) {
        this.goodInt = goodInt;
    }

    @Override
    public boolean equals(Object obj) {
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        final SimpleBean other = (SimpleBean) obj;
        if (this.goodInt != other.goodInt
            && (this.goodInt == null
                                || !this.goodInt.equals(other.goodInt))) {
            return false;
        }
        return true;
    }

    @Override
    public int hashCode() {
        int hash = 7;
        hash = 41 * hash + (this.goodInt != null ? this.goodInt.hashCode() : 0);
        return hash;
    }
}

Test class for SimpleBean just showing the equals and hashcode tests

import org.junit.Test;
import static org.junit.Assert.*;

public class TestSimpleBean {

    static final class Fixture {

        static SimpleBean x = new SimpleBean(new Integer(100));
        static SimpleBean y = new SimpleBean(new Integer(100));
        static SimpleBean z = new SimpleBean(new Integer(100));
        static SimpleBean notx = new SimpleBean(new Integer(1));
    }

    @Test
    /**
     * A class is equal to itself.
     */
    public void testEqual_ToSelf() {

        assertTrue("Class equal to itself.", Fixture.x.equals(Fixture.x));
    }

    /**
     * x.equals(WrongType) must return false;
     *
     */
    @Test
    public void testPassIncompatibleType_isFalse() {
        assertFalse("Passing incompatible object to equals should return false", Fixture.x.equals("string"));
    }

    /**
     * x.equals(null) must return false;
     *
     */
    @Test
    public void testNullReference_isFalse() {
        assertFalse("Passing null to equals should return false", Fixture.x.equals(null));
    }

    /**
     * 1. x, x.equals(x) must return true.
     * 2. x and y, x.equals(y) must return true if and only if y.equals(x) returns true.
     */
    @Test
    public void testEquals_isReflexive_isSymmetric() {

        assertTrue("Reflexive test fail x,y", Fixture.x.equals(Fixture.y));
        assertTrue("Symmetric test fail y", Fixture.y.equals(Fixture.x));

    }

    /**
     * 1. x.equals(y) returns true
     * 2. y.equals(z) returns true
     * 3. x.equals(z) must return true
     */
    @Test
    public void testEquals_isTransitive() {

        assertTrue("Transitive test fails x,y", Fixture.x.equals(Fixture.y));
        assertTrue("Transitive test fails y,z", Fixture.y.equals(Fixture.z));
        assertTrue("Transitive test fails x,z", Fixture.x.equals(Fixture.z));
    }

    /**
     * Repeated calls to equals consistently return true or false.
     */
    @Test
    public void testEquals_isConsistent() {

        assertTrue("Consistent test fail x,y", Fixture.x.equals(Fixture.y));
        assertTrue("Consistent test fail x,y", Fixture.x.equals(Fixture.y));
        assertTrue("Consistent test fail x,y", Fixture.x.equals(Fixture.y));
        assertFalse(Fixture.notx.equals(Fixture.x));
        assertFalse(Fixture.notx.equals(Fixture.x));
        assertFalse(Fixture.notx.equals(Fixture.x));

    }

    /**
     * Repeated calls to hashcode should consistently return the same integer.
     */
    @Test
    public void testHashcode_isConsistent() {

        int initial_hashcode = Fixture.x.hashCode();

        assertEquals("Consistent hashcode test fails", initial_hashcode, Fixture.x.hashCode());
        assertEquals("Consistent hashcode test fails", initial_hashcode, Fixture.x.hashCode());
    }

    /**
     * Objects that are equal using the equals method should return the same integer.
     */
    @Test
    public void testHashcode_twoEqualsObjects_produceSameNumber() {

        int xhashcode = Fixture.x.hashCode();
        int yhashcode = Fixture.y.hashCode();

        assertEquals("Equal object, return equal hashcode test fails", xhashcode, yhashcode);
    }

    /**
     * A more optimal implementation of hashcode ensures
     * that if the objects are unequal different integers are produced.
     *
     */
    @Test
    public void testHashcode_twoUnEqualObjects_produceDifferentNumber() {

        int xhashcode = Fixture.x.hashCode();
        int yhashcode = Fixture.notx.hashCode();

        assertTrue("Equal object, return unequal hashcode test fails", !(xhashcode == yhashcode));
    }
}

Conclusions

To me the benefit is clear. Its very easy to break these two methods. Converting one of the attribute types can easily break equals and possibly hashcode. Its essential to have a test in place to prevent the bug going unnoticed.

Note on nulls

In some cases extra tests may be required for null checking on both sides. For instance in the case where an object relies upon an inner class to provide it a key, and its possible for this key to be null.:

   /**
     * x.key = null, y.key = null, must return false.
     */
    @Test
    public void testKeysNull_NotEqual() {

        Thing noKeyAvailableA = new Thing();
        Thing noKeyAvailableB = new Thing ();
        assertFalse(noKeyAvailableA.equals(noKeyAvailableB));
    }

    /**
     * x.key= null, y.key != null, must return false.
     */
    @Test
    public void testKeyNearsideNullFarsideNotNull_NotEqual() {
        Fixture fixture = new Fixture();
        Thing noKeyAvailable = new Thing ();
        assertFalse(noKeyAvailable.equals(fixture.x));
    }

    /**
     * y.key = null, x.key != null, must return false.
     */
    @Test
    public void testKeyFarsideNotNullFarsideNull_NotEqual() {
        Fixture fixture = new Fixture();
        Thing noKeyAvailable = new Thing ();
        assertFalse(fixture.x.equals(noKeyAvailable));
    }

                          

Its no revelation that Eclipse, Netbeans and others can generate code. Its particularly useful if getters, setters or constructors are required. Implementing an interface is very simple indeed as these IDE will stub out the interface methods. More complex methods though require some thought. Generation of the equals method is such a case.

How to write a good equals method is well documented by Joshua Bloch in Effective Java, Chapter 3 by Joshua Bloch.

Eclipse V Netbeans who generates the best code?

Before we get deeper into the code here are two efforts at generating the equals method for this class:

public class SimpleBean  {
    private final BigDecimal bigDecimal;
    public SimpleBean(BigDecimal bigDecimal) {
        this.bigDecimal = bigDecimal;
    }
}

The results for even such a simple class are interesting.

Netbeans

      @Override
      public boolean equals(Object obj) {
          if (obj == null) {
              return false;
          }
          if (getClass() != obj.getClass()) {
              return false;
          }
          final SimpleBean other = (SimpleBean) obj;
          if (this.bigDecimal != other.bigDecimal &&
                (this.bigDecimal == null ||
                !this.bigDecimal.equals(other.bigDecimal))) {
              return false;
          }
          return true;
     }

The Netbeans attempt is reasonable at first sight. Even with the above there are a few observations and a bug which I will come to later on. Can you spot it?

• The getClass system for checking that our object can be tested for equality is a little inflexible. For classes that implement a common interface its nice to be able to compare across implementations. This is often done using the if (!(obj instanceof MyType)) check. GetClass is optimal, but it would be good to have an option in the generation.
• The style of the value check is a little compressed for some tastes.

Eclipse

  @Override
  public boolean equals(Object obj) {
      if (this == obj)
	  return true;
      if (obj == null)
	  return false;
      if (getClass() != obj.getClass())
          return false;
      SimpleBean other = (SimpleBean) obj;
      if (bigDecimal == null) {
        if (other.bigDecimal != null)
          return false;
       } else if (!bigDecimal.equals(other.bigDecimal))
          return false;
       return true;
}

Eclipse generates very similar code. The bug is still there though, can you see it yet?

• Eclipse has extra options. You can switch out that getClass for the more flexible instanceof check.
• The style above is better and can be improved with the introduction of blocks on all if statements.
• Eclipse does more optimization assuming that more often than not an object is passed in.

Neither are good! The generated equals bug exposed!

It should be clear when I write a test that will fail for either of the above implementations.

@Test
    public void testObjectInconsistantWithEquals_Equals() {
        SimpleBean testSimpleBean = new SimpleBean(new BigDecimal("0"));
        SimpleBean expectedEqualSimpleBean = new SimpleBean(new BigDecimal("0.0"));
        assertTrue("Equality Test Fail", testSimpleBean.equals(expectedEqualSimpleBean));
    }
}

The above test fails because BigDecimal has an equals implementation that will return false when it checks 100 against 100.00. Its implementation of the compare method is declared as being inconsistent with equals. This in itself is interesting but for this example it means we can modify the generated code to provide a fix using this.bigDecimal.compareTo(other.bigDecimal) != 0 instead of relying on the generated use of equals.

Recommendations

In light of the above I would suggest the following points.

• Apart from primitive and well known objects generated equals methods can be very bad indeed.
• Always write a test for equals, do not rely on an IDE.
• If you change your object, remember to re-visit the equals method.