Added Aggregates.replaceWith helper

JAVA-3305

Author: rozza

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

@@ -490,7 +490,26 @@ public static Bson merge(final MongoNamespace namespace, final MergeOptions opti
      * @since 3.4
      */
     public static <TExpression> Bson replaceRoot(final TExpression value) {
-        return new ReplaceRootStage<TExpression>(value);
+        return new ReplaceStage<TExpression>(value);
+    }
+
+    /**
+     * Creates a $replaceRoot pipeline stage
+     *
+     * <p>With $replaceWith, you can promote an embedded document to the top-level.
+     * You can also specify a new document as the replacement.</p>
+     *
+     * <p>The $replaceWith is an alias for {@link #replaceRoot(Object)}.</p>
+     *
+     * @param <TExpression> the new root type
+     * @param value         the new root value
+     * @return the $replaceRoot pipeline stage
+     * @mongodb.driver.manual reference/operator/aggregation/replaceWith/ $replaceWith
+     * @mongodb.server.release 4.2
+     * @since 3.11
+     */
+    public static <TExpression> Bson replaceWith(final TExpression value) {
+        return new ReplaceStage<TExpression>(value, true);
     }
 
     /**
@@ -1140,22 +1159,34 @@ public String toString() {
         }
     }
 
-    private static class ReplaceRootStage<TExpression> implements Bson {
+    private static class ReplaceStage<TExpression> implements Bson {
         private final TExpression value;
+        private final boolean replaceWith;
+
+        ReplaceStage(final TExpression value) {
+            this(value, false);
+        }
 
-        ReplaceRootStage(final TExpression value) {
+        ReplaceStage(final TExpression value, final boolean replaceWith) {
             this.value = value;
+            this.replaceWith = replaceWith;
         }
 
         @Override
         public <TDocument> BsonDocument toBsonDocument(final Class<TDocument> tDocumentClass, final CodecRegistry codecRegistry) {
             BsonDocumentWriter writer = new BsonDocumentWriter(new BsonDocument());
             writer.writeStartDocument();
-            writer.writeName("$replaceRoot");
-            writer.writeStartDocument();
-            writer.writeName("newRoot");
-            BuildersHelper.encodeValue(writer, value, codecRegistry);
-            writer.writeEndDocument();
+
+            if (replaceWith) {
+                writer.writeName("$replaceWith");
+                BuildersHelper.encodeValue(writer, value, codecRegistry);
+            } else {
+                writer.writeName("$replaceRoot");
+                writer.writeStartDocument();
+                writer.writeName("newRoot");
+                BuildersHelper.encodeValue(writer, value, codecRegistry);
+                writer.writeEndDocument();
+            }
             writer.writeEndDocument();
 
             return writer.getDocument();
@@ -1170,7 +1201,7 @@ public boolean equals(final Object o) {
                 return false;
             }
 
-            ReplaceRootStage<?> that = (ReplaceRootStage<?>) o;
+            ReplaceStage<?> that = (ReplaceStage<?>) o;
 
             return value != null ? value.equals(that.value) : that.value == null;
         }

driver-core/src/test/functional/com/mongodb/client/model/AggregatesFunctionalSpecification.groovy

@@ -50,6 +50,7 @@ import static com.mongodb.client.model.Aggregates.merge
 import static com.mongodb.client.model.Aggregates.out
 import static com.mongodb.client.model.Aggregates.project
 import static com.mongodb.client.model.Aggregates.replaceRoot
+import static com.mongodb.client.model.Aggregates.replaceWith
 import static com.mongodb.client.model.Aggregates.sample
 import static com.mongodb.client.model.Aggregates.skip
 import static com.mongodb.client.model.Aggregates.sort
@@ -890,4 +891,35 @@ class AggregatesFunctionalSpecification extends OperationFunctionalSpecification
         then:
         results == [Document.parse('{b: 1, _id: 7}')]
     }
+
+    @IgnoreIf({ !serverVersionAtLeast(4, 2) })
+    def '$replaceWith'() {
+        given:
+        def helper = getCollectionHelper()
+        def results = []
+
+        when:
+        helper.drop()
+        helper.insertDocuments(Document.parse('{_id: 0, a1: {b: 1}, a2: 2}'))
+        results = helper.aggregate([replaceWith('$a1')])
+
+        then:
+        results == [Document.parse('{b: 1}')]
+
+        when:
+        helper.drop()
+        helper.insertDocuments(Document.parse('{_id: 0, a1: {b: {c1: 4, c2: 5}}, a2: 2}'))
+        results = helper.aggregate([replaceWith('$a1.b')])
+
+        then:
+        results == [Document.parse('{c1: 4, c2: 5}')]
+
+        when:
+        helper.drop()
+        helper.insertDocuments(Document.parse('{_id: 0, a1: {b: 1, _id: 7}, a2: 2}'))
+        results = helper.aggregate([replaceWith('$a1')])
+
+        then:
+        results == [Document.parse('{b: 1, _id: 7}')]
+    }
 }

driver-core/src/test/unit/com/mongodb/client/model/AggregatesSpecification.groovy

@@ -50,6 +50,7 @@ import static com.mongodb.client.model.Aggregates.merge
 import static com.mongodb.client.model.Aggregates.out
 import static com.mongodb.client.model.Aggregates.project
 import static com.mongodb.client.model.Aggregates.replaceRoot
+import static com.mongodb.client.model.Aggregates.replaceWith
 import static com.mongodb.client.model.Aggregates.sample
 import static com.mongodb.client.model.Aggregates.skip
 import static com.mongodb.client.model.Aggregates.sort
@@ -169,14 +170,20 @@ class AggregatesSpecification extends Specification {
         parse('{ $project : { title : 1 , author : 1, lastName : "$author.last" } }')
     }
 
-    @IgnoreIf({ !serverVersionAtLeast(3, 4) })
     def 'should render $replaceRoot'() {
         expect:
         toBson(replaceRoot('$a1')) == parse('{$replaceRoot: {newRoot: "$a1"}}')
         toBson(replaceRoot('$a1.b')) == parse('{$replaceRoot: {newRoot: "$a1.b"}}')
         toBson(replaceRoot('$a1')) == parse('{$replaceRoot: {newRoot: "$a1"}}')
     }
 
+    def 'should render $replaceWith'() {
+        expect:
+        toBson(replaceWith('$a1')) == parse('{$replaceWith: "$a1"}')
+        toBson(replaceWith('$a1.b')) == parse('{$replaceWith: "$a1.b"}')
+        toBson(replaceWith('$a1')) == parse('{$replaceWith: "$a1"}')
+    }
+
     def 'should render $sort'() {
         expect:
         toBson(sort(ascending('title', 'author'))) == parse('{ $sort : { title : 1 , author : 1 } }')