DATAMONGO-2319 - Deprecate Query.withHint(String) and introduce withHint(Document).

The $hint operator is deprecated since MongoDB 3.2 so we're now deprecating Query.withHint() accepting a String as the String is expected to be a valid document. Therefore, we're introducing withHint(Document) to accept a type-safe representation of query hints.

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

@@ -142,14 +142,32 @@ public class Query {
 	}
 
 	/**
-	 * Configures the query to use the given hint when being executed.
+	 * Configures the query to use the given hint when being executed. {@code hint} is parsed as {@link Document}.
 	 *
-	 * @param name must not be {@literal null} or empty.
+	 * @param hint must not be {@literal null} or empty.
 	 * @return
+	 * @see Document#parse(String)
+	 * @deprecated since 2.2, use {@link #withHint(Document)}
 	 */
-	public Query withHint(String name) {
-		Assert.hasText(name, "Hint must not be empty or null!");
-		this.hint = name;
+	@Deprecated
+	public Query withHint(String hint) {
+
+		Assert.hasText(hint, "Hint must not be empty or null!");
+		this.hint = hint;
+		return this;
+	}
+
+	/**
+	 * Configures the query to use the given {@link Document hint} when being executed.
+	 *
+	 * @param hint must not be {@literal null}.
+	 * @return
+	 * @since 2.2
+	 */
+	public Query withHint(Document hint) {
+
+		Assert.notNull(hint, "Hint must not be null!");
+		this.hint = hint.toJson();
 		return this;
 	}
 
@@ -284,8 +302,10 @@ public class Query {
 
 	/**
 	 * @return
+	 * @deprecated since 2.2. Return type to be changed to {@link Document}.
 	 */
 	@Nullable
+	@Deprecated
 	public String getHint() {
 		return hint;
 	}

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

@@ -73,6 +73,15 @@ public class QueryCursorPreparerUnitTests {
 		verify(cursor).hint(new Document("age", 1));
 	}
 
+	@Test // DATAMONGO-2319
+	public void appliesDocumentHintsCorrectly() {
+
+		Query query = query(where("foo").is("bar")).withHint(Document.parse("{ age: 1 }"));
+		prepare(query);
+
+		verify(cursor).hint(new Document("age", 1));
+	}
+
 	@Test // DATAMONGO-957
 	public void doesNotApplyMetaWhenEmpty() {