equals : Java Glossary

equals

A method of Object for comparing two objects. If you don’t override equals, the default version simply compares the references, in other words even if all the fields in the two objects are identical the objects will still not compare as equal. They will compare as equal only when both references point to precisely the same object. This default equals is usually useless as the proverbial tits on a bull. You have to write your own equals to compare field by field, ignoring irrelevant fields. You can override equals like this:

Note that your method must work even when passed a null or an Object of the wrong type.
Note that the method signature specifies Object. If you change it to something else, you won’t be overriding the official equals method, but creating a new unrelated method that will only be used in some contexts.
Whenever you implement an equals method, you must implement a corresponding hashCode method.
The equals method implements an equivalence relation. In other words, your equals method must behave in a civilised way, behaving as people would expect a method called equals ought to behave.
1. It must be reflexive: x.equals(x) should return true.
2. It must be symmetric: x.equals(y) should return true if and only if y.equals(x).
3. It must be transitive: if x.equals(y) and y.equals(z), then x.equals(z) should return true.
4. It must be consistent: multiple invocations of x.equals(y) must consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified.
What happens if your equals method violates these rules or your hashCode method does not match your equals method? Usually all that happens is the various collections such as Hashtable, HashMap and HashSet don’t work. Java can’t find the objects you put in the collections. Unfortunately, you won’t get a warning message explaining what you did wrong, so best to write a little test code to make sure your methods behave according to the four rules.
equals is a method of Object so every object implements it. There is no corresponding interface, so generics do not apply.
Nearly always you should override equals ( Object other ) not equals ( SomethingElse other ). Otherwise methods like HashSet. contains or HashMap. get which use equals ( Object other ), will use the default == implementation of equals rather than yours. You can get this wrong and your code will still almost work.

Strategy

Here is a strategy for writing an equals method for some Object:

Check for equality of the cached hashcodes. If they are not equal you know right away the two Objects can’t be equal.
You then compare the two addresses/references. If equal, you know the entire Objects must be equal (the same).
Failing that, you check the Object sizes. If they are not the same you know the two can’t be equal. There is no method to give you the aggregate Object size. By that I mean the sum of the lengths of the variable parts of the Object that participate in the equality test.
Failing that, you do your byte by byte comparison.

Whenever you implement equals, you must also implement a matching hashCode.

Learning More

Oracle’s Javadoc on equals package : available:

on the web at Oracle.com
in the current JDK 1.7.0_17 or in the old JDK 1.6.0_45 on your local Windows J: drive.

Oracle’s Javadoc on Arrays.deepEquals() : available:

on the web at Oracle.com
in the current JDK 1.7.0_17 or in the old JDK 1.6.0_45 on your local Windows J: drive.

hashCode
hashCode and equals
HashMap
HashSet
Hashtable
String comparison

	available on the web at:	http://mindprod.com/jgloss/equals.html
	optional Replicator mirror of mindprod.com on local hard disk J:	J:\mindprod\jgloss\equals.html
	Please email your feedback for publication, letters to the editor, errors, omissions, typos, formatting errors, ambiguities, unclear wording, broken/redirected link reports, suggestions to improve this page or comments to Roedy Green : . If you want your message, your name or email kept confidential, not considered for public posting, please explicitly specify that. Unless you state otherwise, I will treat your message as a letter to the editor that I may or may not publish in the feedback section. After that, it will be too late to retract it. If you disagree with something I said, especially when sending an ad-hominem attack, a rant composed mainly of obscenities or a death threat, please quote the offending passage and cite the web page where you found it, tell me why you think it is wrong, and, if possible, provide some supporting evidence. I can’t very well fix erroneous or ambiguous text if I can’t find it.
Blog	Canadian Mind Products IP:[65.110.21.43] Your face IP:[107.21.156.140]
Feedback	You are visitor number 40,264.