Java 9 java.util.Objects Additions

1. Introduction

The java.util.Objects class has been part of Java since version 1.7. This class provides static utility methods for objects which can be used to perform some of the everyday tasks like checking for equality, null checks, etc.

In this article, we will look at the new methods introduced in the java.util.Objects class in Java 9.

2. The requireNonNullElse Method

This method accepts two parameters and returns the first parameter if it is not null, the second parameter otherwise. If both parameters are null, it throws NullPointerException:

private List<String> aMethodReturningNullList(){
    return null;
}

@Test
public void givenNullObject_whenRequireNonNullElse_thenElse() {
    List<String> aList = Objects.<List>requireNonNullElse(
      aMethodReturningNullList(), Collections.EMPTY_LIST);
 
    assertThat(aList, is(Collections.EMPTY_LIST));
}

private List<String> aMethodReturningNonNullList() {
    return List.of("item1", "item2");
}

@Test
public void givenObject_whenRequireNonNullElse_thenObject() {
    List<String> aList = Objects.<List>requireNonNullElse(
      aMethodReturningNonNullList(), Collections.EMPTY_LIST);
 
    assertThat(aList, is(List.of("item1", "item2")));
}

@Test(expected = NullPointerException.class)
public void givenNull_whenRequireNonNullElse_thenException() {
    Objects.<List>requireNonNullElse(null, null);
}

3. Using requireNonNullElseGet

This method is similar to requireNonNullElse, except that the second parameter, is a java.util.function.Supplier interface which allows a lazy instantiation of the provided collection. The Supplier implementation is responsible for returning a non-null object as shown below:

@Test
public void givenObject_whenRequireNonNullElseGet_thenObject() {
    List<String> aList = Objects.<List>requireNonNullElseGet(
      null, List::of);
    assertThat(aList, is(List.of()));
}

4. Using checkIndex

This method is used for checking if the index is within the given length. It returns the index if 0 <= index < length. Otherwise, it throws an IndexOutOfBoundsException as shown below:

@Test
public void givenNumber_whenInvokeCheckIndex_thenNumber() {
    int length = 5;
 
    assertThat(Objects.checkIndex(4, length), is(4));
}

@Test(expected = IndexOutOfBoundsException.class)
public void givenOutOfRangeNumber_whenInvokeCheckIndex_thenException() {
    int length = 5;
    Objects.checkIndex(5, length);
}

5. Using checkFromToIndex

This method is used to check if the given sub range formed by [fromIndex, toIndex) is within the range formed by [0, length). If the sub-range is valid, then it returns the lower bound as shown below:

@Test
public void givenSubRange_whenCheckFromToIndex_thenNumber() {
    int length = 6;
 
    assertThat(Objects.checkFromToIndex(2,length,length), is(2));
}

@Test(expected = IndexOutOfBoundsException.class)
public void givenInvalidSubRange_whenCheckFromToIndex_thenException() {
    int length = 6;
    Objects.checkFromToIndex(2,7,length);
}

Note: In mathematics, a range represented in the form of  [a, b) indicates the range is inclusive of a and exclusive of b. [ and ] state that the number is included and ( and ) state that the number is excluded.

6. Using checkFromIndexSize

This method is similar to checkFromToIndex except that instead of providing the upper bound of the sub-range we provide the size and the lower bound of the sub-range.

The sub-range, in this case, is [fromIndex, fromIndex + size) and this method checks that the sub range is within the range formed by [0, length):

@Test
public void givenSubRange_whenCheckFromIndexSize_thenNumber() {
    int length = 6;
 
    assertThat(Objects.checkFromIndexSize(2,3,length), is(2));
}

@Test(expected = IndexOutOfBoundsException.class)
public void givenInvalidSubRange_whenCheckFromIndexSize_thenException() {
    int length = 6;
    Objects.checkFromIndexSize(2, 6, length);
}

7. Conclusion

The java.util.Objects class in JDK 9 covers few new utility methods. It is also encouraging because this service class has been regularly updated since the time it was introduced in Java 7.

The code for this article can be found over on GitHub.