Sequenced Collections

Sequenced Collections provide new interfaces for the collections framework which unify and extend the functionality of existing collections with a defined encounter order of elements. The new interface SequencedCollection includes methods to access (get, add, and remove) elements at both ends of a sequenced collection. The interface SequencedMap defines similar operations for maps with a defined encounter order of entries.

Affected Collection Types

Various existing collection types now implement the new interfaces in JDK 21. They can be grouped into different categories based on properties of the underlying encounter order.

Some collections are ordered based on an element-based ordering defined by a Comparator or the natural ordering provided by Comparable implementations. In other collections, the encounter order is based on the so-called insertion order that is determined by the order in which methods to add and remove elements have been called.

Some collections can contain equal elements multiple times. Other collections cannot contain such duplicates. Maps are similar to the latter kind of collections because they cannot contain multiple entries with the same key.

The following table groups implementations or extensions of the new interfaces based on the mentioned properties. We do not show implementations or extensions of interfaces listed in this table.

	insertion order	element-based order
with duplicates	List, Deque
without duplicates	LinkedHashSet	SortedSet
maps	LinkedHashMap	SortedMap

We can see that there are no sequenced collections supporting duplicates with an element-based encounter order. For collections without duplicates, however, there are implementations with both insertion order and element-based ordering.

The following methods in the SequencedCollection interface have been promoted from the existing Deque interface and provide access to both ends:

• getFirst and getLast query elements
• addFirst and addLast insert elements
• removeFirst and removeLast delete elements

Corresponding methods for maps are called differently:

• firstEntry and lastEntry query entries
• putFirst and putLast insert entries
• pollFirstEntry and pollLastEntry delete entries

The methods to insert elements (or entries in maps) are interesting for collections without duplicates or with an element-based encounter order. The following table summarizes their behavior.

	insertion order	element-based order
with duplicates	addFirst/addLast always insert new element
without duplicates	addFirst/addLast reposition existing element	addFirst/addLast not supported
maps	putFirst/putLast reposition existing entry	putFirst/putLast not supported

The decision to unify collections with different underlying characteristics under a single interface likely involved weighing simplicity against specificity. Unsupported operations from the table above are implemented using UnsupportedOperationException.

Sequenced collections also define a reversed method that returns a view of the collection they are called on with reversed encounter order.