Improve the toCollection and related API documentation

JAVA-5833

Author: stIncMale

driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/AggregatePublisher.java

@@ -17,15 +17,19 @@
 package com.mongodb.reactivestreams.client;
 
 import com.mongodb.ExplainVerbosity;
+import com.mongodb.MongoNamespace;
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.client.cursor.TimeoutMode;
+import com.mongodb.client.model.Aggregates;
 import com.mongodb.client.model.Collation;
+import com.mongodb.client.model.MergeOptions;
 import com.mongodb.lang.Nullable;
 import org.bson.BsonValue;
 import org.bson.Document;
 import org.bson.conversions.Bson;
 import org.reactivestreams.Publisher;
+import org.reactivestreams.Subscriber;
 
 import java.util.concurrent.TimeUnit;
 
@@ -83,13 +87,31 @@ public interface AggregatePublisher<TResult> extends Publisher<TResult> {
     AggregatePublisher<TResult> bypassDocumentValidation(@Nullable Boolean bypassDocumentValidation);
 
     /**
-     * Aggregates documents according to the specified aggregation pipeline, which must end with a $out stage.
+     * Aggregates documents according to the specified aggregation pipeline, which must end with an
+     * {@link Aggregates#out(String, String) $out} or {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage.
+     * Calling this method and then {@linkplain Publisher#subscribe(Subscriber) subscribing} to the returned {@link Publisher}
+     * is a preferred alternative to {@linkplain #subscribe(Subscriber) subscribing} to this {@link AggregatePublisher}.
      *
+     * @throws IllegalStateException if the pipeline does not end with an {@code $out} or {@code $merge} stage
      * @return an empty publisher that indicates when the operation has completed
      * @mongodb.driver.manual aggregation/ Aggregation
      */
     Publisher<Void> toCollection();
 
+    /**
+     * Requests {@link AggregatePublisher} to start streaming data according to the specified aggregation pipeline.
+     * <ul>
+     *     <li>
+     *     If the aggregation pipeline ends with an {@link Aggregates#out(String, String) $out} or
+     *     {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage,
+     *     then {@linkplain MongoCollection#find() finds all} documents in the affected namespace and produces them.
+     *     You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise, produces no elements.</li>
+     * </ul>
+     */
+    void subscribe(Subscriber<? super TResult> s);
+
     /**
      * Sets the collation options
      *

driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MapReducePublisher.java

@@ -16,19 +16,22 @@
 
 package com.mongodb.reactivestreams.client;
 
-
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.client.cursor.TimeoutMode;
 import com.mongodb.client.model.Collation;
 import com.mongodb.lang.Nullable;
 import org.bson.conversions.Bson;
 import org.reactivestreams.Publisher;
+import org.reactivestreams.Subscriber;
 
 import java.util.concurrent.TimeUnit;
 
 /**
  * Publisher for map reduce.
+ * <p>
+ * By default, the {@code MapReducePublisher} produces the results inline. You can write map-reduce output to a collection by using the
+ * {@link #collectionName(String)} and {@link #toCollection()} methods.</p>
  *
  * @param <TResult> The type of the result.
  * @since 1.0
@@ -44,6 +47,7 @@ public interface MapReducePublisher<TResult> extends Publisher<TResult> {
      *
      * @param collectionName the name of the collection that you want the map-reduce operation to write its output.
      * @return this
+     * @see #toCollection()
      */
     MapReducePublisher<TResult> collectionName(String collectionName);
 
@@ -152,14 +156,29 @@ public interface MapReducePublisher<TResult> extends Publisher<TResult> {
     MapReducePublisher<TResult> bypassDocumentValidation(@Nullable Boolean bypassDocumentValidation);
 
     /**
-     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must specify a
-     * non-inline result.
+     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must not produce
+     * results inline. Calling this method and then {@linkplain Publisher#subscribe(Subscriber) subscribing} to the returned
+     * {@link Publisher} is a preferred alternative to {@linkplain #subscribe(Subscriber) subscribing} to this {@link MapReducePublisher}.
      *
      * @return an empty publisher that indicates when the operation has completed
+     * @throws IllegalStateException if a {@linkplain #collectionName(String) collection name} to write the results to has not been specified
+     * @see #collectionName(String)
      * @mongodb.driver.manual aggregation/ Aggregation
      */
     Publisher<Void> toCollection();
 
+    /**
+     * Requests {@link MapReducePublisher} to start streaming data according to the specified map-reduce function with the given options.
+     * <ul>
+     *     <li>
+     *     If the aggregation produces results inline, then {@linkplain MongoCollection#find() finds all} documents in the
+     *     affected namespace and produces them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise, produces no elements.</li>
+     * </ul>
+     */
+    void subscribe(Subscriber<? super TResult> s);
+
     /**
      * Sets the collation options
      *

driver-scala/src/main/scala/org/mongodb/scala/AggregateObservable.scala

@@ -25,6 +25,7 @@ import org.mongodb.scala.bson.BsonValue
 import org.mongodb.scala.bson.DefaultHelper.DefaultsTo
 import org.mongodb.scala.bson.conversions.Bson
 import org.mongodb.scala.model.Collation
+import org.reactivestreams.Subscriber
 
 import scala.concurrent.duration.Duration
 import scala.reflect.ClassTag
@@ -192,9 +193,13 @@ case class AggregateObservable[TResult](private val wrapped: AggregatePublisher[
   }
 
   /**
-   * Aggregates documents according to the specified aggregation pipeline, which must end with a `\$out` stage.
+   * Aggregates documents according to the specified aggregation pipeline, which must end with an `\$out` or `\$merge` stage.
+   * Calling this method and then `subscribing` to the returned [[SingleObservable]]
+   * is a preferred alternative to subscribing to this [[AggregateObservable]].
    *
    * [[https://www.mongodb.com/docs/manual/aggregation/ Aggregation]]
+   *
+   * @throws java.lang.IllegalStateException if the pipeline does not end with an `\$out` or `\$merge` stage
    * @return an Observable that indicates when the operation has completed.
    */
   def toCollection(): SingleObservable[Unit] = wrapped.toCollection()
@@ -257,5 +262,23 @@ case class AggregateObservable[TResult](private val wrapped: AggregatePublisher[
   )(implicit e: ExplainResult DefaultsTo Document, ct: ClassTag[ExplainResult]): SingleObservable[ExplainResult] =
     wrapped.explain[ExplainResult](ct, verbosity)
 
+  /**
+   * Requests [[AggregateObservable]] to start streaming data according to the specified aggregation pipeline.
+   *
+   *  - If the aggregation pipeline ends with an `\$out` or `\$merge` stage,
+   *    then finds all documents in the affected namespace and produces them.
+   *    You may want to use [[toCollection]] instead.
+   *  - Otherwise, produces no elements.
+   */
   override def subscribe(observer: Observer[_ >: TResult]): Unit = wrapped.subscribe(observer)
+
+  /**
+   * Requests [[AggregateObservable]] to start streaming data according to the specified aggregation pipeline.
+   *
+   *  - If the aggregation pipeline ends with an `\$out` or `\$merge` stage,
+   *    then finds all documents in the affected namespace and produces them.
+   *    You may want to use [[toCollection]] instead.
+   *  - Otherwise, produces no elements.
+   */
+  override def subscribe(observer: Subscriber[_ >: TResult]): Unit = wrapped.subscribe(observer)
 }

driver-scala/src/main/scala/org/mongodb/scala/MapReduceObservable.scala

@@ -23,12 +23,16 @@ import com.mongodb.client.model.MapReduceAction
 import com.mongodb.reactivestreams.client.MapReducePublisher
 import org.mongodb.scala.bson.conversions.Bson
 import org.mongodb.scala.model.Collation
+import org.reactivestreams.Subscriber
 
 import scala.concurrent.duration.Duration
 
 /**
  * Observable for map reduce.
  *
+ * By default, the [[MapReduceObservable]] produces the results inline. You can write map-reduce output to a collection by using the
+ * [[collectionName]] and [[toCollection]] methods.
+ *
  * @define docsRef https://www.mongodb.com/docs/manual/reference
  *
  * @tparam TResult The type of the result.
@@ -44,6 +48,7 @@ case class MapReduceObservable[TResult](wrapped: MapReducePublisher[TResult]) ex
    *
    * @param collectionName the name of the collection that you want the map-reduce operation to write its output.
    * @return this
+   * @see [[toCollection]]
    */
   def collectionName(collectionName: String): MapReduceObservable[TResult] = {
     wrapped.collectionName(collectionName)
@@ -214,11 +219,14 @@ case class MapReduceObservable[TResult](wrapped: MapReducePublisher[TResult]) ex
   }
 
   /**
-   * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must specify a
-   * non-inline result.
+   * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must not produce
+   * results inline. Calling this method and then subscribing to the returned [[SingleObservable]] is a preferred alternative to
+   * subscribing to this [[MapReduceObservable]].
    *
    * @return an Observable that indicates when the operation has completed
    * [[https://www.mongodb.com/docs/manual/aggregation/ Aggregation]]
+   * @throws java.lang.IllegalStateException if a collection name to write the results to has not been specified
+   * @see [[collectionName]]
    */
   def toCollection(): SingleObservable[Unit] = wrapped.toCollection()
 
@@ -246,5 +254,21 @@ case class MapReduceObservable[TResult](wrapped: MapReducePublisher[TResult]) ex
    */
   def first(): SingleObservable[TResult] = wrapped.first()
 
+  /**
+   * Requests [[MapReduceObservable]] to start streaming data according to the specified map-reduce function with the given options.
+   *
+   *  - If the aggregation produces results inline, then finds all documents in the
+   *    affected namespace and produces them. You may want to use [[toCollection]] instead.
+   *  - Otherwise, produces no elements.
+   */
   override def subscribe(observer: Observer[_ >: TResult]): Unit = wrapped.subscribe(observer)
+
+  /**
+   * Requests [[MapReduceObservable]] to start streaming data according to the specified map-reduce function with the given options.
+   *
+   *  - If the aggregation produces results inline, then finds all documents in the
+   *    affected namespace and produces them. You may want to use [[toCollection]] instead.
+   *  - Otherwise, produces no elements.
+   */
+  override def subscribe(observer: Subscriber[_ >: TResult]): Unit = wrapped.subscribe(observer)
 }

driver-sync/src/main/com/mongodb/client/AggregateIterable.java

@@ -17,10 +17,13 @@
 package com.mongodb.client;
 
 import com.mongodb.ExplainVerbosity;
+import com.mongodb.MongoNamespace;
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.client.cursor.TimeoutMode;
+import com.mongodb.client.model.Aggregates;
 import com.mongodb.client.model.Collation;
+import com.mongodb.client.model.MergeOptions;
 import com.mongodb.lang.Nullable;
 import org.bson.BsonValue;
 import org.bson.Document;
@@ -38,15 +41,47 @@
 public interface AggregateIterable<TResult> extends MongoIterable<TResult> {
 
     /**
-     * Aggregates documents according to the specified aggregation pipeline, which must end with a $out or $merge stage.
+     * Aggregates documents according to the specified aggregation pipeline, which must end with an
+     * {@link Aggregates#out(String, String) $out} or {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage.
+     * This method is the preferred alternative to {@link #iterator()}, {@link #cursor()}.
      *
-     * @throws IllegalStateException if the pipeline does not end with a $out or $merge stage
+     * @throws IllegalStateException if the pipeline does not end with an {@code $out} or {@code $merge} stage
      * @mongodb.driver.manual reference/operator/aggregation/out/ $out stage
      * @mongodb.driver.manual reference/operator/aggregation/merge/ $merge stage
      * @since 3.4
      */
     void toCollection();
 
+    /**
+     * Aggregates documents according to the specified aggregation pipeline.
+     * <ul>
+     *     <li>
+     *     If the aggregation pipeline ends with an {@link Aggregates#out(String, String) $out} or
+     *     {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage,
+     *     then {@linkplain MongoCollection#find() finds all} documents in the affected namespace and returns a {@link MongoCursor}
+     *     over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise, returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> iterator();
+
+    /**
+     * Aggregates documents according to the specified aggregation pipeline.
+     * <ul>
+     *     <li>
+     *     If the aggregation pipeline ends with an {@link Aggregates#out(String, String) $out} or
+     *     {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage,
+     *     then {@linkplain MongoCollection#find() finds all} documents in the affected namespace and returns a {@link MongoCursor}
+     *     over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise, returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> cursor();
+
     /**
      * Enables writing to temporary files. A null value indicates that it's unspecified.
      *

driver-sync/src/main/com/mongodb/client/MapReduceIterable.java

@@ -27,9 +27,9 @@
 
 /**
  * Iterable for map-reduce.
- *
- * <p>By default the {@code MapReduceIterable} returns the results inline. You can write map-reduce output to a collection by using the
- * {@link MapReduceIterable#collectionName(String)} method.</p>
+ * <p>
+ * By default, the {@code MapReduceIterable} produces the results inline. You can write map-reduce output to a collection by using the
+ * {@link #collectionName(String)} and {@link #toCollection()} methods.</p>
  *
  * @param <TResult> The type of the result.
  * @since 3.0
@@ -39,22 +39,49 @@
 public interface MapReduceIterable<TResult> extends MongoIterable<TResult> {
 
     /**
-     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must specify a
-     * non-inline result.
+     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must not produce
+     * results inline. This method is the preferred alternative to {@link #iterator()}, {@link #cursor()}.
      *
-     * @throws IllegalStateException if a collection name to write the results to has not been specified
+     * @throws IllegalStateException if a {@linkplain #collectionName(String) collection name} to write the results to has not been specified
      * @see #collectionName(String)
      * @since 3.4
      */
     void toCollection();
 
+    /**
+     * Aggregates documents according to the specified map-reduce function with the given options.
+     * <ul>
+     *     <li>
+     *     If the aggregation produces results inline, then {@linkplain MongoCollection#find() finds all} documents in the
+     *     affected namespace and returns a {@link MongoCursor} over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise, returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> iterator();
+
+    /**
+     * Aggregates documents according to the specified map-reduce function with the given options.
+     * <ul>
+     *     <li>
+     *     If the aggregation produces results inline, then {@linkplain MongoCollection#find() finds all} documents in the
+     *     affected namespace and returns a {@link MongoCursor} over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise, returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> cursor();
+
     /**
      * Sets the collectionName for the output of the MapReduce
      *
      * <p>The default action is replace the collection if it exists, to change this use {@link #action}.</p>
      *
      * @param collectionName the name of the collection that you want the map-reduce operation to write its output.
      * @return this
+     * @see #toCollection()
      */
     MapReduceIterable<TResult> collectionName(String collectionName);
 

driver-sync/src/main/com/mongodb/client/MongoIterable.java

@@ -29,13 +29,16 @@
  */
 public interface MongoIterable<TResult> extends Iterable<TResult> {
 
+    /**
+     * @return A {@link MongoCursor} that must be {@linkplain MongoCursor#close() closed}.
+     */
     @Override
     MongoCursor<TResult> iterator();
 
     /**
      * Returns a cursor used for iterating over elements of type {@code TResult}. The cursor is primarily used for change streams.
      *
-     * @return a cursor
+     * @return a cursor equivalent to that returned from {@link #iterator()}.
      * @since 3.11
      */
     MongoCursor<TResult> cursor();