8011800: Add java.util.Objects.requireNonNull(T, Supplier<String>)

Reviewed-by: alanb, dholmes, mduigou

src/share/classes/java/util/Objects.java

 /*
- * 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,30 @@ public final class Objects {
             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>Unlike the method {@link requireNonNull(Object, String},
+     * this method allows creation of the message to be deferred until
+     * after the null check is made. While this may confer a
+     * performance advantage in the non-null case, when deciding to
+     * call this method care should be taken that the costs of
+     * creating the message supplier are less than the cost of just
+     * creating the string message directly.
+     *
+     * @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;
+    }
 }

test/java/util/Objects/BasicObjectsTest.java

 /*
- * 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,12 +23,13 @@
 
 /*
  * @test
- * @bug 6797535 6889858 6891113
+ * @bug 6797535 6889858 6891113 8011800
  * @summary Basic tests for methods in java.util.Objects
  * @author  Joseph D. Darcy
  */
 
 import java.util.*;
+import java.util.function.*;
 
 public class BasicObjectsTest {
     public static void main(String... args) {
@@ -40,7 +41,7 @@ public class BasicObjectsTest {
         errors += testToString();
         errors += testToString2();
         errors += testCompare();
-        errors += testNonNull();
+        errors += testRequireNonNull();
         if (errors > 0 )
             throw new RuntimeException();
     }
@@ -158,49 +159,54 @@ public class BasicObjectsTest {
         return errors;
     }
 
-    private static int testNonNull() {
+    private static int testRequireNonNull() {
         int errors = 0;
-        String s;
 
-        // Test 1-arg variant
-        try {
-            s = Objects.requireNonNull("pants");
-            if (s != "pants") {
-                System.err.printf("1-arg non-null failed to return its arg");
-                errors++;
-            }
-        } catch (NullPointerException e) {
-            System.err.printf("1-arg nonNull threw unexpected NPE");
-            errors++;
-        }
+        final String RNN_1 = "1-arg requireNonNull";
+        final String RNN_2 = "2-arg requireNonNull";
+        final String RNN_3 = "Supplier requireNonNull";
 
-        try {
-            s = Objects.requireNonNull(null);
-            System.err.printf("1-arg nonNull failed to throw NPE");
-            errors++;
-        } catch (NullPointerException e) {
-            // Expected
-        }
+        Function<String, String> rnn1 = s -> Objects.requireNonNull(s);
+        Function<String, String> rnn2 = s -> Objects.requireNonNull(s, "trousers");
+        Function<String, String> rnn3 = s -> Objects.requireNonNull(s, () -> "trousers");
+
+        errors += testRNN_NonNull(rnn1, RNN_1);
+        errors += testRNN_NonNull(rnn2, RNN_2);
+        errors += testRNN_NonNull(rnn3, RNN_3);
+
+        errors += testRNN_Null(rnn1, RNN_1, null);
+        errors += testRNN_Null(rnn2, RNN_2, "trousers");
+        errors += testRNN_Null(rnn3, RNN_3, "trousers");
+        return errors;
+    }
 
-        // Test 2-arg variant
+    private static int testRNN_NonNull(Function<String, String> testFunc,
+                                           String testFuncName) {
+        int errors = 0;
         try {
-            s = Objects.requireNonNull("pants", "trousers");
+            String s = testFunc.apply("pants");
             if (s != "pants") {
-                System.err.printf("2-arg nonNull failed to return its arg");
+                System.err.printf(testFuncName + " failed to return its arg");
                 errors++;
             }
         } catch (NullPointerException e) {
-            System.err.printf("2-arg nonNull threw unexpected NPE");
+            System.err.printf(testFuncName + " threw unexpected NPE");
             errors++;
         }
+        return errors;
+    }
 
+    private static int testRNN_Null(Function<String, String> testFunc,
+                                               String testFuncName,
+                                               String expectedMessage) {
+        int errors = 0;
         try {
-            s = Objects.requireNonNull(null, "pantaloons");
-            System.err.printf("2-arg nonNull failed to throw NPE");
+            String s = testFunc.apply(null);
+            System.err.printf(testFuncName + " failed to throw NPE");
             errors++;
         } catch (NullPointerException e) {
-            if (e.getMessage() != "pantaloons") {
-                System.err.printf("2-arg nonNull threw NPE w/ bad detail msg");
+            if (e.getMessage() != expectedMessage) {
+                System.err.printf(testFuncName + " threw NPE w/ bad detail msg");
                 errors++;
             }
         }