A disclaimer or two for Optional

[Brian Goetz]

No javac interaction for now. 

Sent from my iPhone

On Nov 27, 2013, at 7:43 PM, Joe Bowbeer <joe.bowbeer at gmail.com> wrote:

> I approve. It seems definitive.
> 
> It is also scary. Will javac emit these warnings?
> 
> On Nov 26, 2013 1:36 PM, "Brian Goetz" <brian.goetz at oracle.com> wrote:
>> OK, after several iterations with Doug and JohnR, I think we have a winner.
>> 
>> Then Optional would have a disclaimer:
>> 
>>  * <p>This is a <a href="../package-summary.html#ValueBased">value-based</a>
>>  * class; use of identity-sensitive operations on instances of {@code Optional}
>>  * may have unpredictable effects and should be avoided.
>>  *
>> 
>> pointing to (which lives in some suitable place, probably a .html file java/lang/doc-files):
>> 
>> 
>> <h2><a name="ValueBased">Value-based classes</a></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 immutable (though may contain references to mutable objects);</li>
>>     <li>have value-based implementations of <code>equals</code>,
>>         <code>hashCode</code>, and <code>toString</code>, which are computed
>>         solely from the instance's state and not on its identity or the state
>>         of any other object;</li>
>>     <li>make no use of identity-sensitive operations such as reference
>>         equality between instances, identity hash code of instances, or
>>         synchronization on an instances's intrinsic lock;</li>
>>     <li>are considered equal solely based on <code>Object.equals()</code>, not
>>         based on reference equality (<code>==</code>);</li>
>>     <li>are not instantiated through accessible constructors, but instead
>>         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>Object.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
>> identity-sensitive operations on instances of value-based classes may have
>> unpredictable effects and should be avoided.</p>