Prepares Jedis redis checkpoint store for release (Azure#32580)

* Add readme samples.

* Clean up sample.

* Clean-up second sample.

* Add CHANGELOG entry.

* Update jedis to the latest release.

* Update test assets and rename sample.

* Adding javadoc sample.

* Removing unchecked throw.

* Fix broken link.

* Fix localisation.

Author: conniey

eng/versioning/external_dependencies.txt

@@ -112,7 +112,7 @@ org.postgresql:postgresql;42.3.8
 org.slf4j:slf4j-api;1.7.36
 org.slf4j:slf4j-nop;1.7.36
 org.slf4j:slf4j-simple;1.7.36
-redis.clients:jedis;4.2.3
+redis.clients:jedis;4.3.1
 io.lettuce:lettuce-core;6.2.0.RELEASE
 org.redisson:redisson;3.17.0
 net.bytebuddy:byte-buddy;1.12.20

sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/CHANGELOG.md

@@ -4,8 +4,11 @@
 
 ### Features Added
 
-### Breaking Changes
+- Added implementation of `CheckpointStore` with `redis.clients.Jedis`
 
-### Bugs Fixed
+### Other Changes
 
+#### Dependency Updates
 
+- Add `azure-messaging-eventhubs` dependency to `5.16.0-beta.1`.
+- Add `jedis` dependency `4.3.1`.

sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/README.md

@@ -2,7 +2,7 @@
 
 Azure Event Hubs Checkpoint Store can be used for storing checkpoints while processing events from Azure Event Hubs.
 This package makes use of Redis as a persistent store for maintaining checkpoints and partition ownership information.
-The `JedisRedisCheckpointStore` provided in this package can be plugged in to `EventProcessor`.
+The `JedisRedisCheckpointStore` provided in this package can be plugged in to `EventProcessorClient`.
 
 [Source code][source_code]| [API reference documentation][api_documentation] | [Product
 documentation][event_hubs_product_docs] | [Samples][sample_examples]
@@ -18,7 +18,7 @@ documentation][event_hubs_product_docs] | [Samples][sample_examples]
 - Azure Event Hubs instance
     - Step-by-step guide for [creating an Event Hub using the Azure Portal][event_hubs_create]
 - Azure Redis Cache or a suitable alternative Redis server
-    - Step-by-step guide for [creating a Redis Cache using the Azure Portal][redis_cache]
+    - Step-by-step guide for [creating a Redis Cache using the Azure Portal][redis_quickstart]
 
 ### Include the package
 #### Include the BOM file
@@ -66,8 +66,9 @@ add the direct dependency to your project as follows.
 
 ### Authenticate the storage container client
 
-In order to create an instance of `JedisCheckpointStore`, a `JedisPool` object must be created. To make this `JedisPool` object, a hostname String and a primary key String are required. These can be used as shown below to create a `JedisPool` object.
-
+In order to create an instance of `JedisCheckpointStore`, a `JedisPool` object must be created. To make this `JedisPool`
+object, a hostname String and a primary key String are required. These can be used as shown below to create a
+`JedisPool` object.
 
 ## Key concepts
 
@@ -77,16 +78,26 @@ Key concepts are explained in detail [here][key_concepts].
 - [Create and run an instance of JedisRedisCheckpointStore][sample_jedis_client]
 - [Consume events from all Event Hub partitions][sample_event_processor]
 
-### Create an instance of JedisPool with Azure Redis Cache
+### Create an instance of JedisPool
+
+To create an instance of JedisPool using Azure Redis Cache, follow the instructions in
+[Use Azure Cache for Redis in Java][redis_quickstart_java] to fetch the hostname and access key.  Otherwise, use
+connection information from a running Redis instance.
 
-```java
-String hostname = "yourHostName.redis.cache.windows.net";
+```java readme-sample-createJedis
+JedisClientConfig clientConfig = DefaultJedisClientConfig.builder()
+    .password("<YOUR_REDIS_PRIMARY_ACCESS_KEY>")
+    .ssl(true)
+    .build();
 
-String password = "<PRIMARY KEY FOR AZURE REDIS CACHE>";
+String redisHostName = "<YOUR_REDIS_HOST_NAME>.redis.cache.windows.net";
+HostAndPort hostAndPort = new HostAndPort(redisHostName, 6380);
+JedisPool jedisPool = new JedisPool(hostAndPort, clientConfig);
 
-String name = "<NAME OF THE USER CLIENT>"; //this can also be a default value as the connection of Redis Cache is not dependent on this value
+// Do things with JedisPool.
 
