New Sequenced Collection Types in Java’s Collections Framework

Published on march 21, 2023

It has been decided to promote JEP 431: Sequenced Collections from Candidate to Proposed to Target status for JDK 21. In order to represent a well-defined collection whose elements are arranged in a well-defined sequence or ordering as a structural property of the collection, a new family of interfaces is proposed. As a result, the Collections Framework requires a uniform set of operations and a well-defined ordering.

There has long been a need within Java’s collections framework for a type of collection that represents a sequence of elements with a defined encounter order and a uniform set of operations that apply to such collections. The current type hierarchy does not support encounter order, making it difficult to express certain practical concepts in APIs. The proposal proposes the introduction of new interfaces to represent collections with a defined encounter order and provide uniform APIs for accessing and processing their first and last elements in reverse order.

There has been a repeated complaint and problem about the lack of collection types that represent sequences of elements with defined encounter orders. Despite the fact that List and Deque specify an encounter order, their common supertype is Collection, which does not. Similarly, Set does not specify an encounter order, and subtypes such as HashSet do not, but subtypes such as SortedSet and LinkedHashSet do.

This problem has been addressed by the definition of new interfaces for sequenced collections, sequenced sets, and sequenced maps that are retrofitted into the existing collection’s type hierarchy. All of the new methods declared in these interfaces have default implementations. It is important to note that sequenced collections, sets, and maps all have different characteristics, i.e. sequenced collections are defined as collections with elements that have a predefined encounter order, sequenced sets are defined as sequenced collections without duplicate elements, and sequenced maps are defined as maps with defined encounter orders.

As a result of the reversed() method, all sequenced types have the ability to process elements in both directions using all the usual iteration mechanisms, including enhanced for loops, explicit iterator() loops, forEach(), stream(), parallelStream(), and toArray(). Reversed() provides a reversed-ordered view of the original collection.

In addition to reversed(), SequencedSet provides the same methods as SequencedCollection.

LinkedHashSet implements SequencedSet, SortedSet implements SequencedSet as its immediate superinterface, and Deque implements SequencedCollection as its immediate superinterface. Each of these new interfaces fits neatly into the existing hierarchy of collections types. LinkedHashMap implements SequencedMap, SortedMap implements SequencedMap, and SortedMap implements SequencedMap.

Explicit-positioning APIs like SortedSet::addFirst and SortedMap::putLast throw UnsupportedOperationExceptions as their elements are arranged relative to each other. However, the asymmetry of not implementing all SequencedCollection operations is of value as it allows SortedSet and SortedMap to be incorporated into the sequenced collection family, allowing them to be used more widely.

As a result, Java’s Collections Framework has made a significant step forward by introducing new interfaces to represent collections that have a defined encounter order and a uniform set of operations that apply to such collections. Developers will become more intuitive and efficient by providing consistent and easy-to-use support for encounter order.