Javadocs update 2 (Azure#17826)

* Update documentation for message batch, messages, and processor client. * Adding links to options. * Add transaction code snippets. * Adding sender, receiver, and session client documentation. * Fix docs naming * Update to getSubject -> getLabel * Change to getFirstData()
AzureSDKAutomation · Nov 28, 2020 · 33362b5 · 33362b5
1 parent 276c40e
commit 33362b5
Show file tree

Hide file tree

Showing 21 changed files with 749 additions and 577 deletions.
diff --git a/...-messaging-servicebus/src/main/java/com/azure/messaging/servicebus/ServiceBusMessage.java b/...-messaging-servicebus/src/main/java/com/azure/messaging/servicebus/ServiceBusMessage.java
@@ -15,6 +15,7 @@
 import com.azure.core.util.Context;
 import com.azure.core.util.logging.ClientLogger;
 
+import java.nio.charset.StandardCharsets;
 import java.time.Duration;
 import java.time.OffsetDateTime;
 import java.time.ZoneOffset;
@@ -36,10 +37,12 @@
  * in the <a href="https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads">product
  * documentation</a>.
  *
+ * @see ServiceBusReceivedMessage
  * @see ServiceBusMessageBatch
  * @see ServiceBusSenderAsyncClient#sendMessage(ServiceBusMessage)
  * @see ServiceBusSenderClient#sendMessage(ServiceBusMessage)
- * @see BinaryData
+ * @see <a href="https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads">Service Bus
+ *      message payloads</a>
  * @see <a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-complete-v1.0-os.pdf">AMQP 1.0 specification
  *     </a>
  */
@@ -65,9 +68,9 @@ public ServiceBusMessage(byte[] body) {
     }
 
     /**
-     * Creates a {@link ServiceBusMessage} with a {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8} encoded body.
+     * Creates a {@link ServiceBusMessage} with a {@link StandardCharsets#UTF_8 UTF-8} encoded body.
      *
-     * @param body The content of the Service bus message.
+     * @param body The content of the Service Bus message.
      *
      * @throws NullPointerException if {@code body} is null.
      */
@@ -200,15 +203,6 @@ public ServiceBusMessage(ServiceBusReceivedMessage receivedMessage) {
         this.context = Context.NONE;
     }
 
-    /**
-     * Gets the {@link AmqpAnnotatedMessage}.
-     *
-     * @return The raw AMQP message.
-     */
-    public AmqpAnnotatedMessage getRawAmqpMessage() {
-        return amqpAnnotatedMessage;
-    }
-
     /**
      * Gets the set of free-form {@link ServiceBusMessage} properties which may be used for passing metadata associated
      * with the {@link ServiceBusMessage} during Service Bus operations. A common use-case for {@code
@@ -222,17 +216,16 @@ public Map<String, Object> getApplicationProperties() {
     }
 
     /**
-     * Gets the actual payload/data wrapped by the {@link ServiceBusMessage}.
+     * Gets the actual payload wrapped by the {@link ServiceBusMessage}.
      *
      * <p>The {@link BinaryData} wraps byte array and is an abstraction over many different ways it can be represented.
-     * It provides many convenience API including APIs to serialize/deserialize object.
-     * <p>
-     * If the means for deserializing the raw data is not apparent to consumers, a common technique is to make use of
-     * {@link #getApplicationProperties()} when creating the event, to associate serialization hints as an aid to
-     * consumers who wish to deserialize the binary data.
-     * </p>
+     * It provides convenience APIs to serialize/deserialize the object.</p>
+     *
+     * <p>If the means for deserializing the raw data is not apparent to consumers, a common technique is to make use
+     * of {@link #getApplicationProperties()} when creating the event, to associate serialization hints as an aid to
+     * consumers who wish to deserialize the binary data.</p>
      *
-     * @return A byte array representing the data.
+     * @return Binary data representing the payload.
      */
     public BinaryData getBody() {
         final AmqpMessageBodyType type = amqpAnnotatedMessage.getBody().getBodyType();
@@ -252,6 +245,10 @@ public BinaryData getBody() {
     /**
      * Gets the content type of the message.
      *
+     * <p>
+     * Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5,
+     * for example "application/json".
+     * </p>
      * @return The content type of the {@link ServiceBusMessage}.
      */
     public String getContentType() {
@@ -282,7 +279,7 @@ public ServiceBusMessage setContentType(String contentType) {
      * reflecting the MessageId of a message that is being replied to.
      * </p>
      *
-     * @return correlation id of this message
+     * @return The correlation id of this message.
      * @see <a href="https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation">Message
      *     Routing and Correlation</a>
      */
@@ -346,8 +343,7 @@ public ServiceBusMessage setSubject(String subject) {
      * identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If
      * enabled, the
      * <a href="https://docs.microsoft.com/azure/service-bus-messaging/duplicate-detection">duplicate detection</a>
-     * feature identifies and removes second and further submissions of messages with the same {@link #getMessageId()
-     * message id}.
+     * feature identifies and removes second and further submissions of messages with the same {@code messageId}.
      * </p>
      *
      * @return Id of the {@link ServiceBusMessage}.
@@ -415,6 +411,15 @@ public ServiceBusMessage setPartitionKey(String partitionKey) {
         return this;
     }
 
+    /**
+     * Gets the {@link AmqpAnnotatedMessage}.
+     *
+     * @return The raw AMQP message.
+     */
+    public AmqpAnnotatedMessage getRawAmqpMessage() {
+        return amqpAnnotatedMessage;
+    }
+
     /**
      * Gets the address of an entity to send replies to.
      * <p>

diff --git a/...aging-servicebus/src/main/java/com/azure/messaging/servicebus/ServiceBusMessageBatch.java b/...aging-servicebus/src/main/java/com/azure/messaging/servicebus/ServiceBusMessageBatch.java
@@ -49,27 +49,27 @@ public final class ServiceBusMessageBatch {
     }
 
     /**
-     * Gets the number of {@link ServiceBusMessage events} in the batch.
+     * Gets the number of {@link ServiceBusMessage messages} in the batch.
      *
-     * @return The number of {@link ServiceBusMessage events} in the batch.
+     * @return The number of {@link ServiceBusMessage messages} in the batch.
      */
     public int getCount() {
         return serviceBusMessageList.size();
     }
 
     /**
-     * Gets the maximum size, in bytes, of the {@link ServiceBusMessageBatch}.
+     * Gets the maximum size, in bytes, of the {@link ServiceBusMessageBatch batch}.
      *
-     * @return The maximum size, in bytes, of the {@link ServiceBusMessageBatch}.
+     * @return The maximum size, in bytes, of the {@link ServiceBusMessageBatch batch}.
      */
     public int getMaxSizeInBytes() {
         return maxMessageSize;
     }
 
     /**
-     * Gets the size of the {@link ServiceBusMessageBatch} in bytes.
+     * Gets the size of the {@link ServiceBusMessageBatch batch} in bytes.
      *
-     * @return the size of the {@link ServiceBusMessageBatch} in bytes.
+     * @return The size of the {@link ServiceBusMessageBatch batch} in bytes.
      */
     public int getSizeInBytes() {
         return this.sizeInBytes;

diff --git a/...ng-servicebus/src/main/java/com/azure/messaging/servicebus/ServiceBusProcessorClient.java b/...ng-servicebus/src/main/java/com/azure/messaging/servicebus/ServiceBusProcessorClient.java
@@ -7,6 +7,8 @@
 import com.azure.core.util.Context;
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.core.util.tracing.ProcessKind;
+import com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusProcessorClientBuilder;
+import com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder;
 import com.azure.messaging.servicebus.implementation.models.ServiceBusProcessorClientOptions;
 import org.reactivestreams.Subscriber;
 import org.reactivestreams.Subscription;
@@ -36,19 +38,19 @@
 import static com.azure.messaging.servicebus.implementation.ServiceBusConstants.AZ_TRACING_SERVICE_NAME;
 
 /**
- *  The processor client for processing Service Bus messages. {@link ServiceBusProcessorClient
- *  ServiceBusProcessorClients} provides a push-based mechanism that invokes the message processing callback when a
- *  message is received or the error handler when an error occurs when receiving messages. A
- *  {@link ServiceBusProcessorClient} can be created to process messages for a session-enabled Service Bus entity or
- *  a non session-enabled Service Bus entity.
+ * The processor client for processing Service Bus messages. {@link ServiceBusProcessorClient} provides a push-based
+ * mechanism that invokes the message processing callback when a message is received or the error handler when an error
+ * occurs when receiving messages. A {@link ServiceBusProcessorClient} can be created to process messages for a
+ * session-enabled or non session-enabled Service Bus entity. It supports auto-settlement of messages by default.
  *
  * <p><strong>Create and run a processor</strong></p>
  * {@codesnippet com.azure.messaging.servicebus.servicebusprocessorclient#instantiation}
  *
  * <p><strong>Create and run a session-enabled processor</strong></p>
  * {@codesnippet com.azure.messaging.servicebus.servicebusprocessorclient#session-instantiation}
  *
- * @see ServiceBusClientBuilder
+ * @see ServiceBusProcessorClientBuilder
+ * @see ServiceBusSessionProcessorClientBuilder
  */
 public final class ServiceBusProcessorClient implements AutoCloseable {
 
@@ -109,11 +111,15 @@ public final class ServiceBusProcessorClient implements AutoCloseable {
 
     /**
      * Starts the processor in the background. When this method is called, the processor will initiate a message
-     * receiver that will invoke the message handler when new messages are available. This method is idempotent i.e
-     * calling {@link #start()} again after the processor is already running is a no-op. Calling {@link #start()}
-     * after calling {@link #stop()} will resume processing messages using the same underlying links or active
-     * sessions. Calling {@link #start()} after calling {@link #close()} will start the processor with new links and
-     * a new set of sessions will be processed.
+     * receiver that will invoke the message handler when new messages are available. This method is idempotent (ie.
+     * calling {@code start()} again after the processor is already running is a no-op).
+     * <p>
+     * Calling {@code start()} after calling {@link #stop() stop()} will resume processing messages using the same
+     * underlying connection.
+     * </p>
+     * <p>
+     * Calling {@code start()} after calling {@link #close() close()} will start the processor with a new connection.
+     * </p>
      */
     public synchronized void start() {
         if (isRunning.getAndSet(true)) {
@@ -174,7 +180,7 @@ public synchronized void close() {
      * Returns {@code true} if the processor is running. If the processor is stopped or closed, this method returns
      * {@code false}.
      *
-     * @return {@code true} if the processor is running.
+     * @return {@code true} if the processor is running; {@code false} otherwise.
      */
     public synchronized boolean isRunning() {
         return isRunning.get();
@@ -208,7 +214,7 @@ public void onNext(ServiceBusMessageContext serviceBusMessageContext) {
 
                             processSpanContext =
                                 startProcessTracingSpan(serviceBusMessageContext.getMessage(),
-                                receiverClient.getEntityPath(), receiverClient.getFullyQualifiedNamespace());
+                                    receiverClient.getEntityPath(), receiverClient.getFullyQualifiedNamespace());
                             if (processSpanContext.getData(SPAN_CONTEXT_KEY).isPresent()) {
                                 serviceBusMessageContext.getMessage().addContext(SPAN_CONTEXT_KEY, processSpanContext);
                             }
@@ -275,7 +281,7 @@ private void endProcessTracingSpan(Context processSpanContext, Signal<Void> sign
     }
 
     private Context startProcessTracingSpan(ServiceBusReceivedMessage receivedMessage, String entityPath,
-                                            String fullyQualifiedNamespace) {
+        String fullyQualifiedNamespace) {
 
         Object diagnosticId = receivedMessage.getApplicationProperties().get(DIAGNOSTIC_ID_KEY);
         if (diagnosticId == null || !tracerProvider.isEnabled()) {
@@ -297,7 +303,7 @@ private Context startProcessTracingSpan(ServiceBusReceivedMessage receivedMessag
     }
 
     private void abandonMessage(ServiceBusMessageContext serviceBusMessageContext,
-                                ServiceBusReceiverAsyncClient receiverClient) {
+        ServiceBusReceiverAsyncClient receiverClient) {
         try {
             receiverClient.abandon(serviceBusMessageContext.getMessage()).block();
         } catch (Exception exception) {