A disclaimer or two for Optional

[Howard Lovatt]

I think the wording is very good, but would like the description of them to directly say don't synchronise on them. It implies don't synchronise, but I think spelling that out would be a good thing. 

If a Value annotation were added it could be seen at runtime which would be useful. For example when custom serialising and deserialising. In future additions of Java the annotation could be used to warn against using == etc on values. Further into the future maybe the runtime will treat them as a special case. Integer etc could also be annotated and have their public constructors deprecated. 

As I said, I think the wording is very good and a welcome addition. 

 -- Howard.  

Sent from my iPad

> On 27 Nov 2013, at 7:35 am, 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>
>