-JedisPool jedisPool = new JedisPool(poolConfig, hostname, port, 1000, 1000, password, Protocol.DEFAULT_DATABASE, name, true, null, null, null);
+// Finally, dispose of resource
+jedisPool.close();
 ```
 
 ### Consume events using an Event Processor Client
@@ -95,38 +106,50 @@ To consume events for all partitions of an Event Hub, you'll create an
 [`EventProcessorClient`][source_eventprocessorclient] for a specific consumer group. When an Event Hub is created, it
 provides a default consumer group that can be used to get started.
 
-The [`EventProcessorClient`][source_eventprocessorclient] will delegate processing of events to a callback function that you
-provide, allowing you to focus on the logic needed to provide value while the processor holds responsibility for
-managing the underlying consumer operations.
+The [`EventProcessorClient`][source_eventprocessorclient] will delegate processing of events to a callback function
+that you provide, allowing you to focus on the logic needed to provide value while the processor holds responsibility
+for managing the underlying consumer operations.
 
 In our example, we will focus on building the [`EventProcessor`][source_eventprocessorclient], use the
 [`JedisRedisCheckpointStore`][source_jedisredischeckpointstore], and a simple callback function to process the events
 received from the Event Hubs, writes to console and updates the checkpoint in Blob storage after each event.
 
-```java
-JedisPool jedisPool = new JedisPool(poolConfig, hostname, port, 1000, 1000, password, Protocol.DEFAULT_DATABASE, name, true, null, null, null);
+```java readme-sample-createCheckpointStore
+JedisClientConfig clientConfig = DefaultJedisClientConfig.builder()
+    .password("<YOUR_REDIS_PRIMARY_ACCESS_KEY>")
+    .ssl(true)
+    .build();
+
+String redisHostName = "<YOUR_REDIS_HOST_NAME>.redis.cache.windows.net";
+HostAndPort hostAndPort = new HostAndPort(redisHostName, 6380);
+JedisPool jedisPool = new JedisPool(hostAndPort, clientConfig);
 
 EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
     .consumerGroup("<< CONSUMER GROUP NAME >>")
-    .connectionString("<< EVENT HUB CONNECTION STRING >>")
+    .connectionString("<< EVENT HUB NAMESPACE CONNECTION STRING >>")
+    .eventHubName("<< EVENT HUB NAME >>")
     .checkpointStore(new JedisRedisCheckpointStore(jedisPool))
     .processEvent(eventContext -> {
         System.out.println("Partition id = " + eventContext.getPartitionContext().getPartitionId() + " and "
             + "sequence number of event = " + eventContext.getEventData().getSequenceNumber());
     })
-    .processError(errorContext -> {
-        System.out.println("Error occurred while processing events " + errorContext.getThrowable().getMessage());
+    .processError(context -> {
+        System.out.println("Error occurred while processing events " + context.getThrowable().getMessage());
     })
     .buildEventProcessorClient();
 
 // This will start the processor. It will start processing events from all partitions.
 eventProcessorClient.start();
 
 // (for demo purposes only - adding sleep to wait for receiving events)
-TimeUnit.SECONDS.sleep(5);
+// Your application will probably keep the eventProcessorClient alive until the program ends.
+TimeUnit.SECONDS.sleep(2);
 
 // When the user wishes to stop processing events, they can call `stop()`.
 eventProcessorClient.stop();
+
+// Dispose of JedisPool resource.
+jedisPool.close();
 ```
 
 ## Troubleshooting
@@ -137,13 +160,6 @@ Azure SDK for Java offers a consistent logging story to help aid in troubleshoot
 their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help
 locate the root issue. View the [logging][logging] wiki for guidance about enabling logging.
 
-### Default SSL library
-
-All client libraries, by default, use the Tomcat-native Boring SSL library to enable native-level performance for SSL
-operations. The Boring SSL library is an uber jar containing native libraries for Linux / macOS / Windows, and provides
-better performance compared to the default SSL implementation within the JDK. For more information, including how to
-reduce the dependency size, refer to the [performance tuning][performance_tuning] section of the wiki.
-
 ## Next steps
 
 Get started by exploring the samples [here][samples_readme].
@@ -157,18 +173,17 @@ Guidelines][guidelines] for more information.
 [api_documentation]: https://azure.github.io/azure-sdk-for-java
 [event_hubs_create]: https://docs.microsoft.com/azure/event-hubs/event-hubs-create
 [event_hubs_product_docs]: https://docs.microsoft.com/azure/event-hubs/
