Java Objects.hash() vs Objects.hashCode()

1. Introduction

A hashcode is a numeric representation of the contents of an object.

In Java, there are a few different methods we can use to get a hashcode for an object:

• Object.hashCode() 
• Objects.hashCode() – introduced in Java 7
• Objects.hash() – introduced in Java 7

In this tutorial, we're going to look at each of those methods. First, we'll start with definitions and basic examples. After we have the basic usage down, we'll dig into the differences between them and the ramifications those differences may have.

2. Basic Usage

2.1. Object.hashCode()

We can use the Object.hashCode() method to retrieve the hashcode of an object. It's very similar to Objects.hashCode() except that we can't use it if our object is null.

With that said, let's call Object.hashCode() on two identical Double objects:

Double valueOne = Double.valueOf(1.0012);
Double valueTwo = Double.valueOf(1.0012);
        
int hashCode1 = valueOne.hashCode();
int hashCode2 = valueTwo.hashCode();
        
assertEquals(hashCode1, hashCode2);

As expected, we receive identical hashcodes.

In contrast, now let's call Object.hashCode() on a null object with the expectation that a NullPointerException is thrown:

Double value = null;
value.hashCode();

2.2. Objects.hashCode()

Objects.hashCode() is a null-safe method we can use to get the hashcode of an object. Hashcodes are necessary for hash tables and the proper implementation of equals().

The general contract for a hashcode as specified in the JavaDoc is:

• That the returned integer be the same each time it's called for an unchanged object during the same execution of the application
• For two objects that are equal according to their equals() method, return the same hashcode

Although it's not a requirement, distinct objects return different hashcodes as much as possible.

First, let's call Objects.hashCode() on two identical strings:

String stringOne = "test";
String stringTwo = "test";
int hashCode1 = Objects.hashCode(stringOne);
int hashCode2 = Objects.hashCode(stringTwo);
        
assertEquals(hashCode1, hashCode2);

Now, we expect the returned hashcodes to be identical.

On the other hand, if we provide a null to Objects.hashCode(), we'll get zero back:

String nullString = null;
int hashCode = Objects.hashCode(nullString);
assertEquals(0, hashCode);

2.3. Objects.hash()

Unlike Objects.hashCode(), which takes only a single object, Objects.hash() can take one or more objects and provides a hashcode for them. Under the hood, the hash() method works by putting the supplied objects into an array and calling Arrays.hashCode() on them. If we provide only one object to the Objects.hash() method, we can't expect the same results as calling Objects.hashCode() on the object.

First, let's call Objects.hash() with two pairs of identical strings:

String strOne = "one";
String strTwo = "two";
String strOne2 = "one";
String strTwo2 = "two";
        
int hashCode1 = Objects.hash(strOne, strTwo);
int hashCode2 = Objects.hash(strOne2, strTwo2);
        
assertEquals(hashCode1, hashCode2);

Next, let's call Objects.hash() and Objects.hashCode() with a single string:

String testString = "test string";
int hashCode1 = Objects.hash(testString);
int hashCode2 = Objects.hashCode(testString);
        
assertNotEquals(hashCode1, hashCode2);

As expected, the two hashcodes returned do not match.

3. Key Differences

In the previous section, we hit on the key difference between Objects.hash() and Objects.hashCode(). Now, let's dig into it a little deeper so we can understand some of the ramifications.

If we need to override one of our class's equals() method, it's critical that we properly override hashCode() as well.

Let's start by creating a simple Player class for our example:

public class Player {
    private String firstName;
    private String lastName;
    private String position;
    // Standard getters/setters
}

3.1. Multiple Field Hashcode Implementation

Let's imagine that our Player class is considered unique across all three fields: firstName, lastName, and position.

With that said, let's look at how we might have implemented Player.hashCode() prior to Java 7:

@Override
public int hashCode() {
    int result = 17;
    result = 31 * result + firstName != null ? firstName.hashCode() : 0;
    result = 31 * result + lastName != null ? lastName.hashCode() : 0;
    result = 31 * result + position != null ? position.hashCode() : 0;
    return result;
}

Because both Objects.hashCode() and Objects.hash() were introduced with Java 7, we have to explicitly check for null before calling Object.hashCode() on each field.

Let's confirm that we can both call hashCode() twice on the same object and get the same result and that we can call it on identical objects and get the same result:

Player player = new Player("Eduardo", "Rodriguez", "Pitcher");
Player indenticalPlayer = new Player("Eduardo", "Rodriguez", "Pitcher");
        
int hashCode1 = player.hashCode();
int hashCode2 = player.hashCode();
int hashCode3 = indenticalPlayer.hashCode();
        
assertEquals(hashCode1, hashCode2);
assertEquals(hashCode1, hashCode3);

Next, let's look at how we can shorten that a bit by taking advantage of null-safety we get with Objects.hashCode():

int result = 17;
result = 31 * result + Objects.hashCode(firstName);
result = 31 * result + Objects.hashCode(lastName);
result = 31 * result + Objects.hashCode(position);
return result;

If we run the same unit test, we should expect the same results.

Because our class relies on multiple fields to determine equality, let's go a step further and use Objects.hash() to make our hashCode() method very succinct:

return Objects.hash(firstName, lastName, position);

After this update, we should be able to successfully run our unit test again.

3.2. Objects.hash() Details

Under the hood, when we call Objects.hash(), the values are placed in an array, and then Arrays.hashCode() is called on the array.

With that said, let's create a Player and compare its hashcode to Arrays.hashCode() with the values we use:

@Test
public void whenCallingHashCodeAndArraysHashCode_thenSameHashCodeReturned() {
    Player player = new Player("Bobby", "Dalbec", "First Base");
    int hashcode1 = player.hashCode();
    String[] playerInfo = {"Bobby", "Dalbec", "First Base"};
    int hashcode2 = Arrays.hashCode(playerInfo);
        
    assertEquals(hashcode1, hashcode2);
}

We created a Player and then created a String[]. Then we called hashCode() on the Player and used Arrays.hashCode() on the array and received the same hashcode.

4. Conclusion

In this article, we learned how and when to use the Object.hashCode(), Objects.hashCode() and Objects.hash(). Additionally, we looked into the differences between them.

As a review, let's quickly summarize their usage:

• Object.hashCode(): use to get the hashcode of a single, non-null object
• Objects.hashCode(): use to get the hashcode of a single object that might be null
• Objects.hash(): use to get a hashcode for multiple objects

As always, the example code is available over on GitHub.