Use T first, T... more in $search/$setWindowFields query building API to represent that at least one value is required (#966)

Author: stIncMale

driver-core/src/main/com/mongodb/client/model/Aggregates.java

@@ -35,6 +35,7 @@
 import java.util.Objects;
 
 import static com.mongodb.assertions.Assertions.assertTrue;
+import static com.mongodb.internal.Iterables.concat;
 import static java.util.Arrays.asList;
 import static org.bson.assertions.Assertions.notNull;
 
@@ -614,17 +615,17 @@ public static Bson sample(final int size) {
      *               Sorting is required by certain functions and may be required by some windows (see {@link Windows} for more details).
      *               Sorting is used only for the purpose of computing window functions and does not guarantee ordering
      *               of the output documents.
-     * @param output A nonempty array of {@linkplain WindowedComputation windowed computations}.
+     * @param output A {@linkplain WindowedComputation windowed computation}.
+     * @param moreOutput More {@linkplain WindowedComputation windowed computations}.
      * @param <TExpression> The {@code partitionBy} expression type.
      * @return The {@code $setWindowFields} pipeline stage.
      * @mongodb.driver.dochub core/window-functions-set-window-fields $setWindowFields
      * @mongodb.server.release 5.0
      * @since 4.3
      */
     public static <TExpression> Bson setWindowFields(@Nullable final TExpression partitionBy, @Nullable final Bson sortBy,
-                                                     final WindowedComputation... output) {
-        notNull("output", output);
-        return setWindowFields(partitionBy, sortBy, asList(output));
+            final WindowedComputation output, final WindowedComputation... moreOutput) {
+        return setWindowFields(partitionBy, sortBy, concat(notNull("output", output), moreOutput));
     }
 
     /**
@@ -640,7 +641,8 @@ public static <TExpression> Bson setWindowFields(@Nullable final TExpression par
      *               Sorting is required by certain functions and may be required by some windows (see {@link Windows} for more details).
      *               Sorting is used only for the purpose of computing window functions and does not guarantee ordering
      *               of the output documents.
-     * @param output A nonempty list of {@linkplain WindowedComputation windowed computations}.
+     * @param output A list of {@linkplain WindowedComputation windowed computations}.
+     * Specifying an empty list is not an error, but the resulting stage does not do anything useful.
      * @param <TExpression> The {@code partitionBy} expression type.
      * @return The {@code $setWindowFields} pipeline stage.
      * @mongodb.driver.dochub core/window-functions-set-window-fields $setWindowFields

driver-core/src/main/com/mongodb/client/model/search/AutocompleteSearchOperator.java

@@ -19,8 +19,8 @@
 import com.mongodb.annotations.Evolving;
 
 /**
- * @see SearchOperator#autocomplete(String, FieldSearchPath)
- * @see SearchOperator#autocomplete(Iterable, FieldSearchPath)
+ * @see SearchOperator#autocomplete(FieldSearchPath, String, String...)
+ * @see SearchOperator#autocomplete(FieldSearchPath, Iterable)
  * @since 4.7
  */
 @Evolving
@@ -32,10 +32,18 @@ public interface AutocompleteSearchOperator extends SearchOperator {
     /**
      * Creates a new {@link AutocompleteSearchOperator} that uses fuzzy search.
      *
-     * @param option Fuzzy search option.
      * @return A new {@link AutocompleteSearchOperator}.
      */
-    AutocompleteSearchOperator fuzzy(SearchFuzzy option);
+    AutocompleteSearchOperator fuzzy();
+
+    /**
+     * Creates a new {@link AutocompleteSearchOperator} that uses fuzzy search.
+     *
+     * @param options The fuzzy search options.
+     * Specifying {@link FuzzySearchOptions#fuzzySearchOptions()} is equivalent to calling {@link #fuzzy()}.
+     * @return A new {@link AutocompleteSearchOperator}.
+     */
+    AutocompleteSearchOperator fuzzy(FuzzySearchOptions options);
 
     /**
      * Creates a new {@link AutocompleteSearchOperator} that does not require tokens to appear in the same order as they are specified.

driver-core/src/main/com/mongodb/client/model/search/DateNearSearchOperator.java

@@ -22,7 +22,7 @@
 import java.time.Instant;
 
 /**
- * @see SearchOperator#near(Instant, Duration, FieldSearchPath)
+ * @see SearchOperator#near(Instant, Duration, FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#near(Instant, Duration, Iterable)
  * @since 4.7
  */

driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperator.java

@@ -19,7 +19,7 @@
 import com.mongodb.annotations.Evolving;
 
 /**
- * @see SearchOperator#dateRange(FieldSearchPath)
+ * @see SearchOperator#dateRange(FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#dateRange(Iterable)
  * @since 4.7
  */

driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperatorBase.java

@@ -24,7 +24,7 @@
  * A base for a {@link DateRangeSearchOperator} which allows creating instances of this operator.
  * This interface is a technicality and does not represent a meaningful element of the full-text search query syntax.
  *
- * @see SearchOperator#dateRange(FieldSearchPath)
+ * @see SearchOperator#dateRange(FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#dateRange(Iterable)
  * @since 4.7
  */

driver-core/src/main/com/mongodb/client/model/search/SearchFuzzy.java renamed to driver-core/src/main/com/mongodb/client/model/search/FuzzySearchOptions.java

@@ -19,8 +19,6 @@
 import com.mongodb.annotations.Evolving;
 import org.bson.conversions.Bson;
 
-import static com.mongodb.assertions.Assertions.notNull;
-
 /**
  * Fuzzy search options that may be used with some {@link SearchOperator}s.
  *
@@ -30,58 +28,58 @@
  */
 @Evolving
 @Beta(Beta.Reason.CLIENT)
-public interface SearchFuzzy extends Bson {
+public interface FuzzySearchOptions extends Bson {
     /**
-     * Creates a new {@link SearchFuzzy} with the maximum
+     * Creates a new {@link FuzzySearchOptions} with the maximum
      * <a href="https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance">number of single-character edits</a>
      * required to match a search term.
      *
      * @param maxEdits The maximum number of single-character edits required to match a search term.
-     * @return A new {@link SearchFuzzy}.
+     * @return A new {@link FuzzySearchOptions}.
      */
-    SearchFuzzy maxEdits(int maxEdits);
+    FuzzySearchOptions maxEdits(int maxEdits);
 
     /**
-     * Creates a new {@link SearchFuzzy} with the number of characters at the beginning of a search term that must exactly match.
+     * Creates a new {@link FuzzySearchOptions} with the number of characters at the beginning of a search term that must exactly match.
      *
      * @param prefixLength The number of characters at the beginning of a search term that must exactly match.
-     * @return A new {@link SearchFuzzy}.
+     * @return A new {@link FuzzySearchOptions}.
      */
-    SearchFuzzy prefixLength(int prefixLength);
+    FuzzySearchOptions prefixLength(int prefixLength);
 
     /**
-     * Creates a new {@link SearchFuzzy} with the maximum number of variations to generate and consider to match a search term.
+     * Creates a new {@link FuzzySearchOptions} with the maximum number of variations to generate and consider to match a search term.
      *
      * @param maxExpansions The maximum number of variations to generate and consider to match a search term.
-     * @return A new {@link SearchFuzzy}.
+     * @return A new {@link FuzzySearchOptions}.
      */
-    SearchFuzzy maxExpansions(int maxExpansions);
+    FuzzySearchOptions maxExpansions(int maxExpansions);
 
     /**
-     * Creates a new {@link SearchFuzzy} from a {@link Bson} in situations when there is no builder method that better satisfies your needs.
+     * Creates a new {@link FuzzySearchOptions} with the specified option in situations when there is no builder method
+     * that better satisfies your needs.
      * This method cannot be used to validate the syntax.
      * <p>
      * <i>Example</i><br>
-     * The following code creates two functionally equivalent {@link SearchFuzzy} objects,
+     * The following code creates two functionally equivalent {@link FuzzySearchOptions} objects,
      * though they may not be {@linkplain Object#equals(Object) equal}.
      * <pre>{@code
-     *  SearchFuzzy fuzzy1 = SearchFuzzy.defaultSearchFuzzy().maxEdits(1);
-     *  SearchFuzzy fuzzy2 = SearchFuzzy.of(new Document("maxEdits", 1));
+     *  FuzzySearchOptions options1 = FuzzySearchOptions.fuzzySearchOptions().maxEdits(1)
+     *  FuzzySearchOptions options2 = FuzzySearchOptions.fuzzySearchOptions().option("maxEdits", 1)
      * }</pre>
      *
-     * @param fuzzy A {@link Bson} representing the required {@link SearchFuzzy}.
-     * @return A new {@link SearchFuzzy}.
+     * @param name The option name.
+     * @param value The option value.
+     * @return A new {@link FuzzySearchOptions}.
      */
-    static SearchFuzzy of(final Bson fuzzy) {
-        return new SearchConstructibleBson(notNull("fuzzy", fuzzy));
-    }
+    FuzzySearchOptions option(String name, Object value);
 
     /**
-     * Returns {@link SearchFuzzy} that represents server defaults.
+     * Returns {@link FuzzySearchOptions} that represents server defaults.
      *
-     * @return {@link SearchFuzzy} that represents server defaults.
+     * @return {@link FuzzySearchOptions} that represents server defaults.
      */
-    static SearchFuzzy defaultSearchFuzzy() {
+    static FuzzySearchOptions fuzzySearchOptions() {
         return SearchConstructibleBson.EMPTY_IMMUTABLE;
     }
 }

driver-core/src/main/com/mongodb/client/model/search/GeoNearSearchOperator.java

@@ -20,7 +20,7 @@
 import com.mongodb.client.model.geojson.Point;
 
 /**
- * @see SearchOperator#near(Point, Number, FieldSearchPath)
+ * @see SearchOperator#near(Point, Number, FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#near(Point, Number, Iterable)
  * @since 4.7
  */

driver-core/src/main/com/mongodb/client/model/search/NumberNearSearchOperator.java

@@ -19,7 +19,7 @@
 import com.mongodb.annotations.Evolving;
 
 /**
- * @see SearchOperator#near(Number, Number, FieldSearchPath)
+ * @see SearchOperator#near(Number, Number, FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#near(Number, Number, Iterable)
  * @since 4.7
  */

driver-core/src/main/com/mongodb/client/model/search/NumberRangeSearchOperator.java

@@ -19,7 +19,7 @@
 import com.mongodb.annotations.Evolving;
 
 /**
- * @see SearchOperator#numberRange(FieldSearchPath)
+ * @see SearchOperator#numberRange(FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#numberRange(Iterable)
  * @since 4.7
  */

driver-core/src/main/com/mongodb/client/model/search/NumberRangeSearchOperatorBase.java

@@ -22,7 +22,7 @@
  * A base for a {@link NumberRangeSearchOperator} which allows creating instances of this operator.
  * This interface is a technicality and does not represent a meaningful element of the full-text search query syntax.
  *
- * @see SearchOperator#numberRange(FieldSearchPath)
+ * @see SearchOperator#numberRange(FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#numberRange(Iterable)
  * @since 4.7
  */