What are HashMap contract rules?

In Java, a HashMap relies heavily on the correct implementation of the `hashCode()` and `equals()` methods for its keys. These methods define the 'contract' that custom objects must adhere to when used as keys, ensuring the HashMap can store and retrieve entries efficiently and correctly.

The Importance of `hashCode()` and `equals()`

When an object is used as a key in a HashMap, the HashMap first uses the key's hashCode() method to determine which 'bucket' (or array index) the entry should be stored in or retrieved from. If multiple keys hash to the same bucket (a 'collision'), it then uses the equals() method to distinguish between the keys. Incorrect implementations of these methods can lead to objects being lost, not found, or unexpected behavior within the HashMap.

The `hashCode()` Contract Rules

The java.lang.Object class defines the following contract for its hashCode() method:

• Consistency: If an object's internal state (the information used in equals() comparisons) remains unchanged, repeated invocations of hashCode() on the same object must consistently return the same integer. This integer need not be consistent between different executions of an application.
• Equality: If two objects are equal according to the equals(Object obj) method, then calling hashCode() on each of the two objects must produce the same integer result. This is the most crucial rule for HashMaps.
• Inequality (Optional): If two objects are unequal according to the equals(Object obj) method, it is *not* required that calling hashCode() on each of the two objects must produce different integer results. However, producing distinct integer results for unequal objects can improve the performance of hash tables.

class Person {
    private String name;
    private int age;

    // ... constructor, getters ...

    @Override
    public int hashCode() {
        int result = 17;
        result = 31 * result + (name == null ? 0 : name.hashCode());
        result = 31 * result + age;
        return result;
    }

    // ... equals() method ...
}

The `equals()` Contract Rules

The java.lang.Object class defines the following contract for its equals() method:

• Reflexivity: For any non-null reference value x, x.equals(x) must return true.
• Symmetry: For any non-null reference values x and y, x.equals(y) must return true if and only if y.equals(x) returns true.
• Transitivity: For any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) must return true.
• Consistency: For any non-null reference values x and y, multiple invocations of x.equals(y) must consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• Nullity: For any non-null reference value x, x.equals(null) must return false.

class Person {
    private String name;
    private int age;

    // ... constructor, getters ...

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Person person = (Person) o;
        return age == person.age &&
               Objects.equals(name, person.name);
    }

    // ... hashCode() method ...
}

Consequences of Violating the Contract

Violating these contracts, especially the hashCode()-equals() consistency rule, can lead to severe issues when using objects as keys in HashMaps (or any hash-based collection like HashSet or HashTable):

• Object Retrieval Failure: An object might be put into the HashMap, but when you try to retrieve it using an equal object (or even the same object if its mutable state used in hashCode() changes), the HashMap might look in the wrong bucket, leading to a null return.
• Duplicate Entries: If equals() is implemented incorrectly (e.g., always returning false) or hashCode() returns different values for equal objects, the HashMap might store multiple entries for logically identical keys, violating its principle of unique keys.
• Unpredictable Behavior: Inconsistent results, performance degradation due to poor hash distribution, and difficult-to-debug logical errors can arise.

Best Practices

• Always Override Both: If you override equals(), you *must* override hashCode() as well, and vice-versa.
• Use IDE Generation: Most modern IDEs (IntelliJ IDEA, Eclipse) can auto-generate correct hashCode() and equals() methods, which is highly recommended.
• Include equals() Fields in hashCode(): Ensure that all fields used in the equals() method are also used in the hashCode() method.
• Immutability for Keys: If possible, use immutable objects as HashMap keys. This guarantees that their hashCode() value will not change after they are put into the map, preventing retrieval issues.
• Objects.equals() and Objects.hash(): Utilize java.util.Objects.equals() for null-safe comparisons in equals() and java.util.Objects.hash() for generating hashCode() to simplify implementations and reduce errors.