A disclaimer or two for Optional

[Joe Bowbeer]

I want javac to warn about any code that may have unpredictable results.
This is even more important if the unpredictable results may not manifest
immediately.

On Saturday, November 30, 2013, Brian Goetz wrote:

> No javac interaction for now.
>
> Sent from my iPhone
>
> On Nov 27, 2013, at 7:43 PM, Joe Bowbeer <joe.bowbeer at gmail.com<javascript:_e({}, 'cvml', '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<javascript:_e({}, 'cvml', '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>
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/lambda-libs-spec-experts/attachments/20131130/269f2a0f/attachment.html