Deprecate DBCollectionFindOptions#getModifiers

Replace with per-modifier properties:

* comment
* hint
* min
* max
* returnKey
* showRecordId

JAVA-3022

Author: jyemin

driver-legacy/src/main/com/mongodb/DBCursor.java

@@ -349,7 +349,7 @@ public DBCursor addSpecial(@Nullable final String name, @Nullable final Object v
      * @since 2.12
      */
     public DBCursor comment(final String comment) {
-        findOptions.getModifiers().put("$comment", comment);
+        findOptions.comment(comment);
         return this;
     }
 
@@ -378,7 +378,7 @@ public DBCursor maxScan(final int max) {
      * @since 2.12
      */
     public DBCursor max(final DBObject max) {
-        findOptions.getModifiers().put("$max", max);
+        findOptions.max(max);
         return this;
     }
 
@@ -391,7 +391,7 @@ public DBCursor max(final DBObject max) {
      * @since 2.12
      */
     public DBCursor min(final DBObject min) {
-        findOptions.getModifiers().put("$min", min);
+        findOptions.min(min);
         return this;
     }
 
@@ -403,7 +403,7 @@ public DBCursor min(final DBObject min) {
      * @since 2.12
      */
     public DBCursor returnKey() {
-        findOptions.getModifiers().put("$returnKey", true);
+        findOptions.returnKey(true);
         return this;
     }
 
@@ -428,7 +428,7 @@ public DBCursor showDiskLoc() {
      * @mongodb.driver.manual reference/operator/meta/hint/ $hint
      */
     public DBCursor hint(final DBObject indexKeys) {
-        findOptions.getModifiers().put("$hint", indexKeys);
+        findOptions.hint(indexKeys);
         return this;
     }
 
@@ -559,7 +559,13 @@ private FindOperation<DBObject> getQueryOperation(final Decoder<DBObject> decode
                                                 .modifiers(collection.wrapAllowNull(findOptions.getModifiers()))
                                                 .projection(collection.wrapAllowNull(findOptions.getProjection()))
                                                 .sort(collection.wrapAllowNull(findOptions.getSort()))
-                                                .collation(findOptions.getCollation());
+                                                .collation(findOptions.getCollation())
+                                                .comment(findOptions.getComment())
+                                                .hint(collection.wrapAllowNull(findOptions.getHint()))
+                                                .min(collection.wrapAllowNull(findOptions.getMin()))
+                                                .max(collection.wrapAllowNull(findOptions.getMax()))
+                                                .returnKey(findOptions.isReturnKey())
+                                                .showRecordId(findOptions.isShowRecordId());
 
         if ((this.options & Bytes.QUERYOPTION_TAILABLE) != 0) {
             if ((this.options & Bytes.QUERYOPTION_AWAITDATA) != 0) {
@@ -1080,7 +1086,7 @@ private DBCollectionCountOptions getDbCollectionCountOptions() {
                 .collation(getCollation())
                 .maxTime(findOptions.getMaxTime(MILLISECONDS), MILLISECONDS);
 
-        Object hint = findOptions.getModifiers().get("$hint");
+        Object hint = findOptions.getHint() != null ? findOptions.getHint() : findOptions.getModifiers().get("$hint");
         if (hint != null) {
             if (hint instanceof String) {
                 countOptions.hintString((String) hint);

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

@@ -51,6 +51,12 @@ public final class DBCollectionFindOptions {
     private ReadPreference readPreference;
     private ReadConcern readConcern;
     private Collation collation;
+    private String comment;
+    private DBObject hint;
+    private DBObject max;
+    private DBObject min;
+    private boolean returnKey;
+    private boolean showRecordId;
 
     /**
      * Construct a new instance
@@ -80,6 +86,12 @@ public DBCollectionFindOptions copy() {
         copiedOptions.readPreference(readPreference);
         copiedOptions.readConcern(readConcern);
         copiedOptions.collation(collation);
+        copiedOptions.comment(comment);
+        copiedOptions.hint(hint);
+        copiedOptions.max(max);
+        copiedOptions.min(min);
+        copiedOptions.returnKey(returnKey);
+        copiedOptions.showRecordId(showRecordId);
         return copiedOptions;
     }
 
@@ -435,4 +447,145 @@ public DBCollectionFindOptions collation(@Nullable final Collation collation) {
         this.collation = collation;
         return this;
     }
+
+    /**
+     * Returns the comment to send with the query. The default is not to include a comment with the query.
+     *
+     * @return the comment
+     * @since 3.9
+     */
+    @Nullable
+    public String getComment() {
+        return comment;
+    }
+
+    /**
+     * Sets the comment to the query. A null value means no comment is set.
+     *
+     * @param comment the comment
+     * @return this
+     * @since 3.9
+     */
+    public DBCollectionFindOptions comment(@Nullable final String comment) {
+        this.comment = comment;
+        return this;
+    }
+
+    /**
+     * Returns the hint for which index to use. The default is not to set a hint.
+     *
+     * @return the hint
+     * @since 3.9
+     */
+    @Nullable
+    public DBObject getHint() {
+        return hint;
+    }
+
+    /**
+     * Sets the hint for which index to use. A null value means no hint is set.
+     *
+     * @param hint the hint
+     * @return this
+     * @since 3.9
+     */
+    public DBCollectionFindOptions hint(@Nullable final DBObject hint) {
+        this.hint = hint;
+        return this;
+    }
+
+    /**
+     * Returns the exclusive upper bound for a specific index. By default there is no max bound.
+     *
+     * @return the max
+     * @since 3.9
+     */
+    @Nullable
+    public DBObject getMax() {
+        return max;
+    }
+
+    /**
+     * 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.9
+     */
+    public DBCollectionFindOptions max(@Nullable final DBObject max) {
+        this.max = max;
+        return this;
+    }
+
+    /**
+     * Returns the minimum inclusive lower bound for a specific index. By default there is no min bound.
+     *
+     * @return the min
+     * @since 3.9
+     */
+    @Nullable
+    public DBObject getMin() {
+        return min;
+    }
+
+    /**
+     * 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.9
+     */
+    public DBCollectionFindOptions min(@Nullable final DBObject min) {
+        this.min = min;
+        return this;
+    }
+
+    /**
+     * Returns the returnKey. If true the find operation will return only the index keys in the resulting documents.
+     *
+     * Default value is false. If returnKey is true and the find command does not use an index, the returned documents will be empty.
+     *
+     * @return the returnKey
+     * @since 3.9
+     */
+    public boolean isReturnKey() {
+        return returnKey;
+    }
+
+    /**
+     * 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.9
+     */
+    public DBCollectionFindOptions returnKey(final boolean returnKey) {
+        this.returnKey = returnKey;
+        return this;
+    }
+
+    /**
+     * Returns the showRecordId.
+     *
+     * Determines whether to return the record identifier for each document. If true, adds a field $recordId to the returned documents.
+     * The default is false.
+     *
+     * @return the showRecordId
+     * @since 3.9
+     */
+    public boolean isShowRecordId() {
+        return showRecordId;
+    }
+
+    /**
+     * Sets the showRecordId. Set to true to add a field {@code $recordId} to the returned documents.
+     *
+     * @param showRecordId the showRecordId
+     * @return this
+     * @since 3.9
+     */
+    public DBCollectionFindOptions showRecordId(final boolean showRecordId) {
+        this.showRecordId = showRecordId;
+        return this;
+    }
 }

driver-legacy/src/test/unit/com/mongodb/DBCursorSpecification.groovy

@@ -211,6 +211,13 @@ class DBCursorSpecification extends Specification {
         def bsonModifiers = BsonDocument.parse(modifiers.toJson())
         def bsonProjection = BsonDocument.parse(projection.toJson())
         def bsonSort = BsonDocument.parse(sort.toJson())
+        def comment = 'comment'
+        def hint = BasicDBObject.parse('{x : 1}')
+        def min = BasicDBObject.parse('{y : 1}')
+        def max = BasicDBObject.parse('{y : 100}')
+        def bsonHint = BsonDocument.parse(hint.toJson())
+        def bsonMin = BsonDocument.parse(min.toJson())
+        def bsonMax = BsonDocument.parse(max.toJson())
         def readConcern = ReadConcern.LOCAL
         def readPreference = ReadPreference.nearest()
         def findOptions = new DBCollectionFindOptions()
@@ -229,6 +236,13 @@ class DBCursorSpecification extends Specification {
                 .readPreference(readPreference)
                 .skip(1)
                 .sort(sort)
+                .comment(comment)
+                .hint(hint)
+                .max(max)
+                .min(min)
+                .returnKey(true)
+                .showRecordId(true)
+
         def cursor = new DBCursor(collection, filter, findOptions)
 
         when:
@@ -250,6 +264,12 @@ class DBCursorSpecification extends Specification {
                 .projection(bsonProjection)
                 .skip(1)
                 .sort(bsonSort)
+                .comment(comment)
+                .hint(bsonHint)
+                .max(bsonMax)
+                .min(bsonMin)
+                .returnKey(true)
+                .showRecordId(true)
         )
 
         executor.getReadPreference() == findOptions.getReadPreference()

driver-legacy/src/test/unit/com/mongodb/client/model/DBCollectionFindOptionsSpecification.groovy

@@ -46,6 +46,12 @@ class DBCollectionFindOptionsSpecification extends Specification {
         options.getReadPreference() == null
         options.getSkip() == 0
         options.getSort() == null
+        options.getComment() == null
+        options.getHint() == null
+        options.getMax() == null
+        options.getMin() == null
+        !options.isReturnKey()
+        !options.isShowRecordId()
     }
 
     def 'should set and return the expected values'() {
@@ -57,6 +63,10 @@ class DBCollectionFindOptionsSpecification extends Specification {
         def modifiers = BasicDBObject.parse('{$comment: 1}')
         def readConcern = ReadConcern.LOCAL
         def readPreference = ReadPreference.nearest()
+        def comment = 'comment'
+        def hint = BasicDBObject.parse('{x : 1}')
+        def min = BasicDBObject.parse('{y : 1}')
+        def max = BasicDBObject.parse('{y : 100}')
 
         when:
         def options = new DBCollectionFindOptions()
@@ -75,6 +85,12 @@ class DBCollectionFindOptionsSpecification extends Specification {
                 .readPreference(readPreference)
                 .skip(1)
                 .sort(sort)
+                .comment(comment)
+                .hint(hint)
+                .max(max)
+                .min(min)
+                .returnKey(true)
+                .showRecordId(true)
 
         then:
         options.getBatchSize() == 1
@@ -92,6 +108,12 @@ class DBCollectionFindOptionsSpecification extends Specification {
         options.isNoCursorTimeout()
         options.isOplogReplay()
         options.isPartial()
+        options.getComment() == comment
+        options.getHint() == hint
+        options.getMax() == max
+        options.getMin() == min
+        options.isReturnKey()
+        options.isShowRecordId()
     }
 
     def 'it should copy and return the expected values'() {
@@ -103,6 +125,10 @@ class DBCollectionFindOptionsSpecification extends Specification {
         def modifiers = BasicDBObject.parse('{$comment: 1}')
         def readConcern = ReadConcern.LOCAL
         def readPreference = ReadPreference.nearest()
+        def comment = 'comment'
+        def hint = BasicDBObject.parse('{x : 1}')
+        def min = BasicDBObject.parse('{y : 1}')
+        def max = BasicDBObject.parse('{y : 100}')
 
         when:
         def original = new DBCollectionFindOptions()
@@ -121,6 +147,12 @@ class DBCollectionFindOptionsSpecification extends Specification {
                 .readPreference(readPreference)
                 .skip(1)
                 .sort(sort)
+                .comment(comment)
+                .hint(hint)
+                .max(max)
+                .min(min)
+                .returnKey(true)
+                .showRecordId(true)
 
         def options = original.copy()
 
@@ -142,6 +174,12 @@ class DBCollectionFindOptionsSpecification extends Specification {
         options.isNoCursorTimeout()
         options.isOplogReplay()
         options.isPartial()
+        options.getComment() == comment
+        options.getHint() == hint
+        options.getMax() == max
+        options.getMin() == min
+        options.isReturnKey()
+        options.isShowRecordId()
     }
 
 }