DATAMONGO-1836 - Polishing.

Revert constructor change of AggregationOptions to not break existing code. Update since tags. Reformat code.

Align visibility of AggregationOptionsTests with JUnit 5 rules. Update documentation.

Original pull request: #878.

Author: mp911de

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoTemplate.java

@@ -2149,7 +2149,6 @@ protected <O> AggregationResults<O> doAggregate(Aggregation aggregation, String
 			}
 
 			options.getComment().ifPresent(aggregateIterable::comment);
-
 			options.getHint().ifPresent(aggregateIterable::hint);
 
 			if (options.hasExecutionTimeLimit()) {
@@ -2209,7 +2208,6 @@ protected <O> CloseableIterator<O> aggregateStream(Aggregation aggregation, Stri
 			}
 
 			options.getComment().ifPresent(cursor::comment);
-
 			options.getHint().ifPresent(cursor::hint);
 
 			Class<?> domainType = aggregation instanceof TypedAggregation ? ((TypedAggregation) aggregation).getInputType()

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoTemplate.java

@@ -1024,7 +1024,6 @@ private <O> Flux<O> aggregateAndMap(MongoCollection<Document> collection, List<D
 		}
 
 		options.getComment().ifPresent(cursor::comment);
-
 		options.getHint().ifPresent(cursor::hint);
 
 		Optionals.firstNonEmpty(options::getCollation, () -> operations.forType(inputType).getCollation()) //

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/AggregationOptions.java

@@ -74,7 +74,7 @@ public AggregationOptions(boolean allowDiskUse, boolean explain, Document cursor
 	 * @param allowDiskUse whether to off-load intensive sort-operations to disk.
 	 * @param explain whether to get the execution plan for the aggregation instead of the actual results.
 	 * @param cursor can be {@literal null}, used to pass additional options (such as {@code batchSize}) to the
-	 * aggregation.
+	 *          aggregation.
 	 * @param collation collation for string comparison. Can be {@literal null}.
 	 * @since 2.0
 	 */
@@ -89,13 +89,29 @@ public AggregationOptions(boolean allowDiskUse, boolean explain, @Nullable Docum
 	 * @param allowDiskUse whether to off-load intensive sort-operations to disk.
 	 * @param explain whether to get the execution plan for the aggregation instead of the actual results.
 	 * @param cursor can be {@literal null}, used to pass additional options (such as {@code batchSize}) to the
-	 * aggregation.
+	 *          aggregation.
 	 * @param collation collation for string comparison. Can be {@literal null}.
 	 * @param comment execution comment. Can be {@literal null}.
-	 * @param hint can be {@literal null}, used to provide an index that would be forcibly used by query optimizer.
 	 * @since 2.2
 	 */
 	public AggregationOptions(boolean allowDiskUse, boolean explain, @Nullable Document cursor,
+			@Nullable Collation collation, @Nullable String comment) {
+		this(allowDiskUse, explain, cursor, collation, comment, null);
+	}
+
+	/**
+	 * Creates a new {@link AggregationOptions}.
+	 *
+	 * @param allowDiskUse whether to off-load intensive sort-operations to disk.
+	 * @param explain whether to get the execution plan for the aggregation instead of the actual results.
+	 * @param cursor can be {@literal null}, used to pass additional options (such as {@code batchSize}) to the
+	 *          aggregation.
+	 * @param collation collation for string comparison. Can be {@literal null}.
+	 * @param comment execution comment. Can be {@literal null}.
+	 * @param hint can be {@literal null}, used to provide an index that would be forcibly used by query optimizer.
+	 * @since 3.1
+	 */
+	private AggregationOptions(boolean allowDiskUse, boolean explain, @Nullable Document cursor,
 			@Nullable Collation collation, @Nullable String comment, @Nullable Document hint) {
 
 		this.allowDiskUse = allowDiskUse;
@@ -222,12 +238,12 @@ public Optional<String> getComment() {
 	 * Get the hint used to to fulfill the aggregation.
 	 *
 	 * @return never {@literal null}.
+	 * @since 3.1
 	 */
 	public Optional<Document> getHint() {
 		return hint;
 	}
 
-
 	/**
 	 * @return the time limit for processing. {@link Duration#ZERO} is used for the default unbounded behavior.
 	 * @since 3.0
@@ -419,11 +435,11 @@ public Builder comment(@Nullable String comment) {
 		}
 
 		/**
-		 * Define a hint is used forcibly by query optimizer to to fulfill the aggregation.
+		 * Define a hint that is used by query optimizer to to fulfill the aggregation.
 		 *
 		 * @param hint can be {@literal null}.
 		 * @return this.
-		 * @since 2.2
+		 * @since 3.1
 		 */
 		public Builder hint(@Nullable Document hint) {
 
@@ -435,7 +451,7 @@ public Builder hint(@Nullable Document hint) {
 		 * Set the time limit for processing.
 		 *
 		 * @param maxTime {@link Duration#ZERO} is used for the default unbounded behavior. {@link Duration#isNegative()
-		 * Negative} values will be ignored.
+		 *          Negative} values will be ignored.
 		 * @return this.
 		 * @since 3.0
 		 */
@@ -466,13 +482,7 @@ public Builder skipOutput() {
 		 */
 		public AggregationOptions build() {
 
-			AggregationOptions options = new AggregationOptions(
-					allowDiskUse,
-					explain,
-					cursor,
-					collation,
-					comment,
-					hint);
+			AggregationOptions options = new AggregationOptions(allowDiskUse, explain, cursor, collation, comment, hint);
 			if (maxTime != null) {
 				options.maxTime = maxTime;
 			}

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/ReactiveMongoTemplateUnitTests.java

@@ -631,6 +631,7 @@ void aggregateShouldHonorOptionsComment() {
 
 	@Test // DATAMONGO-1836
 	void aggregateShouldHonorOptionsHint() {
+
 		Document hint = new Document("dummyHint", 1);
 		AggregationOptions options = AggregationOptions.builder().hint(hint).build();
 

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/aggregation/AggregationOptionsTests.java

@@ -31,13 +31,13 @@
  * @author Yadhukrishna S Pai
  * @since 1.6
  */
-public class AggregationOptionsTests {
+class AggregationOptionsTests {
 
 	private final Document dummyHint = new Document("dummyField", 1);
 	AggregationOptions aggregationOptions;
 
 	@BeforeEach
-	public void setup() {
+	void setup() {
 		aggregationOptions = newAggregationOptions().explain(true) //
 				.cursorBatchSize(1) //
 				.allowDiskUse(true) //
@@ -47,16 +47,16 @@ public void setup() {
 	}
 
 	@Test // DATAMONGO-960, DATAMONGO-1836
-	public void aggregationOptionsBuilderShouldSetOptionsAccordingly() {
+	void aggregationOptionsBuilderShouldSetOptionsAccordingly() {
 
 		assertThat(aggregationOptions.isAllowDiskUse()).isTrue();
 		assertThat(aggregationOptions.isExplain()).isTrue();
-		assertThat(aggregationOptions.getCursor().get()).isEqualTo(new Document("batchSize", 1));
-		assertThat(aggregationOptions.getHint().get()).isEqualTo(dummyHint);
+		assertThat(aggregationOptions.getCursor()).contains(new Document("batchSize", 1));
+		assertThat(aggregationOptions.getHint()).contains(dummyHint);
 	}
 
 	@Test // DATAMONGO-1637, DATAMONGO-2153, DATAMONGO-1836
-	public void shouldInitializeFromDocument() {
+	void shouldInitializeFromDocument() {
 
 		Document document = new Document();
 		document.put("cursor", new Document("batchSize", 1));
@@ -69,22 +69,17 @@ public void shouldInitializeFromDocument() {
 
 		assertThat(aggregationOptions.isAllowDiskUse()).isTrue();
 		assertThat(aggregationOptions.isExplain()).isTrue();
-		assertThat(aggregationOptions.getCursor().get()).isEqualTo(new Document("batchSize", 1));
+		assertThat(aggregationOptions.getCursor()).contains(new Document("batchSize", 1));
 		assertThat(aggregationOptions.getCursorBatchSize()).isEqualTo(1);
-		assertThat(aggregationOptions.getComment().get()).isEqualTo("hola!");
-		assertThat(aggregationOptions.getHint().get()).isEqualTo(dummyHint);
+		assertThat(aggregationOptions.getComment()).contains("hola!");
+		assertThat(aggregationOptions.getHint()).contains(dummyHint);
 	}
 
 	@Test // DATAMONGO-960, DATAMONGO-2153, DATAMONGO-1836
-	public void aggregationOptionsToString() {
+	void aggregationOptionsToString() {
 
-		assertThat(aggregationOptions.toDocument()).isEqualTo(Document.parse(
-				"{ " +
-						"\"allowDiskUse\" : true , " +
-						"\"explain\" : true , " +
-						"\"cursor\" : { \"batchSize\" : 1}, " +
-						"\"comment\": \"hola!\", " +
-						"\"hint\" : { \"dummyField\" : 1}" +
-						"}"));
+		assertThat(aggregationOptions.toDocument()).isEqualTo(Document
+				.parse("{ " + "\"allowDiskUse\" : true , " + "\"explain\" : true , " + "\"cursor\" : { \"batchSize\" : 1}, "
+						+ "\"comment\": \"hola!\", " + "\"hint\" : { \"dummyField\" : 1}" + "}"));
 	}
 }

src/main/asciidoc/new-features.adoc

@@ -6,6 +6,7 @@
 
 * <<mongo.auditing,Reactive auditing>> enabled through `@EnableReactiveMongoAuditing`. `@EnableMongoAuditing` no longer registers `ReactiveAuditingEntityCallback`.
 * Reactive SpEL support in `@Query` and `@Aggregation` query methods.
+* Aggregation hints via `AggregationOptions.builder().hint(bson).build()`.
 
 [[new-features.3.0]]
 == What's New in Spring Data MongoDB 3.0