Add Javadoc for SubscriptionListener

References #38

Author: acogoluegnes

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

@@ -64,6 +64,15 @@ public interface ConsumerBuilder {
    */
   ConsumerBuilder name(String name);
 
+  /**
+   * Callback on subscription.
+   *
+   * <p>Can be used to set the offset specification before subscribing to the stream.
+   *
+   * @see SubscriptionListener
+   * @param subscriptionListener the listener
+   * @return this builder instance
+   */
   ConsumerBuilder subscriptionListener(SubscriptionListener subscriptionListener);
 
   /**

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

@@ -13,14 +13,53 @@
 // [email protected].
 package com.rabbitmq.stream;
 
+/**
+ * Callback interface to customize a subscription.
+ *
+ * <p>It is possible to change the computed {@link OffsetSpecification} in {@link
+ * #preSubscribe(SubscriptionContext)} by using a custom offset tracking strategy.
+ */
 public interface SubscriptionListener {
 
+  /**
+   * Callback called before the subscription is created.
+   *
+   * <p>The method is called when a {@link Consumer} is created and it registers to broker, and also
+   * when the subscription must be re-created (after a disconnection or when the subscription must
+   * moved because the stream member it was connection becomes unavailable).
+   *
+   * <p>Application code can set the {@link OffsetSpecification} that will be used with the {@link
+   * SubscriptionContext#offsetSpecification(OffsetSpecification)} method.
+   *
+   * @param subscriptionContext
+   */
   void preSubscribe(SubscriptionContext subscriptionContext);
 
+  /** Context object for the subscription. */
   interface SubscriptionContext {
 
+    /**
+     * The offset specification computed by the library.
+     *
+     * <p>If the consumer has no name, the value is the value set with {@link
+     * ConsumerBuilder#offset(OffsetSpecification)} on the first subscription and the offset of the
+     * last dispatched message on subsequent calls (e.g. when the client re-subscribes after a
+     * disconnection).
+     *
+     * <p>If the consumer has a name, the value is the last stored if any.
+     *
+     * @see ConsumerBuilder#name(String)
+     * @return the computed offset specification
+     */
     OffsetSpecification offsetSpecification();
 
+    /**
+     * Set the offset specification to use for the subscription.
+     *
+     * <p>It overrides the value computed by the client.
+     *
+     * @param offsetSpecification the offset specification to use
+     */
     void offsetSpecification(OffsetSpecification offsetSpecification);
   }
 }