equals, hashCode, toString and the Object Contract

A shop stores customers in a HashSet. A clerk adds "Asha, 9876543210" twice, by accident, and the set happily holds both. Later a search for her in a HashMap fails, even though she is definitely in there. The objects look identical when printed, and Java insists they are different.

These bugs come from not knowing one fact: what Java means by "the same" depends on the class, and collections rely on the class getting it right. This article explains the three methods at the heart of that: equals, hashCode and toString.

• The difference between identity and equality.
• What the default equals, hashCode and toString do.
• How to write correct equals and hashCode, and the contract behind them.
• What goes wrong when you break the contract, or mutate a key.
• How immutability avoids a whole family of problems.

There are two different questions you can ask about two objects:

1. Identity: are these two variables referring to the very same object?
2. Equality: do these two objects represent the same value?

Two bank notes of ₹100 are equal in value but are different physical notes. For objects, Java's == answers the identity question, and the equals method is meant to answer the equality question.

// File: Main.javapublic class Main {    public static void main(String[] args) {        String a = new String("java");        String b = new String("java");        String c = a;        System.out.println(a == b);        // different objects        System.out.println(a.equals(b));   // same characters        System.out.println(a == c);        // same object        Integer x = 127;        Integer y = 127;        Integer p = 128;        Integer q = 128;        System.out.println(x == y);        System.out.println(p == q);        System.out.println(p.equals(q));    }}

falsetruetruetruefalsetrue

a == b is false, because new created two objects, and a.equals(b) is true, because String overrides equals to compare characters. The Integer lines are the famous surprise: 127 == 127 is true but 128 == 128 is false. Autoboxing Integer x = 127; calls Integer.valueOf, which is specified to cache objects for values from -128 to 127, so x and y are the same object, while 128 creates separate objects. The lesson: never compare objects with == to ask whether they are equal. Use equals. Reserve == for primitives, for enums, and for deliberate identity checks such as x == null.

Every class inherits three methods from java.lang.Object:

The default toString is useless in logs. You can see its shape without printing a changing hash:

// File: Main.javapublic class Main {    static class Plain {    }    static class Friendly {        private final String name;        private final int age;        Friendly(String name, int age) {            this.name = name;            this.age = age;        }        @Override        public String toString() {            return "Friendly[name=" + name + ", age=" + age + "]";        }    }    public static void main(String[] args) {        System.out.println(new Plain().toString().startsWith("Main$Plain@"));        System.out.println(new Friendly("Asha", 30));    }}

trueFriendly[name=Asha, age=30]

System.out.println(object) calls toString() for you, and so does string concatenation. A good toString includes the class name and the important fields, helps whoever reads a log or a debugger, and never includes secrets such as passwords or tokens (they end up in log files). Keep it simple, since it is for people, not for parsing.

When a class represents a value (a point, an amount of money, an email address, an ISBN), two instances with the same value should be equal. You then override equals. The documentation of Object.equals states a contract, and every override must honour it:

Here is a correct implementation for a small value class, using the modern pattern-matching form of instanceof:

// File: Point.javaimport java.util.Objects;public final class Point {    private final int x;    private final int y;    public Point(int x, int y) {        this.x = x;        this.y = y;    }    @Override    public boolean equals(Object o) {        if (this == o) {            return true;        }        if (!(o instanceof Point other)) {     // also false when o is null            return false;        }        return x == other.x && y == other.y;    }    @Override    public int hashCode() {        return Objects.hash(x, y);    }    @Override    public String toString() {        return "Point(" + x + ", " + y + ")";    }}

The steps are always the same: return true for the same reference, return false if the argument is not the right type (an instanceof test is also false for null), then compare the significant fields. Use == for primitive fields and Objects.equals(a, b) for reference fields, because it handles null safely.

Three traps deserve a warning:

