RFR: 8247402: Documentation for Map::compute contains confusing implementation requirements

[Pavel Rappo]

On Wed, 25 Nov 2020 20:22:21 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> @pavelrappo 
>> 
>>> What is the required level of fidelity particular (pseudo-) code has to have?
>> 
>> It's potentially a large discussion, one that could be had in the context of my JEP draft http://openjdk.java.net/jeps/8068562 . However, speaking practically, it's possible to focus the discussion fairly concisely: the main responsibility of the `@implSpec` ("Implementation Requirements") section is to give implementors of subclasses enough information to decide whether to inherit the implementation or to override it, and if they override it, what behavior they can expect if they were to call `super.compute`.
>> 
>> In this case, a null-value-tolerating Map implementation needs to know that the default implementation calls `remove` in the particular case that you mentioned. A concurrent Map implementation will also need to know that the default implementation calls `get(key)` and `containsKey(key)` at different times, potentially leading to a race condition. Both of these inform the override vs. inherit decision.
>
> @stuart-marks 
> 
>> Both of these inform the override vs. inherit decision.
> 
> So in this case - fixing the specification to match the default implementation seems to be the right call - as existing implementations that do not override are more probably depending on the current default behavior.

@dfuch, @stuart-marks, and @Martin-Buchholz: thanks for reviewing the CSR.
@johnlinp: I have finalized the CSR; now we are waiting for it to be approved.

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

PR: https://git.openjdk.java.net/jdk/pull/714