diff --git a/jdk/src/share/classes/java/lang/doc-files/ValueBased.html b/jdk/src/share/classes/java/lang/doc-files/ValueBased.html
new file mode 100644
index 00000000000..7e1ee8bbf2c
--- /dev/null
+++ b/jdk/src/share/classes/java/lang/doc-files/ValueBased.html
@@ -0,0 +1,42 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+  <title>Value-based Classes</title>
+  <link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
+</head>
+<body>
+<h2 id="ValueBased">Value-based Classes</h2>
+
+Some classes, such as <code>java.util.Optional</code> and
+<code>java.time.LocalDateTime</code>, are <em>value-based</em>.  Instances of a
+value-based class:
+<ul>
+    <li>are final and immutable (though may contain references to mutable
+        objects);</li>
+    <li>have implementations of <code>equals</code>,
+        <code>hashCode</code>, and <code>toString</code> which are computed
+        solely from the instance's state and not from its identity or the state
+        of any other object or variable;</li>
+    <li>make no use of identity-sensitive operations such as reference
+        equality (<code>==</code>) between instances, identity hash code of
+        instances, or synchronization on an instances's intrinsic lock;</li>
+    <li>are considered equal solely based on <code>equals()</code>, not
+        based on reference equality (<code>==</code>);</li>
+    <li>do not have accessible constructors, but are instead instantiated
+        through factory methods which make no committment as to the identity
+        of returned instances;</li>
+    <li>are <em>freely substitutable</em> when equal, meaning that interchanging
+        any two instances <code>x</code> and <code>y</code> that are equal
+        according to <code>equals()</code> in any computation or method
+        invocation should produce no visible change in behavior.
+    </li>
+</ul>
+
+<p>A program may produce unpredictable results if it attempts to distinguish two
+    references to equal values of a value-based class, whether directly via reference
+    equality or indirectly via an appeal to synchronization, identity hashing,
+    serialization, or any other identity-sensitive mechanism.  Use of such
+    identity-sensitive operations on instances of value-based classes may have
+    unpredictable effects and should be avoided.</p>
+</body>
+</html>
diff --git a/jdk/src/share/classes/java/util/Optional.java b/jdk/src/share/classes/java/util/Optional.java
index 10b79234b18..d471058ec16 100644
--- a/jdk/src/share/classes/java/util/Optional.java
+++ b/jdk/src/share/classes/java/util/Optional.java
@@ -40,6 +40,11 @@ import java.util.function.Supplier;
  * {@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 results and should be avoided.
+ *
  * @since 1.8
  */
 public final class Optional<T> {
diff --git a/jdk/src/share/classes/java/util/OptionalDouble.java b/jdk/src/share/classes/java/util/OptionalDouble.java
index eda306cf7d4..0efc770fa03 100644
--- a/jdk/src/share/classes/java/util/OptionalDouble.java
+++ b/jdk/src/share/classes/java/util/OptionalDouble.java
@@ -31,7 +31,7 @@ import java.util.function.Supplier;
 /**
  * A container object which may or may not contain a {@code double} value.
  * If a value is present, {@code isPresent()} will return {@code true} and
- * {@code get()} will return the value.
+ * {@code getAsDouble()} will return the value.
  *
  * <p>Additional methods that depend on the presence or absence of a contained
  * value are provided, such as {@link #orElse(double) orElse()}
@@ -39,6 +39,11 @@ import java.util.function.Supplier;
  * {@link #ifPresent(java.util.function.DoubleConsumer) 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 OptionalDouble} may have unpredictable results and should be avoided.
+ *
  * @since 1.8
  */
 public final class OptionalDouble {
diff --git a/jdk/src/share/classes/java/util/OptionalInt.java b/jdk/src/share/classes/java/util/OptionalInt.java
index 66478ce4713..5cb9275242b 100644
--- a/jdk/src/share/classes/java/util/OptionalInt.java
+++ b/jdk/src/share/classes/java/util/OptionalInt.java
@@ -31,7 +31,7 @@ import java.util.function.Supplier;
 /**
  * A container object which may or may not contain a {@code int} value.
  * If a value is present, {@code isPresent()} will return {@code true} and
- * {@code get()} will return the value.
+ * {@code getAsInt()} will return the value.
  *
  * <p>Additional methods that depend on the presence or absence of a contained
  * value are provided, such as {@link #orElse(int) orElse()}
@@ -39,6 +39,11 @@ import java.util.function.Supplier;
  * {@link #ifPresent(java.util.function.IntConsumer) 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 OptionalInt} may have unpredictable results and should be avoided.
+ *
  * @since 1.8
  */
 public final class OptionalInt {
diff --git a/jdk/src/share/classes/java/util/OptionalLong.java b/jdk/src/share/classes/java/util/OptionalLong.java
index f07cc0d3d3a..589a59fd3ae 100644
--- a/jdk/src/share/classes/java/util/OptionalLong.java
+++ b/jdk/src/share/classes/java/util/OptionalLong.java
@@ -31,7 +31,7 @@ import java.util.function.Supplier;
 /**
  * A container object which may or may not contain a {@code long} value.
  * If a value is present, {@code isPresent()} will return {@code true} and
- * {@code get()} will return the value.
+ * {@code getAsLong()} will return the value.
  *
  * <p>Additional methods that depend on the presence or absence of a contained
  * value are provided, such as {@link #orElse(long) orElse()}
@@ -39,6 +39,11 @@ import java.util.function.Supplier;
  * {@link #ifPresent(java.util.function.LongConsumer) 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 OptionalLong} may have unpredictable results and should be avoided.
+ *
  * @since 1.8
  */
 public final class OptionalLong {
