What sort of equality does the Apache Commons ObjectUtils equals method test for?

Question

I have always understood there to be two types of equality in Java,

• value equality : uses the .equals() method to test that two objects implement an equivalence relation on non-null object references.
• reference equality : uses the == operator to test that two primitive types or memory locations are equal.

The following pages describe these language fundamentals in more detail.

• Wikibooks Java Programming : Java Programming/Comparing Objects
• xyzws Java EE FAQ : What are the differences between the equality operator and the equals method?
• Java Platform API : Javadoc for Object.equals()
• Java Language Specification : Equality Operators

What none of these links explicitly specify is what should happen if two null object references are compared for value equality. The implicit assumption is that a NullPointerException should be thrown but this is not what is done by the ObjectUtils.equals() method, which might be considered a best practice utility method.

What worries me is that Apache Commons seems to have effectively introduced a third measure of equality into Java by the back door and that the already confusing state of affairs might have been made greatly more complex. I call it a third measure of equality because it attempts to test for value equality and when that fails it falls back to testing for reference equality. The Apache Commons equality test has many similarities with the value equality and reference equality but is also distinctly different.

Am I right to be concerned and to want to avoid using the ObjectUtils.equals() where ever possible?

Is there an argument for claiming that ObjectUtils.equals() provides a useful union of the other two measures of equality?

Chosen Answer

There doesn't seem to be a consensus opinion on this question but I decided to mark Bozho's as correct because he best drew my attention to what I now see as the greatest problem with null-safe equals checks. We should all be writing fail-fast code that addresses the root cause of why two null objects are being compared for value equality rather than trying to sweep the problem under the carpet.

Answer 1

Here's the code of ObjectUtils.equals(..):

public static boolean equals(Object object1, Object object2) {
     if (object1 == object2) {
       return true;
     }
     if ((object1 == null) || (object2 == null)) {
       return false;
    }
    return object1.equals(object2);
}

ObjecUtils docs state clearly that objects passed can be null.

Now on the matter whether true should be returned if you compare two nulls. In my opinion - no, because:

• when you compare two objects, you are probably going to do something with them later on. This will lead to a NullPointerException
• passing two nulls to compare means that they got from somewhere instead of "real" objects, perhaps due to some problem. In that case comparing them alone is wrong - the program flow should have halted before that.
• In a custom library we're using here we have a method called equalOrBothNull() - which differs from the equals method in this utility in the null comparison.

Answer 2

If you are concerned about this then you could either 1) not use this method 2) write your own to wrap it

public class MyObjectUtils {
    public static boolean equals(Object obj1, Object obj2) {
        return obj1 != null && obj2 != null && ObjectUtils.equals(obj1, obj2);
    }
}

To me it seems weird to allow for null to be equals to null, but this doesn't seem like a large problem. For the most part, I wouldn't expect my application to even get into code paths that involve equality tests if one or more objects are null.

Answer 3

Am I right to be concerned and to want to avoid using the ObjectUtils.equals() where ever possible?

No. What you need to consider equals depends on your requirements. And wanting to consider two nulls equal and any non-null unequal to a null without having to deal with NullPointerExceptions is a very, very common requirement (e.g. when you want to fire value-change events from a setter).

Actually, it's how equals() in general should work, and typically, half of that behvaiour is implemented (the API doc of Object.equals() states "For any non-null reference value x, x.equals(null) should return false.") - that it doesn't work the other way round is mainly due to technical restrictions (the language was designed without multiple dispatch to be simpler).