RFR: 8266571: Sequenced Collections

[Stuart Marks]

On Wed, 21 Sep 2022 04:01:13 GMT, Chen Liang <liach at openjdk.org> wrote:

>> PR for Sequenced Collections implementation.
>
> Since we added reversal to deque, can we add notes to a few Collections APIs like `Collections::asLifoQueue` about this newer alternative? Also on using `reverse` on the list view than actually reversing a whole list.
> 
> In addition, the new methods should have `@since 20` tags, such as on `LinkedList::reversed`, `SortedSet::addFirst`. Other similar methods are version-tagged, like `Collection::spliterator` or `Method::getParameterCount`.

@liach 

> Since we added reversal to deque, can we add notes to a few Collections APIs like `Collections::asLifoQueue` about this newer alternative? Also on using `reverse` on the list view than actually reversing a whole list.
> 
> In addition, the new methods should have `@since 20` tags, such as on `LinkedList::reversed`, `SortedSet::addFirst`. Other similar methods are version-tagged, like `Collection::spliterator` or `Method::getParameterCount`.

Good points. I've added a API notes to asLifeQueue and reverse, and I've added a bunch of @since tags. Let me know if you find other places that need them.

> Is there a particular reason we define poll (null on empty) in SequencedMap but remove (NSEE on empty) in SequencedCollection?
> 
> I understand that SequencedCollection doesn't want to be null-ambiguous, and map entries are non-null so poll there is not ambiguous. But I still think using remove for both look more consistent.

@liach 

> Is there a particular reason we define poll (null on empty) in SequencedMap but remove (NSEE on empty) in SequencedCollection?
> 
> I understand that SequencedCollection doesn't want to be null-ambiguous, and map entries are non-null so poll there is not ambiguous. But I still think using remove for both look more consistent.

Yes, this is definitely an asymmetry. I did it this way to avoid proliferation of new methods, so I just promoted existing ones from NavigableMap into SequencedMap. But I might take another swing at this and see if there's a way to get throwing versions into SequencedMap. The problem is that `firstKey` throws if empty but `firstEntry` returns null if empty. So to make things consistently throwing, we'd need to add `getFirst/LastEntry` and `removeFirst/LastEntry` to SequencedMap (and probably get rid of some of the other methods). This would make SequencedMap and probably LinkedHashMap fairly nice, but it would clutter up NavigableMap.

> Just curious, will sequenced collections be delivered directly or will it incubate/preview first?

No plans to preview. (If it were for preview, the JEP would state that prominently.)

> src/java.base/share/classes/java/util/Collections.java line 1248:
> 
>> 1246:      * @param  s the set for which an unmodifiable view is to be returned.
>> 1247:      * @return an unmodifiable view of the specified sequenced set.
>> 1248:      */
> 
> Suggestion:
> 
>      * @since 20
>      */
> 
> The last one was misplaced.

Oops, good catch. Will fix.

> src/java.base/share/classes/java/util/Collections.java line 5980:
> 
>> 5978:      * an eviction policy, which is not possible with a {@code LinkedHashSet}.
>> 5979:      *
>> 5980:      * <pre>{@code
> 
> Can we upgrade this to a snippet?

At some point yes.

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

PR Comment: https://git.openjdk.org/jdk/pull/7387#issuecomment-1301524326
PR Comment: https://git.openjdk.org/jdk/pull/7387#issuecomment-1304414879
PR Comment: https://git.openjdk.org/jdk/pull/7387#issuecomment-1476757813
PR Review Comment: https://git.openjdk.org/jdk/pull/7387#discussion_r1014575871
PR Review Comment: https://git.openjdk.org/jdk/pull/7387#discussion_r1140749658