Object equality

Writing equals and hashCode methods for data objects

By Alex Blewitt, JavaWorld.com, 06/14/04

Print
Email
Feedback
Resources
Discuss

Digg
Reddit
SlashDot
Stumble
del.icio.us
Technorati
dzone

Every Java object inherits a set of base methods from java.lang.Object that every client can use:

Creational methods

Object()

Default no-argument constructor

clone()

Returns a new instance of the class
Synchronizing methods

notify()^F

Sends a signal to a waiting thread (on the current instance)

notifyAll()^F

Sends a signal to all waiting threads (on the current instance)

wait()^F

Forces the current thread to wait for a signal (on the current instance)

Equality methods

equals(Object)

Returns true if this instance is equal to the argument

hashCode()

Returns a hash code based on the instance data
Other methods

toString()

Returns a string representation of the object

finalize()

Performs garbage-collection duties

getClass()^F

Returns the Class object associated with the instance

Each of these methods has a sensible default behavior that can be overridden in the subclasses (except for final methods, marked above with ^F). This article discusses overriding the equals() and hashCode() methods for data objects.

So, what do the equals() and hashCode() methods do?

The purpose of the equals() method is to determine whether the argument is equal to the current instance. This method is used in virtually all of the java.util collections classes, and many other low-level libraries (such as RMI (Remote Method Invocation), JDBC (Java Database Connectivity), etc.) implicitly depend on the correct behavior. The method should return true if the two objects can be considered equal and false otherwise. Of course, what data is considered equal is up to each individual class to define.

Since computing an object's equality is a time-consuming task, Java also provides a quick way of determining if an object is equal or not, using hashCode(). This returns a small number based on the object's internal datastructure; if two objects have different hash codes, then they cannot be equal to each other. (Think of it like searching for two words in a dictionary; if they both begin with "A" then they may be equal; however, if one begins with "A" and the other begins with "B" then they cannot be equal.)

The purpose of computing a hash code is that the hash should be quicker to calculate and compare than computing full object equality. Datastructures such as the HashMap implicitly use the hash code to avoid computing equality of objects where possible. One of the reasons why a HashMap looks up data faster than a List is because the list has to search the entire datastructure for a match, whereas the HashMap only searches those that have the same hash value.

Importantly, it is an error for a class to have an equals() method without overriding the default hashCode() method. In an inheritance hierarchy, only the top class needs to provide a hashCode() method. This is discussed further below.

Implementing equals()

The equals() method's signature must be:

public boolean equals(Object)

Note: Regardless of which class contains the equals() method, the signature must always declare an Object argument type. Since Java's libraries look for one with an Object argument, if the signature is not correct, then the java.lang.Object method will be called instead, leading to incorrect behavior.