Java 9 java.util.Objects Additions – Java 9 java.util.Objects 新增内容

1. Introduction

1.介绍

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.

java.util.Objects类从1.7版开始就是Java的一部分。这个类为对象提供了静态的实用方法，可以用来执行一些日常的任务，如平等检查、null检查等等。

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

在这篇文章中，我们将看看Java 9中java.util.Objects类中引入的新方法。

2. The requireNonNullElse Method

2、requireNonNullElse方法

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:

该方法接受两个参数，如果第一个参数不是null，则返回第二个参数。如果两个参数都是null，它会抛出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

3、使用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:

这个方法类似于requireNonNullElse，除了第二个参数，是一个java.util.function.Supplier接口，允许对提供的集合进行懒惰的实例化。Supplier实现负责返回一个非空对象，如下所示。

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

4. Using checkIndex

4.使用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:

该方法用于检查索引是否在给定的长度内。如果0 <= index < length，它返回索引。否则，它会抛出一个IndexOutOfBoundsException，如下所示。

@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

5.使用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:

这个方法用来检查由[fromIndex, toIndex)组成的给定子范围是否在[0, length)组成的范围内。如果子范围是有效的，那么它返回下限，如下图所示。

@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.

注：在数学中，以[a，b]的形式表示的范围包括a，不包括b，[和]表示数字包括在内，（和）表示数字不包括在内。

6. Using checkFromIndexSize

6.使用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.

这个方法与checkFromToIndex类似，只是我们不提供子范围的上限，而是提供子范围的大小和下限。

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):

在这种情况下，子范围是[fromIndex, fromIndex + size)，这个方法检查子范围是否在[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

7.结论

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.

JDK 9中的java.util.Objects类涵盖了少数新的实用方法。这也是令人鼓舞的，因为这个服务类自从在Java 7中引入后就一直在定期更新。

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

这篇文章的代码可以在GitHub上找到over。