• Signature. The method must be equals(Object). If you write equals(Point other), you have overloaded it, not overridden it, and collections will still call the original. @Override makes the compiler catch this.
• Inheritance. If a subclass adds fields that participate in equality, symmetry is hard to preserve (a Point and a ColorPoint cannot be equal both ways unless the colour is ignored). Making the class final, as here, or using composition avoids the problem.
• Floating-point fields. Do not compare double values with == in equals if they come from calculations. Use Double.compare.

hashCode returns an int that hash-based collections use to decide where to look for an object. Article 12 explains the machinery. For now, the contract that matters is:

If two objects are equal according to equals, they must have the same hashCode.

The converse is not required: two unequal objects may share a hash code (a collision), and good hash functions simply make that unlikely. The result must also be consistent: the same object must return the same value while its significant fields do not change.

What happens when you break the rule? A class that overrides equals but not hashCode inherits an identity-based hash code, so two equal objects will usually have different hash codes.

// File: Main.javaimport java.util.HashSet;import java.util.Objects;import java.util.Set;public class Main {    static class BrokenPoint {        final int x;        final int y;        BrokenPoint(int x, int y) {            this.x = x;            this.y = y;        }        @Override        public boolean equals(Object o) {            return o instanceof BrokenPoint p && x == p.x && y == p.y;        }        // hashCode() forgotten    }    static class GoodPoint {        final int x;        final int y;        GoodPoint(int x, int y) {            this.x = x;            this.y = y;        }        @Override        public boolean equals(Object o) {            return o instanceof GoodPoint p && x == p.x && y == p.y;        }        @Override        public int hashCode() {            return Objects.hash(x, y);        }    }    public static void main(String[] args) {        Set<BrokenPoint> broken = new HashSet<>();        broken.add(new BrokenPoint(1, 2));        System.out.println("broken contains equal point: " + broken.contains(new BrokenPoint(1, 2)));        broken.add(new BrokenPoint(1, 2));        System.out.println("broken size after adding a duplicate: " + broken.size());        Set<GoodPoint> good = new HashSet<>();        good.add(new GoodPoint(1, 2));        System.out.println("good contains equal point: " + good.contains(new GoodPoint(1, 2)));        good.add(new GoodPoint(1, 2));        System.out.println("good size after adding a duplicate: " + good.size());    }}

broken contains equal point: falsebroken size after adding a duplicate: 2good contains equal point: truegood size after adding a duplicate: 1

The first set did exactly the bug from the start of this article: it does not find an equal object, and it accepts a duplicate. (With the identity-based default, the broken results are expected with overwhelming probability, because two objects almost never share a hash code by chance, but it is the contract violation, not luck, that you should rely on.) The second set behaves correctly, because equal objects hash equally.

Objects.hash(x, y) is the simplest correct way to compute a hash from the same fields as equals. It is not the fastest, and for most classes it is fine. IDEs can also generate equals and hashCode, and records (article 9) generate them for you.

The contract says that the hash code must be consistent while the object is unchanged. What if the object is changed while it sits in a hash-based collection?

// File: Main.javaimport java.util.HashSet;import java.util.Objects;import java.util.Set;public class Main {    static class MutablePoint {        int x;        int y;        MutablePoint(int x, int y) {            this.x = x;            this.y = y;        }        @Override        public boolean equals(Object o) {            return o instanceof MutablePoint p && x == p.x && y == p.y;        }        @Override        public int hashCode() {            return Objects.hash(x, y);        }    }    public static void main(String[] args) {        Set<MutablePoint> set = new HashSet<>();        MutablePoint p = new MutablePoint(1, 2);        set.add(p);        System.out.println("before: " + set.contains(p));        p.x = 99;      // changes the hash code while p is inside the set        System.out.println("after change: " + set.contains(p));        System.out.println("size: " + set.size());    }}

before: trueafter change: falsesize: 1

After the mutation, set.contains(p) is false for the very object that is in the set, because the set looks in the bucket for the new hash code, and the object is stored under the old one. The object is still counted in size, so you have an element that is in the collection and unreachable by lookup. Never mutate an object in a way that changes its equals or hashCode while it is a key in a map or an element in a set. The robust solution is to make such classes immutable.

