JDK 8 code review request for 8011800: Add java.util.Objects.requireNonNull(T, Supplier<String>)

[Peter Levart]

Hi Joe,

This is similar to recent addition to j.u.l.Logger, which is ok. No 
matter how lambda construction is optimized, if it captures any 
non-constant arguments, new object will always be constructed (unless 
perhaps JIT could optimize this away using escape analysis). Myself I 
often find that the following overloads could also be useful:

     public static <T> T requireNonNull(T obj, String messageFormat, 
Object arg1);
     public static <T> T requireNonNull(T obj, String messageFormat, 
Object arg1, Object arg2);
     public static <T> T requireNonNull(T obj, String messageFormat, 
Object arg1, Object arg2, Object arg3);
     ...

...this is for example useful when you check the return value from a 
method or function and want to message some context (arguments passed to 
method/function) with the NPE...

Regards, Peter

On 04/09/2013 11:12 PM, Joe Darcy wrote:
> Hello,
>
> Please review my changes for
>
>     8011800: Add java.util.Objects.requireNonNull(T, Supplier<String>)
>     http://cr.openjdk.java.net/~darcy/8011800.0/
>
> which add a new method to java.util.Objects to take a Supplier<String> 
> rather than a String.
>
> Patch inline below.
>
> Thanks,
>
> -Joe
>
> --- old/src/share/classes/java/util/Objects.java    2013-04-09 
> 14:08:34.000000000 -0700
> +++ new/src/share/classes/java/util/Objects.java    2013-04-09 
> 14:08:33.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -25,6 +25,8 @@
>
>  package java.util;
>
> +import java.util.function.Supplier;
> +
>  /**
>   * This class consists of {@code static} utility methods for operating
>   * on objects.  These utilities include {@code null}-safe or {@code
> @@ -226,4 +228,31 @@
>              throw new NullPointerException(message);
>          return obj;
>      }
> +
> +    /**
> +     * Checks that the specified object reference is not {@code null} 
> and
> +     * throws a customized {@link NullPointerException} if it is.
> +     *
> +     * <p>Compared to the sibling method {@link requireNonNull(Object,
> +     * String}, this methods allows creation of the message to be
> +     * deferred until after the null check is made. Note that if the
> +     * supplier is provided via a lambda expression, there can be an
> +     * overhead involved in creating the supplier. Therefore, while
> +     * this method may confer a net performance advantage in the
> +     * non-null case, it is most likely to do so if creating the
> +     * message string is expensive.
> +     *
> +     * @param obj     the object reference to check for nullity
> +     * @param messageSupplier supplier of the detail message to be
> +     * used in the event that a {@code NullPointerException} is thrown
> +     * @param <T> the type of the reference
> +     * @return {@code obj} if not {@code null}
> +     * @throws NullPointerException if {@code obj} is {@code null}
> +     * @since 1.8
> +     */
> +    public static <T> T requireNonNull(T obj, Supplier<String> 
> messageSupplier) {
> +        if (obj == null)
> +            throw new NullPointerException(messageSupplier.get());
> +        return obj;
> +    }
>  }
> --- old/test/java/util/Objects/BasicObjectsTest.java    2013-04-09 
> 14:08:34.000000000 -0700
> +++ new/test/java/util/Objects/BasicObjectsTest.java    2013-04-09 
> 14:08:34.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -23,7 +23,7 @@
>
>  /*
>   * @test
> - * @bug 6797535 6889858 6891113
> + * @bug 6797535 6889858 6891113 8011800
>   * @summary Basic tests for methods in java.util.Objects
>   * @author  Joseph D. Darcy
>   */
> @@ -166,17 +166,17 @@
>          try {
>              s = Objects.requireNonNull("pants");
>              if (s != "pants") {
> -                System.err.printf("1-arg non-null failed to return 
> its arg");
> +                System.err.printf("1-arg requireNonNull failed to 
> return its arg");
>                  errors++;
>              }
>          } catch (NullPointerException e) {
> -            System.err.printf("1-arg nonNull threw unexpected NPE");
> +            System.err.printf("1-arg requireNonNull threw unexpected 
> NPE");
>              errors++;
>          }
>
>          try {
>              s = Objects.requireNonNull(null);
> -            System.err.printf("1-arg nonNull failed to throw NPE");
> +            System.err.printf("1-arg requireNonNull failed to throw 
> NPE");
>              errors++;
>          } catch (NullPointerException e) {
>              // Expected
> @@ -186,17 +186,40 @@
>          try {
>              s = Objects.requireNonNull("pants", "trousers");
>              if (s != "pants") {
> -                System.err.printf("2-arg nonNull failed to return its 
> arg");
> +                System.err.printf("2-arg requireNonNull failed to 
> return its arg");
>                  errors++;
>              }
>          } catch (NullPointerException e) {
> -            System.err.printf("2-arg nonNull threw unexpected NPE");
> +            System.err.printf("2-arg requireNonNull threw unexpected 
> NPE");
>              errors++;
>          }
>
>          try {
>              s = Objects.requireNonNull(null, "pantaloons");
> -            System.err.printf("2-arg nonNull failed to throw NPE");
> +            System.err.printf("2-arg requireNonNull failed to throw 
> NPE");
> +            errors++;
> +        } catch (NullPointerException e) {
> +            if (e.getMessage() != "pantaloons") {
> +                System.err.printf("2-arg requireNonNull threw NPE w/ 
> bad detail msg");
> +                errors++;
> +            }
> +        }
> +
> +        // Test supplier rvariant
> +        try {
> +            s = Objects.requireNonNull("pants", () -> "trousers");
> +            if (s != "pants") {
> +                System.err.printf("Supplier requireNonNull failed to 
> return its arg");
> +                errors++;
> +            }
> +        } catch (NullPointerException e) {
> +            System.err.printf("Supplier nonNull threw unexpected NPE");
> +            errors++;
> +        }
> +
> +        try {
> +            s = Objects.requireNonNull(null, () -> "pantaloons");
> +            System.err.printf("Suppiler requireNonNull failed to 
> throw NPE");
>              errors++;
>          } catch (NullPointerException e) {
>              if (e.getMessage() != "pantaloons") {
>