Md Sanwar Hossain

Software Engineer · Java · Spring Boot · Microservices

Java Sequenced Collections API: Ordered Traversal, Reversed Views & the End of LinkedHashMap Hacks

Java 21 finally plugged a 28-year gap in the Collections Framework: a unified, type-safe way to access the first and last elements of any ordered collection, iterate in reverse, and add elements at either end — without casting, converting, or writing bespoke utility methods. The Sequenced Collections API (JEP 431) is one of those small-but-consequential changes that immediately cleans up code you have been writing ugly workarounds for since Java 1.2.

1. Introduction — The Order Management Hack Catalogue

The order management service at a mid-sized e-commerce company accumulates a specific kind of technical debt. The business rule is simple: display the most recently placed order at the top of the customer's order history, and use the oldest order to calculate loyalty tier. Trivial, right? Here is what the codebase actually looked like before Java 21.

To get the most recently placed order from a LinkedHashMap<String, Order> (keyed by order ID, insertion-ordered by placement time), developers converted the entry set to an array, indexed to the last position, and wrapped it in an Optional. To get the oldest order, they created a stream, called findFirst(), and hoped that insertion order was stable. To iterate in reverse for the activity feed, they copied all values into an ArrayList, called Collections.reverse(), iterated, and then discarded the copy. For displaying the last five orders, they used stream().skip(map.size() - 5).collect(toList()) — allocating a full stream just to skip to near the end.

None of these workarounds are wrong, exactly. They all produce correct results. But they are verbose, allocation-heavy, and — most dangerously — fragile. When a new developer replaces the LinkedHashMap with a TreeMap for natural key ordering, every one of those workarounds silently changes semantics. The code looked like it was accessing "first" and "last" entries, but it was actually relying on implementation-specific iteration order that was never expressed in the type system. The Sequenced Collections API exists precisely to make order a first-class, type-checkable contract.

2. Real-World Problem — The Pre-Java-21 Collection API Gap

The fundamental problem is that Java's collection hierarchy never had a common supertype for collections that define a meaningful encounter order. List has get(0) and get(size()-1). Deque has peekFirst() and peekLast(). SortedSet has first() and last(). LinkedHashSet has none of these — you reach the first element by calling iterator().next() and the last element by iterating to the end. These types all guarantee a defined traversal order but expose zero shared API for exploiting it.

The concrete mess appears at API boundaries. A service method that needs to "process the most recent entry" must either accept a concrete type (LinkedHashMap) — leaking implementation details — or accept Map and document "must be insertion-ordered" in Javadoc that no compiler will enforce. Neither is satisfactory. The result, observed in virtually every large Java codebase, is a scattering of utility methods with names like getLastEntry(Map), firstElement(Collection), and reverseIterate(Set) that all do the same logical thing with slightly different semantics and no unified contract.

3. Deep Dive — SequencedCollection, SequencedSet & SequencedMap

JEP 431 introduces three new interfaces into java.util. Each is a minimal, targeted addition that slots precisely into the existing collection hierarchy.

SequencedCollection<E> extends Collection<E> and adds six methods: addFirst(E), addLast(E), getFirst(), getLast(), removeFirst(), removeLast(), and one more: reversed(), which returns a SequencedCollection<E> that is a live, backed reverse view of the original. List and Deque now extend SequencedCollection. Default implementations are provided for all methods except reversed(), which each implementing class overrides to return the most efficient reverse view for its structure.

SequencedSet<E> extends both SequencedCollection<E> and Set<E>, overriding reversed() to return a SequencedSet<E>. LinkedHashSet, SortedSet, and NavigableSet now implement SequencedSet. This is the change that finally gives LinkedHashSet first-class ordered access — after twenty-five years of being the only ordered set with no way to access its first or last element without iterating.

SequencedMap<K, V> extends Map<K, V> and adds firstEntry(), lastEntry(), pollFirstEntry(), pollLastEntry(), putFirst(K, V), putLast(K, V), and reversed(). It also exposes sequencedKeySet(), sequencedValues(), and sequencedEntrySet(), which return SequencedSet and SequencedCollection views respectively. LinkedHashMap, SortedMap, and NavigableMap now implement SequencedMap.

The hierarchy is carefully designed to be non-breaking. All new methods on SequencedCollection have default implementations that delegate to existing iterator-based operations, so existing implementations of List or Set do not need to change. Only reversed() is abstract in SequencedCollection, and the JDK provides implementations for all its standard classes. Third-party collections need only implement reversed() to become fully sequenced.

4. Solution Approach — Polymorphic Code & Reversed Views

The primary benefit of the Sequenced Collections API is the ability to write polymorphic code that expresses order intent in the type system. Instead of accepting a LinkedHashMap to guarantee insertion order, a method can now accept SequencedMap<K, V> and communicate its ordering requirement clearly, while remaining compatible with LinkedHashMap, TreeMap, and any future ordered map implementation.

