RFR: 8254275: Development to revise "value-based class" & apply to wrappers [v3]

[Dan Smith]

On Fri, 16 Oct 2020 20:44:25 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Dan Smith has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Addressing review comments in ValueBased.html
>
> src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 49:
> 
>> 47:         the behavior of the class's methods;</li>
>> 48:     <li>perform no synchronization using an instance's monitor;</li>
>> 49:     <li>do not have (or have deprecated any) accessible constructors;</li>
> 
> Having an accessible constructor should not be prohibited.
> Constructors do not imply or contradict the other constraints.
> And when we get to Valhalla, primitive classes are allowed to have accessible constructors.
> At least for the time being, the wrapper classes DO have accessible constructors; if the constraint is retained, then
> Integer, etc cannot be value-based.

The idea behind all the instance creation restrictions is this: clients of value-based classes should never be promised
a unique, private identity associated with any instances they are given. By designing the API in this way, we
discourage clients from inappropriate dependencies on identity, and pave the way for the classes to more smoothly
migrate to be primitive classes someday.

Yes, primitive classes can have public constructors. But if a *migrated* primitive class has a public constructor, its
clients will face binary and behavioral incompatibilities when the migration happens. If clients are using factories
that don't promise unique identities, and aren't doing risky synchronization on objects they don't uniquely control,
they will encounter neither of those incompatibilities.

The "or have deprecated any" rule allows for classes like the wrapper classes that do have accessible constructors, but
have used deprecation to discourage clients from using them. Deprecation is a strong enough signal that when clients
face future incompatibilities, they will have been sufficiently warned.

-------------

PR: https://git.openjdk.java.net/valhalla/pull/222