== Why is this an issue?

Java 21 introduces the new Sequenced Collections API, which applies to all collections with a defined sequence on their elements, such as `LinkedList`, `TreeSet`, and others (see https://openjdk.org/jeps/431[JEP 431]).
For projects using Java 21 and onwards, use this API instead of workaround implementations that were necessary before Java 21.

This rule identifies instances where `Collection.reverse(List)` is used instead of the reversed view of a list (`SequencedCollection.reversed()`).
It is important to note that this replacement is only valid in cases where the returned list is accessed in a read-only manner.
This is because `SequencedCollection.reversed()` returns a view of the original list, meaning modifications made to the returned list will be reflected in the original list.
On the other hand, `Collection.reverse(List)` creates a completely new list that is not connected with the original list.

`SequencedCollection.reversed()` should be the preferred method for two reasons:

1. It returns a more lightweight object, as it does not need to recreate the underlying data structure as `Collection.reverse(List)` does. It merely provides a wrapper for element access and the iterator.
2. It abstracts from the fact that the collection instance is a list. This results in more generic code that is easier to port, for instance, when you want to use another collection data structure.

== How to fix it

Replace `Collection.reverse(list)` with `list.reversed()`.

=== Code examples

==== Noncompliant code example

[source,java,diff-id=1,diff-type=noncompliant]
----
void foo(List<String> list) {
  var reverseList = Collections.reverse(list); // Noncompliant
  // ... (read-only operations)
}
----

==== Compliant solution

[source,java,diff-id=1,diff-type=compliant]
----
void foo(List<String> list) {
  var reverseList = list.reversed(); // Compliant
  // do something
  // ...
}
----

== Resources
=== Documentation

* Java Documentation - https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/SequencedCollection.html[Interface SequencedCollection]
* OpenJDK - https://openjdk.org/jeps/431[JEP 431: Sequenced Collections]
* Java Documentation - https://docs.oracle.com/en/java/javase/21/core/creating-sequenced-collections-sets-and-maps.html#GUID-DCFE1D88-A0F5-47DE-A816-AEDA50B97523[Creating Sequenced Collections, Sets, and Maps]