Summary

Add unmodifiable set and map with defined encounter order, which can be created from static factory methods on java.util.SequencedMap and java.util.SequencedSet classes.

Problem

Some sets and maps, where there are no duplicate keys/elements, also have stable encounter orders. java.util.LinkedHashMap provides such a functionality.

However, the Java SE platform lacks utilities to easily create or validate unmodifiable set or maps with defined encounter orders across trust boundaries.

Users currently can resort to LinkedHashMap or LinkedHashSet within an unmodifiable map or set wrapper, but such structure is inconvenient to construct and incurs a lot of copying overheads.

An unmodifiable set or map with a well-defined encounter order is the subject of the "classifier" proposal (JDK-8357674), which can bring optimizations to such sets and maps in the future.

Solution

Create "unmodifiable set and map with defined encounter order" in SequencedMap and SequencedSet.

They are similar to those in java.util.Map and Set, that they:

• Deeply unmodifiable for potentially-noop modification operations itself and all derived views
• Reject null consistently, including for contains queries
• Supports serialization on themselves, but not for the derived views
• Reject duplicate element/key at creation, except for copying from another Collection in (Sequenced)Set
• Value-based

The only differences they have are that sequenced versions have well-defined encounter order, while the non-sequenced ones do not and the order is subject to change.

SequencedMap has of, ofEntries(Map.Entry...), and copyOf(Map) factories, and SequencedSet has of, of(E...), and copyOf(Collection) factories.

These factories together support both creation of small collections and sanitizing across trust boundaries.

Specification

An initial spec is attached.