Java 21 introduced Sequenced Collections as a preview feature (JEP 431) that provides a consistent API for collections with defined encounter orders. These new interfaces—SequencedSet, SequencedMap, and SequencedCollection—offer standardized methods for accessing first and last elements and reversing views.

Overview of Sequenced Collections

The Problem Before Java 21

Before Java 21, different collection types had inconsistent APIs for accessing endpoints:

• List had getFirst(), getLast()
• Deque had getFirst(), getLast(), getFirst(), getLast()
• SortedSet had first(), last()
• LinkedHashSet had no direct endpoint access

The Solution: Sequenced Collections

Java 21 introduces a unified hierarchy:

Collection └── SequencedCollection ├── List ├── Deque └── SequencedSet ├── LinkedHashSet └── SortedSet/NavigableSet Map └── SequencedMap ├── LinkedHashMap └── SortedMap/NavigableMap

SequencedSet Interface

Definition and Methods

interface SequencedSet<E> extends SequencedCollection<E>, Set<E> { // Inherits from SequencedCollection: // E getFirst(); // E getLast(); // void addFirst(E); // void addLast(E); // E removeFirst(); // E removeLast(); // SequencedSet-specific: SequencedSet<E> reversed(); }

Example 1: Basic SequencedSet Operations

import java.util.*; public class SequencedSetDemo { public static void main(String[] args) { // Create a SequencedSet (LinkedHashSet implements SequencedSet) SequencedSet<String> fruitSet = new LinkedHashSet<>(); // Add elements - maintains insertion order fruitSet.add("Apple"); fruitSet.add("Banana"); fruitSet.add("Cherry"); fruitSet.add("Date"); System.out.println("Original set: " + fruitSet); // Access first and last elements System.out.println("First element: " + fruitSet.getFirst()); System.out.println("Last element: " + fruitSet.getLast()); // Add elements at ends fruitSet.addFirst("Apricot"); // Adds to beginning fruitSet.addLast("Elderberry"); // Adds to end System.out.println("After adding first/last: " + fruitSet); // Remove elements from ends String removedFirst = fruitSet.removeFirst(); String removedLast = fruitSet.removeLast(); System.out.println("Removed first: " + removedFirst); System.out.println("Removed last: " + removedLast); System.out.println("After removals: " + fruitSet); // Get reversed view SequencedSet<String> reversedSet = fruitSet.reversed(); System.out.println("Reversed view: " + reversedSet); // Modifications through reversed view affect original reversedSet.addFirst("Zucchini"); System.out.println("After adding to reversed: " + fruitSet); } }

Output:

Original set: [Apple, Banana, Cherry, Date] First element: Apple Last element: Date After adding first/last: [Apricot, Apple, Banana, Cherry, Date, Elderberry] Removed first: Apricot Removed last: Elderberry After removals: [Apple, Banana, Cherry, Date] Reversed view: [Date, Cherry, Banana, Apple] After adding to reversed: [Zucchini, Apple, Banana, Cherry, Date]

Example 2: SequencedSet with SortedSet

import java.util.*; public class SortedSetSequencedDemo { public static void main(String[] args) { // TreeSet also implements SequencedSet SequencedSet<Integer> numbers = new TreeSet<>(); numbers.add(30); numbers.add(10); numbers.add(20); numbers.add(40); System.out.println("Sorted set: " + numbers); System.out.println("First: " + numbers.getFirst()); // 10 System.out.println("Last: " + numbers.getLast()); // 40 // reversed() returns a view in descending order SequencedSet<Integer> descending = numbers.reversed(); System.out.println("Descending view: " + descending); // Attempting mutating operations on sorted sets try { numbers.addFirst(5); // Would break sorting - throws UnsupportedOperationException } catch (UnsupportedOperationException e) { System.out.println("addFirst not supported by TreeSet"); } try { numbers.addLast(50); // Would break sorting - throws UnsupportedOperationException } catch (UnsupportedOperationException e) { System.out.println("addLast not supported by TreeSet"); } } }

Output:

Sorted set: [10, 20, 30, 40] First: 10 Last: 40 Descending view: [40, 30, 20, 10] addFirst not supported by TreeSet addLast not supported by TreeSet

SequencedMap Interface

Definition and Methods

interface SequencedMap<K, V> extends Map<K, V> { // Entry accessors Entry<K, V> firstEntry(); Entry<K, V> lastEntry(); // Key accessors K firstKey(); K lastKey(); // Element addition Entry<K, V> pollFirstEntry(); Entry<K, V> pollLastEntry(); // Element removal Entry<K, V> putFirst(K key, V value); Entry<K, V> putLast(K key, V value); // Reversed view SequencedMap<K, V> reversed(); // Sequenced views SequencedSet<K> sequencedKeySet(); SequencedCollection<V> sequencedValues(); SequencedSet<Entry<K, V>> sequencedEntrySet(); }

Example 3: Basic SequencedMap Operations

import java.util.*; public class SequencedMapDemo { public static void main(String[] args) { // LinkedHashMap implements SequencedMap SequencedMap<String, Integer> studentScores = new LinkedHashMap<>(); // Add elements in order studentScores.put("Alice", 85); studentScores.put("Bob", 92); studentScores.put("Charlie", 78); studentScores.put("Diana", 95); System.out.println("Original map: " + studentScores); // Access first and last entries System.out.println("First entry: " + studentScores.firstEntry()); System.out.println("Last entry: " + studentScores.lastEntry()); System.out.println("First key: " + studentScores.firstKey()); System.out.println("Last key: " + studentScores.lastKey()); // Add elements at ends studentScores.putFirst("Aaron", 88); // Adds to beginning studentScores.putLast("Zoe", 91); // Adds to end System.out.println("After putFirst/putLast: " + studentScores); // Poll (remove and return) entries from ends Map.Entry<String, Integer> polledFirst = studentScores.pollFirstEntry(); Map.Entry<String, Integer> polledLast = studentScores.pollLastEntry(); System.out.println("Polled first: " + polledFirst); System.out.println("Polled last: " + polledLast); System.out.println("After polling: " + studentScores); // Get reversed view SequencedMap<String, Integer> reversedMap = studentScores.reversed(); System.out.println("Reversed map: " + reversedMap); // Sequenced views System.out.println("Sequenced keys: " + studentScores.sequencedKeySet()); System.out.println("Sequenced values: " + studentScores.sequencedValues()); System.out.println("Sequenced entries: " + studentScores.sequencedEntrySet()); } }

Output:

Original map: {Alice=85, Bob=92, Charlie=78, Diana=95} First entry: Alice=85 Last entry: Diana=95 First key: Alice Last key: Diana After putFirst/putLast: {Aaron=88, Alice=85, Bob=92, Charlie=78, Diana=95, Zoe=91} Polled first: Aaron=88 Polled last: Zoe=91 After polling: {Alice=85, Bob=92, Charlie=78, Diana=95} Reversed map: {Diana=95, Charlie=78, Bob=92, Alice=85} Sequenced keys: [Alice, Bob, Charlie, Diana] Sequenced values: [85, 92, 78, 95] Sequenced entries: [Alice=85, Bob=92, Charlie=78, Diana=95]

Example 4: SequencedMap with SortedMap

import java.util.*; public class SortedMapSequencedDemo { public static void main(String[] args) { // TreeMap implements SequencedMap SequencedMap<Integer, String> products = new TreeMap<>(); products.put(103, "Keyboard"); products.put(101, "Mouse"); products.put(104, "Monitor"); products.put(102, "Headphones"); System.out.println("Sorted map: " + products); System.out.println("First entry: " + products.firstEntry()); System.out.println("Last entry: " + products.lastEntry()); // Reversed view (descending order) SequencedMap<Integer, String> descendingProducts = products.reversed(); System.out.println("Descending order: " + descendingProducts); // Poll operations work with sorted maps Map.Entry<Integer, String> firstProduct = products.pollFirstEntry(); Map.Entry<Integer, String> lastProduct = products.pollLastEntry(); System.out.println("Removed first: " + firstProduct); System.out.println("Removed last: " + lastProduct); System.out.println("After polling: " + products); // putFirst/putLast are not supported by TreeMap try { products.putFirst(100, "Webcam"); } catch (UnsupportedOperationException e) { System.out.println("putFirst not supported by TreeMap"); } } }

Output:

Sorted map: {101=Mouse, 102=Headphones, 103=Keyboard, 104=Monitor} First entry: 101=Mouse Last entry: 104=Monitor Descending order: {104=Monitor, 103=Keyboard, 102=Headphones, 101=Mouse} Removed first: 101=Mouse Removed last: 104=Monitor After polling: {102=Headphones, 103=Keyboard} putFirst not supported by TreeMap

Practical Use Cases

Example 5: LRU (Least Recently Used) Cache

import java.util.*; public class LRUCache<K, V> { private final SequencedMap<K, V> cache; private final int maxSize; public LRUCache(int maxSize) { this.maxSize = maxSize; this.cache = new LinkedHashMap<>(maxSize, 0.75f, true) { @Override protected boolean removeEldestEntry(Map.Entry<K, V> eldest) { return size() > maxSize; } }; } public V get(K key) { return cache.get(key); } public void put(K key, V value) { cache.put(key, value); } public V getRecent() { return cache.isEmpty() ? null : cache.getLast(); } public V getOldest() { return cache.isEmpty() ? null : cache.getFirst(); } public void displayCache() { System.out.println("Cache (oldest to newest): " + cache); System.out.println("Oldest: " + getOldest()); System.out.println("Newest: " + getRecent()); } public static void main(String[] args) { LRUCache<String, String> cache = new LRUCache<>(3); cache.put("A", "Data A"); cache.put("B", "Data B"); cache.put("C", "Data C"); cache.displayCache(); // Access pattern affects order cache.get("A"); // Moves A to most recent cache.displayCache(); // Adding new element evicts oldest cache.put("D", "Data D"); cache.displayCache(); } }

Output:

Cache (oldest to newest): {A=Data A, B=Data B, C=Data C} Oldest: Data A Newest: Data C Cache (oldest to newest): {B=Data B, C=Data C, A=Data A} Oldest: Data B Newest: Data A Cache (oldest to newest): {C=Data C, A=Data A, D=Data D} Oldest: Data C Newest: Data D

Example 6: Navigation History

import java.util.*; public class NavigationHistory { private final SequencedDeque<String> history = new LinkedHashSet<>(); private final int maxHistorySize; public NavigationHistory(int maxHistorySize) { this.maxHistorySize = maxHistorySize; } public void visitPage(String url) { history.remove(url); // Remove if already exists (avoid duplicates) history.addLast(url); // Add as most recent // Trim history if exceeds max size while (history.size() > maxHistorySize) { history.removeFirst(); } } public String goBack() { if (history.size() < 2) { return null; } // Remove current history.removeLast(); // Return previous return history.getLast(); } public List<String> getHistory() { return new ArrayList<>(history); } public List<String> getRecentFirst() { List<String> recentFirst = new ArrayList<>(history.reversed()); return recentFirst; } public static void main(String[] args) { NavigationHistory nav = new NavigationHistory(5); nav.visitPage("home"); nav.visitPage("products"); nav.visitPage("product-details"); nav.visitPage("cart"); nav.visitPage("checkout"); System.out.println("History (oldest first): " + nav.getHistory()); System.out.println("History (recent first): " + nav.getRecentFirst()); // Go back String previous = nav.goBack(); System.out.println("Went back to: " + previous); System.out.println("Current history: " + nav.getHistory()); // Visit new page nav.visitPage("confirmation"); System.out.println("After new visit: " + nav.getHistory()); } }

Migration Guide

Before Java 21 vs After Java 21

Before Java 21:

// Inconsistent APIs List<String> list = new ArrayList<>(); String first = list.get(0); // or list.isEmpty() ? null : list.get(0) Deque<String> deque = new ArrayDeque<>(); String first = deque.getFirst(); SortedSet<String> sortedSet = new TreeSet<>(); String first = sortedSet.first(); LinkedHashSet<String> linkedSet = new LinkedHashSet<>(); // No direct way to get first/last!

After Java 21:

// Unified API SequencedCollection<String> collection = ...; String first = collection.getFirst(); String last = collection.getLast(); SequencedSet<String> set = ...; String first = set.getFirst(); SequencedMap<String, Integer> map = ...; Map.Entry<String, Integer> firstEntry = map.firstEntry();

Key Benefits

1. Consistent API: Unified methods across different collection types
2. Improved Readability: Clear intent when accessing collection endpoints
3. Reversible Views: Built-in support for reversed iteration
4. Reduced Boilerplate: No need for workarounds to access first/last elements
5. Enhanced Functionality: Additional operations like addFirst, addLast

Implementation Support

SequencedSet implementations:

• LinkedHashSet
• TreeSet (read-only for mutation operations)
• ConcurrentSkipListSet (read-only for mutation operations)

SequencedMap implementations:

• LinkedHashMap
• TreeMap (read-only for putFirst/putLast)
• ConcurrentSkipListMap (read-only for putFirst/putLast)

Conclusion

Sequenced Collections in Java 21 provide:

• Standardized endpoint access across collection types
• Reversible views for bidirectional traversal
• Consistent mutation operations where supported
• Backward compatibility with existing collections

When to use SequencedSet/SequencedMap:

• When you need consistent access to collection endpoints
• For ordered collections where position matters
• When building navigation systems, caches, or history tracking
• For cleaner, more maintainable collection code

These new interfaces make Java collections more expressive and eliminate many common pain points when working with ordered collections.

Note: Sequenced Collections are a preview feature in Java 21. Make sure to enable preview features (--enable-preview) when compiling and running code that uses these interfaces.