Added javadoc to publisher interfaces

Author: bbakerman

src/main/java/org/dataloader/BatchPublisher.java

@@ -7,16 +7,30 @@
 /**
  * A function that is invoked for batch loading a stream of data values indicated by the provided list of keys.
  * <p>
- * The function will call the provided {@link Subscriber} to process the values it has retrieved to allow
+ * The function <b>must</b> call the provided {@link Subscriber} to process the values it has retrieved to allow
  * the future returned by {@link DataLoader#load(Object)} to complete as soon as the individual value is available
  * (rather than when all values have been retrieved).
  * <p>
- * <b>NOTE:</b> It is <b>required </b> that {@link Subscriber#onNext(Object)} is invoked on each value in the same order as
- * the provided keys.
+ * <b>NOTE:</b> It is <b>required</b> that {@link Subscriber#onNext(Object)} is invoked on each value in the same order as
+ * the provided keys and that you provide a value for every key provided.
  *
  * @param <K> type parameter indicating the type of keys to use for data load requests.
  * @param <V> type parameter indicating the type of values returned
+ * @see BatchLoader for the non-reactive version
  */
 public interface BatchPublisher<K, V> {
+    /**
+     * Called to batch the provided keys into a stream of values.  You <b>must</b> provide
+     * the same number of values as there as keys, and they <b>must</b> be in the order of the keys.
+     * <p>
+     * The idiomatic approach would be to create a reactive {@link org.reactivestreams.Publisher} that provides
+     * the values given the keys and then subscribe to it with the provided {@link Subscriber}.
+     * <p>
+     * <b>NOTE:</b> It is <b>required</b> that {@link Subscriber#onNext(Object)} is invoked on each value in the same order as
+     * the provided keys and that you provide a value for every key provided.
+     *
+     * @param keys       the collection of keys to load
+     * @param subscriber as values arrive you must call the subscriber for each value
+     */
     void load(List<K> keys, Subscriber<V> subscriber);
 }

src/main/java/org/dataloader/BatchPublisherWithContext.java

@@ -5,8 +5,30 @@
 import java.util.List;
 
 /**
- * An {@link BatchPublisher} with a {@link BatchLoaderEnvironment} provided as an extra parameter to {@link #load}.
+ * This form of {@link BatchPublisher} is given a {@link org.dataloader.BatchLoaderEnvironment} object
+ * that encapsulates the calling context.  A typical use case is passing in security credentials or database details
+ * for example.
+ * <p>
+ * See {@link BatchPublisher} for more details on the design invariants that you must implement in order to
+ * use this interface.
  */
 public interface BatchPublisherWithContext<K, V> {
+    /**
+     * Called to batch the provided keys into a stream of values.  You <b>must</b> provide
+     * the same number of values as there as keys, and they <b>must</b> be in the order of the keys.
+     * <p>
+     * The idiomatic approach would be to create a reactive {@link org.reactivestreams.Publisher} that provides
+     * the values given the keys and then subscribe to it with the provided {@link Subscriber}.
+     * <p>
+     * <b>NOTE:</b> It is <b>required</b> that {@link Subscriber#onNext(Object)} is invoked on each value in the same order as
+     * the provided keys and that you provide a value for every key provided.
+     * <p>
+     * This is given an environment object to that maybe be useful during the call.  A typical use case
+     * is passing in security credentials or database details for example.
+     *
+     * @param keys        the collection of keys to load
+     * @param subscriber  as values arrive you must call the subscriber for each value
+     * @param environment an environment object that can help with the call
+     */
     void load(List<K> keys, Subscriber<V> subscriber, BatchLoaderEnvironment environment);
 }

src/main/java/org/dataloader/MappedBatchPublisher.java

@@ -8,13 +8,23 @@
 /**
  * A function that is invoked for batch loading a stream of data values indicated by the provided list of keys.
  * <p>
- * The function will call the provided {@link Subscriber} to process the key/value pairs it has retrieved to allow
+ * The function <b>must</b> call the provided {@link Subscriber} to process the key/value pairs it has retrieved to allow
  * the future returned by {@link DataLoader#load(Object)} to complete as soon as the individual value is available
  * (rather than when all values have been retrieved).
  *
  * @param <K> type parameter indicating the type of keys to use for data load requests.
  * @param <V> type parameter indicating the type of values returned
+ * @see MappedBatchLoader for the non-reactive version
  */
 public interface MappedBatchPublisher<K, V> {
+    /**
+     * Called to batch the provided keys into a stream of map entries of keys and values.
+     * <p>
+     * The idiomatic approach would be to create a reactive {@link org.reactivestreams.Publisher} that provides
+     * the values given the keys and then subscribe to it with the provided {@link Subscriber}.
+     *
+     * @param keys       the collection of keys to load
+     * @param subscriber as values arrive you must call the subscriber for each value
+     */
     void load(List<K> keys, Subscriber<Map.Entry<K, V>> subscriber);
 }

src/main/java/org/dataloader/MappedBatchPublisherWithContext.java

@@ -6,8 +6,27 @@
 import java.util.Map;
 
 /**
- * A {@link MappedBatchPublisher} with a {@link BatchLoaderEnvironment} provided as an extra parameter to {@link #load}.
+ * This form of {@link MappedBatchPublisher} is given a {@link org.dataloader.BatchLoaderEnvironment} object
+ * that encapsulates the calling context.  A typical use case is passing in security credentials or database details
+ * for example.
+ * <p>
+ * See {@link MappedBatchPublisher} for more details on the design invariants that you must implement in order to
+ * use this interface.
  */
 public interface MappedBatchPublisherWithContext<K, V> {
+
+    /**
+     * Called to batch the provided keys into a stream of map entries of keys and values.
+     * <p>
+     * The idiomatic approach would be to create a reactive {@link org.reactivestreams.Publisher} that provides
+     * the values given the keys and then subscribe to it with the provided {@link Subscriber}.
+     * <p>
+     * This is given an environment object to that maybe be useful during the call.  A typical use case
+     * is passing in security credentials or database details for example.
+     *
+     * @param keys        the collection of keys to load
+     * @param subscriber  as values arrive you must call the subscriber for each value
+     * @param environment an environment object that can help with the call
+     */
     void load(List<K> keys, Subscriber<Map.Entry<K, V>> subscriber, BatchLoaderEnvironment environment);
 }