Overriding hashCode() And equals() For Records

1. Introduction

Java 14 introduced the idea of a record as an easy and better way to pass around immutable data objects. A record has only the most fundamental methods that a Class has, constructors and getter setters, and is hence a restricted form of a class, similar to an Enum in Java. A record is a plain data carrier, a form of a class used to pass data that is not altered.

In this tutorial, we’ll discuss how to override the default hashCode() and equals() implementation of a record.

2. The hashCode() and equals() Methods

A Java Object class has the equals() and hashCode() methods defined. Since all classes in Java inherit from the Object class, they have the default implementation of the methods as well.

The equals() method is meant to assert the equality of two objects, and the default implementation implies that if two objects are of the same identity, they’re equal. The hashCode() method, which returns an integer value based on the current class instance, is implemented in tandem with the definition of equality.

A record, being a restricted form of a Class in Java, comes with its default implementation of equals(), hashCode(), and toString(). We can instantiate records using the new keyword. We can also compare two instances of a record for equality, as we would, for a class.

3. Default Implementation of hashCode() and equals() for record

Any record of type R inherits directly from java.lang.Record. By default, Java provides a default implementation of the two methods for usage. 

The default equals() implementation obeys the contract of the Object’s equals() method. Additionally, when we create a new record instance by copying all the attributes of another record instance, these two record instances must be equal. This is important, as the notion of a record is to be a data carrier of data that is not altered. 

Let’s say we have a record of Person type, and we create two instances of the record:

public record Person(String firstName, String lastName, String SSN, String dateOfBirth) {}; 

Person rob = new Person("Robert", "Frost", "HDHDB223", "2000-01-02");
Person mike = new Person("Mike", "Adams", "ABJDJ2883", "2001-01-02");

Notice that we can do so because records provide default constructors considering all the record fields out of the box. Additionally, we also have an out of the box equals() for use, enabling us to compare instances of Person: 

@Test
public void givenTwoRecords_whenDefaultEquals_thenCompareEquality() {
    Person robert = new Person("Robert", "Frost", "HDHDB223", "2000-01-02");
    Person mike = new Person("Mike", "Adams", "ABJDJ2883", "2001-01-02");
    assertNotEquals(robert, mike);
}

The default hashCode() implementation returns a hash code(integer) value derived by combining all the hashed values of the record’s attributes and following the Object‘s hash code contract. Two records created from the same components must have the same hashCode value as well:

@Test
public void givenTwoRecords_hashCodesShouldBeSame() {
    Person robert = new Person("Robert", "Frost", "HDHDB223", "2000-01-02");
    Person robertCopy = new Person("Robert", "Frost", "HDHDB223", "2000-01-02");
    assertEquals(robert.hashCode(), robertCopy.hashCode());
}

4. Custom Implementation of hashCode() and equals() for record

Java does provide the ability to override the default implementations of the equals() and hashCode() methods. For example, let’s say we decide that it is enough to assert the equality of two Movie records (having several attributes) if the titles and the year of release are identical. 

In such a scenario, we can choose to override the default implementation, which considers every attribute to assert equality with our own:

record Movie(String name, Integer yearOfRelease, String distributor) {

@Override
public boolean equals(Object other) {
    if (this == other) {
        return true;
    }
    if (other == null) {
        return false;
    }   
    if (!(other instanceof Movie)) {
        return false;
    }
    Movie movie = (Movie) other;
    if (movie.name.equals(this.name) && movie.yearOfRelease.equals(this.yearOfRelease)) {
        return true;
    }
    return false;
}

This implementation is somewhat similar to any other custom implementation of equals() for a Java Class: 

• if two instances are the same, they must be equal
• if the other instance is null, the equality fails
• if the other instance is not of the same type, the equality fails
• after casting the other object to the record type, if the name and yearOfRelease attributes are the same as that of the current object, they must be equal

While checking the equality of two Movie records, however, in the case of a collision, the compiler turns towards the hashCode() to determine the equality. Hence it’s important to override the hashCode() method’s implementation as well:

@Override
public int hashCode() {
    return Objects.hash(name, yearOfRelease);
}

We can test the equality of two Movie records correctly now:

@Test
public void givenTwoRecords_whenCustomImplementation_thenCompareEquality() {
    Movie movie1 = new Movie("The Batman", 2022, "WB");
    Movie movie2 = new Movie("The Batman", 2022, "Dreamworks");
    assertEquals(movie1, movie2);
    assertEquals(movie1.hashCode(), movie2.hashCode());
}

5. When to Override the Default Implementations

Java spec expects any custom implementation of equals() of a record to satisfy the rule that a copy of the record must be equal to the original record. However, since Java records are meant for passing immutable data records around, it is generally safe to go with the default implementations of equals() and hashCode() provided by Java.

However, records are shallowly immutable. This means if a record has a mutable attribute such as a List, they’re not automatically immutable. With the default implementation, two records are equal only when all the attributes of the two instances are equal, regardless of whether the attributes are of primitive or reference types. 

This poses a challenge for record instances to serve their purpose, and it is best to override the default equals() and hashCode() implementations. It also makes a perfect candidate to be used as keys in a Map. This means we should carefully handle a record with a possible mutable data element. 

6. Conclusion

In this article, we looked at how records provide us with a default implementation of equals() and hashCode() methods. We also looked at how we can override the default implementations with our custom implementations.

We also looked at when we should consider overriding the default behaviors. 

As usual, all code samples can be found over on GitHub.