DATAMONGO-1827 - Polishing.

Allow open/close projection on return type for findAndReplace.
Use default methods for delegation and remove collation from FindAndRemoveOption in favor of the collation set on the query itself.
Update Javadoc and reference documentation.

Original Pull Request: spring-projects#569

Author: christophstrobl

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

@@ -24,8 +24,8 @@
 import com.mongodb.client.result.UpdateResult;
 
 /**
- * {@link ExecutableUpdateOperation} allows creation and execution of MongoDB update / findAndModify / findAndReplace operations in a
- * fluent API style. <br />
+ * {@link ExecutableUpdateOperation} allows creation and execution of MongoDB update / findAndModify / findAndReplace
+ * operations in a fluent API style. <br />
  * The starting {@literal domainType} is used for mapping the {@link Query} provided via {@code matching}, as well as
  * the {@link Update} via {@code apply} into the MongoDB specific representations. The collection to operate on is by
  * default derived from the initial {@literal domainType} and can be defined there via
@@ -59,6 +59,10 @@ public interface ExecutableUpdateOperation {
 
 	/**
 	 * Trigger findAndModify execution by calling one of the terminating methods.
+	 *
+	 * @author Christoph Strobl
+	 * @author Mark Paluch
+	 * @since 2.0
 	 */
 	interface TerminatingFindAndModify<T> {
 
@@ -81,7 +85,12 @@ default Optional<T> findAndModify() {
 	}
 
 	/**
-	 * Trigger findAndReplace execution by calling one of the terminating methods.
+	 * Trigger
+	 * <a href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/">findOneAndReplace<a/>
+	 * execution by calling one of the terminating methods.
+	 *
+	 * @author Mark Paluch
+	 * @since 2.1
 	 */
 	interface TerminatingFindAndReplace<T> {
 
@@ -158,7 +167,7 @@ interface UpdateWithUpdate<T> {
 		 * @throws IllegalArgumentException if options is {@literal null}.
 		 * @since 2.1
 		 */
-		FindAndReplaceWithOptions<T> replaceWith(T replacement);
+		FindAndReplaceWithProjection<T> replaceWith(T replacement);
 	}
 
 	/**
@@ -220,6 +229,7 @@ interface FindAndModifyWithOptions<T> {
 	 * Define {@link FindAndReplaceOptions}.
 	 *
 	 * @author Mark Paluch
+	 * @author Christoph Strobl
 	 * @since 2.1
 	 */
 	interface FindAndReplaceWithOptions<T> extends TerminatingFindAndReplace<T> {
@@ -231,7 +241,28 @@ interface FindAndReplaceWithOptions<T> extends TerminatingFindAndReplace<T> {
 		 * @return new instance of {@link FindAndReplaceOptions}.
 		 * @throws IllegalArgumentException if options is {@literal null}.
 		 */
-		TerminatingFindAndReplace<T> withOptions(FindAndReplaceOptions options);
+		FindAndReplaceWithProjection<T> withOptions(FindAndReplaceOptions options);
+	}
+
+	/**
+	 * Result type override (Optional).
+	 *
+	 * @author Christoph Strobl
+	 * @since 2.1
+	 */
+	interface FindAndReplaceWithProjection<T> extends FindAndReplaceWithOptions<T> {
+
+		/**
+		 * Define the target type fields should be mapped to. <br />
+		 * Skip this step if you are anyway only interested in the original domain type.
+		 *
+		 * @param resultType must not be {@literal null}.
+		 * @param <R> result type.
+		 * @return new instance of {@link FindAndReplaceWithProjection}.
+		 * @throws IllegalArgumentException if resultType is {@literal null}.
+		 */
+		<R> FindAndReplaceWithOptions<R> as(Class<R> resultType);
+
 	}
 
 	/**

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

@@ -51,7 +51,7 @@ public <T> ExecutableUpdate<T> update(Class<T> domainType) {
 
 		Assert.notNull(domainType, "DomainType must not be null!");
 
-		return new ExecutableUpdateSupport<>(template, domainType, ALL_QUERY, null, null, null, null, null);
+		return new ExecutableUpdateSupport<>(template, domainType, ALL_QUERY, null, null, null, null, null, domainType);
 	}
 
 	/**
@@ -60,17 +60,19 @@ public <T> ExecutableUpdate<T> update(Class<T> domainType) {
 	 */
 	@RequiredArgsConstructor
 	@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
-	static class ExecutableUpdateSupport<T> implements ExecutableUpdate<T>, UpdateWithCollection<T>, UpdateWithQuery<T>,
-			TerminatingUpdate<T>, FindAndReplaceWithOptions<T>, TerminatingFindAndReplace<T> {
+	static class ExecutableUpdateSupport<T>
+			implements ExecutableUpdate<T>, UpdateWithCollection<T>, UpdateWithQuery<T>, TerminatingUpdate<T>,
+			FindAndReplaceWithOptions<T>, TerminatingFindAndReplace<T>, FindAndReplaceWithProjection<T> {
 
 		@NonNull MongoTemplate template;
-		@NonNull Class<T> domainType;
+		@NonNull Class domainType;
 		Query query;
 		@Nullable Update update;
 		@Nullable String collection;
 		@Nullable FindAndModifyOptions findAndModifyOptions;
 		@Nullable FindAndReplaceOptions findAndReplaceOptions;
-		@Nullable T replacement;
+		@Nullable Object replacement;
+		@NonNull Class<T> targetType;
 
 		/*
 		 * (non-Javadoc)
@@ -82,7 +84,7 @@ public TerminatingUpdate<T> apply(Update update) {
 			Assert.notNull(update, "Update must not be null!");
 
 			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, findAndModifyOptions,
-					findAndReplaceOptions, replacement);
+					findAndReplaceOptions, replacement, targetType);
 		}
 
 		/*
@@ -95,7 +97,7 @@ public UpdateWithQuery<T> inCollection(String collection) {
 			Assert.hasText(collection, "Collection must not be null nor empty!");
 
 			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, findAndModifyOptions,
-					findAndReplaceOptions, replacement);
+					findAndReplaceOptions, replacement, targetType);
 		}
 
 		/*
@@ -108,33 +110,33 @@ public TerminatingFindAndModify<T> withOptions(FindAndModifyOptions options) {
 			Assert.notNull(options, "Options must not be null!");
 
 			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, options,
-					findAndReplaceOptions, replacement);
+					findAndReplaceOptions, replacement, targetType);
 		}
 
 		/*
 		 * (non-Javadoc)
 		 * @see org.springframework.data.mongodb.core.ExecutableUpdateOperation.UpdateWithUpdate#replaceWith(Object)
 		 */
 		@Override
-		public FindAndReplaceWithOptions<T> replaceWith(T replacement) {
+		public FindAndReplaceWithProjection<T> replaceWith(T replacement) {
 
 			Assert.notNull(replacement, "Replacement must not be null!");
 
 			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, findAndModifyOptions,
-					findAndReplaceOptions, replacement);
+					findAndReplaceOptions, replacement, targetType);
 		}
 
 		/*
 		 * (non-Javadoc)
 		 * @see org.springframework.data.mongodb.core.ExecutableUpdateOperation.FindAndReplaceWithOptions#withOptions(org.springframework.data.mongodb.core.FindAndReplaceOptions)
 		 */
 		@Override
-		public TerminatingFindAndReplace<T> withOptions(FindAndReplaceOptions options) {
+		public FindAndReplaceWithProjection<T> withOptions(FindAndReplaceOptions options) {
 
 			Assert.notNull(options, "Options must not be null!");
 
 			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, findAndModifyOptions,
-					options, replacement);
+					options, replacement, targetType);
 		}
 
 		/*
@@ -147,7 +149,20 @@ public UpdateWithUpdate<T> matching(Query query) {
 			Assert.notNull(query, "Query must not be null!");
 
 			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, findAndModifyOptions,
-					findAndReplaceOptions, replacement);
+					findAndReplaceOptions, replacement, targetType);
+		}
+
+		/*
+		 * (non-Javadoc)
+		 * @see org.springframework.data.mongodb.core.ReactiveUpdateOperation.FindAndReplaceWithProjection#as(java.lang.Class)
+		 */
+		@Override
+		public <R> FindAndReplaceWithOptions<R> as(Class<R> resultType) {
+
+			Assert.notNull(resultType, "ResultType must not be null!");
+
+			return new ExecutableUpdateSupport<>(template, domainType, query, update, collection, findAndModifyOptions,
+					findAndReplaceOptions, replacement, resultType);
 		}
 
 		/*
@@ -183,8 +198,9 @@ public UpdateResult upsert() {
 		 */
 		@Override
 		public @Nullable T findAndModifyValue() {
+
 			return template.findAndModify(query, update,
-					findAndModifyOptions != null ? findAndModifyOptions : new FindAndModifyOptions(), domainType,
+					findAndModifyOptions != null ? findAndModifyOptions : new FindAndModifyOptions(), targetType,
 					getCollectionName());
 		}
 
@@ -194,9 +210,10 @@ public UpdateResult upsert() {
 		 */
 		@Override
 		public @Nullable T findAndReplaceValue() {
-			return template.findAndReplace(query, replacement,
-					findAndReplaceOptions != null ? findAndReplaceOptions : new FindAndReplaceOptions(), domainType,
-					getCollectionName());
+
+			return (T) template.findAndReplace(query, replacement,
+					findAndReplaceOptions != null ? findAndReplaceOptions : FindAndReplaceOptions.empty(), domainType,
+					getCollectionName(), targetType);
 		}
 
 		private UpdateResult doUpdate(boolean multi, boolean upsert) {

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

@@ -36,15 +36,17 @@ public class FindAndModifyOptions {
 	/**
 	 * Static factory method to create a FindAndModifyOptions instance
 	 *
-	 * @return a new instance
+	 * @return new instance of {@link FindAndModifyOptions}.
 	 */
 	public static FindAndModifyOptions options() {
 		return new FindAndModifyOptions();
 	}
 
 	/**
-	 * @param options
-	 * @return
+	 * Create new {@link FindAndModifyOptions} based on option of given {@litearl source}.
+	 * 
+	 * @param source can be {@literal null}.
+	 * @return new instance of {@link FindAndModifyOptions}.
 	 * @since 2.0
 	 */
 	public static FindAndModifyOptions of(@Nullable FindAndModifyOptions source) {

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

@@ -15,90 +15,95 @@
  */
 package org.springframework.data.mongodb.core;
 
-import java.util.Optional;
-
-import org.springframework.data.mongodb.core.query.Collation;
-import org.springframework.lang.Nullable;
-
 /**
  * Options for
  * <a href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/">findOneAndReplace<a/>.
+ * <br />
+ * Defaults to
+ * <dl>
+ * <dt>returnNew</dt>
+ * <dd>false</dd>
+ * <dt>upsert</dt>
+ * <dd>false</dd>
+ * </dl>
  *
  * @author Mark Paluch
+ * @author Christoph Strobl
  * @since 2.1
  */
 public class FindAndReplaceOptions {
 
 	private boolean returnNew;
 	private boolean upsert;
 
-	private @Nullable Collation collation;
-
 	/**
 	 * Static factory method to create a {@link FindAndReplaceOptions} instance.
+	 * <dl>
+	 * <dt>returnNew</dt>
+	 * <dd>false</dd>
+	 * <dt>upsert</dt>
+	 * <dd>false</dd>
+	 * </dl>
 	 *
-	 * @return a new instance
+	 * @return new instance of {@link FindAndReplaceOptions}.
 	 */
 	public static FindAndReplaceOptions options() {
 		return new FindAndReplaceOptions();
 	}
 
 	/**
-	 * @param options
-	 * @return
+	 * Static factory method to create a {@link FindAndReplaceOptions} instance with
+	 * <dl>
+	 * <dt>returnNew</dt>
+	 * <dd>false</dd>
+	 * <dt>upsert</dt>
+	 * <dd>false</dd>
+	 * </dl>
+	 *
+	 * @return new instance of {@link FindAndReplaceOptions}.
 	 */
-	public static FindAndReplaceOptions of(@Nullable FindAndReplaceOptions source) {
-
-		FindAndReplaceOptions options = new FindAndReplaceOptions();
-
-		if (source == null) {
-			return options;
-		}
-
-		options.returnNew = source.returnNew;
-		options.upsert = source.upsert;
-		options.collation = source.collation;
-
-		return options;
+	public static FindAndReplaceOptions empty() {
+		return new FindAndReplaceOptions();
 	}
 
-	public FindAndReplaceOptions returnNew(boolean returnNew) {
-		this.returnNew = returnNew;
-		return this;
-	}
+	/**
+	 * Return the replacement document.
+	 *
+	 * @return this.
+	 */
+	public FindAndReplaceOptions returnNew() {
 
-	public FindAndReplaceOptions upsert(boolean upsert) {
-		this.upsert = upsert;
+		this.returnNew = true;
 		return this;
 	}
 
 	/**
-	 * Define the {@link Collation} specifying language-specific rules for string comparison.
+	 * Insert a new document if not exists.
 	 *
-	 * @param collation
-	 * @return
+	 * @return this.
 	 */
-	public FindAndReplaceOptions collation(@Nullable Collation collation) {
+	public FindAndReplaceOptions upsert() {
 
-		this.collation = collation;
+		this.upsert = true;
 		return this;
 	}
 
+	/**
+	 * Get the bit indicating to return the replacement document.
+	 *
+	 * @return
+	 */
 	public boolean isReturnNew() {
 		return returnNew;
 	}
 
-	public boolean isUpsert() {
-		return upsert;
-	}
-
 	/**
-	 * Get the {@link Collation} specifying language-specific rules for string comparison.
+	 * Get the bit indicating if to create a new document if not exists.
 	 *
 	 * @return
 	 */
-	public Optional<Collation> getCollation() {
-		return Optional.ofNullable(collation);
+	public boolean isUpsert() {
+		return upsert;
 	}
 
 }