A disclaimer or two for Optional

[Brian Goetz]

I wish we could go farther.  Such as:

   ... and will likely result in thrown exceptions in future versions of 
the JDK.

On 10/19/2013 2:44 PM, Remi Forax wrote:
> I agree.
>
> Rémi
>
> On 10/19/2013 08:16 PM, Doug Lea wrote:
>>
>> This arose while contemplating some JDK9 possibilities...
>>
>> Note that Optional is itself a value-like class, without
>> a public constructor, just factory methods.
>> The factory methods do not even guarantee to return unique
>> objects. For all that the spec does and should say,
>> every call to Optional.of could return the same Optional
>> object. (This would require a magical implementation,
>> but still not disallowed, and variants that sometimes
>> return the same one are very much possible.)
>>
>> This means that there are no object-identity-related
>> guarantees for Optionals. "myOptional1 == myOptional2"
>> tells you nothing, and synchronized(myOptional) has
>> unpredictable effects -- it might block forever.
>>
>> People might find this surprising, so we probably want to
>> add a sentence or two to the javadoc. How about the following.
>> (We could symmetrically say that the instance returned by
>> Optional.empty() need not be the  same each time, but that
>> might be overkill?)
>>
>>     /**
>>      * Returns an {@code Optional} with the specified present non-null
>> value.
>> adding...
>> * The returned instance need not be unique. Thus the results of
>> * comparing two instances using @code{==}, or using one as the
>> * argument for a @code{synchronized} block are arbitrary and should
>> * be avoided.
>>      *
>>      * @param <T> the class of the value
>>      * @param value the value to be present, which must be non-null
>>      * @return an {@code Optional} with the value present
>>      * @throws NullPointerException if value is null
>>      */
>>     public static <T> Optional<T> of(T value) {
>>         return new Optional<>(value);
>>     }
>>
>