feat(memorystore): added valkey caching practical source-code samples

memorystore/valkey/caching/snippets/README.md

@@ -0,0 +1,43 @@
+# Caching Samples
+
+This folder contains a samples in form of stand-alone snippets that demonstrate useful scenarios.
+
+## Prerequisites
+
+Ensure the following setup is in place.
+
+### Java
+
+You must have java installed locally on your machinee. Run `java --version` to check if this is available.
+
+### Memorystore for Valkey Instance
+
+A working instance of Memorystore for Valkey must be available. You can run the [Valkey CLI](https://valkey.io/topics/cluster-tutorial/#create-a-valkey-cluster) for a local instance, or create an instance through the [GCP Platform](https://console.cloud.google.com/memorystore/valkey/instances?).
+
+To setup a live instance, create a new Memorystore instance through the GCloud CLI using the following
+
+```bash
+gcloud redis instances create myinstance --size=2 --region=LOCATION --redis-version=redis_6_x
+```
+
+Altrernativley, run a local instance through the Valkey CLI
+
+```bash
+valkey-cli
+```
+
+## Running the sample code
+
+Each example contains instructions on any prerequisite configuration.
+
+## Compile the app through Maven (optional)
+
+```bash
+mvn compile
+```
+
+## Run the sample code
+
+```bash
+mvn exec:java -Dexec.mainClass=MemorystoreTtlItem #Replace the main class as needed
+```

memorystore/valkey/caching/snippets/pom.xml

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  Copyright 2025 Google LLC
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>com.example.memorystore</groupId>
+  <artifactId>caching</artifactId>
+  <version>1.0-SNAPSHOT</version>
+
+  <name>Google Cloud Memorystore Sample</name>
+  <url>http://www.example.com</url>
+
+          <!--
+        The parent pom defines common style checks and testing strategies for our samples.
+        Removing or replacing it should not affect the execution of the samples in anyway.
+    -->
+  <parent>
+      <groupId>com.google.cloud.samples</groupId>
+      <artifactId>shared-configuration</artifactId>
+      <version>1.2.0</version>
+  </parent>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <maven.compiler.release>11</maven.compiler.release>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.junit</groupId>
+        <artifactId>junit-bom</artifactId>
+        <version>5.11.0</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <dependencies>
+    <!-- Jedis Redis client library -->
+    <dependency>
+      <groupId>redis.clients</groupId>
+      <artifactId>jedis</artifactId>
+      <version>4.3.1</version>
+    </dependency>
+
+    <!-- Google Cloud Client Libraries -->
+    <dependency>
+      <groupId>com.google.cloud</groupId>
+      <artifactId>google-cloud-core</artifactId>
+      <version>2.16.0</version>
+    </dependency>
+
+    <!-- Unit testing libraries -->
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <artifactId>maven-clean-plugin</artifactId>
+          <version>3.4.0</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-resources-plugin</artifactId>
+          <version>3.3.1</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>3.13.0</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <version>3.3.0</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-jar-plugin</artifactId>
+          <version>3.4.2</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-install-plugin</artifactId>
+          <version>3.1.2</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-deploy-plugin</artifactId>
+          <version>3.1.2</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-site-plugin</artifactId>
+          <version>3.12.1</version>
+        </plugin>
+        <plugin>
+          <artifactId>maven-project-info-reports-plugin</artifactId>
+          <version>3.6.1</version>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+</project>

memorystore/valkey/caching/snippets/src/main/java/samples/MemorystoreDeleteItem.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import redis.clients.jedis.Jedis;
+import redis.clients.jedis.JedisPool;
+
+public final class MemorystoreDeleteItem {
+
+  /** Replace the instance ID of the Memorystore instance. */
+  private static final String INSTANCE_ID = "INSTANCE_ID";
+
+  /** Replace the Memorystore port, if not the default port. */
+  private static final int PORT = 6379;
+
+  /** Replace the id of the item to delete from Memorystore. */
+  private static final String ITEM_ID = "ITEM_ID";
+
+  private MemorystoreDeleteItem() {
+    // No-op; won't be called
+  }
+
+  /**
+   * Deletes an item from Memorystore.
+   *
+   * @param args command-line arguments
+   */
+  public static void main(final String[] args) {
+
+    // Connect to the Memorystore instance
+    JedisPool pool = new JedisPool(INSTANCE_ID, PORT);
+
+    try (Jedis jedis = pool.getResource()) {
+
+      // Attempt to delete the item
+      Long result = jedis.del(ITEM_ID);
+
+      // Check if the item was successfully deleted
+      if (result > 0) {
+        System.out.println("Deleted item: " + ITEM_ID);
+      }
+
+      // Print the cached item not found
+      if (result == 0) {
+        System.out.printf("No cached item found: %s%n", ITEM_ID);
+      }
+    }
+  }
+}

memorystore/valkey/caching/snippets/src/main/java/samples/MemorystoreReadItem.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import redis.clients.jedis.Jedis;
+import redis.clients.jedis.JedisPool;
+
+public final class MemorystoreReadItem {
+
+  /** Replace the instance ID of the Memorystore instance. */
+  private static final String INSTANCE_ID = "INSTANCE_ID";
+
+  /** If valid, replace the port number of the Memorystore instance. */
+  private static final int PORT = 6379;
+
+  /** Replace, the ID of the item to delete from the cache. */
+  private static final String ITEM_ID = "ITEM_ID";
+
+  private MemorystoreReadItem() {
+    // No-op; won't be called
+  }
+
+  /**
+   * Reads an item from Memorystore.
+   *
+   * @param args command-line arguments
+   */
+  public static void main(final String[] args) {
+
+    // Connect to the Memorystore instance
+    JedisPool pool = new JedisPool(INSTANCE_ID, PORT);
+
+    try (Jedis jedis = pool.getResource()) {
+
+      // Attempt to read the cached item
+      String cachedItem = jedis.get(ITEM_ID);
+
+      // Print the cached item if found
+      if (cachedItem != null) {
+        System.out.println("Cached item: " + cachedItem);
+      }
+
+      // Print the cached item not found
+      if (cachedItem == null) {
+        System.out.printf("No cached item found: %s%n", ITEM_ID);
+      }
+    }
+  }
+}

memorystore/valkey/caching/snippets/src/main/java/samples/MemorystoreTTLItem.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import redis.clients.jedis.Jedis;
+import redis.clients.jedis.JedisPool;
+
+public final class MemorystoreTtlItem {
+
+  /** Replace the Memorystore instance id. */
+  private static final String INSTANCE_ID = "INSTANCE_ID";
+
+  /** Replace the Memorystore port, if not the default port. */
+  private static final int PORT = 6379;
+
+  /** Replace the id of the item to write to Memorystore. */
+  private static final String ITEM_ID = "ITEM_ID";
+
+  /** Replace the id of the item to write to Memorystore. */
+  private static final String ITEM_VALUE = "ITEM_VALUE";
+
+  /** Set the initial wait time for checking the cache. */
+  private static final int INITIAL_WAIT_TIME = 5000;
+
+  /** Set the final wait time for checking the cache. */
+  private static final int FINAL_WAIT_TIME = 6000;
+
+  private MemorystoreTtlItem() {
+    // No-op; won't be called
+  }
+
+  /**
+   * Writes to Memorystore with a Time-to-live(TTL) value.
+   *
+   * @param args command-line arguments
+   * @throws InterruptedException if the thread sleep is interrupted
+   */
+  public static void main(final String[] args) throws InterruptedException {
+
+    // Connect to the Memorystore instance
+    JedisPool pool = new JedisPool(INSTANCE_ID, PORT);
+
+    try (Jedis jedis = pool.getResource()) {
+
+      // Set a TTL of 10 seconds during entry creation
+      final int ttlSeconds = 10;
+      jedis.setex(ITEM_ID, ttlSeconds, ITEM_VALUE);
+
+      // Print out the cached item details
+      System.out.printf(
+          "Item cached with ID: %s and value: %s for %ds%n",
+          ITEM_ID, ITEM_VALUE, ttlSeconds);
+
+      // Wait for 5 seconds to demonstrate the TTL countdown
+      System.out.println("Waiting for 5 seconds...");
+      Thread.sleep(INITIAL_WAIT_TIME);
+
+      // Retrieve and print the remaining TTL
+      Long remainingTtl = jedis.ttl(ITEM_ID);
+      System.out.printf("Remaining TTL %s: %ds%n", ITEM_ID, remainingTtl);
+
+      // Wait for another 6 seconds to demonstrate TTL expiry
+      System.out.println("Waiting for 6s for TTL expiry...");
+      Thread.sleep(FINAL_WAIT_TIME);
+
+      // Check the remaining TTL and item existence
+      remainingTtl = jedis.ttl(ITEM_ID);
+      if (remainingTtl < 0) {
+        System.out.printf("Item with ID %s has expired.", ITEM_ID);
+      }
+
+      if (remainingTtl >= 0) {
+        System.out.printf("Found Item %s", ITEM_ID, remainingTtl);
+      }
+    }
+  }
+}