The reversed() method deserves special attention. It returns a live, backed view — not a copy. Mutations to the original collection are immediately visible through the reversed view, and mutations through the reversed view (adding to its "first" position, which is the original's "last") are reflected in the original. This is semantically identical to how List.subList() works: a view, not a snapshot. The implication is that iterating a reversed view is always O(1) overhead over iterating the original — there is no O(n) copy involved.

For bidirectional algorithms — such as palindrome detection, LRU eviction scanning from both ends, or sliding-window anomaly detection that processes newest-first — reversed() eliminates the need for dual-index bookkeeping or the ListIterator idiom. You can pass the reversed view directly to any method that accepts SequencedCollection, and the recipient does not need to know or care that it is working in reverse order.

5. Architecture & Code Examples — Before/After Patterns

(a) Accessing the first element from a LinkedHashSet — before and after:

// BEFORE Java 21 — verbose and fragile
LinkedHashSet<String> recentTags = buildTagSet();

// Get first: iterator dance
String firstTag = recentTags.iterator().next(); // throws NoSuchElementException if empty

// Get last: iterate the entire set
String lastTag = null;
for (String tag : recentTags) { lastTag = tag; }
// lastTag is null if empty — silent bug waiting to happen

// AFTER Java 21 — SequencedSet API
SequencedSet<String> recentTags = buildTagSet(); // LinkedHashSet implements SequencedSet

String firstTag = recentTags.getFirst(); // throws NoSuchElementException if empty (documented)
String lastTag  = recentTags.getLast();  // O(1) for LinkedHashSet, throws if empty

// Iterate in reverse — no copy, live view
for (String tag : recentTags.reversed()) {
    processNewestFirst(tag);
}

(b) Reverse iteration over a LinkedHashMap — eliminating the copy:

// BEFORE Java 21 — allocate an ArrayList just to reverse
LinkedHashMap<String, Order> ordersByPlacementTime = loadOrders();
List<Map.Entry<String, Order>> entries = new ArrayList<>(ordersByPlacementTime.entrySet());
Collections.reverse(entries); // O(n) mutation of the copy
for (Map.Entry<String, Order> entry : entries) {
    renderOrderCard(entry.getValue());
}

// AFTER Java 21 — live reversed view, zero allocation
SequencedMap<String, Order> ordersByPlacementTime = loadOrders();
for (Map.Entry<String, Order> entry : ordersByPlacementTime.reversed().sequencedEntrySet()) {
    renderOrderCard(entry.getValue()); // newest-first, no intermediate collection
}

(c) Cache eviction helper taking SequencedMap to remove the LRU entry:

// Polymorphic eviction — works with any SequencedMap (LinkedHashMap in insertion order,
// access-ordered LinkedHashMap as LRU cache, TreeMap, etc.)
public <K, V> Map.Entry<K, V> evictOldestEntry(SequencedMap<K, V> cache) {
    Map.Entry<K, V> oldestEntry = cache.firstEntry(); // first = oldest in encounter order
    if (oldestEntry != null) {
        cache.pollFirstEntry(); // atomically retrieves and removes
        log.info("Evicted oldest entry: key={}", oldestEntry.getKey());
    }
    return oldestEntry;
}

// Usage with an access-ordered LinkedHashMap (access-order = true) the first entry is LRU
SequencedMap<String, CachedResult> resultCache = new LinkedHashMap<>(100, 0.75f, true);
if (resultCache.size() > MAX_CACHE_SIZE) {
    evictOldestEntry(resultCache); // evicts LRU when map is access-ordered
}

(d) Implementing a recency-first list with addFirst:

// Recency-first activity feed using SequencedCollection
public class ActivityFeed {
    private final SequencedCollection<ActivityEvent> events = new LinkedList<>();
    private static final int MAX_EVENTS = 50;

    public void record(ActivityEvent event) {
        events.addFirst(event);   // newest event at the logical "start"
        if (events.size() > MAX_EVENTS) {
            events.removeLast();  // drop the oldest entry to enforce the size cap
        }
    }

    public ActivityEvent latestEvent() {
        return events.getFirst(); // O(1), no index arithmetic
    }

    public List<ActivityEvent> snapshot() {
        // Returns events newest-first; reversed() gives oldest-first for archival
        return List.copyOf(events);
    }
}

6. Failure Scenarios & Trade-offs

Mutating through a reversed view. Because reversed() returns a live backed view, mutations through the reversed view take effect on the original collection with positional semantics inverted. Calling addFirst() on a reversed view adds to the last position of the original. This is logically correct but counterintuitive, and mixing direct mutations with reversed-view mutations in the same code block is a reliable source of bugs. The safest rule: treat reversed views as read-only unless you have explicitly modelled the positional inversion in your mental model.

UnsupportedOperationException on immutable sequenced collections. The factory methods List.of(), List.copyOf(), and Collections.unmodifiableList() return collections that implement SequencedCollection, but all mutating operations — addFirst, addLast, removeFirst, removeLast — throw UnsupportedOperationException. The read operations (getFirst, getLast, reversed) work fine. This is consistent with the existing contract for unmodifiable views, but developers expecting the new API to "just work" on any SequencedCollection will encounter this at runtime with no compile-time signal.

Performance characteristics vary by implementation. getFirst() and getLast() are O(1) for LinkedList, ArrayDeque, and LinkedHashMap. For ArrayList, getFirst() is O(1) but addFirst() is O(n) due to the array shift — identical to the pre-existing behaviour of add(0, element). The Sequenced Collections API does not change these complexity characteristics; it merely standardizes the API. Always check the Javadoc for the specific implementation you are using.

7. When NOT to Use Sequenced Collections

Unordered data. If your data has no meaningful encounter order — you are using HashMap for fast O(1) lookup without caring about iteration order — then SequencedMap is not applicable. Do not switch a HashMap to LinkedHashMap just to use the new API. LinkedHashMap maintains insertion order by maintaining an additional doubly-linked list over all entries, which increases per-entry memory overhead by two object references. If you never need ordered traversal, that is wasted memory.

When access patterns never need first/last semantics. Code that only iterates a collection in a single direction, processes all elements without positional awareness, or uses the collection purely as an existence check (contains-only patterns) gains nothing from the sequenced interface. In these cases, using the broader Collection or Iterable as the parameter type is still the more flexible, less constraining choice.

When you need range queries. If your use case is "give me all entries between key A and key B" or "give me the five smallest keys," that is the domain of NavigableMap (with subMap, headMap, tailMap) and NavigableSet. Both now implement SequencedMap and SequencedSet respectively, so you can use them together — but SequencedMap alone is not a substitute for range-query APIs. Reach for TreeMap with NavigableMap for range queries, not just SequencedMap.

8. Optimization Techniques

Avoid unnecessary toList() conversions. The most common pre-Java-21 pattern for "process in reverse" was new ArrayList<>(collection); Collections.reverse(list); list.forEach(...);. With sequenced collections, this entire sequence collapses to collection.reversed().forEach(...) — a live view iteration that allocates no intermediate collection. Searching your codebase for Collections.reverse after upgrading to Java 21 is a quick way to find candidates for cleanup.

Use SequencedCollection as method parameter type for maximum API flexibility. When writing library or service methods that operate on any ordered sequence, accepting SequencedCollection<T> instead of List<T> or Deque<T> makes your API callable with LinkedHashSet, ArrayDeque, LinkedList, and future ordered collection types. This is the collections-hierarchy equivalent of accepting Iterable instead of Collection — prefer the most abstract type that provides the semantics you actually need.

Combine with Java records for immutable value snapshots of first/last. When you need a stable snapshot of the head and tail of a sequenced collection — for logging, auditing, or passing to an asynchronous task — Java records are a natural fit. A single-line record declaration captures both endpoints with value semantics, making them safe to pass across thread boundaries without defensive copying of the full collection:

record CollectionBounds<T>(T first, T last) {
    static <T> CollectionBounds<T> of(SequencedCollection<T> col) {
        return new CollectionBounds<>(col.getFirst(), col.getLast());
    }
}

// Capture a thread-safe snapshot of head/tail before handing off to async processing
SequencedCollection<Order> recentOrders = fetchOrders(customerId);
CollectionBounds<Order> bounds = CollectionBounds.of(recentOrders);
executor.submit(() -> auditService.recordBounds(bounds)); // safe: record is immutable

9. Key Takeaways

• Java 21's Sequenced Collections API (JEP 431) adds three interfaces — SequencedCollection, SequencedSet, SequencedMap — that unify first/last access and reverse traversal across all ordered collection types.
• reversed() returns a live backed view with zero allocation overhead; it is not a copy, so mutations to the original are immediately visible through the view and vice versa.
• LinkedHashSet finally gets getFirst() and getLast() after 25 years; this alone eliminates a class of iterator-based boilerplate endemic to every large Java codebase.
• Accept SequencedMap<K,V> instead of LinkedHashMap<K,V> in method signatures to express ordering requirements in the type system without leaking implementation details.
• Mutating methods on immutable sequenced collections throw UnsupportedOperationException at runtime — there is no compile-time guard; design defensive code accordingly.
• The upgrade is non-breaking: all new methods have default implementations, so existing custom List/Set implementations do not require changes to compile against Java 21.

10. Conclusion

The Sequenced Collections API is one of those changes that, once you use it, makes you wonder how you ever wrote Java without it. The collection types that needed it — LinkedHashSet, LinkedHashMap, all the Deque and List variants — have always supported meaningful encounter order. The API simply makes that order a first-class, expressible, type-checkable contract rather than an undocumented emergent property of the implementation.

For teams upgrading to Java 21, the migration path is straightforward: scan your codebase for Collections.reverse, iterator-to-last-element patterns, and LinkedHashMap-casted parameters, and refactor them to use the new API. The payoff is cleaner method signatures, fewer intermediate allocations, less boilerplate in utility layers, and — most importantly — code whose ordering requirements are visible to every reader and enforced by the compiler.

Java 21 as an LTS release deserves serious adoption if your team has been lingering on Java 11 or 17. Beyond sequenced collections, the same release delivers virtual threads, pattern matching for switch, and record patterns — all production-ready. Sequenced collections may not be the headline feature, but in day-to-day backend development it may be the one you reach for most often.

Last updated: March 2026 — Written by Md Sanwar Hossain