Add Javadoc for single active consumer API

References #46

Author: acogoluegnes

src/main/java/com/rabbitmq/stream/Consumer.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2020-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").
@@ -34,5 +34,11 @@ public interface Consumer extends AutoCloseable {
   @Override
   void close();
 
+  /**
+   * The stored offset for this named consumer on the configured stream.
+   *
+   * @return stored offset
+   * @since 0.6.0
+   */
   long storedOffset();
 }

src/main/java/com/rabbitmq/stream/ConsumerBuilder.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2020-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").
@@ -29,10 +29,15 @@ public interface ConsumerBuilder {
   /**
    * Set the consumer to consume from a super stream (partitioned stream).
    *
+   * <p>This is meant to be used with {@link #singleActiveConsumer()}.
+   *
    * <p>This is an experimental API, subject to change.
    *
+   * <p>RabbitMQ 3.11 or more is required.
+   *
    * @param superStream
    * @return this builder instance
+   * @see #singleActiveConsumer()
    */
   ConsumerBuilder superStream(String superStream);
 
@@ -64,8 +69,45 @@ public interface ConsumerBuilder {
    */
   ConsumerBuilder name(String name);
 
+  /**
+   * Declare the consumer as a single active consumer.
+   *
+   * <p>A single active consumer must set up a name with {@link #name(String)}.
+   *
+   * <p>Instances of the same application can declare several single active consumer instances with
+   * the same name and only one will be active at a time, meaning it will be the only one to get
+   * messages from the broker.
+   *
+   * <p>If the active consumer instance stops or crashes, the broker will choose a new active
+   * instance among the remaining ones.
+   *
+   * <p>This is an experimental API, subject to change.
+   *
+   * <p>RabbitMQ 3.11 or more is required.
+   *
+   * @return this builder instance
+   * @since 0.6.0
+   * @see #name(String)
+   */
   ConsumerBuilder singleActiveConsumer();
 
+  /**
+   * Set the listener for single active consumer updates.
+   *
+   * <p>This listener is usually set when manual offset tracking is used, either server-side or with
+   * an external datastore.
+   *
+   * <p>This is an experimental API, subject to change.
+   *
+   * <p>RabbitMQ 3.11 or more is required.
+   *
+   * @param consumerUpdateListener
+   * @return this builder instance
+   * @since 0.6.0
+   * @see #singleActiveConsumer()
+   * @see ConsumerUpdateListener
+   * @see #manualTrackingStrategy()
+   */
   ConsumerBuilder consumerUpdateListener(ConsumerUpdateListener consumerUpdateListener);
 
   /**
@@ -78,6 +120,7 @@ public interface ConsumerBuilder {
    * @see SubscriptionListener
    * @param subscriptionListener the listener
    * @return this builder instance
+   * @since 0.5.0
    */
   ConsumerBuilder subscriptionListener(SubscriptionListener subscriptionListener);
 

src/main/java/com/rabbitmq/stream/ConsumerUpdateListener.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2021-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").
@@ -13,18 +13,60 @@
 // [email protected].
 package com.rabbitmq.stream;
 
+/**
+ * An interface for reacting to status changes of single active consumers.
+ *
+ * <p>An application uses the {@link #update(Context)} callback to compute the offset to start
+ * consuming from when the consumer becomes active.
+ *
+ * <p>The application can also use the {@link #update(Context)} callback to store the offset of the
+ * last message it processed when the consumer goes from active to passive.
+ *
+ * <p>This is especially useful when using manual server-side offset tracking or offset tracking
+ * from an external datastore.
+ *
+ * @see ConsumerBuilder#singleActiveConsumer()
+ * @see ConsumerBuilder#manualTrackingStrategy()
+ */
 public interface ConsumerUpdateListener {
 
+  /**
+   * Callback when the consumer status change.
+   *
+   * @param context information on the status change
+   * @return the offset specification to consume from if the status is active
+   */
   OffsetSpecification update(Context context);
 
+  /** Information on the status change. */
   interface Context {
 
+    /**
+     * The consumer instance.
+     *
+     * @return
+     */
     Consumer consumer();
 
+    /**
+     * The stream (partition in a super stream) involved.
+     *
+     * @return
+     */
     String stream();
 
+    /**
+     * The new status of the consumer.
+     *
+     * @return
+     */
     Status status();
 
+    /**
+     * The previous status of the consumer.
+     *
+     * @return
+     */
     Status previousStatus();
   }
 

src/main/java/com/rabbitmq/stream/OffsetSpecification.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2020-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/main/java/com/rabbitmq/stream/SubscriptionListener.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2021-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/main/java/com/rabbitmq/stream/impl/AsyncRetry.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2020-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/main/java/com/rabbitmq/stream/impl/StreamConsumerBuilder.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2020-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/test/java/com/rabbitmq/stream/impl/AlarmsTest.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2021-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/test/java/com/rabbitmq/stream/impl/SacStreamConsumerTest.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2021-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/test/java/com/rabbitmq/stream/impl/SacSuperStreamConsumerTest.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2021-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").

src/test/java/com/rabbitmq/stream/impl/SuperStreamConsumerTest.java

@@ -1,4 +1,4 @@
-// Copyright (c) 2021 VMware, Inc. or its affiliates.  All rights reserved.
+// Copyright (c) 2021-2022 VMware, Inc. or its affiliates.  All rights reserved.
 //
 // This software, the RabbitMQ Stream Java client library, is dual-licensed under the
 // Mozilla Public License 2.0 ("MPL"), and the Apache License version 2 ("ASL").