JEP! 431: Sequenced Collections

JEP 431: Sequenced Collectionsopenjdk.org

Java’s collections framework lacks a collection type that represents a sequence of elements with a defined encounter order. It also lacks a uniform set of operations that apply across such collections.

For example, List and Deque both define an encounter order but their common supertype is Collection, which does not. Similarly, Set does not define an encounter order, and subtypes such as HashSet do not define one, but subtypes such as SortedSet and LinkedHashSet do.

Before JDK 21, ordered collections had inconsistent APIs; now Java finally has one common vocabulary for ‘first’, ‘last’, and ‘reversed’ RUN :

com.wlodar.jeeps.jep431sequencedcollections.Jep431SequencedCollectionsDemo

interface SequencedCollection<E> extends Collection<E> {
    // new method
    SequencedCollection<E> reversed();
    // methods promoted from Deque
    void addFirst(E);
    void addLast(E);
    E getFirst();
    E getLast();
    E removeFirst();
    E removeLast();
}

interface SequencedSet<E> extends Set<E>, SequencedCollection<E> {
    SequencedSet<E> reversed();    // covariant override
}

interface SequencedMap<K,V> extends Map<K,V> {
    // new methods
    SequencedMap<K,V> reversed();
    SequencedSet<K> sequencedKeySet();
    SequencedCollection<V> sequencedValues();
    SequencedSet<Entry<K,V>> sequencedEntrySet();
    V putFirst(K, V);
    V putLast(K, V);
    // methods promoted from NavigableMap
    Entry<K, V> firstEntry();
    Entry<K, V> lastEntry();
    Entry<K, V> pollFirstEntry();
    Entry<K, V> pollLastEntry();
}