Add [SequencedCollection](https://docs.oracle.com/en/java/javase/21…

…/docs/api/java.base/java/util/SequencedCollection.html) methods to `ImmutableSortedSet`. There are a couple reasons that this is maybe kind of nice, and then there's my real motivation for doing it. Reasons that this is maybe kind of nice: - We add `@DoNotCall` and `@Deprecated` to the mutator methods, as usual. - We refine the return type of `reversed()` to `ImmutableSortedSet`. But again, those aren't my real motivation. (If they _were_ my real motivation, you might notice, then there would be no reason for us to override `getFirst()` and `getLast()`.) My _real_ motivation is that we are looking to give `guava-android` APIs that use Java 8+ types in their signatures, such as `ImmutableSet.toImmutableSet`. And as a result of some part of those changes, we start seeing errors in some of our Google-internal build rules. Those errors come because some the desugaring process is inserting its own versions of `getFirst` and friends, versions that refer to the desugar-provided copies of `SortedSet` and `NavigableSet`, which our build process then looks for but cannot find. Since this CL is preparation for adding `ImmutableSet.toImmutableSet`, it constitutes further progress toward #6567 RELNOTES=`collect`: Added [`SequencedCollection`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/SequencedCollection.html) methods to `ImmutableSortedSet`. PiperOrigin-RevId: 575207552
google · Oct 21, 2023 · 5ab75bb · 5ab75bb
1 parent 9c6b9d9
commit 5ab75bb
Show file tree

Hide file tree

Showing 2 changed files with 176 additions and 0 deletions.
diff --git a/android/guava/src/com/google/common/collect/ImmutableSortedSet.java b/android/guava/src/com/google/common/collect/ImmutableSortedSet.java
@@ -663,6 +663,22 @@ public E last() {
     return descendingIterator().next();
   }
 
+  /**
+   * @since NEXT. Note, however, that Java 21 users can call this method with any version of Guava.
+   */
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  public final E getFirst() {
+    return first();
+  }
+
+  /**
+   * @since NEXT. Note, however, that Java 21 users can call this method with any version of Guava.
+   */
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  public final E getLast() {
+    return last();
+  }
+
   /**
    * Guaranteed to throw an exception and leave the set unmodified.
    *
@@ -697,6 +713,68 @@ public final E pollLast() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @CanIgnoreReturnValue
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final E removeFirst() {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @CanIgnoreReturnValue
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final E removeLast() {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final void addFirst(E e) {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final void addLast(E e) {
+    throw new UnsupportedOperationException();
+  }
+
   @GwtIncompatible // NavigableSet
   @LazyInit
   @CheckForNull
@@ -715,6 +793,16 @@ public ImmutableSortedSet<E> descendingSet() {
     return result;
   }
 
+  /**
+   * @since NEXT. Note, however, that a variant of this method with return type {@link NavigableSet}
+   *     is available to Java 21 users with any version of Guava.
+   */
+  @GwtIncompatible // NavigableSet
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  public final ImmutableSortedSet<E> reversed() {
+    return descendingSet();
+  }
+
   // Most classes should implement this as new DescendingImmutableSortedSet<E>(this),
   // but we push down that implementation because ProGuard can't eliminate it even when it's always
   // overridden.

diff --git a/guava/src/com/google/common/collect/ImmutableSortedSet.java b/guava/src/com/google/common/collect/ImmutableSortedSet.java
@@ -731,6 +731,22 @@ public E last() {
     return descendingIterator().next();
   }
 
+  /**
+   * @since NEXT. Note, however, that Java 21 users can call this method with any version of Guava.
+   */
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  public final E getFirst() {
+    return first();
+  }
+
+  /**
+   * @since NEXT. Note, however, that Java 21 users can call this method with any version of Guava.
+   */
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  public final E getLast() {
+    return last();
+  }
+
   /**
    * Guaranteed to throw an exception and leave the set unmodified.
    *
@@ -765,6 +781,68 @@ public final E pollLast() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @CanIgnoreReturnValue
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final E removeFirst() {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @CanIgnoreReturnValue
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final E removeLast() {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final void addFirst(E e) {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Guaranteed to throw an exception and leave the set unmodified.
+   *
+   * @since NEXT
+   * @throws UnsupportedOperationException always
+   * @deprecated Unsupported operation.
+   */
+  @Deprecated
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  @DoNotCall("Always throws UnsupportedOperationException")
+  @CheckForNull
+  public final void addLast(E e) {
+    throw new UnsupportedOperationException();
+  }
+
   @GwtIncompatible // NavigableSet
   @LazyInit
   @CheckForNull
@@ -783,6 +861,16 @@ public ImmutableSortedSet<E> descendingSet() {
     return result;
   }
 
+  /**
+   * @since NEXT. Note, however, that a variant of this method with return type {@link NavigableSet}
+   *     is available to Java 21 users with any version of Guava.
+   */
+  @GwtIncompatible // NavigableSet
+  @SuppressWarnings("MissingOverride") // only an override under JDK 21+
+  public final ImmutableSortedSet<E> reversed() {
+    return descendingSet();
+  }
+
   // Most classes should implement this as new DescendingImmutableSortedSet<E>(this),
   // but we push down that implementation because ProGuard can't eliminate it even when it's always
   // overridden.