feat: add the remaining leaderboard APIs (#412)

* feat: add the remaining leaderboard APIs Add leaderboard fetchByRank, getRank, length, and delete APIs. Set the default leaderboard max received message size to 200MB. Make SortOrder in fetchByRank nullable and have it default to ascending if null. Make the different null check validation methods use the same backing validateNotNull. Add a fetchByScore signature that doesn't take any arguments and fetches the first 8192 elements of a leaderboard. Comment fixes.
momentohq · Jan 15, 2025 · dce6078 · dce6078
1 parent 370067e
commit dce6078
Show file tree

Hide file tree

Showing 10 changed files with 907 additions and 75 deletions.
diff --git a/momento-sdk/src/intTest/java/momento/sdk/leaderboard/LeaderboardClientTest.java b/momento-sdk/src/intTest/java/momento/sdk/leaderboard/LeaderboardClientTest.java
diff --git a/momento-sdk/src/main/java/momento/sdk/ILeaderboard.java b/momento-sdk/src/main/java/momento/sdk/ILeaderboard.java
@@ -3,15 +3,18 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import momento.sdk.responses.SortOrder;
+import momento.sdk.responses.leaderboard.DeleteResponse;
 import momento.sdk.responses.leaderboard.FetchResponse;
+import momento.sdk.responses.leaderboard.LengthResponse;
 import momento.sdk.responses.leaderboard.RemoveElementsResponse;
 import momento.sdk.responses.leaderboard.UpsertResponse;
 
 public interface ILeaderboard {
 
   /**
-   * Updates elements in a leaderboard or inserts elements if they do not already exist. The
+   * Update elements in a leaderboard or insert elements if they do not already exist. The
    * leaderboard is also created if it does not already exist. Note: can upsert a maximum of 8192
    * elements at a time.
    *
@@ -22,7 +25,54 @@ public interface ILeaderboard {
   CompletableFuture<UpsertResponse> upsert(@Nonnull Map<Integer, Double> elements);
 
   /**
-   * Fetch the elements in the given leaderboard by index (rank). Note: can fetch a maximum of 8192
+   * Fetch the elements of the leaderboard by score. Note: can fetch a maximum of 8192 elements at a
+   * time.
+   *
+   * @param minScore The minimum score (inclusive) of the elements to fetch. Defaults to negative
+   *     infinity.
+   * @param maxScore The maximum score (exclusive) of the elements to fetch. Defaults to positive
+   *     infinity.
+   * @param order The order to fetch the elements in. Defaults to {@link SortOrder#ASCENDING}.
+   * @param offset The number of elements to skip before returning the first element. Defaults to 0.
+   *     Note: this is not the score of the first element to return, but the number of elements of
+   *     the result set to skip before returning the first element.
+   * @param count The maximum number of elements to return. Defaults to 8192, which is the maximum
+   *     that can be fetched at a time.
+   * @return A future containing the result of the fetch operation: {@link FetchResponse.Success}
+   *     containing the elements, or {@link FetchResponse.Error}.
+   */
+  CompletableFuture<FetchResponse> fetchByScore(
+      @Nullable Double minScore,
+      @Nullable Double maxScore,
+      @Nullable SortOrder order,
+      @Nullable Integer offset,
+      @Nullable Integer count);
+
+  /**
+   * Fetch the elements of the leaderboard by score. Note: can fetch a maximum of 8192 elements at a
+   * time.
+   *
+   * @param minScore The minimum score (inclusive) of the elements to fetch. Defaults to negative
+   *     infinity.
+   * @param maxScore The maximum score (exclusive) of the elements to fetch. Defaults to positive
+   *     infinity.
+   * @param order The order to fetch the elements in. Defaults to {@link SortOrder#ASCENDING}.
+   * @return A future containing the result of the fetch operation: {@link FetchResponse.Success}
+   *     containing the elements, or {@link FetchResponse.Error}.
+   */
+  CompletableFuture<FetchResponse> fetchByScore(
+      @Nullable Double minScore, @Nullable Double maxScore, @Nullable SortOrder order);
+
+  /**
+   * Fetch the first 8192 elements of the leaderboard, sorted by score ascending.
+   *
+   * @return A future containing the result of the fetch operation: {@link FetchResponse.Success}
+   *     containing the elements, or {@link FetchResponse.Error}.
+   */
+  CompletableFuture<FetchResponse> fetchByScore();
+
+  /**
+   * Fetch the elements of the leaderboard by index (rank). Note: can fetch a maximum of 8192
    * elements at a time and rank is 0-based (index begins at 0).
    *
    * @param startRank The rank of the first element to fetch. This rank is inclusive, i.e. the
@@ -31,20 +81,49 @@ public interface ILeaderboard {
    * @param endRank The rank of the last element to fetch. This rank is exclusive, i.e. the element
    *     at this rank will not be fetched. Ranks can be used to manually paginate through the
    *     leaderboard in batches of 8192 elements (e.g. request 0-8192, then 8192-16384, etc.).
-   * @param order The order to fetch the elements in.
+   * @param order The order to fetch the elements in. Defaults to {@link SortOrder#ASCENDING}.
    * @return A future containing the result of the fetch operation: {@link FetchResponse.Success}
    *     containing the elements, or {@link FetchResponse.Error}.
    */
   CompletableFuture<FetchResponse> fetchByRank(
-      int startRank, int endRank, @Nonnull SortOrder order);
+      int startRank, int endRank, @Nullable SortOrder order);
+
+  /**
+   * Look up the rank of the given elements in the leaderboard. The returned elements will be sorted
+   * numerically by their IDs. Note: rank is 0-based (index begins at 0).
+   *
+   * @param ids The IDs of the elements to fetch from the leaderboard.
+   * @param order The rank order to fetch the elements in, based on their scores. Defaults to {@link
+   *     SortOrder#ASCENDING}.
+   * @return A future containing the result of the fetch operation: {@link FetchResponse.Success}
+   *     containing the elements, or {@link FetchResponse.Error}.
+   */
+  CompletableFuture<FetchResponse> getRank(
+      @Nonnull Iterable<Integer> ids, @Nullable SortOrder order);
 
   /**
-   * Remove multiple elements from the given leaderboard Note: can remove a maximum of 8192 elements
-   * at a time.
+   * Fetch the length (number of items) of the leaderboard.
+   *
+   * @return A future containing the result of the length operation: {@link LengthResponse.Success}
+   *     containing the length of the leaderboard, or {@link LengthResponse.Error}.
+   */
+  CompletableFuture<LengthResponse> length();
+
+  /**
+   * Remove multiple elements from the leaderboard. Note: can remove a maximum of 8192 elements at a
+   * time.
    *
    * @param ids The IDs of the elements to remove from the leaderboard.
    * @return A future containing the result of the remove operation: {@link
    *     RemoveElementsResponse.Success} or {@link RemoveElementsResponse.Error}.
    */
   CompletableFuture<RemoveElementsResponse> removeElements(@Nonnull Iterable<Integer> ids);
+
+  /**
+   * Delete all elements in the leaderboard.
+   *
+   * @return A future containing the result of the delete operation: {@link DeleteResponse.Success},
+   *     or {@link DeleteResponse.Error}.
+   */
+  CompletableFuture<DeleteResponse> delete();
 }
