RFR: 8266571: Sequenced Collections [v7]

[Stuart Marks]

On Wed, 19 Apr 2023 10:06:38 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Stuart Marks has updated the pull request incrementally with three additional commits since the last revision:
>> 
>>  - Remove unnecessary 'final' from a couple places.
>>  - Clarify ordering of Collection.addAll and Map.putAll; add links to
>>    encounter order.
>>  - Make constructors private for several reverse-ordered views.
>
> src/java.base/share/classes/java/util/SequencedCollection.java line 98:
> 
>> 96:      *
>> 97:      * @implSpec
>> 98:      * The implementation in this class always throws {@code UnsupportedOperationException}.
> 
> class -> interface? This appears in other interfaces as well. We tend to code to interfaces with collections, so this distinction seems relevant.

There's some ambiguity here; "class" can refer to an ordinary concrete or abstract class, a record class, an interface, an enumeration, an annotation type, and probably more things in the future. This is referring to the implementation that actually resides in `java.util.SequencedCollection.class`. If "interface" were used this would tend to imply that it's inherited by implementations of SequencedCollection, which it definitely isn't. I'm leaning toward standardized `@implSpec` wording of "the implementation in this class..."

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

PR Review Comment: https://git.openjdk.org/jdk/pull/7387#discussion_r1171701316