diff --git a/examples/cache-with-aws/build.gradle.kts b/examples/cache-with-aws/build.gradle.kts index 9b08d9d1..138b2523 100644 --- a/examples/cache-with-aws/build.gradle.kts +++ b/examples/cache-with-aws/build.gradle.kts @@ -17,7 +17,7 @@ repositories { } dependencies { - implementation("software.momento.java:sdk:1.18.0") + implementation("software.momento.java:sdk:1.19.0") // For examples to store secrets in AWS Secrets Manager implementation("software.amazon.awssdk:secretsmanager:2.20.93") diff --git a/examples/cache/build.gradle.kts b/examples/cache/build.gradle.kts index ce0fb2c1..47669dcf 100644 --- a/examples/cache/build.gradle.kts +++ b/examples/cache/build.gradle.kts @@ -17,7 +17,7 @@ repositories { } dependencies { - implementation("software.momento.java:sdk:1.18.0") + implementation("software.momento.java:sdk:1.19.0") implementation("com.google.guava:guava:31.1-android") diff --git a/examples/cache/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java b/examples/cache/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java index 00e9068d..eb5c0676 100644 --- a/examples/cache/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java +++ b/examples/cache/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java @@ -38,17 +38,14 @@ public static void example_API_CredentialProviderFromString() { CredentialProvider.fromString(authToken); } - @SuppressWarnings("ResultOfMethodCallIgnored") public static void example_API_ConfigurationLaptop() { Configurations.Laptop.v1(); } - @SuppressWarnings("ResultOfMethodCallIgnored") public static void example_API_ConfigurationInRegionLatest() { Configurations.InRegion.latest(); } - @SuppressWarnings("ResultOfMethodCallIgnored") public static void example_API_ConfigurationLowLatency() { Configurations.LowLatency.latest(); } diff --git a/examples/lambda/docker/build.gradle.kts b/examples/lambda/docker/build.gradle.kts index 1b596e60..0f359f0e 100644 --- a/examples/lambda/docker/build.gradle.kts +++ b/examples/lambda/docker/build.gradle.kts @@ -12,7 +12,7 @@ repositories { dependencies { implementation("com.amazonaws:aws-lambda-java-core:1.2.1") - implementation("software.momento.java:sdk:1.18.0") + implementation("software.momento.java:sdk:1.19.0") } tasks.jar { diff --git a/examples/leaderboard/README.md b/examples/leaderboard/README.md new file mode 100644 index 00000000..e00f04ba --- /dev/null +++ b/examples/leaderboard/README.md @@ -0,0 +1,39 @@ +logo + +[![project status](https://momentohq.github.io/standards-and-practices/badges/project-status-official.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md) +[![project stability](https://momentohq.github.io/standards-and-practices/badges/project-stability-stable.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md) + + +# Momento Java SDK - Leaderboard Client Examples + +## Running the Examples + +- You do not need gradle to be installed +- JDK 14 or above is required to run the example +- To get started with Momento you will need a Momento API key. You can get one from the + [Momento Console](https://console.gomomento.com). + +### Basic + +```bash +MOMENTO_API_KEY= ./gradlew basic +``` + +Example Code: [BasicExample.java](src/main/java/momento/client/example/BasicExample.java) + +## Using the Java SDK in your project + +### Gradle Configuration + +Update your Gradle build to include the components + +#### build.gradle.kts + +```kotlin +dependencies { + implementation("software.momento.java:sdk:1.x.x") +} +``` + +---------------------------------------------------------------------------------------- +For more info, visit our website at [https://gomomento.com](https://gomomento.com)! diff --git a/examples/leaderboard/README.template.md b/examples/leaderboard/README.template.md new file mode 100644 index 00000000..867a40cc --- /dev/null +++ b/examples/leaderboard/README.template.md @@ -0,0 +1,34 @@ +{{ ossHeader }} + +# Momento Java SDK - Leaderboard Client Examples + +## Running the Examples + +- You do not need gradle to be installed +- JDK 14 or above is required to run the example +- To get started with Momento you will need a Momento API key. You can get one from the + [Momento Console](https://console.gomomento.com). + +### Basic + +```bash +MOMENTO_API_KEY= ./gradlew basic +``` + +Example Code: [BasicExample.java](src/main/java/momento/client/example/BasicExample.java) + +## Using the Java SDK in your project + +### Gradle Configuration + +Update your Gradle build to include the components + +#### build.gradle.kts + +```kotlin +dependencies { + implementation("software.momento.java:sdk:1.x.x") +} +``` + +{{ ossFooter }} diff --git a/examples/leaderboard/build.gradle.kts b/examples/leaderboard/build.gradle.kts new file mode 100644 index 00000000..1ec675f8 --- /dev/null +++ b/examples/leaderboard/build.gradle.kts @@ -0,0 +1,64 @@ +/* + * This file was generated by the Gradle 'init' task. + * + * This generated file contains a sample Java library project to get you started. + * For more details take a look at the 'Building Java & JVM projects' chapter in the Gradle + * User Manual available at https://docs.gradle.org/7.2/userguide/building_java_projects.html + */ + +plugins { + application + id("com.diffplug.spotless") version "5.15.1" +} + +repositories { + // Use Maven Central for resolving dependencies. + mavenCentral() +} + +dependencies { + implementation("software.momento.java:sdk:1.19.0") + + // Logging framework to log and enable logging in the Momento client. + implementation("ch.qos.logback:logback-classic:1.4.7") + + // Use JUnit Jupiter for testing. + testImplementation("org.junit.jupiter:junit-jupiter:5.9.2") +} + +spotless { + java { + removeUnusedImports() + googleJavaFormat("1.11.0") + } +} + +tasks.test { + // Use JUnit Platform for unit tests. + useJUnitPlatform() +} + +task("basic", JavaExec::class) { + description = "Run the basic example" + classpath = sourceSets.main.get().runtimeClasspath + mainClass.set("momento.client.example.BasicExample") +} + +task("docExamples", JavaExec::class) { + description = "Validate that the API doc examples run" + classpath = sourceSets.main.get().runtimeClasspath + mainClass.set("momento.client.example.doc_examples.DocExamplesJavaAPIs") +} + +task("docCheatSheet", JavaExec::class) { + description = "Validate that the doc cheat sheet runs" + classpath = sourceSets.main.get().runtimeClasspath + mainClass.set("momento.client.example.doc_examples.CheatSheet") +} + +task("docsTasks") { + dependsOn("docCheatSheet") + dependsOn("docExamples") +} + +task("prepareKotlinBuildScriptModel") {} diff --git a/examples/leaderboard/src/main/java/momento/client/example/BasicExample.java b/examples/leaderboard/src/main/java/momento/client/example/BasicExample.java new file mode 100644 index 00000000..782c8572 --- /dev/null +++ b/examples/leaderboard/src/main/java/momento/client/example/BasicExample.java @@ -0,0 +1,87 @@ +package momento.client.example; + +import java.time.Duration; +import java.util.HashMap; +import java.util.Map; +import momento.sdk.CacheClient; +import momento.sdk.ILeaderboard; +import momento.sdk.LeaderboardClient; +import momento.sdk.auth.CredentialProvider; +import momento.sdk.auth.EnvVarCredentialProvider; +import momento.sdk.config.Configurations; +import momento.sdk.config.LeaderboardConfigurations; +import momento.sdk.responses.SortOrder; +import momento.sdk.responses.leaderboard.DeleteResponse; +import momento.sdk.responses.leaderboard.FetchResponse; +import momento.sdk.responses.leaderboard.LeaderboardElement; +import momento.sdk.responses.leaderboard.UpsertResponse; + +public class BasicExample { + private static final String API_KEY_ENV_VAR = "MOMENTO_API_KEY"; + private static final Duration DEFAULT_ITEM_TTL = Duration.ofSeconds(60); + + private static final String CACHE_NAME = "cache"; + private static final String LEADERBOARD_NAME = "leaderboard"; + + public static void main(String[] args) { + final CredentialProvider credentialProvider = new EnvVarCredentialProvider(API_KEY_ENV_VAR); + + try (final CacheClient cacheClient = + CacheClient.create( + credentialProvider, Configurations.Laptop.latest(), DEFAULT_ITEM_TTL); + final LeaderboardClient leaderboardClient = + LeaderboardClient.builder(credentialProvider, LeaderboardConfigurations.Laptop.latest()) + .build()) { + + cacheClient.createCache(CACHE_NAME).join(); + + final ILeaderboard leaderboard = leaderboardClient.leaderboard(CACHE_NAME, LEADERBOARD_NAME); + + final Map elements = new HashMap<>(); + elements.put(1, 1.0); + elements.put(2, 2.0); + elements.put(3, 3.0); + + UpsertResponse upsertResponse = leaderboard.upsert(elements).join(); + if (upsertResponse instanceof UpsertResponse.Error error) { + System.out.println("Error during upsert: " + error.getMessage()); + } + + System.out.println("First two elements by rank ascending:"); + final FetchResponse byRankResponse = + leaderboard.fetchByRank(0, 2, SortOrder.ASCENDING).join(); + if (byRankResponse instanceof FetchResponse.Success success) { + for (LeaderboardElement element : success.elementsList()) { + System.out.printf( + "Rank: %d, ID: %d, Score: %.2f%n", + element.getRank(), element.getId(), element.getScore()); + } + } else if (byRankResponse instanceof FetchResponse.Error error) { + System.out.println("Error during fetch: " + error.getMessage()); + } + + upsertResponse = leaderboard.upsert(Map.of(3, 5.0, 4, 6.0)).join(); + if (upsertResponse instanceof UpsertResponse.Error error) { + System.out.println("Error during upsert: " + error.getMessage()); + } + + System.out.println("Elements by score descending:"); + final FetchResponse byScoreResponse = + leaderboard.fetchByScore(1.0, 5.1, SortOrder.DESCENDING).join(); + if (byScoreResponse instanceof FetchResponse.Success success) { + for (LeaderboardElement element : success.elementsList()) { + System.out.printf( + "Rank: %d, ID: %d, Score: %.2f%n", + element.getRank(), element.getId(), element.getScore()); + } + } else if (byScoreResponse instanceof FetchResponse.Error error) { + System.out.println("Error during fetch: " + error.getMessage()); + } + + final DeleteResponse deleteResponse = leaderboard.delete().join(); + if (deleteResponse instanceof DeleteResponse.Error error) { + System.out.println("Error during delete: " + error.getMessage()); + } + } + } +} diff --git a/examples/leaderboard/src/main/java/momento/client/example/doc_examples/CheatSheet.java b/examples/leaderboard/src/main/java/momento/client/example/doc_examples/CheatSheet.java new file mode 100644 index 00000000..76db1d05 --- /dev/null +++ b/examples/leaderboard/src/main/java/momento/client/example/doc_examples/CheatSheet.java @@ -0,0 +1,17 @@ +package momento.client.example.doc_examples; + +import momento.sdk.LeaderboardClient; +import momento.sdk.auth.CredentialProvider; +import momento.sdk.config.LeaderboardConfigurations; + +public class CheatSheet { + public static void main(String[] args) { + try (final LeaderboardClient leaderboardClient = + LeaderboardClient.builder( + CredentialProvider.fromEnvVar("MOMENTO_API_KEY"), + LeaderboardConfigurations.Laptop.latest()) + .build()) { + // ... + } + } +} diff --git a/examples/leaderboard/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java b/examples/leaderboard/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java new file mode 100644 index 00000000..b1610d78 --- /dev/null +++ b/examples/leaderboard/src/main/java/momento/client/example/doc_examples/DocExamplesJavaAPIs.java @@ -0,0 +1,271 @@ +package momento.client.example.doc_examples; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.ThreadLocalRandom; +import java.util.stream.Collectors; +import java.util.stream.IntStream; +import momento.sdk.ILeaderboard; +import momento.sdk.LeaderboardClient; +import momento.sdk.auth.CredentialProvider; +import momento.sdk.config.LeaderboardConfigurations; +import momento.sdk.exceptions.InvalidArgumentException; +import momento.sdk.responses.SortOrder; +import momento.sdk.responses.leaderboard.FetchResponse; +import momento.sdk.responses.leaderboard.LeaderboardElement; +import momento.sdk.responses.leaderboard.LengthResponse; +import momento.sdk.responses.leaderboard.RemoveElementsResponse; +import momento.sdk.responses.leaderboard.UpsertResponse; +import momento.sdk.responses.storage.DeleteResponse; + +public class DocExamplesJavaAPIs { + + @SuppressWarnings("EmptyTryBlock") + public static void example_API_InstantiateLeaderboardClient() { + try (final LeaderboardClient leaderboardClient = + LeaderboardClient.builder( + CredentialProvider.fromEnvVar("MOMENTO_API_KEY"), + LeaderboardConfigurations.Laptop.latest()) + .build()) { + // ... + } + } + + public static void example_API_CreateLeaderboard( + LeaderboardClient leaderboardClient, String cacheName, String leaderboardName) { + final ILeaderboard leaderboard; + try { + leaderboard = leaderboardClient.leaderboard(cacheName, leaderboardName); + } catch (InvalidArgumentException e) { + throw new RuntimeException( + "Cache name '" + + cacheName + + "' or leaderboard name '" + + leaderboardName + + "' is invalid.", + e); + } + } + + public static void example_API_LeaderboardUpsert(ILeaderboard leaderboard) { + final Map elements = + Map.of( + 123, 100.0, + 456, 200.0, + 789, 300.0); + final UpsertResponse response = leaderboard.upsert(elements).join(); + if (response instanceof UpsertResponse.Success) { + System.out.println("Successfully upserted elements."); + } else if (response instanceof UpsertResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to call upsert elements into a leaderboard: " + + error.getErrorCode(), + error); + } + } + + public static void example_API_LeaderboardUpsertPagination( + ILeaderboard leaderboard, int totalNumElements) { + final Map elements = + IntStream.range(0, totalNumElements) + .boxed() + .collect( + Collectors.toMap(i -> i + 1, i -> i * ThreadLocalRandom.current().nextDouble())); + + for (long i = 0; i < elements.size(); i += 8192) { + final Map batch = + elements.entrySet().stream() + .skip(i) + .limit(8192) + .collect( + Collectors.toMap( + Map.Entry::getKey, Map.Entry::getValue, (v1, v2) -> v1, HashMap::new)); + + final UpsertResponse response = leaderboard.upsert(batch).join(); + if (response instanceof UpsertResponse.Success) { + System.out.printf("Successfully upserted batch of %d elements%n", batch.size()); + } else if (response instanceof UpsertResponse.Error error) { + throw new RuntimeException( + "An error occurred while upserting a batch of elements: " + error.getErrorCode(), + error); + } + } + } + + public static void example_API_LeaderboardFetchByScore(ILeaderboard leaderboard) { + // By default, FetchByScore will fetch the elements from the entire score range + // with zero offset in ascending order. It can return 8192 elements at a time. + FetchResponse response = leaderboard.fetchByScore().join(); + if (response instanceof FetchResponse.Success success) { + System.out.println("Successfully fetched elements:"); + for (LeaderboardElement element : success.values()) { + System.out.printf( + "id: %d, score: %.2f, rank: %d%n", + element.getId(), element.getScore(), element.getRank()); + } + } else if (response instanceof FetchResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to fetch elements: " + error.getErrorCode(), error); + } + + // Example specifying all FetchByScore options. You can provide any subset of these options + // to modify your FetchByScore request. + response = leaderboard.fetchByScore(1.0, 5.0, SortOrder.DESCENDING, 10, 10).join(); + if (response instanceof FetchResponse.Success success) { + System.out.println("Successfully fetched elements:"); + for (LeaderboardElement element : success.values()) { + System.out.printf( + "id: %d, score: %.2f, rank: %d%n", + element.getId(), element.getScore(), element.getRank()); + } + } else if (response instanceof FetchResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to fetch elements: " + error.getErrorCode(), error); + } + } + + public static void example_API_LeaderboardFetchByScorePagination( + ILeaderboard leaderboard, int totalNumElements) { + for (int offset = 0; offset < totalNumElements; offset += 8192) { + final FetchResponse response = + leaderboard.fetchByScore(null, null, null, offset, null).join(); + if (response instanceof FetchResponse.Success success) { + System.out.println("Successfully fetched elements:"); + for (LeaderboardElement element : success.values()) { + System.out.printf( + "id: %d, score: %.2f, rank: %d%n", + element.getId(), element.getScore(), element.getRank()); + } + } else if (response instanceof FetchResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to fetch elements: " + error.getErrorCode(), error); + } + } + } + + public static void example_API_LeaderboardFetchByRank(ILeaderboard leaderboard) { + final FetchResponse response = leaderboard.fetchByRank(0, 10, SortOrder.ASCENDING).join(); + if (response instanceof FetchResponse.Success success) { + System.out.println("Successfully fetched elements:"); + for (LeaderboardElement element : success.values()) { + System.out.printf( + "id: %d, score: %.2f, rank: %d%n", + element.getId(), element.getScore(), element.getRank()); + } + } else if (response instanceof FetchResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to fetch elements: " + error.getErrorCode(), error); + } + } + + public static void example_API_LeaderboardFetchByRankPagination( + ILeaderboard leaderboard, int totalNumElements) { + for (int rank = 0; rank < totalNumElements; rank += 8192) { + final FetchResponse response = + leaderboard.fetchByRank(rank, rank + 8192, SortOrder.ASCENDING).join(); + if (response instanceof FetchResponse.Success success) { + System.out.println("Successfully fetched elements:"); + for (LeaderboardElement element : success.values()) { + System.out.printf( + "id: %d, score: %.2f, rank: %d%n", + element.getId(), element.getScore(), element.getRank()); + } + } else if (response instanceof FetchResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to fetch elements: " + error.getErrorCode(), error); + } + } + } + + public static void example_API_LeaderboardGetRank(ILeaderboard leaderboard) { + final Set ids = Set.of(123, 456, 789); + final FetchResponse response = leaderboard.getRank(ids, SortOrder.ASCENDING).join(); + if (response instanceof FetchResponse.Success success) { + System.out.println("Successfully fetched elements:"); + for (LeaderboardElement element : success.values()) { + System.out.printf( + "id: %d, score: %.2f, rank: %d%n", + element.getId(), element.getScore(), element.getRank()); + } + } else if (response instanceof FetchResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to fetch elements: " + error.getErrorCode(), error); + } + } + + public static void example_API_LeaderboardLength(ILeaderboard leaderboard) { + final LengthResponse response = leaderboard.length().join(); + if (response instanceof LengthResponse.Success success) { + System.out.printf("Leaderboard length: %d%n", success.length()); + } else if (response instanceof LengthResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to get the length of a leaderboard: " + + error.getErrorCode(), + error); + } + } + + public static void example_API_LeaderboardRemoveElements(ILeaderboard leaderboard) { + final Set ids = Set.of(123, 456, 789); + final RemoveElementsResponse response = leaderboard.removeElements(ids).join(); + if (response instanceof RemoveElementsResponse.Success) { + System.out.println("Successfully removed elements."); + } else if (response instanceof RemoveElementsResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to remove elements: " + error.getErrorCode(), error); + } + } + + @SuppressWarnings("ConstantValue") + public static void example_API_LeaderboardRemoveElementsPagination(ILeaderboard leaderboard) { + final List ids = List.of(/* your ids */ ); + for (int i = 0; i < ids.size(); i += 8192) { + final List idsSublist = ids.subList(i, Math.min(i + 8192, ids.size())); + final RemoveElementsResponse response = leaderboard.removeElements(idsSublist).join(); + if (response instanceof RemoveElementsResponse.Success) { + System.out.println("Successfully removed elements."); + } else if (response instanceof RemoveElementsResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to remove elements: " + error.getErrorCode(), + error); + } + } + } + + public static void example_API_LeaderboardDelete(ILeaderboard leaderboard) { + final momento.sdk.responses.leaderboard.DeleteResponse response = leaderboard.delete().join(); + if (response instanceof DeleteResponse.Success) { + System.out.println("Successfully deleted leaderboard."); + } else if (response instanceof DeleteResponse.Error error) { + throw new RuntimeException( + "An error occurred while attempting to delete the leaderboard: " + error.getErrorCode(), + error); + } + } + + public static void main(String[] args) { + try (final LeaderboardClient leaderboardClient = + LeaderboardClient.builder( + CredentialProvider.fromEnvVar("MOMENTO_API_KEY"), + LeaderboardConfigurations.Laptop.latest()) + .build()) { + example_API_InstantiateLeaderboardClient(); + example_API_CreateLeaderboard(leaderboardClient, "test-cache", "leaderboard"); + + final ILeaderboard leaderboard = leaderboardClient.leaderboard("test-cache", "leaderboard"); + example_API_LeaderboardUpsert(leaderboard); + example_API_LeaderboardUpsertPagination(leaderboard, 2); + example_API_LeaderboardFetchByScore(leaderboard); + example_API_LeaderboardFetchByScorePagination(leaderboard, 2); + example_API_LeaderboardFetchByRank(leaderboard); + example_API_LeaderboardFetchByRankPagination(leaderboard, 2); + example_API_LeaderboardGetRank(leaderboard); + example_API_LeaderboardLength(leaderboard); + example_API_LeaderboardRemoveElements(leaderboard); + example_API_LeaderboardRemoveElementsPagination(leaderboard); + example_API_LeaderboardDelete(leaderboard); + } + } +} diff --git a/examples/leaderboard/src/main/resources/logback.xml b/examples/leaderboard/src/main/resources/logback.xml new file mode 100644 index 00000000..29d89338 --- /dev/null +++ b/examples/leaderboard/src/main/resources/logback.xml @@ -0,0 +1,17 @@ + + + + + + + + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} -%kvp- %msg%n + + + + + + + diff --git a/examples/settings.gradle.kts b/examples/settings.gradle.kts index 35d139af..fa763050 100644 --- a/examples/settings.gradle.kts +++ b/examples/settings.gradle.kts @@ -26,3 +26,4 @@ include("lambda:docker") include("token") include("topic") include("storage") +include("leaderboard") diff --git a/examples/storage/build.gradle.kts b/examples/storage/build.gradle.kts index 8020702c..1ec675f8 100644 --- a/examples/storage/build.gradle.kts +++ b/examples/storage/build.gradle.kts @@ -17,7 +17,7 @@ repositories { } dependencies { - implementation("software.momento.java:sdk:1.18.0") + implementation("software.momento.java:sdk:1.19.0") // Logging framework to log and enable logging in the Momento client. implementation("ch.qos.logback:logback-classic:1.4.7") diff --git a/examples/token/build.gradle.kts b/examples/token/build.gradle.kts index 992427fa..9a0f4aaa 100644 --- a/examples/token/build.gradle.kts +++ b/examples/token/build.gradle.kts @@ -17,7 +17,7 @@ repositories { } dependencies { - implementation("software.momento.java:sdk:1.18.0") + implementation("software.momento.java:sdk:1.19.0") implementation("com.google.guava:guava:31.1-android") diff --git a/examples/topic/build.gradle.kts b/examples/topic/build.gradle.kts index fd78bfd6..585cbc38 100644 --- a/examples/topic/build.gradle.kts +++ b/examples/topic/build.gradle.kts @@ -17,7 +17,7 @@ repositories { } dependencies { - implementation("software.momento.java:sdk:1.18.0") + implementation("software.momento.java:sdk:1.19.0") implementation("com.google.guava:guava:31.1-android")