Added hintString to FindIterable

Also removed deprecations for count hintString

JAVA-3441

Author: rozza

driver-async/src/main/com/mongodb/async/client/FindIterable.java

@@ -189,6 +189,17 @@ public interface FindIterable<T> extends MongoIterable<T> {
      */
     FindIterable<T> hint(@Nullable Bson hint);
 
+    /**
+     * Sets the hint to apply.
+     *
+     * <p>Note: If {@link FindIterable#hint(Bson)} is set that will be used instead of any hint string.</p>
+     *
+     * @param hint the name of the index which should be used for the operation
+     * @return this
+     * @since 3.12
+     */
+    FindIterable<T> hintString(@Nullable String hint);
+
     /**
      * Sets the exclusive upper bound for a specific index. A null value means no max is set.
      *

driver-async/src/main/com/mongodb/async/client/FindIterableImpl.java

@@ -154,6 +154,12 @@ public FindIterable<TResult> hint(@Nullable final Bson hint) {
         return this;
     }
 
+    @Override
+    public FindIterable<TResult> hintString(@Nullable final String hint) {
+        findOptions.hintString(hint);
+        return this;
+    }
+
     @Override
     public FindIterable<TResult> max(@Nullable final Bson max) {
         findOptions.max(max);

driver-async/src/test/unit/com/mongodb/async/client/FindIterableSpecification.groovy

@@ -28,6 +28,7 @@ import com.mongodb.client.model.Collation
 import com.mongodb.operation.FindOperation
 import org.bson.BsonDocument
 import org.bson.BsonInt32
+import org.bson.BsonString
 import org.bson.Document
 import org.bson.codecs.BsonValueCodecProvider
 import org.bson.codecs.DocumentCodec
@@ -76,7 +77,7 @@ class FindIterableSpecification extends Specification {
                 .partial(false)
                 .collation(null)
                 .comment('my comment')
-                .hint(new Document('hint', 1))
+                .hintString('a_1')
                 .min(new Document('min', 1))
                 .max(new Document('max', 1))
                 .maxScan(42L)
@@ -104,7 +105,7 @@ class FindIterableSpecification extends Specification {
                 .cursorType(CursorType.NonTailable)
                 .slaveOk(true)
                 .comment('my comment')
-                .hint(new BsonDocument('hint', new BsonInt32(1)))
+                .hint(new BsonString('a_1'))
                 .min(new BsonDocument('min', new BsonInt32(1)))
                 .max(new BsonDocument('max', new BsonInt32(1)))
                 .maxScan(42L)

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

@@ -51,9 +51,7 @@ public Bson getHint() {
      * Gets the hint string to apply.
      *
      * @return the hint string, which should be the name of an existing index
-     * @deprecated Prefer {@link #getHint()}
      */
-    @Deprecated
     @Nullable
     public String getHintString() {
         return hintString;
@@ -73,11 +71,11 @@ public CountOptions hint(@Nullable final Bson hint) {
     /**
      * Sets the hint to apply.
      *
+     * <p>Note: If {@link CountOptions#hint(Bson)} is set that will be used instead of any hint string.</p>
+     *
      * @param hint the name of the index which should be used for the operation
      * @return this
-     * @deprecated Prefer {@link #hint(Bson)}
      */
-    @Deprecated
     public CountOptions hintString(@Nullable final String hint) {
         this.hintString = hint;
         return this;

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

@@ -50,6 +50,7 @@ public final class FindOptions {
     private Collation collation;
     private String comment;
     private Bson hint;
+    private String hintString;
     private Bson max;
     private Bson min;
     private long maxScan;
@@ -84,6 +85,7 @@ public FindOptions(final FindOptions from) {
         partial = from.partial;
         comment = from.comment;
         hint = from.hint;
+        hintString = from.hintString;
         max = from.max;
         min = from.min;
         maxScan = from.maxScan;
@@ -453,6 +455,29 @@ public FindOptions hint(@Nullable final Bson hint) {
         return this;
     }
 
+    /**
+     * Gets the hint string to apply.
+     *
+     * @return the hint string, which should be the name of an existing index
+     * @since 3.12
+     */
+    @Nullable
+    public String getHintString() {
+        return hintString;
+    }
+
+    /**
+     * Sets the hint to apply.
+     *
+     * @param hint the name of the index which should be used for the operation
+     * @return this
+     * @since 3.12
+     */
+    public FindOptions hintString(@Nullable final String hint) {
+        this.hintString = hint;
+        return this;
+    }
+
     /**
      * Returns the exclusive upper bound for a specific index. By default there is no max bound.
      *

driver-core/src/main/com/mongodb/internal/operation/Operations.java

@@ -147,7 +147,7 @@ <TResult> FindOperation<TResult> find(final MongoNamespace findNamespace, final
     @SuppressWarnings("deprecation")
     private <TResult> FindOperation<TResult> createFindOperation(final MongoNamespace findNamespace, final Bson filter,
                                                                  final Class<TResult> resultClass, final FindOptions options) {
-        return new FindOperation<TResult>(findNamespace, codecRegistry.get(resultClass))
+        FindOperation<TResult> operation = new FindOperation<TResult>(findNamespace, codecRegistry.get(resultClass))
                 .retryReads(retryReads)
                 .filter(filter == null ? new BsonDocument() : filter.toBsonDocument(documentClass, codecRegistry))
                 .batchSize(options.getBatchSize())
@@ -165,13 +165,19 @@ private <TResult> FindOperation<TResult> createFindOperation(final MongoNamespac
                 .slaveOk(readPreference.isSlaveOk())
                 .collation(options.getCollation())
                 .comment(options.getComment())
-                .hint(toBsonDocumentOrNull(options.getHint()))
                 .min(toBsonDocumentOrNull(options.getMin()))
                 .max(toBsonDocumentOrNull(options.getMax()))
                 .maxScan(options.getMaxScan())
                 .returnKey(options.isReturnKey())
                 .showRecordId(options.isShowRecordId())
                 .snapshot(options.isSnapshot());
+
+        if (options.getHint() != null) {
+            operation.hint(toBsonDocument(options.getHint()));
+        } else if (options.getHintString() != null) {
+            operation.hint(new BsonString(options.getHintString()));
+        }
+        return operation;
     }
 
     <TResult> DistinctOperation<TResult> distinct(final String fieldName, final Bson filter,

driver-core/src/main/com/mongodb/operation/FindOperation.java

@@ -109,7 +109,7 @@ public class FindOperation<T> implements AsyncReadOperation<AsyncBatchCursor<T>>
     private boolean partial;
     private Collation collation;
     private String comment;
-    private BsonDocument hint;
+    private BsonValue hint;
     private BsonDocument max;
     private BsonDocument min;
     private long maxScan;
@@ -529,7 +529,7 @@ public FindOperation<T> comment(final String comment) {
      * @return the hint
      * @since 3.5
      */
-    public BsonDocument getHint() {
+    public BsonValue getHint() {
         return hint;
     }
 
@@ -540,7 +540,7 @@ public BsonDocument getHint() {
      * @return this
      * @since 3.5
      */
-    public FindOperation<T> hint(final BsonDocument hint) {
+    public FindOperation<T> hint(final BsonValue hint) {
         this.hint = hint;
         return this;
     }

driver-core/src/test/functional/com/mongodb/operation/FindOperationSpecification.groovy

@@ -86,6 +86,7 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
         operation.getFilter() == null
         operation.getMaxTime(MILLISECONDS) == 0
         operation.getMaxAwaitTime(MILLISECONDS) == 0
+        operation.getHint() == null
         operation.getLimit() == 0
         operation.getSkip() == 0
         operation.getBatchSize() == 0
@@ -103,6 +104,7 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
         def filter = new BsonDocument('filter', new BsonInt32(1))
         def projection = new BsonDocument('projection', new BsonInt32(1))
         def modifiers = new BsonDocument('modifiers', new BsonInt32(1))
+        def hint = new BsonString('a_1')
 
         when:
         FindOperation operation = new FindOperation<Document>(getNamespace(), new DocumentCodec())
@@ -111,6 +113,7 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
                 .filter(filter)
                 .limit(20)
                 .skip(30)
+                .hint(hint)
                 .batchSize(40)
                 .projection(projection)
                 .modifiers(modifiers)
@@ -127,6 +130,7 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
         operation.getMaxAwaitTime(MILLISECONDS) == 20000
         operation.getLimit() == 20
         operation.getSkip() == 30
+        operation.getHint() == hint
         operation.getBatchSize() == 40
         operation.getProjection() == projection
         operation.getModifiers() == modifiers
@@ -433,11 +437,15 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
 
     def 'should apply $hint'() {
         given:
-        def hint = new BsonDocument('a', new BsonInt32(1))
-        collectionHelper.createIndex(hint)
+        def index = new BsonDocument('a', new BsonInt32(1))
+        collectionHelper.createIndex(index)
 
         def operation = new FindOperation<Document>(getNamespace(), new DocumentCodec())
-                .modifiers(new BsonDocument('$hint', hint))
+        if (useModifer) {
+            operation.modifiers(new BsonDocument('$hint', hint))
+        } else {
+            operation.hint(hint)
+        }
         operation = async ? operation.asExplainableOperationAsync(QUERY_PLANNER) :
                 operation.asExplainableOperation(QUERY_PLANNER)
 
@@ -446,13 +454,14 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
 
         then:
         if (serverVersionAtLeast(3, 0)) {
-            assertEquals(hint, QueryOperationHelper.getKeyPattern(explainPlan))
+            assertEquals(index, QueryOperationHelper.getKeyPattern(explainPlan))
         } else {
             assertEquals(new BsonString('BtreeCursor a_1'), explainPlan.cursor)
         }
 
         where:
-        async << [true, false]
+        [async, useModifer, hint] << [[true, false], [true, false], [new BsonDocument('a', new BsonInt32(1)),
+                                                                     new BsonString('a_1')]].combinations()
     }
 
     @IgnoreIf({ isSharded() })

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

@@ -18,6 +18,7 @@ package com.mongodb.client.model
 
 import com.mongodb.CursorType
 import org.bson.BsonDocument
+import org.bson.Document
 import spock.lang.Specification
 
 import static java.util.concurrent.TimeUnit.MILLISECONDS
@@ -35,6 +36,8 @@ class FindOptionsSpecification extends Specification {
         options.getMaxAwaitTime(MILLISECONDS) == 0
         options.getProjection() == null
         options.getSort() == null
+        options.getHint() == null
+        options.getHintString() == null
         options.getLimit() == 0
         options.getSkip() == 0
         options.getBatchSize() == 0
@@ -172,4 +175,20 @@ class FindOptionsSpecification extends Specification {
         then:
         options.getMaxAwaitTime(SECONDS) == 1
     }
+
+    def 'should set hint'() {
+        expect:
+        new FindOptions().hint(hint).getHint() == hint
+
+        where:
+        hint << [null, new BsonDocument(), new Document('a', 1)]
+    }
+
+    def 'should set hintString'() {
+        expect:
+        new FindOptions().hintString(hintString).getHintString() == hintString
+
+        where:
+        hintString << [null, 'a_1']
+    }
 }

driver-legacy/src/main/com/mongodb/client/model/DBCollectionCountOptions.java

@@ -62,9 +62,7 @@ public DBObject getHint() {
      * Gets the hint string to apply.
      *
      * @return the hint string, which should be the name of an existing index
-     * @deprecated Prefer {@link #getHint()}
      */
-    @Deprecated
     @Nullable
     public String getHintString() {
         return hintString;
@@ -86,9 +84,7 @@ public DBCollectionCountOptions hint(@Nullable final DBObject hint) {
      *
      * @param hint the name of the index which should be used for the operation
      * @return this
-     * @deprecated Prefer {@link #hint(DBObject)}
      */
-    @Deprecated
     public DBCollectionCountOptions hintString(@Nullable final String hint) {
         this.hintString = hint;
         return this;