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

[Joe Darcy]

On 04/09/2013 06:00 PM, Mike Duigou wrote:
> Are we convinced that the capture cost of the lambdas likely to be used as suppliers is generally (*) better than the string construction that using a Supplier would avoid?
>
> (*) I say "generally" because I am certain examples could be found in which either is clearly better.

I know I've hesitated to use the existing requireNonNull method with a 
custom message at times because of having to always pay the string 
construction cost.

I think the supplier passed as a lambda combination is on the right side 
of likely vm optimization attention in the JDK 8 train.

-Joe

>
> Mike
>
> On Apr 9 2013, at 14:12 , 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") {
>>