--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/lang/doc-files/ValueBased.html Tue Dec 03 21:22:14 2013 -0800
@@ -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>