Support JDK 21 Sequenced Collections

[rhys-saldanha]

1. What are you trying to do?

Please see JEP-431 for background on what a Sequenced Collection is.

The javadoc for ImmutableCollection mentions that most Guava Collections have a well-defined iteration order. Indeed, I often rely on this behaviour. This issue is to discuss support for the SequencedCollections interface, in order to better communicate that Guava Collections have this property.

2. What's the best code you can write to accomplish that without the new feature?

This example does not make much sense without the context of the added methods in SequencedCollection, however:

final var foo = ImmutableSet.of(1,2,3);
foo.asList().get(0); // = 1

3. What would that same code look like if we added your feature?

Sequenced Collections add new convenience methods that arise from having a defined iteration order. Applying this to (for example) ImmutableSet, which preserves insertion order, would result in the following code being valid:

final var foo = ImmutableSet.of(1,2,3);
foo.getFirst(); // = 1

(Optional) What would the method signatures for your feature look like?

No response

Concrete Use Cases

I have not yet used Guava with JDK 21.

Please see related Guava discussion: https://groups.google.com/g/guava-discuss/c/IXWZCHn7yJs

Packages

com.google.common.collect

Checklist

• I agree to follow the code of conduct.

• I have read and understood the contribution guidelines.

• I have read and understood Guava's philosophy, and I strongly believe that this proposal aligns with it.

• I have visited the idea graveyard, and did not see anything similar to this idea.

[cpovirk]

One thing that Rhys mentioned that I hadn't considered before was the documentation aspect: For someone new to, say, ImmutableMap, it could be useful to see that it's an implementation of SequencedMap. While we try to drive home the benefits of our immutable collections, a page like https://guava.dev/ImmutableMap doesn't mention ordering until you follow a link or at least read about a factory method like of.

Then there's the benefit of the methods themselves, like getFirst, as mentioned above. We could add those without worrying about some of the complexities that come with implementing the interface. That said, as discussed in the link above, that still leaves a couple challenges. I think the could both be solved by using --release 8, but that requires dealing with Unsafe and other unavailable APIs. --release 8 has a pretty good chance of becoming important someday (for this and other reasons), so we should reevaluate the SequencedCollection methods at that point.