Event Hubs doc updates

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

@@ -117,9 +117,9 @@ public EventData(String body) {
     }
 
     /**
-     * The set of free-form event properties which may be used for passing metadata associated with the event with the
-     * event body during Event Hubs operations. A common use-case for {@code properties()} is to associate serialization
-     * hints for the {@link #getBody()} as an aid to consumers who wish to deserialize the binary data.
+     * Gets the set of free-form event properties which may be used for passing metadata associated with the event with
+     * the event body during Event Hubs operations. A common use-case for {@code properties()} is to associate
+     * serialization hints for the {@link #getBody()} as an aid to consumers who wish to deserialize the binary data.
      *
      * <p><strong>Adding serialization hint using {@code getProperties()}</strong></p>
      * <p>In the sample, the type of telemetry is indicated by adding an application property with key "eventType".</p>
@@ -136,8 +136,8 @@ public Map<String, Object> getProperties() {
      * Properties that are populated by Event Hubs service. As these are populated by the Event Hubs service, they are
      * only present on a <b>received</b> {@link EventData}.
      *
-     * @return an encapsulation of all SystemProperties appended by EventHubs service into EventData. {@code null} if
-     * the {@link EventData} is not received and is created by the public constructors.
+     * @return An encapsulation of all system properties appended by EventHubs service into {@link EventData}.
+     *     {@code null} if the {@link EventData} is not received from the Event Hubs service.
      */
     public Map<String, Object> getSystemProperties() {
         return systemProperties;
@@ -152,7 +152,7 @@ public Map<String, Object> getSystemProperties() {
      * wish to deserialize the binary data.
      * </p>
      *
-     * @return ByteBuffer representing the data.
+     * @return A byte array representing the data.
      */
     public byte[] getBody() {
         return Arrays.copyOf(body, body.length);
@@ -168,7 +168,8 @@ public String getBodyAsString() {
     }
 
     /**
-     * Gets the offset of the event when it was received from the associated Event Hub partition.
+     * Gets the offset of the event when it was received from the associated Event Hub partition. This is only present
+     * on a <b>received</b> {@link EventData}.
      *
      * @return The offset within the Event Hub partition of the received event. {@code null} if the {@link EventData}
      *     was not received from Event Hubs service.
@@ -178,8 +179,9 @@ public Long getOffset() {
     }
 
     /**
-     * Gets a partition key used for message partitioning. If it exists, this value was used to compute a hash to select
-     * a partition to send the message to.
+     * Gets the partition hashing key if it was set when originally publishing the event. If it exists, this value was
+     * used to compute a hash to select a partition to send the message to. This is only present on a <b>received</b>
+     * {@link EventData}.
      *
      * @return A partition key for this Event Data. {@code null} if the {@link EventData} was not received from Event
      *     Hubs service or there was no partition key set when the event was sent to the Event Hub.
@@ -189,7 +191,8 @@ public String getPartitionKey() {
     }
 
     /**
-     * Gets the instant, in UTC, of when the event was enqueued in the Event Hub partition.
+     * Gets the instant, in UTC, of when the event was enqueued in the Event Hub partition. This is only present on a
+     * <b>received</b> {@link EventData}.
      *
      * @return The instant, in UTC, this was enqueued in the Event Hub partition. {@code null} if the {@link EventData}
      *     was not received from Event Hubs service.
@@ -200,7 +203,8 @@ public Instant getEnqueuedTime() {
 
     /**
      * Gets the sequence number assigned to the event when it was enqueued in the associated Event Hub partition. This
-     * is unique for every message received in the Event Hub partition.
+     * is unique for every message received in the Event Hub partition. This is only present on a <b>received</b>
+     * {@link EventData}.
      *
      * @return The sequence number for this event. {@code null} if the {@link EventData} was not received from Event
      *     Hubs service.

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

@@ -73,16 +73,18 @@
  * <p>In the sample, the namespace connection string is used to create a synchronous Event Hub consumer. Notice that
  * {@code "EntityPath"} <b>is</b> in the connection string.</p>
  *
- * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.instantiation}
+ * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerclient.instantiation}
  *
  * <p><strong>Creating producers and consumers that share the same connection</strong></p>
  * <p>By default, a dedicated connection is created for each producer and consumer created from the builder. If users
  * wish to use the same underlying connection, they can toggle {@link #shareConnection() shareConnection()}.</p>
  *
  * {@codesnippet com.azure.messaging.eventhubs.eventhubclientbuilder.instantiation}
  *
- * @see EventHubClient
- * @see EventHubAsyncClient
+ * @see EventHubProducerAsyncClient
+ * @see EventHubProducerClient
+ * @see EventHubConsumerAsyncClient
+ * @see EventHubConsumerClient
  */
 @ServiceClientBuilder(serviceClients = {EventHubProducerAsyncClient.class, EventHubProducerClient.class,
     EventHubConsumerAsyncClient.class, EventHubConsumerClient.class})

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

@@ -12,7 +12,6 @@
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.messaging.eventhubs.implementation.EventHubManagementNode;
 import com.azure.messaging.eventhubs.models.EventPosition;
-import com.azure.messaging.eventhubs.models.PartitionContext;
 import com.azure.messaging.eventhubs.models.PartitionEvent;
 import com.azure.messaging.eventhubs.models.ReceiveOptions;
 import reactor.core.publisher.BaseSubscriber;
@@ -33,21 +32,21 @@
  * or all partitions in the context of a specific consumer group.
  *
  * <p><strong>Creating an {@link EventHubConsumerAsyncClient}</strong></p>
- * <p>Required parameters are {@code consumerGroup}, and credentials are required when
- * creating a consumer.</p> {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.instantiation}
+ * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.instantiation}
  *
  * <p><strong>Consuming events a single partition from Event Hub</strong></p>
  * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.receive#string-eventposition}
  *
- * <p><strong>Rate limiting consumption of events from Event Hub</strong></p>
- * <p>For event consumers that need to limit the number of events they receive at a given time, they can use {@link
- * BaseSubscriber#request(long)}.</p> {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.receive#string-eventposition-basesubscriber}
- *
  * <p><strong>Viewing latest partition information</strong></p>
  * <p>Latest partition information as events are received can by setting
- * {@link ReceiveOptions#setTrackLastEnqueuedEventProperties(boolean) setTrackLastEnqueuedEventProperties} to {@code
- * true}. As events come in, explore the {@link PartitionContext} object. {@codesnippet
- * com.azure.messaging.eventhubs.eventhubconsumerasyncclient.receive#boolean-receiveoptions}
+ * {@link ReceiveOptions#setTrackLastEnqueuedEventProperties(boolean) setTrackLastEnqueuedEventProperties} to
+ * {@code true}. As events come in, explore the {@link PartitionEvent} object.
+ * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.receiveFromPartition#string-eventposition-receiveoptions}
+ *
+ * <p><strong>Rate limiting consumption of events from Event Hub</strong></p>
+ * <p>For event consumers that need to limit the number of events they receive at a given time, they can use
+ * {@link BaseSubscriber#request(long)}.</p>
+ * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.receive#string-eventposition-basesubscriber}
  *
  * <p><strong>Receiving from all partitions</strong></p>
  * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerasyncclient.receive#boolean}
@@ -138,6 +137,8 @@ public Flux<String> getPartitionIds() {
      * @param partitionId The unique identifier of a partition associated with the Event Hub.
      *
      * @return The set of information for the requested partition under the Event Hub this client is associated with.
+     *
+     * @throws NullPointerException if {@code partitionId} is null.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<PartitionProperties> getPartitionProperties(String partitionId) {
@@ -171,10 +172,10 @@ public Flux<PartitionEvent> receiveFromPartition(String partitionId, EventPositi
      *
      * <ul>
      * <li>If receive is invoked where {@link ReceiveOptions#getOwnerLevel()} has a value, then Event Hubs service will
-     * guarantee only one active consumer exists per partitionId and consumer group combination. This consumer is
-     * sometimes referred to as an "Epoch Consumer."</li>
+     * guarantee only one active consumer exists per partitionId and consumer group combination. This receive operation
+     * is sometimes referred to as an "Epoch Consumer".</li>
      * <li>Multiple consumers per partitionId and consumer group combination can be created by not setting
-     * {@link ReceiveOptions#getOwnerLevel()} when creating consumers. This non-exclusive consumer is sometimes
+     * {@link ReceiveOptions#getOwnerLevel()} when invoking receive operations. This non-exclusive consumer is sometimes
      * referred to as a "Non-Epoch Consumer."</li>
      * </ul>
      *
@@ -208,17 +209,16 @@ public Flux<PartitionEvent> receiveFromPartition(String partitionId, EventPositi
     /**
      * Consumes events from all partitions starting from the beginning of each partition.
      *
-     * <p>
-     * This method is not recommended for production use; the {@link EventProcessorClient} should be used for reading
-     * events from all partitions in a production scenario, as it offers a much more robust experience with higher
-     * throughput.
+     * <p>This method is <b>not</b> recommended for production use; the {@link EventProcessorClient} should be used for
+     * reading events from all partitions in a production scenario, as it offers a much more robust experience with
+     * higher throughput.
      *
      * It is important to note that this method does not guarantee fairness amongst the partitions. Depending on service
      * communication, there may be a clustering of events per partition and/or there may be a noticeable bias for a
-     * given partition or subset of partitions.
-     * </p>
+     * given partition or subset of partitions.</p>
+     *
      *
-     * @return A stream of events for every partition in the Event Hub starting from {@code startingPosition}.
+     * @return A stream of events for every partition in the Event Hub starting from the beginning of each partition.
      */
     public Flux<PartitionEvent> receive() {
         return receive(true, defaultReceiveOptions);
@@ -227,15 +227,13 @@ public Flux<PartitionEvent> receive() {
     /**
      * Consumes events from all partitions.
      *
-     * <p>
-     * This method is not recommended for production use; the {@link EventProcessorClient} should be used for reading
-     * events from all partitions in a production scenario, as it offers a much more robust experience with higher
-     * throughput.
+     * <p>This method is <b>not</b> recommended for production use; the {@link EventProcessorClient} should be used for
+     * reading events from all partitions in a production scenario, as it offers a much more robust experience with
+     * higher throughput.
      *
      * It is important to note that this method does not guarantee fairness amongst the partitions. Depending on service
      * communication, there may be a clustering of events per partition and/or there may be a noticeable bias for a
-     * given partition or subset of partitions.
-     * </p>
+     * given partition or subset of partitions.</p>
      *
      * @param startReadingAtEarliestEvent {@code true} to begin reading at the first events available in each
      *     partition; otherwise, reading will begin at the end of each partition seeing only new events as they are
@@ -248,17 +246,24 @@ public Flux<PartitionEvent> receive(boolean startReadingAtEarliestEvent) {
     }
 
     /**
-     * Consumes events from all partitions.
+     * Consumes events from all partitions configured with a set of {@code receiveOptions}.
      *
-     * <p>
-     * This method is not recommended for production use; the {@link EventProcessorClient} should be used for reading
-     * events from all partitions in a production scenario, as it offers a much more robust experience with higher
-     * throughput.
+     * <p>This method is <b>not</b> recommended for production use; the {@link EventProcessorClient} should be used for
+     * reading events from all partitions in a production scenario, as it offers a much more robust experience with
+     * higher throughput.
      *
      * It is important to note that this method does not guarantee fairness amongst the partitions. Depending on service
      * communication, there may be a clustering of events per partition and/or there may be a noticeable bias for a
-     * given partition or subset of partitions.
-     * </p>
+     * given partition or subset of partitions.</p>
+     *
+     * <ul>
+     * <li>If receive is invoked where {@link ReceiveOptions#getOwnerLevel()} has a value, then Event Hubs service will
+     * guarantee only one active consumer exists per partitionId and consumer group combination. This receive operation
+     * is sometimes referred to as an "Epoch Consumer".</li>
+     * <li>Multiple consumers per partitionId and consumer group combination can be created by not setting
+     * {@link ReceiveOptions#getOwnerLevel()} when invoking receive operations. This non-exclusive consumer is sometimes
+     * referred to as a "Non-Epoch Consumer."</li>
+     * </ul>
      *
      * @param startReadingAtEarliestEvent {@code true} to begin reading at the first events available in each
      *     partition; otherwise, reading will begin at the end of each partition seeing only new events as they are

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

@@ -26,7 +26,6 @@
  * a specific consumer group.
  *
  * <p><strong>Creating a synchronous consumer</strong></p>
- * <p>Required parameters are {@code consumerGroup} and credentials when creating a consumer.</p>
  * {@codesnippet com.azure.messaging.eventhubs.eventhubconsumerclient.instantiation}
  *
  * <p><strong>Consuming events from a single partition</strong></p>
@@ -56,7 +55,7 @@ public class EventHubConsumerClient implements Closeable {
      * Gets the fully qualified Event Hubs namespace that the connection is associated with. This is likely similar to
      * {@code {yournamespace}.servicebus.windows.net}.
      *
-     * @return The fully qualified Event Hubs namespace that the connection is associated with
+     * @return The fully qualified Event Hubs namespace that the connection is associated with.
      */
     public String getFullyQualifiedNamespace() {
         return consumer.getFullyQualifiedNamespace();
@@ -93,7 +92,7 @@ public EventHubProperties getEventHubProperties() {
     /**
      * Retrieves the identifiers for the partitions of an Event Hub.
      *
-     * @return A Flux of identifiers for the partitions of an Event Hub.
+     * @return The set of identifiers for the partitions of an Event Hub.
      */
     public IterableStream<String> getPartitionIds() {
         return new IterableStream<>(consumer.getPartitionIds());
@@ -106,6 +105,8 @@ public IterableStream<String> getPartitionIds() {
      * @param partitionId The unique identifier of a partition associated with the Event Hub.
      *
      * @return The set of information for the requested partition under the Event Hub this client is associated with.
+     *
+     * @throws NullPointerException if {@code partitionId} is null.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public PartitionProperties getPartitionProperties(String partitionId) {
@@ -123,7 +124,9 @@ public PartitionProperties getPartitionProperties(String partitionId) {
      *     {@code maximumMessageCount} events. If a stream for the events was opened before, the same position within
      *     that partition is returned. Otherwise, events are read starting from {@code startingPosition}.
      *
-     * @throws IllegalArgumentException if {@code maximumMessageCount} is less than 1.
+     * @throws NullPointerException if {@code partitionId}, or {@code startingPosition} is null.
+     * @throws IllegalArgumentException if {@code maximumMessageCount} is less than 1, or if {@code partitionId} is an
+     *     empty string.
      */
     public IterableStream<PartitionEvent> receiveFromPartition(String partitionId, int maximumMessageCount,
         EventPosition startingPosition) {
@@ -142,7 +145,8 @@ public IterableStream<PartitionEvent> receiveFromPartition(String partitionId, i
      * @return A set of {@link PartitionEvent} that was received. The iterable contains up to
      *     {@code maximumMessageCount} events.
      *
-     * @throws NullPointerException if {@code maximumWaitTime} or {@code eventPosition} is null.
+     * @throws NullPointerException if {@code partitionId}, {@code maximumWaitTime}, or {@code startingPosition} is
+     *     {@code null}.
      * @throws IllegalArgumentException if {@code maximumMessageCount} is less than 1 or {@code maximumWaitTime} is
      *     zero or a negative duration.
      */
@@ -188,7 +192,7 @@ public IterableStream<PartitionEvent> receiveFromPartition(String partitionId, i
      * @return A set of {@link PartitionEvent} that was received. The iterable contains up to
      *     {@code maximumMessageCount} events.
      *
-     * @throws NullPointerException if {@code maximumWaitTime}, {@code eventPosition}, {@code partitionId}, or
+     * @throws NullPointerException if {@code maximumWaitTime}, {@code startingPosition}, {@code partitionId}, or
      *     {@code receiveOptions} is {@code null}.
      * @throws IllegalArgumentException if {@code maximumMessageCount} is less than 1 or {@code maximumWaitTime} is
      *     zero or a negative duration.