An immutable object cannot change after it is created. String, Integer, BigDecimal and LocalDate are immutable, which is a large part of why they are safe to use as map keys and to share between parts of a program.

To make your own class immutable:

1. Declare the class final (or ensure no subclass can add mutable state).
2. Make all fields private final.
3. Provide no methods that modify state. If you need a "changed" version, return a new object.
4. Initialise everything in the constructor.
5. Copy mutable inputs and outputs. If a field holds a mutable object (a List, an array, a Date), copy it on the way in and expose a copy or an unmodifiable view on the way out. These are defensive copies.

// File: Main.javaimport java.util.ArrayList;import java.util.List;public class Main {    static final class Playlist {        private final String name;        private final List<String> songs;        Playlist(String name, List<String> songs) {            this.name = name;            this.songs = List.copyOf(songs);       // defensive copy in: unmodifiable snapshot        }        List<String> songs() {            return songs;                          // safe to return: it is unmodifiable        }        Playlist withSong(String song) {           // "change" by creating a new object            List<String> more = new ArrayList<>(songs);            more.add(song);            return new Playlist(name, more);        }    }    public static void main(String[] args) {        List<String> original = new ArrayList<>(List.of("Intro", "Verse"));        Playlist playlist = new Playlist("Study", original);        original.add("Hidden track");              // the caller changes their own list        System.out.println(playlist.songs());      // the playlist is unaffected        Playlist bigger = playlist.withSong("Outro");        System.out.println(playlist.songs() + " vs " + bigger.songs());        try {            playlist.songs().add("Sneaky");        } catch (UnsupportedOperationException e) {            System.out.println("cannot modify the playlist from outside");        }    }}

[Intro, Verse][Intro, Verse] vs [Intro, Verse, Outro]cannot modify the playlist from outside

Without the defensive copy, the line original.add("Hidden track") would have changed the playlist from the outside, breaking its supposed immutability. List.copyOf (Java 10) makes an unmodifiable snapshot, and List.of creates unmodifiable lists too.

Immutability costs you something: every change creates a new object, which can matter for large structures. In return you get simpler reasoning (an object's state cannot surprise you), safe sharing, automatic thread safety (there is nothing to synchronise, which article 19 uses), and safe use as keys. A sound default for value-like classes is to make them immutable, and to make entities with identity and a lifecycle (an account, an order) mutable but carefully encapsulated.

The java.util.Objects class has helpers that remove boilerplate:

• Objects.equals(a, b): null-safe equality.
• Objects.hash(...): a hash code over several values.
• Objects.requireNonNull(value, "message"): fail fast with a clear message.
• Objects.toString(obj, "default"): a null-safe string.

• Using == on objects to test for equality, especially String and boxed numbers.
• Overriding equals without hashCode.
• Writing equals(Point) and silently overloading.
• Comparing the wrong things: including a field in hashCode that is not in equals is fine, but the reverse breaks the contract.
• Mutating a hash key.
• Returning a mutable internal field (a list or array) directly, which breaks encapsulation.
• Putting secrets in toString.
• Relying on a hashCode value being the same between runs or JVM versions. It is not specified.

import java.util.Objects;public final class Money {    private final long paise;    private final String currency;    public Money(long paise, String currency) {        this.paise = paise;        this.currency = Objects.requireNonNull(currency);    }    @Override    public boolean equals(Object o) {        if (this == o) return true;        if (!(o instanceof Money other)) return false;        return paise == other.paise && currency.equals(other.currency);    }    @Override    public int hashCode() {        return Objects.hash(paise, currency);    }    @Override    public String toString() {        return paise + " paise " + currency;    }}

• Next: Strings, StringBuilder, Text Blocks and Time applies immutability to the most used class in Java.
• To see why hash codes matter: Maps and How HashMap Works.
• For a shortcut that writes equals, hashCode and toString for you: Enums, Records and Sealed Types.