A disclaimer or two for Optional

[Tim Peierls]

Whoops, I never responded to the latest proposal. I think it's fine, just
what I was hoping for when I wrote, earlier in this thread:

I think a better way to prepare folks for such a language change would be
> to create a separate section in an overview or package doc that describes
> valueish types and what you shouldn't do with them, perhaps mentioning the
> possibility of a language change that would make such misuse entirely
> broken, and add links from the class comment for all such types to this
> section.


Glad there's no mention of language change. And "value-based" is certainly
better than "valueish". :-)

--tim


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>
>
>>
>>