-[java_8_sdk_javadocs]: https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html
 [jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable
 [key_concepts]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-blob/README.md#key-concepts
 [logging]: https://github.com/Azure/azure-sdk-for-java/wiki/Logging-with-Azure-SDK
 [maven]: https://maven.apache.org/
-[performance_tuning]: https://github.com/Azure/azure-sdk-for-java/wiki/Performance-Tuning
-[redis_cache]: https://docs.microsoft.com/azure/azure-cache-for-redis/cache-configure
+[redis_quickstart]: https://learn.microsoft.com/azure/azure-cache-for-redis/quickstart-create-redis
+[redis_quickstart_java]: https://learn.microsoft.com/azure/azure-cache-for-redis/cache-java-get-started
 [samples_readme]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis
 [sample_jedis_client]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/samples/java/com/azure/messaging/eventhubs/checkpointstore/jedis/JedisRedisCheckpointStoreSample.java
-[sample_event_processor]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/samples/java/com/azure/messaging/eventhubs/checkpointstore/jedis/EventProcessorJedisRedisCheckpointStoreSample.java
-[sample_examples]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis
+[sample_event_processor]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/samples/java/com/azure/messaging/eventhubs/checkpointstore/jedis/EventProcessorClientJedisSample.java
+[sample_examples]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/samples
 [source_code]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis
 [source_eventprocessorclient]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventProcessorClient.java
-[source_jedisredischeckpointstore]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis
+[source_jedisredischeckpointstore]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/main/java/com/azure/messaging/eventhubs/checkpointstore/jedis/JedisRedisCheckpointStore.java
 [guidelines]: https://github.com/Azure/azure-sdk-for-java/blob/main/CONTRIBUTING.md

sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/pom.xml

@@ -46,7 +46,7 @@
     <dependency>
       <groupId>redis.clients</groupId>
       <artifactId>jedis</artifactId>
-      <version>4.2.3</version> <!-- {x-version-update;redis.clients:jedis;external_dependency} -->
+      <version>4.3.1</version> <!-- {x-version-update;redis.clients:jedis;external_dependency} -->
     </dependency>
 
     <!-- Test dependencies -->
@@ -83,24 +83,22 @@
   </dependencies>
 
   <build>
-  <plugins>
-    <plugin>
-      <groupId>org.apache.maven.plugins</groupId>
-      <artifactId>maven-enforcer-plugin</artifactId>
-      <version>3.0.0-M3</version> <!-- {x-version-update;org.apache.maven.plugins:maven-enforcer-plugin;external_dependency} -->
-      <configuration>
-        <rules>
-          <bannedDependencies>
-            <includes>
-              <include>redis.clients:jedis:[4.2.3]</include> <!-- {x-include-update;redis.clients:jedis;external_dependency} -->
-              <include>org.mockito:mockito-inline:[4.5.1]</include> <!-- {x-include-update;org.mockito:mockito-inline;external_dependency} -->
-            </includes>
-          </bannedDependencies>
-        </rules>
-      </configuration>
-    </plugin>
-  </plugins>
-</build>
-
-
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>3.0.0-M3</version> <!-- {x-version-update;org.apache.maven.plugins:maven-enforcer-plugin;external_dependency} -->
+        <configuration>
+          <rules>
+            <bannedDependencies>
+              <includes>
+                <include>redis.clients:jedis:[4.3.1]</include> <!-- {x-include-update;redis.clients:jedis;external_dependency} -->
+                <include>org.mockito:mockito-inline:[4.5.1]</include> <!-- {x-include-update;org.mockito:mockito-inline;external_dependency} -->
+              </includes>
+            </bannedDependencies>
+          </rules>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
 </project>

sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/main/java/com/azure/messaging/eventhubs/checkpointstore/jedis/JedisRedisCheckpointStore.java

@@ -7,24 +7,45 @@
 import com.azure.core.util.serializer.JsonSerializerProviders;
 import com.azure.core.util.serializer.TypeReference;
 import com.azure.messaging.eventhubs.CheckpointStore;
+import com.azure.messaging.eventhubs.EventProcessorClient;
+import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
 import com.azure.messaging.eventhubs.models.Checkpoint;
 import com.azure.messaging.eventhubs.models.PartitionOwnership;
-
 import reactor.core.Exceptions;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
+import redis.clients.jedis.Jedis;
+import redis.clients.jedis.JedisPool;
+import redis.clients.jedis.Transaction;
 
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Set;
 
-import redis.clients.jedis.JedisPool;
-import redis.clients.jedis.Jedis;
-import redis.clients.jedis.Transaction;
-
 /**
  * Implementation of {@link CheckpointStore} that uses Azure Redis Cache, specifically Jedis.
+ *
+ * <p><strong>Instantiate checkpoint store</strong></p>
+ * Demonstrates one way to instantiate the checkpoint store. {@link JedisPool} has multiple ways to create an instance.
+ *
+ * <!-- src_embed com.azure.messaging.eventhubs.jedisredischeckpointstore.instantiation -->
+ * <pre>
+ * JedisClientConfig clientConfig = DefaultJedisClientConfig.builder&#40;&#41;
+ *     .password&#40;&quot;&lt;YOUR_REDIS_PRIMARY_ACCESS_KEY&gt;&quot;&#41;
+ *     .ssl&#40;true&#41;
+ *     .build&#40;&#41;;
+ *
+ * String redisHostName = &quot;&lt;YOUR_REDIS_HOST_NAME&gt;.redis.cache.windows.net&quot;;
+ * HostAndPort hostAndPort = new HostAndPort&#40;redisHostName, 6380&#41;;
+ * JedisPool jedisPool = new JedisPool&#40;hostAndPort, clientConfig&#41;;
+ *
+ * CheckpointStore checkpointStore = new JedisRedisCheckpointStore&#40;jedisPool&#41;;
+ * </pre>
+ * <!-- end com.azure.messaging.eventhubs.jedisredischeckpointstore.instantiation -->
+ *
+ * @see EventProcessorClient
+ * @see EventProcessorClientBuilder
  */
 public class JedisRedisCheckpointStore implements CheckpointStore {
 
@@ -40,7 +61,7 @@ public class JedisRedisCheckpointStore implements CheckpointStore {
      * @param jedisPool a JedisPool object that creates a pool connected to the Azure Redis Cache
      * @throws IllegalArgumentException thrown when JedisPool object supplied is null
      */
-    public JedisRedisCheckpointStore(JedisPool jedisPool) throws IllegalArgumentException {
+    public JedisRedisCheckpointStore(JedisPool jedisPool) {
         if (jedisPool == null) {
             throw LOGGER.logExceptionAsError(Exceptions
                 .propagate(new IllegalArgumentException(

sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-jedis/src/samples/java/com/azure/messaging/eventhubs/checkpointstore/jedis/EventProcessorClientJedisSample.java

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.messaging.eventhubs.checkpointstore.jedis;
+
+import com.azure.messaging.eventhubs.EventProcessorClient;
+import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
+import com.azure.messaging.eventhubs.models.ErrorContext;
+import com.azure.messaging.eventhubs.models.EventContext;
+import redis.clients.jedis.DefaultJedisClientConfig;
+import redis.clients.jedis.HostAndPort;
+import redis.clients.jedis.JedisClientConfig;
+import redis.clients.jedis.JedisPool;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Sample for using {@link JedisRedisCheckpointStore} with {@link EventProcessorClient}.
+ */
+public class EventProcessorClientJedisSample {
+    /**
+     * The main method to run the sample.
+     *
+     * @param args Unused arguments given to the sample
+     *
+     * @throws Exception an Exception will be thrown in case of errors while running the sample
+     */
+    public static void main(String[] args) throws Exception {
+        JedisClientConfig clientConfig = DefaultJedisClientConfig.builder()
+            .password("<YOUR_REDIS_PRIMARY_ACCESS_KEY>")
+            .ssl(true)
+            .build();
+
+        String redisHostName = "<YOUR_REDIS_HOST_NAME>.redis.cache.windows.net";
+        HostAndPort hostAndPort = new HostAndPort(redisHostName, 6380);
+        JedisPool jedisPool = new JedisPool(hostAndPort, clientConfig);
+
+        EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
+            .consumerGroup("<< CONSUMER GROUP NAME >>")
+            .connectionString("<< EVENT HUB NAMESPACE CONNECTION STRING >>")
+            .eventHubName("<< EVENT HUB NAME >>")
+            .processEvent(eventContext -> onEvent(eventContext))
+            .processError(errorContext -> onError(errorContext))
+            .checkpointStore(new JedisRedisCheckpointStore(jedisPool))
+            .buildEventProcessorClient();
+
+        // Starts the event processor
+        eventProcessorClient.start();
+
+        // Perform other tasks while the event processor is processing events in the background.
+        TimeUnit.MINUTES.sleep(5);
+
+        // Stops the event processor
+        eventProcessorClient.stop();
+    }
+
+    private static void onEvent(EventContext eventContext) {
+        System.out.printf("Processing event from partition %s with sequence number %d %n",
+            eventContext.getPartitionContext().getPartitionId(), eventContext.getEventData().getSequenceNumber());
+        if (eventContext.getEventData().getSequenceNumber() % 10 == 0) {
+            eventContext.updateCheckpoint();
+        }
+    }
+
+    private static void onError(ErrorContext errorContext) {
+        System.out.printf("Error occurred in partition processor for partition %s, %s.%n",
+            errorContext.getPartitionContext().getPartitionId(),
+            errorContext.getThrowable());
+    }
+}