diff --git a/momento-sdk/src/main/java/momento/sdk/Leaderboard.java b/momento-sdk/src/main/java/momento/sdk/Leaderboard.java
@@ -3,8 +3,11 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import momento.sdk.responses.SortOrder;
+import momento.sdk.responses.leaderboard.DeleteResponse;
 import momento.sdk.responses.leaderboard.FetchResponse;
+import momento.sdk.responses.leaderboard.LengthResponse;
 import momento.sdk.responses.leaderboard.RemoveElementsResponse;
 import momento.sdk.responses.leaderboard.UpsertResponse;
 
@@ -25,14 +28,54 @@ public CompletableFuture<UpsertResponse> upsert(@Nonnull Map<Integer, Double> el
     return leaderboardDataClient.upsert(cacheName, leaderboardName, elements);
   }
 
+  @Override
+  public CompletableFuture<FetchResponse> fetchByScore(
+      @Nullable Double minScore,
+      @Nullable Double maxScore,
+      @Nullable SortOrder order,
+      @Nullable Integer offset,
+      @Nullable Integer count) {
+    return leaderboardDataClient.fetchByScore(
+        cacheName, leaderboardName, minScore, maxScore, order, offset, count);
+  }
+
+  @Override
+  public CompletableFuture<FetchResponse> fetchByScore(
+      @Nullable Double minScore, @Nullable Double maxScore, @Nullable SortOrder order) {
+    return leaderboardDataClient.fetchByScore(
+        cacheName, leaderboardName, minScore, maxScore, order, null, null);
+  }
+
+  @Override
+  public CompletableFuture<FetchResponse> fetchByScore() {
+    return leaderboardDataClient.fetchByScore(
+        cacheName, leaderboardName, null, null, null, null, null);
+  }
+
   @Override
   public CompletableFuture<FetchResponse> fetchByRank(
-      int startRank, int endRank, @Nonnull SortOrder order) {
+      int startRank, int endRank, @Nullable SortOrder order) {
     return leaderboardDataClient.fetchByRank(cacheName, leaderboardName, startRank, endRank, order);
   }
 
+  @Override
+  public CompletableFuture<FetchResponse> getRank(
+      @Nonnull Iterable<Integer> ids, @Nullable SortOrder order) {
+    return leaderboardDataClient.getRank(cacheName, leaderboardName, ids, order);
+  }
+
+  @Override
+  public CompletableFuture<LengthResponse> length() {
+    return leaderboardDataClient.length(cacheName, leaderboardName);
+  }
+
   @Override
   public CompletableFuture<RemoveElementsResponse> removeElements(@Nonnull Iterable<Integer> ids) {
     return leaderboardDataClient.removeElements(cacheName, leaderboardName, ids);
   }
+
+  @Override
+  public CompletableFuture<DeleteResponse> delete() {
+    return leaderboardDataClient.delete(cacheName, leaderboardName);
+  }
 }