6889858: Add nonNull methods to java.util.Objects

Reviewed-by: darcy
Contributed-by: jjb@google.com

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

@@ -107,4 +107,50 @@ public class Objects {
     public static <T> int compare(T a, T b, Comparator<? super T> c) {
         return (a == b) ? 0 :  c.compare(a, b);
     }
+
+    /**
+     * Checks that the specified object reference is not {@code null}. This
+     * method is designed primarily for doing parameter validation in methods
+     * and constructors, as demonstrated below:
+     * <blockquote><pre>
+     * public Foo(Bar bar) {
+     *     this.bar = Objects.nonNull(bar);
+     * }
+     * </pre></blockquote>
+     *
+     * @param obj the object reference to check for nullity
+     * @param <T> the type of the reference
+     * @return {@code obj} if not {@code null}
+     * @throws NullPointerException if {@code obj} is {@code null}
+     */
+    public static <T> T nonNull(T obj) {
+        if (obj == null)
+            throw new NullPointerException();
+        return obj;
+    }
+
+    /**
+     * Checks that the specified object reference is not {@code null} and
+     * throws a customized {@link NullPointerException} if it is. This method
+     * is designed primarily for doing parameter validation in methods and
+     * constructors with multiple parameters, as demonstrated below:
+     * <blockquote><pre>
+     * public Foo(Bar bar, Baz baz) {
+     *     this.bar = Objects.nonNull(bar, "bar must not be null");
+     *     this.baz = Objects.nonNull(baz, "baz must not be null");
+     * }
+     * </pre></blockquote>
+     *
+     * @param obj     the object reference to check for nullity
+     * @param message 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}
+     */
+    public static <T> T nonNull(T obj, String message) {
+        if (obj == null)
+            throw new NullPointerException(message);
+        return obj;
+    }
 }

test/java/util/Objects/BasicObjectsTest.java

@@ -37,6 +37,7 @@ public class BasicObjectsTest {
         errors += testHashCode();
         errors += testToString();
         errors += testCompare();
+        errors += testNonNull();
         if (errors > 0 )
             throw new RuntimeException();
     }
@@ -102,4 +103,53 @@ public class BasicObjectsTest {
         }
         return errors;
     }
+
+    private static int testNonNull() {
+        int errors = 0;
+        String s;
+
+        // Test 1-arg variant
+        try {
+            s = Objects.nonNull("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++;
+        }
+
+        try {
+            s = Objects.nonNull(null);
+            System.err.printf("1-arg nonNull failed to throw NPE");
+            errors++;
+        } catch (NullPointerException e) {
+            // Expected
+        }
+
+        // Test 2-arg variant
+        try {
+            s = Objects.nonNull("pants", "trousers");
+            if (s != "pants") {
+                System.err.printf("2-arg nonNull failed to return its arg");
+                errors++;
+            }
+        } catch (NullPointerException e) {
+            System.err.printf("2-arg nonNull threw unexpected NPE");
+            errors++;
+        }
+
+        try {
+            s = Objects.nonNull(null, "pantaloons");
+            System.err.printf("2-arg nonNull failed to throw NPE");
+            errors++;
+        } catch (NullPointerException e) {
+            if (e.getMessage() != "pantaloons") {
+                System.err.printf("2-arg nonNull threw NPE w/ bad detail msg");
+                errors++;
+            }
+        }
+        return errors;
+    }
 }