We need help to migrate from bucket 1 to 2; and, the == problem

[Dan Smith]

On Apr 26, 2022, at 8:22 AM, Kevin Bourrillion <kevinb at google.com<mailto:kevinb at google.com>> wrote:

It's a great start, but the key difference is that we need to be able to apply this process to *our own* types, not just the JDK types. Really, we should see whatever we need to do for JDK types as a clue to what other library owners will need as well.

Yes, a public annotation was the original proposal. At some point we scaled that back to just JDK-internal. The discussions were a long time ago, but if I remember right the main concern was that a formalized, Java SE notion of "value-based class" would lead to some unwanted complexity when we eventually get to *real* value classes (e.g., a misguided CS 101 course question: "what's the difference between a value-based class and a value class? which one should you use?"). It seemed like producing some special warnings for JDK classes would address the bulk of the problem without needing to fall into this trap.

Would an acceptable compromise be for a third-party tool to support its own annotations, while also recognizing @jdk.internal.ValueBased as an alternative spelling of the same thing?

(Secondarily... why are we warning only on synchronization, and not on `==` or (marginal) `identityHC`?)

I think this was simply not a battle that we wanted to fight—discouraging all uses of '==' on type Integer, for example.

We spent some time trying to figure out what to say about '==', and came up with this:

"the class does not provide any instance creation mechanism that promises a unique identity on each method call—in particular, any factory method's contract must allow for the possibility that if two independently-produced instances are equal according to equals(), they may also be equal according to ==;"

and

"When two instances of a value-based class are equal (according to `equals`), a program should not attempt to distinguish between their identities, whether directly via reference equality or indirectly via an appeal to synchronization, identity hashing, serialization, or any other identity-sensitive mechanism."

(See https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/doc-files/ValueBased.html)

Within these constraints, there are reasonable things that can be done with '==', like optimizing for a situation where 'equals' is likely to be true. (I'm sympathetic to "don't do that anyway!", but it's more of a convention thing that javac would tend not to get involved with.)