Sequenced Collections (Java 21) — first, last, reversed — Finally

Sequenced collections (Java 21, JEP 431) add three new interfaces that formalize 'a collection with a well-defined encounter order' and give Java a uniform API for first/last access and reverse iteration.

The three interfaces

`SequencedCollection` — superinterface of List and Deque:

• getFirst(), getLast()
• addFirst(e), addLast(e)
• removeFirst(), removeLast()
• reversed() — returns a view

`SequencedSet` = SequencedCollection + Set

• Adopted by LinkedHashSet and SortedSet

`SequencedMap`

• firstEntry(), lastEntry()
• putFirst(k, v), putLast(k, v)
• pollFirstEntry(), pollLastEntry()
• reversed()
• sequencedKeySet(), sequencedValues(), sequencedEntrySet()

Motivation

Pre-Java 21, there was a mess:

• List.get(0) vs Deque.getFirst() vs LinkedHashSet.iterator().next() vs SortedSet.first()
• No built-in last() for LinkedHashSet or LinkedHashMap
• Reverse iteration was a different API per collection

Sequenced collections unify all this.

Retrofit via default methods

Now implement Sequenced\*

• List (ArrayList, LinkedList) — SequencedCollection
• Deque (ArrayDeque) — SequencedCollection
• LinkedHashSet, SortedSet/TreeSet — SequencedSet
• LinkedHashMap, SortedMap/TreeMap — SequencedMap

Do NOT implement

• HashSet, HashMap, ConcurrentHashMap — no defined order
• PriorityQueue — iteration order doesn't match priority order

Possible because default method implementations in the interfaces mean no class needs modification; subclasses override for efficiency.

`reversed()` is a view, not a copy

• O(1) construction, no allocation
• Lazy iteration in reverse order
• Mutations to original reflect in view and vice versa
• If you want a true reversed copy: new ArrayList<>(list.reversed())
• Compare with Collections.reverse(list) which mutates the original

LRU cache pattern is now idiomatic

• LinkedHashMap + putLast(key, value) + pollFirstEntry() for eviction
• Before Java 21, you had to use the accessOrder constructor argument — clunky

Empty behavior

• getFirst/getLast throw NoSuchElementException on empty
• Different from Deque.peekFirst/peekLast (return null)
• Check isEmpty() first or use try/catch

Immutable collections work too

• List.of(a, b, c).getFirst() returns a
• list.addFirst(...) throws UnsupportedOperationException on immutable
• List.of(a, b, c).reversed() returns an immutable reversed view

Practical improvements

Cleaner code everywhere:

• list.getFirst() beats list.get(0) — intent is clear
• list.getLast() beats list.get(list.size() - 1) — less risk of bug
• lhm.firstEntry() on LinkedHashMap was previously impossible without iteration

Reverse iteration for free:

• LinkedHashSet.reversed() — iterate newest-to-oldest
• LinkedHashMap.reversed() — same for maps
• Previously required copying to a list and reversing

APIs can require ordering:

• Methods can accept SequencedMap instead of Map
• Forces the caller to use an ordered map
• Better than runtime assertions about encounter order

Caveats

1. Not all collections qualify — HashMap, HashSet, ConcurrentHashMap, PriorityQueue don't

2. `reversed()` is a view — mutations propagate

3. Empty collection throws NoSuchElementException — always check size

4. Immutable collections — mutating methods throw UOE

5. sequencedEntrySet() — different from entrySet(); returns a SequencedSet with reverse support

No breaking changes

• Old code works unchanged
• New methods added via default methods
• Adopt incrementally

Recommendation: Start using `getFirst()`, `getLast()`, `addFirst()`, `addLast()` as your default for List, Deque, LinkedHashSet, and LinkedHashMap — the intent is clearer than get(0) or iterator().next(). For LRU caches on LinkedHashMap, the putLast + pollFirstEntry pattern replaces the old accessOrder constructor trick — cleaner and more explicit. Remember `reversed()` is a view, not a copy: O(1) construction, mutations propagate both ways; copy with new ArrayList<>(list.reversed()) if you need independence. Watch the empty collection trap — getFirst/getLast throw NoSuchElementException, unlike Deque.peekFirst which returns null. When designing APIs, accept `SequencedMap` or `SequencedCollection` instead of Map or Collection when you care about encounter order — you get compile-time enforcement. And note which collections don't implement these: HashMap, HashSet, ConcurrentHashMap, PriorityQueue — because they genuinely lack a defined order. This is a small, well-scoped API addition but one of the most universally useful — you'll use it every day.