Updated FindOperation, Options and Iterables

Modifiers have now been deprecated and made first class
options.

JAVA-2427

Author: rozza

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

@@ -92,7 +92,9 @@ public interface FindIterable<T> extends MongoIterable<T> {
      * @param modifiers the query modifiers to apply, which may be null.
      * @return this
      * @mongodb.driver.manual reference/operator/query-modifier/ Query Modifiers
+     * @deprecated use the individual setters instead
      */
+    @Deprecated
     FindIterable<T> modifiers(Bson modifiers);
 
     /**
@@ -165,4 +167,80 @@ public interface FindIterable<T> extends MongoIterable<T> {
      * @mongodb.server.release 3.4
      */
     FindIterable<T> collation(Collation collation);
+
+    /**
+     * Sets the comment to the query. A null value means no comment is set.
+     *
+     * @param comment the comment
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> comment(String comment);
+
+    /**
+     * Sets the hint for which index to use. A null value means no hint is set.
+     *
+     * @param hint the hint
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> hint(Bson hint);
+
+    /**
+     * Sets the exclusive upper bound for a specific index. A null value means no max is set.
+     *
+     * @param max the max
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> max(Bson max);
+
+    /**
+     * Sets the minimum inclusive lower bound for a specific index. A null value means no max is set.
+     *
+     * @param min the min
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> min(Bson min);
+
+    /**
+     * Sets the maximum number of documents or index keys to scan when executing the query.
+     *
+     * A zero value or less will be ignored, and indicates that the driver should respect the server's default value.
+     *
+     * @param maxScan the maxScan
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> maxScan(long maxScan);
+
+    /**
+     * Sets the returnKey. If true the find operation will return only the index keys in the resulting documents.
+     *
+     * @param returnKey the returnKey
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> returnKey(boolean returnKey);
+
+    /**
+     * Sets the showRecordId. Set to true to add a field {@code $recordId} to the returned documents.
+     *
+     * @param showRecordId the showRecordId
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> showRecordId(boolean showRecordId);
+
+    /**
+     * Sets the snapshot.
+     *
+     * If true it prevents the cursor from returning a document more than once because of an intervening write operation.
+     *
+     * @param snapshot the snapshot
+     * @return this
+     * @since 3.5
+     */
+    FindIterable<T> snapshot(boolean snapshot);
 }

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

@@ -38,6 +38,8 @@
 import static com.mongodb.assertions.Assertions.notNull;
 import static java.util.concurrent.TimeUnit.MILLISECONDS;
 
+
+@SuppressWarnings("deprecation")
 class FindIterableImpl<TDocument, TResult> implements FindIterable<TResult> {
     private final MongoNamespace namespace;
     private final Class<TDocument> documentClass;
@@ -149,6 +151,54 @@ public FindIterable<TResult> cursorType(final CursorType cursorType) {
         return this;
     }
 
+    @Override
+    public FindIterable<TResult> comment(final String comment) {
+        findOptions.comment(comment);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> hint(final Bson hint) {
+        findOptions.hint(hint);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> max(final Bson max) {
+        findOptions.max(max);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> min(final Bson min) {
+        findOptions.min(min);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> maxScan(final long maxScan) {
+        findOptions.maxScan(maxScan);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> returnKey(final boolean returnKey) {
+        findOptions.returnKey(returnKey);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> showRecordId(final boolean showRecordId) {
+        findOptions.showRecordId(showRecordId);
+        return this;
+    }
+
+    @Override
+    public FindIterable<TResult> snapshot(final boolean snapshot) {
+        findOptions.snapshot(snapshot);
+        return this;
+    }
+
     @Override
     public void first(final SingleResultCallback<TResult> callback) {
         notNull("callback", callback);
@@ -205,7 +255,15 @@ private FindOperation<TResult> createQueryOperation() {
                .partial(findOptions.isPartial())
                .slaveOk(readPreference.isSlaveOk())
                .readConcern(readConcern)
-               .collation(findOptions.getCollation());
+               .collation(findOptions.getCollation())
+               .comment(findOptions.getComment())
+               .hint(toBsonDocument(findOptions.getHint()))
+               .min(toBsonDocument(findOptions.getMin()))
+               .max(toBsonDocument(findOptions.getMax()))
+               .maxScan(findOptions.getMaxScan())
+               .returnKey(findOptions.isReturnKey())
+               .showRecordId(findOptions.isShowRecordId())
+               .snapshot(findOptions.isSnapshot());
     }
 
     private BsonDocument toBsonDocument(final Bson document) {

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

@@ -52,6 +52,7 @@ class FindIterableSpecification extends Specification {
     def readConcern = ReadConcern.DEFAULT
     def collation = Collation.builder().locale('en').build()
 
+    @SuppressWarnings('deprecation')
     def 'should build the expected findOperation'() {
         given:
         def cursor = Stub(AsyncBatchCursor) {
@@ -73,6 +74,14 @@ class FindIterableSpecification extends Specification {
                 .noCursorTimeout(false)
                 .partial(false)
                 .collation(null)
+                .comment('my comment')
+                .hint(new Document('hint', 1))
+                .min(new Document('min', 1))
+                .max(new Document('max', 1))
+                .maxScan(42L)
+                .returnKey(false)
+                .showRecordId(false)
+                .snapshot(false)
         def findIterable = new FindIterableImpl(namespace, Document, Document, codecRegistry, readPreference, readConcern, executor,
                                                 new Document('filter', 1), findOptions)
 
@@ -95,6 +104,14 @@ class FindIterableSpecification extends Specification {
                 .skip(10)
                 .cursorType(CursorType.NonTailable)
                 .slaveOk(true)
+                .comment('my comment')
+                .hint(new BsonDocument('hint', new BsonInt32(1)))
+                .min(new BsonDocument('min', new BsonInt32(1)))
+                .max(new BsonDocument('max', new BsonInt32(1)))
+                .maxScan(42L)
+                .returnKey(false)
+                .showRecordId(false)
+                .snapshot(false)
         )
         readPreference == secondary()
 
@@ -113,6 +130,14 @@ class FindIterableSpecification extends Specification {
                 .noCursorTimeout(true)
                 .partial(true)
                 .collation(collation)
+                .comment('alt comment')
+                .hint(new Document('hint', 2))
+                .min(new Document('min', 2))
+                .max(new Document('max', 2))
+                .maxScan(88L)
+                .returnKey(true)
+                .showRecordId(true)
+                .snapshot(true)
                 .into([]) { result, t -> }
 
         operation = executor.getReadOperation() as FindOperation<Document>
@@ -134,6 +159,14 @@ class FindIterableSpecification extends Specification {
                 .partial(true)
                 .slaveOk(true)
                 .collation(collation)
+                .comment('alt comment')
+                .hint(new BsonDocument('hint', new BsonInt32(2)))
+                .min(new BsonDocument('min', new BsonInt32(2)))
+                .max(new BsonDocument('max', new BsonInt32(2)))
+                .maxScan(88L)
+                .returnKey(true)
+                .showRecordId(true)
+                .snapshot(true)
         )
     }