A disclaimer or two for Optional

[Tim Peierls]

Ideally, yes, but doubtless getting this into javac now would mean an
enormous delay, leaving an unpleasant choice between having only the doc
warnings now -- with better javac messages left for the future -- and
pushing everything into the distant future. (*Pace* Brian, for whom it
cannot be expressed as a choice.)

Can't FindBugs be a stopgap measure here? If one ignores the docs now and
refuses to (or can't) recompile after a future release that has javac
messages for value-based rules violations, then one should at least run
FindBugs on your class files. (Such violations *are* amenable to FindBugs
detection, aren't they?)

--tim


On Sat, Nov 30, 2013 at 11:43 AM, Joe Bowbeer <joe.bowbeer at gmail.com> wrote:

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