Deprecate options-related DBCursor method

Deprecate:

* addOption
* setOption
* resetOptions
* getOptions

Replace with per-option methods:

* cursorType
* oplogReplay
* noCursorTimeout
* partial

JAVA-3021

Author: jyemin

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

@@ -220,7 +220,9 @@ public void remove() {
      * @return {@code this} so calls can be chained
      * @see Bytes
      * @mongodb.driver.manual ../meta-driver/latest/legacy/mongodb-wire-protocol/#op-query Query Flags
+     * @deprecated Prefer per-option methods, e.g. {@link #cursorType(CursorType)}, {@link #noCursorTimeout(boolean)}, etc.
      */
+    @Deprecated
     public DBCursor addOption(final int option) {
         setOptions(this.options |= option);
         return this;
@@ -234,6 +236,7 @@ public DBCursor addOption(final int option) {
      * @see Bytes
      * @mongodb.driver.manual ../meta-driver/latest/legacy/mongodb-wire-protocol/#op-query Query Flags
      */
+    @Deprecated
     public DBCursor setOptions(final int options) {
         if ((options & Bytes.QUERYOPTION_EXHAUST) != 0) {
             throw new UnsupportedOperationException("exhaust query option is not supported");
@@ -248,6 +251,7 @@ public DBCursor setOptions(final int options) {
      * @return {@code this} so calls can be chained
      * @mongodb.driver.manual ../meta-driver/latest/legacy/mongodb-wire-protocol/#op-query Query Flags
      */
+    @Deprecated
     public DBCursor resetOptions() {
         this.options = 0;
         return this;
@@ -259,6 +263,7 @@ public DBCursor resetOptions() {
      * @return the bitmask of options
      * @mongodb.driver.manual ../meta-driver/latest/legacy/mongodb-wire-protocol/#op-query Query Flags
      */
+    @Deprecated
     public int getOptions() {
         return options;
     }
@@ -493,6 +498,55 @@ public DBObject explain() {
                                            getReadPreference(), getReadConcern()));
     }
 
+    /**
+     * Sets the cursor type.
+     *
+     * @param cursorType the cursor type, which may not be null
+     * @return this
+     * @since 3.9
+     */
+    public DBCursor cursorType(final CursorType cursorType) {
+        findOptions.cursorType(cursorType);
+        return this;
+    }
+
+    /**
+     * Users should not set this under normal circumstances.
+     *
+     * @param oplogReplay if oplog replay is enabled
+     * @return this
+     * @since 3.9
+     */
+    public DBCursor oplogReplay(final boolean oplogReplay) {
+        findOptions.oplogReplay(oplogReplay);
+        return this;
+    }
+
+    /**
+     * The server normally times out idle cursors after an inactivity period (10 minutes)
+     * to prevent excess memory use. Set this option to prevent that.
+     *
+     * @param noCursorTimeout true if cursor timeout is disabled
+     * @return this
+     * @since 3.9
+     */
+    public DBCursor noCursorTimeout(final boolean noCursorTimeout) {
+        findOptions.noCursorTimeout(noCursorTimeout);
+        return this;
+    }
+
+    /**
+     * Get partial results from a sharded cluster if one or more shards are unreachable (instead of throwing an error).
+     *
+     * @param partial if partial results for sharded clusters is enabled
+     * @return this
+     * @since 3.9
+     */
+    public DBCursor partial(final boolean partial) {
+        findOptions.partial(partial);
+        return this;
+    }
+
     @SuppressWarnings("deprecation")
     private FindOperation<DBObject> getQueryOperation(final Decoder<DBObject> decoder) {
         FindOperation<DBObject> operation = new FindOperation<DBObject>(collection.getNamespace(), decoder)

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

@@ -219,7 +219,9 @@ public DBCollectionFindOptions batchSize(final int batchSize) {
      *
      * @return the query modifiers, which may be null
      * @mongodb.driver.manual reference/operator/query-modifier/ Query Modifiers
+     * @deprecated use the individual setters instead
      */
+    @Deprecated
     public DBObject getModifiers() {
         return modifiers;
     }
@@ -230,7 +232,9 @@ public DBObject getModifiers() {
      * @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
     public DBCollectionFindOptions modifiers(@Nullable final DBObject modifiers) {
         this.modifiers = notNull("modifiers", modifiers);
         return this;

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

@@ -147,6 +147,56 @@ class DBCursorSpecification extends Specification {
                                                                 .modifiers(new BsonDocument()))
     }
 
+    def 'DBCursor methods should be used to create the expected operation'() {
+        given:
+        def executor = new TestOperationExecutor([stubBatchCursor()]);
+        def collection = new DB(getMongoClient(), 'myDatabase', executor).getCollection('test')
+        def collation = Collation.builder().locale('en').build()
+        def cursorType = CursorType.NonTailable
+        def filter = new BasicDBObject()
+        def sort = BasicDBObject.parse('{a: 1}')
+        def bsonFilter = new BsonDocument()
+        def bsonSort = BsonDocument.parse(sort.toJson())
+        def readConcern = ReadConcern.LOCAL
+        def readPreference = ReadPreference.nearest()
+        def findOptions = new DBCollectionFindOptions()
+        def cursor = new DBCursor(collection, filter, findOptions)
+                .setReadConcern(readConcern)
+                .setReadPreference(readPreference)
+                .setCollation(collation)
+                .batchSize(1)
+                .cursorType(cursorType)
+                .limit(1)
+                .maxTime(1, TimeUnit.MILLISECONDS)
+                .noCursorTimeout(true)
+                .oplogReplay(true)
+                .partial(true)
+                .skip(1)
+                .sort(sort)
+
+        when:
+        cursor.toArray()
+
+        then:
+        expect executor.getReadOperation(), isTheSameAs(new FindOperation(collection.getNamespace(), collection.getObjectCodec())
+                .batchSize(1)
+                .collation(collation)
+                .cursorType(cursorType)
+                .filter(bsonFilter)
+                .limit(1)
+                .maxTime(1, TimeUnit.MILLISECONDS)
+                .noCursorTimeout(true)
+                .oplogReplay(true)
+                .partial(true)
+                .skip(1)
+                .sort(bsonSort)
+                .modifiers(new BsonDocument())
+        )
+
+        executor.getReadPreference() == readPreference
+        executor.getReadConcern() == readConcern
+    }
+
     def 'DBCollectionFindOptions should be used to create the expected operation'() {
         given:
         def executor = new TestOperationExecutor([stubBatchCursor()]);