More Javadoc

Author: acogoluegnes

src/main/java/com/rabbitmq/client/amqp/Address.java

@@ -19,6 +19,7 @@
 
 import java.util.Objects;
 
+/** Utility class to represent a hostname and a port. */
 public class Address {
 
   private final String host;

src/main/java/com/rabbitmq/client/amqp/AddressBuilder.java

@@ -17,11 +17,35 @@
 // info@rabbitmq.com.
 package com.rabbitmq.client.amqp;
 
+/**
+ * Builder for a <a href="https://www.rabbitmq.com/docs/next/amqp#address-v2">AMQP target address
+ * format v2.</a>
+ *
+ * @param <T> the type of object returned by methods, usually the object itself
+ */
 public interface AddressBuilder<T> {
 
+  /**
+   * Set the exchange.
+   *
+   * @param exchange exchange
+   * @return type-parameter object
+   */
   T exchange(String exchange);
 
+  /**
+   * Set the routing key.
+   *
+   * @param key routing key
+   * @return type-parameter object
+   */
   T key(String key);
 
+  /**
+   * Set the queue.
+   *
+   * @param queue queue
+   * @return type-parameter object
+   */
   T queue(String queue);
 }

src/main/java/com/rabbitmq/client/amqp/AmqpException.java

@@ -17,6 +17,7 @@
 // info@rabbitmq.com.
 package com.rabbitmq.client.amqp;
 
+/** Exception classes. */
 public class AmqpException extends RuntimeException {
 
   public AmqpException(Throwable cause) {
@@ -38,6 +39,7 @@ public AmqpConnectionException(String message, Throwable cause) {
     }
   }
 
+  /** Exception related to security (authentication, permission, etc). */
   public static class AmqpSecurityException extends AmqpException {
 
     public AmqpSecurityException(String message, Throwable cause) {
@@ -60,6 +62,11 @@ public AmqpEntityDoesNotExistException(String message) {
     }
   }
 
+  /**
+   * Exception when a resource is not in an appropriate state.
+   *
+   * <p>An example is a connection that is initializing.
+   */
   public static class AmqpResourceInvalidStateException extends AmqpException {
 
     public AmqpResourceInvalidStateException(String format, Object... args) {
@@ -71,6 +78,7 @@ public AmqpResourceInvalidStateException(String message, Throwable cause) {
     }
   }
 
+  /** Exception when a resource is not usable because it is closed. */
   public static class AmqpResourceClosedException extends AmqpResourceInvalidStateException {
 
     public AmqpResourceClosedException(String message) {

src/main/java/com/rabbitmq/client/amqp/BackOffDelayPolicy.java

@@ -19,25 +19,59 @@
 
 import java.time.Duration;
 
+/**
+ * Contract to determine a delay between attempts of some task.
+ *
+ * <p>The task is typically the creation of a connection.
+ */
 public interface BackOffDelayPolicy {
 
   Duration TIMEOUT = Duration.ofMillis(Long.MAX_VALUE);
 
+  /**
+   * Returns the delay to use for a given attempt.
+   *
+   * <p>The policy can return the TIMEOUT constant to indicate that the task has reached a timeout.
+   *
+   * @param recoveryAttempt number of the recovery attempt
+   * @return the delay, TIMEOUT if the task should stop being retried
+   */
   Duration delay(int recoveryAttempt);
 
+  /**
+   * Policy with a fixed delay.
+   *
+   * @param delay the fixed delay
+   * @return fixed-delay policy
+   */
+  static BackOffDelayPolicy fixed(Duration delay) {
+    return new FixedWithInitialDelayBackOffPolicy(delay, delay);
+  }
+
+  /**
+   * Policy with an initial delay for the first attempt, then a fixed delay.
+   *
+   * @param initialDelay delay for the first attempt
+   * @param delay delay for other attempts than the first one
+   * @return fixed-delay policy with initial delay
+   */
   static BackOffDelayPolicy fixedWithInitialDelay(Duration initialDelay, Duration delay) {
     return new FixedWithInitialDelayBackOffPolicy(initialDelay, delay);
   }
 
+  /**
+   * Policy with an initial delay for the first attempt, then a fixed delay, and a timeout.
+   *
+   * @param initialDelay delay for the first attempt
+   * @param delay delay for other attempts than the first one
+   * @param timeout timeout
+   * @return fixed-delay policy with initial delay and timeout
+   */
   static BackOffDelayPolicy fixedWithInitialDelay(
       Duration initialDelay, Duration delay, Duration timeout) {
     return new FixedWithInitialDelayAndTimeoutBackOffPolicy(initialDelay, delay, timeout);
   }
 
-  static BackOffDelayPolicy fixed(Duration delay) {
-    return new FixedWithInitialDelayBackOffPolicy(delay, delay);
-  }
-
   final class FixedWithInitialDelayBackOffPolicy implements BackOffDelayPolicy {
 
     private final Duration initialDelay;

src/main/java/com/rabbitmq/client/amqp/ConnectionSettings.java

@@ -128,6 +128,9 @@ public interface ConnectionSettings<T> {
   /**
    * SASL mechanism to use.
    *
+   * <p>Supported mechanisms are {@link #SASL_MECHANISM_ANONYMOUS}, {@link #SASL_MECHANISM_PLAIN},
+   * and {@link #SASL_MECHANISM_EXTERNAL}.
+   *
    * @param mechanism SASL mechanism
    * @return type-parameter object
    * @see <a href="https://www.rabbitmq.com/docs/access-control#mechanisms">RabbitMQ Authentication
@@ -225,9 +228,9 @@ interface Affinity<T> {
     /**
      * The type of operation to look affinity with.
      *
-     * <p>PUBLISH will favor the node with the queue leader on it.
+     * <p>{@link Operation#PUBLISH} will favor the node with the queue leader on it.
      *
-     * <p>CONSUME will favor a node with a queue member (replica) on it.
+     * <p>{@link Operation#CONSUME} will favor a node with a queue member (replica) on it.
      *
      * @param operation type of operation
      * @return affinity settings

src/main/java/com/rabbitmq/client/amqp/Consumer.java

@@ -17,29 +17,70 @@
 // info@rabbitmq.com.
 package com.rabbitmq.client.amqp;
 
+/**
+ * API to consume messages from a RabbitMQ queue.
+ *
+ * <p>Instances are configured and created with a {@link ConsumerBuilder}.
+ *
+ * @see Connection#consumerBuilder()
+ * @see ConsumerBuilder
+ */
 public interface Consumer extends AutoCloseable {
 
+  /** Pause the consumer to stop receiving messages. */
   void pause();
 
+  /**
+   * Return the number of unsettled messages.
+   *
+   * @return unsettled message count
+   */
   long unsettledMessageCount();
 
+  /** Request to receive messages again. */
   void unpause();
 
+  /** Close the consumer with its resources. */
   @Override
   void close();
 
+  /** Contract to process a message. */
   @FunctionalInterface
   interface MessageHandler {
 
+    /**
+     * Process a message
+     *
+     * @param context message context
+     * @param message message
+     */
     void handle(Context context, Message message);
   }
 
+  /** Context for message processing. */
   interface Context {
 
+    /**
+     * Accept the message (AMQP 1.0 <code>accepted</code> outcome).
+     *
+     * <p>This means the message has been processed and the broker can delete it.
+     */
     void accept();
 
+    /**
+     * Discard the message (AMQP 1.0 <code>rejected</code> outcome).
+     *
+     * <p>This means the message cannot be processed because it is invalid, the broker can drop it
+     * or dead-letter it if it is configured.
+     */
     void discard();
 
+    /**
+     * Requeue the message (AMQP 1.0 <code>released</code> outcome).
+     *
+     * <p>This means the message has not been processed and the broker can requeue it and deliver it
+     * to the same or a different consumer.
+     */
     void requeue();
   }
 }

src/main/java/com/rabbitmq/client/amqp/impl/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Implementation package.
+ *
+ * <p>Only the {@link com.rabbitmq.client.amqp.impl.AmqpEnvironmentBuilder} is public and should be
+ * used by applications.
+ */
+package com.rabbitmq.client.amqp.impl;

src/main/java/com/rabbitmq/client/amqp/package-info.java

@@ -0,0 +1,2 @@
+/** Main API for the RabbitMQ AMQP 1.0 Java Client. */
+package com.rabbitmq.client.amqp;