Update $out stage rendering to documented format.

This commit makes sure to use the documented command format when rendering the $out aggregation stage.

Original pull request: #4986
Closes #4969

Author: christophstrobl

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

@@ -96,12 +96,14 @@ public OutOperation in(@Nullable String database) {
 	 * .uniqueKey("{ 'field-1' : 1, 'field-2' : 1}")
 	 * </pre>
 	 *
-	 * <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
+	 * <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
 	 *
 	 * @param key can be {@literal null}. Server uses {@literal _id} when {@literal null}.
 	 * @return new instance of {@link OutOperation}.
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public OutOperation uniqueKey(@Nullable String key) {
 
 		Document uniqueKey = key == null ? null : BsonUtils.toDocumentOrElse(key, it -> new Document(it, 1));
@@ -120,12 +122,14 @@ public OutOperation uniqueKey(@Nullable String key) {
 	 * .uniqueKeyOf(Arrays.asList("field-1", "field-2"))
 	 * </pre>
 	 *
-	 * <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
+	 * <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
 	 *
 	 * @param fields must not be {@literal null}.
 	 * @return new instance of {@link OutOperation}.
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public OutOperation uniqueKeyOf(Iterable<String> fields) {
 
 		Assert.notNull(fields, "Fields must not be null");
@@ -138,12 +142,14 @@ public OutOperation uniqueKeyOf(Iterable<String> fields) {
 
 	/**
 	 * Specify how to merge the aggregation output with the target collection. <br />
-	 * <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
+	 * <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
 	 *
 	 * @param mode must not be {@literal null}.
 	 * @return new instance of {@link OutOperation}.
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public OutOperation mode(OutMode mode) {
 
 		Assert.notNull(mode, "Mode must not be null");
@@ -152,36 +158,42 @@ public OutOperation mode(OutMode mode) {
 
 	/**
 	 * Replace the target collection. <br />
-	 * <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
+	 * <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
 	 *
 	 * @return new instance of {@link OutOperation}.
 	 * @see OutMode#REPLACE_COLLECTION
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public OutOperation replaceCollection() {
 		return mode(OutMode.REPLACE_COLLECTION);
 	}
 
 	/**
 	 * Replace/Upsert documents in the target collection. <br />
-	 * <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
+	 * <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
 	 *
 	 * @return new instance of {@link OutOperation}.
 	 * @see OutMode#REPLACE
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public OutOperation replaceDocuments() {
 		return mode(OutMode.REPLACE);
 	}
 
 	/**
 	 * Insert documents to the target collection. <br />
-	 * <strong>NOTE:</strong> Requires MongoDB 4.2 or later.
+	 * <strong>NOTE:</strong> Only suitable for 4.2+ to (not including) 5.0.
 	 *
 	 * @return new instance of {@link OutOperation}.
 	 * @see OutMode#INSERT
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public OutOperation insertDocuments() {
 		return mode(OutMode.INSERT);
 	}
@@ -190,7 +202,10 @@ public OutOperation insertDocuments() {
 	public Document toDocument(AggregationOperationContext context) {
 
 		if (!requiresMongoDb42Format()) {
-			return new Document("$out", collectionName);
+			if (!StringUtils.hasText(databaseName)) {
+				return new Document(getOperator(), collectionName);
+			}
+			return new Document(getOperator(), new Document("db", databaseName).append("coll", collectionName));
 		}
 
 		Assert.state(mode != null, "Mode must not be null");
@@ -215,15 +230,17 @@ public String getOperator() {
 	}
 
 	private boolean requiresMongoDb42Format() {
-		return StringUtils.hasText(databaseName) || mode != null || uniqueKey != null;
+		return mode != null || uniqueKey != null;
 	}
 
 	/**
 	 * The mode for merging the aggregation pipeline output.
 	 *
 	 * @author Christoph Strobl
 	 * @since 2.2
+	 * @deprecated no longer applicable for MongoDB 5+
 	 */
+	@Deprecated
 	public enum OutMode {
 
 		/**

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

@@ -15,8 +15,9 @@
  */
 package org.springframework.data.mongodb.core.aggregation;
 
-import static org.springframework.data.mongodb.core.aggregation.Aggregation.*;
-import static org.springframework.data.mongodb.test.util.Assertions.*;
+import static org.springframework.data.mongodb.core.aggregation.Aggregation.out;
+import static org.springframework.data.mongodb.test.util.Assertions.assertThat;
+import static org.springframework.data.mongodb.test.util.Assertions.assertThatIllegalArgumentException;
 
 import java.util.Arrays;
 
@@ -84,11 +85,12 @@ public void shouldRenderExtendedFormatWithMultiFieldKey() {
 						.containsEntry("$out.uniqueKey", new Document("field-1", 1).append("field-2", 1));
 	}
 
-	@Test // DATAMONGO-2259
-	public void shouldErrorOnExtendedFormatWithoutMode() {
+	@Test // DATAMONGO-2259, GH-4969
+	public void shouldRenderNewExtendedFormatWithoutMode() {
 
-		assertThatThrownBy(() -> out("out-col").in("database-2").toDocument(Aggregation.DEFAULT_CONTEXT))
-				.isInstanceOf(IllegalStateException.class);
+		assertThat(out("out-col").in("database-2").toDocument(Aggregation.DEFAULT_CONTEXT))
+			.containsEntry("$out.coll", "out-col") //
+			.containsEntry("$out.db", "database-2");
 	}
 
 }