Updating service bus and event hubs java docs (Azure#18426)

* Replace README with renderable links.

* Fix format strings.

* Update EventBatchContext and EventHubClientBuilder docs

Author: conniey

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

@@ -14,7 +14,7 @@ documentation][event_hubs_product_docs] | [Samples][sample_examples]
 - A [Java Development Kit (JDK)][jdk_link], version 8 or later.
 - [Maven][maven]
 - Microsoft Azure subscription
-    - You can create a free account at: https://azure.microsoft.com
+    - You can create a free account at: [https://azure.microsoft.com](https://azure.microsoft.com)
 - Azure Event Hubs instance
     - Step-by-step guide for [creating an Event Hub using the Azure Portal][event_hubs_create]
 - Azure Storage account
@@ -81,8 +81,8 @@ BlobContainerAsyncClient blobContainerAsyncClient = new BlobContainerClientBuild
 
 ### Consume events using an Event Processor Client
 
-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 
+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

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

@@ -21,24 +21,23 @@ documentation][event_hubs_product_docs] | [Samples][sample_examples]
 
 ## Table of contents
 
-- [Table of contents](#table-of-contents)
-- [Getting started](#getting-started)
-  - [Prerequisites](#prerequisites)
-  - [Include the package](#include-the-package)
-  - [Authenticate the client](#authenticate-the-client)
-    - [Create an Event Hub producer using a connection string](#create-an-event-hub-producer-using-a-connection-string)
-    - [Create an Event Hub client using Microsoft identity platform (formerly Azure Active Directory)](#create-an-event-hub-client-using-microsoft-identity-platform-formerly-azure-active-directory)
-- [Key concepts](#key-concepts)
-- [Examples](#examples)
-  - [Publish events to an Event Hub](#publish-events-to-an-event-hub)
-  - [Consume events from an Event Hub partition](#consume-events-from-an-event-hub-partition)
-  - [Consume events using an EventProcessorClient](#consume-events-using-an-eventprocessorclient)
-- [Troubleshooting](#troubleshooting)
-  - [Enable client logging](#enable-client-logging)
-  - [Enable AMQP transport logging](#enable-amqp-transport-logging)
-  - [Exceptions](#exceptions)
-- [Next steps](#next-steps)
-- [Contributing](#contributing)
+- [Azure Event Hubs client library for Java](#azure-event-hubs-client-library-for-java)
+  - [Table of contents](#table-of-contents)
+  - [Getting started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Include the package](#include-the-package)
+    - [Authenticate the client](#authenticate-the-client)
+  - [Key concepts](#key-concepts)
+  - [Examples](#examples)
+    - [Publish events to an Event Hub](#publish-events-to-an-event-hub)
+    - [Consume events from an Event Hub partition](#consume-events-from-an-event-hub-partition)
+    - [Consume events using an EventProcessorClient](#consume-events-using-an-eventprocessorclient)
+  - [Troubleshooting](#troubleshooting)
+    - [Enable client logging](#enable-client-logging)
+    - [Enable AMQP transport logging](#enable-amqp-transport-logging)
+    - [Exceptions](#exceptions)
+  - [Next steps](#next-steps)
+  - [Contributing](#contributing)
 
 ## Getting started
 
@@ -47,7 +46,7 @@ documentation][event_hubs_product_docs] | [Samples][sample_examples]
 - A [Java Development Kit (JDK)][jdk_link], version 8 or later.
 - [Maven][maven]
 - Microsoft Azure subscription
-  - You can create a free account at: https://azure.microsoft.com
+  - You can create a free account at: [https://azure.microsoft.com](https://azure.microsoft.com)
 - Azure Event Hubs instance
   - Step-by-step guide for [creating an Event Hub using the Azure Portal][event_hubs_create]
 
@@ -75,7 +74,7 @@ namespace. If you aren't familiar with shared access policies in Azure, you may
 [get an Event Hubs connection string][event_hubs_connection_string].
 
 Both the asynchronous and synchronous Event Hub producer and consumer clients can be created using
-`EventHubClientBuilder`. Invoking `build*Client()` creates a synchronous producer or consumer while 
+`EventHubClientBuilder`. Invoking `build*Client()` creates a synchronous producer or consumer while
 `build*AsyncClient()` creates its asynchronous counterpart.
 
 The snippet below creates a synchronous Event Hub producer.
@@ -166,7 +165,7 @@ distributed evenly among the partitions.
 
 #### Create an Event Hub producer and publish events
 
-Developers can create a producer using `EventHubClientBuilder` and calling `buildProducer*Client()`. Specifying 
+Developers can create a producer using `EventHubClientBuilder` and calling `buildProducer*Client()`. Specifying
 `CreateBatchOptions.setPartitionId(String)` will send events to a specific partition. If `partitionId` is not specified,
 events are automatically routed to a partition. Specifying `CreateBatchOptions.setPartitionKey(String)` will tell Event
 Hubs service to hash the events and send them to the same partition.
@@ -203,7 +202,7 @@ if (eventDataBatch.getCount() > 0) {
 
 #### Publish events using partition identifier
 
-Many Event Hub operations take place within the scope of a specific partition. Any client can call 
+Many Event Hub operations take place within the scope of a specific partition. Any client can call
 `getPartitionIds()` or `getEventHubProperties()` to get the partition ids and metadata about in their Event Hub
 instance.
 
@@ -386,7 +385,7 @@ The recommended way to solve the specific exception the AMQP exception represent
 ## Next steps
 
 Beyond those discussed, the Azure Event Hubs client library offers support for many other scenarios to take
-advantage of the full feature set of the Azure Event Hubs service. To explore some of these scenarios, check out the 
+advantage of the full feature set of the Azure Event Hubs service. To explore some of these scenarios, check out the
 [samples README][samples_readme].
 
 ## Contributing
@@ -409,7 +408,7 @@ Guidelines](https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/eventhub
 [event_hubs_connection_string]: https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string
 [event_hubs_create]: https://docs.microsoft.com/azure/event-hubs/event-hubs-create
 [event_hubs_features]: https://docs.microsoft.com/azure/event-hubs/event-hubs-features
-[event_hubs_messaging_exceptions]: https://docs.microsoft.com/azure/event-hubs/event-hubs-messaging-exceptions 
+[event_hubs_messaging_exceptions]: https://docs.microsoft.com/azure/event-hubs/event-hubs-messaging-exceptions
 [event_hubs_product_docs]: https://docs.microsoft.com/azure/event-hubs/
 [event_hubs_quotas]: https://docs.microsoft.com/azure/event-hubs/event-hubs-quotas
 [EventHubConsumerAsyncClient]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventHubConsumerAsyncClient.java

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/CheckpointStore.java

@@ -12,6 +12,8 @@
 /**
  * An interface that defines the operations for storing and retrieving partition ownership information and checkpoint
  * details for each partition.
+ *
+ * @see EventProcessorClientBuilder#checkpointStore(CheckpointStore)
  */
 public interface CheckpointStore {
 
@@ -23,7 +25,7 @@ public interface CheckpointStore {
      * <strong>{@literal "{your-namespace}.servicebus.windows.net}"</strong>.
      * @param eventHubName The Event Hub name to get ownership information.
      * @param consumerGroup The consumer group name.
-     * @return A flux of partition ownership details of all the partitions that have/had an owner.
+     * @return A {@link Flux} of partition ownership details of all the partitions that have/had an owner.
      */
     Flux<PartitionOwnership> listOwnership(String fullyQualifiedNamespace, String eventHubName,
         String consumerGroup);
@@ -33,7 +35,7 @@ Flux<PartitionOwnership> listOwnership(String fullyQualifiedNamespace, String ev
      * successfully.
      *
      * @param requestedPartitionOwnerships List of partition ownerships this instance is requesting to own.
-     * @return A flux of partitions this instance successfully claimed ownership.
+     * @return A {@link Flux} of partitions this instance successfully claimed ownership.
      */
     Flux<PartitionOwnership> claimOwnership(List<PartitionOwnership> requestedPartitionOwnerships);
 
@@ -44,7 +46,7 @@ Flux<PartitionOwnership> listOwnership(String fullyQualifiedNamespace, String ev
      * @param fullyQualifiedNamespace The fully qualified namespace of the Event Hub.
      * @param eventHubName The Event Hub name to get checkpoint information.
      * @param consumerGroup The consumer group name associated with the checkpoint.
-     * @return A flux of checkpoints associated with the partitions of the Event Hub.
+     * @return A {@link Flux} of checkpoints associated with the partitions of the Event Hub.
      */
     Flux<Checkpoint> listCheckpoints(String fullyQualifiedNamespace, String eventHubName, String consumerGroup);
 

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventDataBatch.java

@@ -12,6 +12,7 @@
 import com.azure.core.util.Context;
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.core.util.tracing.ProcessKind;
+import com.azure.messaging.eventhubs.models.CreateBatchOptions;
 import org.apache.qpid.proton.Proton;
 import org.apache.qpid.proton.amqp.Binary;
 import org.apache.qpid.proton.amqp.Symbol;
@@ -42,7 +43,9 @@
  * sent to the Azure Event Hubs service.
  *
  * @see EventHubProducerClient#createBatch()
+ * @see EventHubProducerClient#createBatch(CreateBatchOptions)
  * @see EventHubProducerAsyncClient#createBatch()
+ * @see EventHubProducerAsyncClient#createBatch(CreateBatchOptions)
  * @see EventHubClientBuilder See EventHubClientBuilder for examples of building an asynchronous or synchronous
  *     producer.
  */

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventHubClientBuilder.java

@@ -65,7 +65,7 @@
  * </ul>
  *
  * <p>
- * In addition, <strong>consumer group</strong> is required when creating {@link EventHubConsumerAsyncClient} or
+ * In addition, the <strong>consumer group</strong> is required when creating {@link EventHubConsumerAsyncClient} or
  * {@link EventHubConsumerClient}.
  * </p>
  *

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventHubConsumerClient.java

@@ -30,8 +30,9 @@
  *
  * <p><strong>Consuming events from a single partition</strong></p>
  * <p>Events from a single partition can be consumed using {@link #receiveFromPartition(String, int, EventPosition)} or
- * {@link #receiveFromPartition(String, int, EventPosition, Duration)}. The call to `receive` completes and returns an
- * {@link IterableStream} when either the maximum number of events is received, or the timeout has elapsed.</p>
+ * {@link #receiveFromPartition(String, int, EventPosition, Duration)}. The call to {@code receiveFromPartition}
+ * completes and returns an {@link IterableStream} when either the maximum number of events is received, or the
+ * timeout has elapsed.</p>
  *
  * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerclient.receive#string-int-eventposition-duration}
  */

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventProcessorClientBuilder.java

@@ -45,19 +45,18 @@
  * from the Event Hub.</li>
  * <li>{@link #processError(Consumer) processError} - A callback that handles errors that may occur while running the
  * EventProcessorClient.</li>
- * <li>Credentials -
- *  <strong>Credentials are required</strong> to perform operations against Azure Event Hubs. They can be set by using
- *  one of the following methods:
- *  <ul>
- *  <li>{@link #connectionString(String)} with a connection string to a specific Event Hub.
- *  </li>
- *  <li>{@link #connectionString(String, String)} with an Event Hub <i>namespace</i> connection string and the Event Hub
- *  name.</li>
- *  <li>{@link #credential(String, String, TokenCredential)} with the fully qualified namespace, Event Hub name, and a
- *  set of credentials authorized to use the Event Hub.
- *  </li>
- *  </ul>
- *  </li>
+ * <li>Credentials to perform operations against Azure Event Hubs. They can be set by using one of the following
+ * methods:
+ * <ul>
+ * <li>{@link #connectionString(String) connectionString(String)} with a connection string to a specific Event Hub.
+ * </li>
+ * <li>{@link #connectionString(String, String) connectionString(String, String)} with an Event Hub <i>namespace</i>
+ * connection string and the Event Hub name.</li>
+ * <li>{@link #credential(String, String, TokenCredential) credential(String, String, TokenCredential)} with the fully
+ * qualified namespace, Event Hub name, and a set of credentials authorized to use the Event Hub.
+ * </li>
+ * </ul>
+ * </li>
  * </ul>
  *
  * <p><strong>Creating an {@link EventProcessorClient}</strong></p>

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/LoadBalancingStrategy.java

@@ -6,6 +6,8 @@
 /**
  * The strategy used by event processor for load balancing the partition ownership to distribute the event processing
  * work with other processor instances.
+ *
+ * @see EventProcessorClientBuilder#loadBalancingStrategy(LoadBalancingStrategy)
  */
 public enum LoadBalancingStrategy {
 

sdk/eventhubs/azure-messaging-eventhubs/src/main/java/com/azure/messaging/eventhubs/models/EventBatchContext.java

@@ -3,10 +3,14 @@
 
 package com.azure.messaging.eventhubs.models;
 
+import com.azure.core.amqp.exception.AmqpException;
 import com.azure.messaging.eventhubs.CheckpointStore;
 import com.azure.messaging.eventhubs.EventData;
 import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
+
+import java.time.Duration;
 import java.util.List;
+import java.util.Objects;
 import java.util.function.Consumer;
 import reactor.core.publisher.Mono;
 
@@ -15,6 +19,9 @@
  * given to the {@link EventProcessorClientBuilder#processEventBatch(Consumer, int) processEventBatch} handler each
  * time an event batch is received from the Event Hub. This class also includes methods to update checkpoint in
  * {@link CheckpointStore} and retrieve the last enqueued event information.
+ *
+ * @see EventProcessorClientBuilder#processEventBatch(Consumer, int)
+ * @see EventProcessorClientBuilder#processEventBatch(Consumer, int, Duration)
  */
 public class EventBatchContext {
 
@@ -36,10 +43,11 @@ public class EventBatchContext {
      */
     public EventBatchContext(PartitionContext partitionContext, List<EventData> events,
         CheckpointStore checkpointStore, LastEnqueuedEventProperties lastEnqueuedEventProperties) {
-        this.checkpointStore = checkpointStore;
-        this.events = events;
+        this.checkpointStore = Objects.requireNonNull(checkpointStore, "'checkpointStore' cannot be null.");
+        this.events = Objects.requireNonNull(events, "'events' cannot be null.");
+        this.partitionContext = Objects.requireNonNull(partitionContext, "'partitionContext' cannot be null.");
+
         this.lastEnqueuedEventProperties = lastEnqueuedEventProperties;
-        this.partitionContext = partitionContext;
     }
 
     /**
@@ -79,12 +87,14 @@ public LastEnqueuedEventProperties getLastEnqueuedEventProperties() {
      * if the update is successful. If {@link #getEvents()} returns an empty, no update to checkpoint will be
      * done.
      *
-     * @return a representation of deferred execution of this call.
+     * @return Gets a {@link Mono} that completes when the checkpoint is updated.
+     * @throws AmqpException if an error occurs when updating the checkpoint.
      */
     public Mono<Void> updateCheckpointAsync() {
-        if (this.events == null || this.events.isEmpty()) {
+        if (this.events.isEmpty()) {
             return Mono.empty();
         }
+
         // update checkpoint of the last event in the batch
         Checkpoint checkpoint = new Checkpoint()
             .setFullyQualifiedNamespace(partitionContext.getFullyQualifiedNamespace())
@@ -101,6 +111,8 @@ public Mono<Void> updateCheckpointAsync() {
      * {@link #getEvents()}. This will serve as the last known successfully processed event in this partition
      * if the update is successful. If {@link #getEvents()} returns an empty, no update to checkpoint will be
      * done.
+     *
+     * @throws AmqpException if an error occurs while updating the checkpoint.
      */
     public void updateCheckpoint() {
         this.updateCheckpointAsync().block();