8167981: Optional: add notes explaining intended use

Reviewed-by: martin, psandoz

jdk/src/java.base/share/classes/java/util/Optional.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, 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
@@ -36,9 +36,9 @@ import java.util.stream.Stream;
  * {@code get()} returns the value.
  *
  * <p>Additional methods that depend on the presence or absence of a contained
- * value are provided, such as {@link #orElse(java.lang.Object) orElse()}
+ * value are provided, such as {@link #orElse(Object) orElse()}
  * (returns a default value if no value is present) and
- * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (performs an
+ * {@link #ifPresent(Consumer) ifPresent()} (performs an
  * action if a value is present).
  *
  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
@@ -46,6 +46,13 @@ import java.util.stream.Stream;
  * ({@code ==}), identity hash code, or synchronization) on instances of
  * {@code Optional} may have unpredictable results and should be avoided.
  *
+ * @apiNote
+ * {@code Optional} is primarily intended for use as a method return type where
+ * there is a clear need to represent "no result," and where using {@code null}
+ * is likely to cause errors. A variable whose type is {@code Optional} should
+ * never itself be {@code null}; it should always point to an {@code Optional}
+ * instance.
+ *
  * @param <T> the type of value
  * @since 1.8
  */
@@ -129,6 +136,12 @@ public final class Optional<T> {
      * If a value is present, returns the value, otherwise throws
      * {@code NoSuchElementException}.
      *
+     * @apiNote
+     * The methods {@link #orElse(Object) orElse} and
+     * {@link #orElseGet(Supplier) orElseGet}
+     * are generally preferable to this method, as they return a substitute
+     * value if the value is absent, instead of throwing an exception.
+     *
      * @return the non-{@code null} value described by this {@code Optional}
      * @throws NoSuchElementException if no value is present
      * @see Optional#isPresent()

jdk/src/java.base/share/classes/java/util/OptionalDouble.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, 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
@@ -37,7 +37,7 @@ import java.util.stream.DoubleStream;
  * <p>Additional methods that depend on the presence or absence of a contained
  * value are provided, such as {@link #orElse(double) orElse()}
  * (returns a default value if no value is present) and
- * {@link #ifPresent(java.util.function.DoubleConsumer) ifPresent()} (performs
+ * {@link #ifPresent(DoubleConsumer) ifPresent()} (performs
  * an action if a value is present).
  *
  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
@@ -45,6 +45,12 @@ import java.util.stream.DoubleStream;
  * ({@code ==}), identity hash code, or synchronization) on instances of
  * {@code OptionalDouble} may have unpredictable results and should be avoided.
  *
+ * @apiNote
+ * {@code OptionalDouble} is primarily intended for use as a method return type where
+ * there is a clear need to represent "no result." A variable whose type is
+ * {@code OptionalDouble} should never itself be {@code null}; it should always point
+ * to an {@code OptionalDouble} instance.
+ *
  * @since 1.8
  */
 public final class OptionalDouble {
@@ -110,6 +116,12 @@ public final class OptionalDouble {
      * If a value is present, returns the value, otherwise throws
      * {@code NoSuchElementException}.
      *
+     * @apiNote
+     * The methods {@link #orElse(double) orElse} and
+     * {@link #orElseGet(DoubleSupplier) orElseGet}
+     * are generally preferable to this method, as they return a substitute
+     * value if the value is absent, instead of throwing an exception.
+     *
      * @return the value described by this {@code OptionalDouble}
      * @throws NoSuchElementException if no value is present
      * @see OptionalDouble#isPresent()

jdk/src/java.base/share/classes/java/util/OptionalInt.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, 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
@@ -37,7 +37,7 @@ import java.util.stream.IntStream;
  * <p>Additional methods that depend on the presence or absence of a contained
  * value are provided, such as {@link #orElse(int) orElse()}
  * (returns a default value if no value is present) and
- * {@link #ifPresent(java.util.function.IntConsumer) ifPresent()} (performs an
+ * {@link #ifPresent(IntConsumer) ifPresent()} (performs an
  * action if a value is present).
  *
  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
@@ -45,6 +45,12 @@ import java.util.stream.IntStream;
  * ({@code ==}), identity hash code, or synchronization) on instances of
  * {@code OptionalInt} may have unpredictable results and should be avoided.
  *
+ * @apiNote
+ * {@code OptionalInt} is primarily intended for use as a method return type where
+ * there is a clear need to represent "no result." A variable whose type is
+ * {@code OptionalInt} should never itself be {@code null}; it should always point
+ * to an {@code OptionalInt} instance.
+ *
  * @since 1.8
  */
 public final class OptionalInt {
@@ -110,6 +116,12 @@ public final class OptionalInt {
      * If a value is present, returns the value, otherwise throws
      * {@code NoSuchElementException}.
      *
+     * @apiNote
+     * The methods {@link #orElse(int) orElse} and
+     * {@link #orElseGet(IntSupplier) orElseGet}
+     * are generally preferable to this method, as they return a substitute
+     * value if the value is absent, instead of throwing an exception.
+     *
      * @return the value described by this {@code OptionalInt}
      * @throws NoSuchElementException if no value is present
      * @see OptionalInt#isPresent()

jdk/src/java.base/share/classes/java/util/OptionalLong.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, 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
@@ -37,7 +37,7 @@ import java.util.stream.LongStream;
  * <p>Additional methods that depend on the presence or absence of a contained
  * value are provided, such as {@link #orElse(long) orElse()}
  * (returns a default value if no value is present) and
- * {@link #ifPresent(java.util.function.LongConsumer) ifPresent()} (performs an
+ * {@link #ifPresent(LongConsumer) ifPresent()} (performs an
  * action if a value is present).
  *
  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
@@ -45,6 +45,12 @@ import java.util.stream.LongStream;
  * ({@code ==}), identity hash code, or synchronization) on instances of
  * {@code OptionalLong} may have unpredictable results and should be avoided.
  *
+ * @apiNote
+ * {@code OptionalLong} is primarily intended for use as a method return type where
+ * there is a clear need to represent "no result." A variable whose type is
+ * {@code OptionalLong} should never itself be {@code null}; it should always point
+ * to an {@code OptionalLong} instance.
+ *
  * @since 1.8
  */
 public final class OptionalLong {
@@ -110,6 +116,12 @@ public final class OptionalLong {
      * If a value is present, returns the value, otherwise throws
      * {@code NoSuchElementException}.
      *
+     * @apiNote
+     * The methods {@link #orElse(long) orElse} and
+     * {@link #orElseGet(LongSupplier) orElseGet}
+     * are generally preferable to this method, as they return a substitute
+     * value if the value is absent, instead of throwing an exception.
+     *
      * @return the value described by this {@code OptionalLong}
      * @throws NoSuchElementException if no value is present
      * @see OptionalLong#isPresent()