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

rev 8872 : 8028816: Add value-type notice to Optional* classes
Reviewed-by: mduigou
Contributed-by: brian.goetz@oracle.com, bitterfoxc@gmail.com

@@ -38,10 +38,15 @@
  * value are provided, such as {@link #orElse(java.lang.Object) orElse()}
  * (return a default value if value not present) and
  * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block
  * of code if the value is present).
  *
+ * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
+ * class; use of identity-sensitive operations (including reference equality
+ * ({@code ==}), identity hash code, or synchronization) on instances of
+ * {@code Optional} may have unpredictable effects and should be avoided.
+ *
  * @since 1.8
  */
 public final class Optional<T> {
     /**
      * Common instance for {@code empty()}.