Add #available method to legacy cursor API (#838)

The new methods are

* com.mongodb.DBCursor#available
* com.mongodb.Cursor#available

with the same semantics as the recently added com.mongodb.client.MongoCursor#available.

JAVA-4422

Author: jyemin

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

@@ -27,6 +27,19 @@
  */
 public interface Cursor extends Iterator<DBObject>, Closeable {
 
+    /**
+     * Gets the number of results available locally without blocking, which may be 0.
+     *
+     * <p>
+     * If the cursor is known to be exhausted, returns 0.  If the cursor is closed before it's been exhausted, it may return a non-zero
+     * value.
+     * </p>
+     *
+     * @return the number of results available locally without blocking
+     * @since 4.5
+     */
+    int available();
+
     /**
      * Gets the server's identifier for this Cursor.
      *

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

@@ -188,6 +188,21 @@ public DBObject next() {
         return nextInternal();
     }
 
+    /**
+     * Gets the number of results available locally without blocking, which may be 0.
+     *
+     * <p>
+     * If the cursor is known to be exhausted, returns 0.  If the cursor is closed before it's been exhausted, it may return a non-zero
+     * value.
+     * </p>
+     *
+     * @return the number of results available locally without blocking
+     * @since 4.5
+     */
+    public int available() {
+        return cursor != null ? cursor.available() : 0;
+    }
+
     /**
      * Non blocking check for tailable cursors to see if another object is available.
      *

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

@@ -26,6 +26,11 @@ class MongoCursorAdapter implements Cursor {
         this.cursor = cursor;
     }
 
+    @Override
+    public int available() {
+        return cursor.available();
+    }
+
     @Override
     public long getCursorId() {
         ServerCursor serverCursor = cursor.getServerCursor();

driver-legacy/src/test/functional/com/mongodb/DBCollectionAggregationTest.java

@@ -146,6 +146,22 @@ public void testWriteConcern() {
         }
     }
 
+    @Test
+    public void testAvailable() {
+        prepareData();
+        Cursor cursor = collection.aggregate(asList(new BasicDBObject("$match", new BasicDBObject())),
+                AggregationOptions.builder().build());
+
+        assertEquals(3, cursor.available());
+
+        cursor.next();
+        assertEquals(2, cursor.available());
+
+        cursor.next();
+        assertEquals(1, cursor.available());
+    }
+
+
     private void verify(final List<DBObject> pipeline, final AggregationOptions options) {
         verify(pipeline, options, ReadPreference.primary());
     }

driver-legacy/src/test/functional/com/mongodb/DBCursorTest.java

@@ -61,6 +61,27 @@ public void after() {
         }
     }
 
+    @Test
+    public void testAvailable() {
+        cursor.batchSize(3);
+        assertEquals(0, cursor.available());
+
+        cursor.next();
+        assertEquals(2, cursor.available());
+
+        cursor.next();
+        assertEquals(1, cursor.available());
+
+        cursor.next();
+        assertEquals(0, cursor.available());
+
+        cursor.next();
+        assertEquals(2, cursor.available());
+
+        cursor.close();
+        assertEquals(0, cursor.available());
+    }
+
     @Test
     public void testNextHasNext() {
         cursor.sort(new BasicDBObject("_id", 1));

driver-sync/src/main/com/mongodb/client/MongoCursor.java

@@ -58,7 +58,12 @@ public interface MongoCursor<TResult> extends Iterator<TResult>, Closeable {
     TResult next();
 
     /**
-     * Gets the number of results available locally without blocking,which may be 0, or 0 when the cursor is exhausted or closed.
+     * Gets the number of results available locally without blocking, which may be 0.
+     *
+     * <p>
+     * If the cursor is known to be exhausted, returns 0.  If the cursor is closed before it's been exhausted, it may return a non-zero
+     * value.
+     * </p>
      *
      * @return the number of results available locally without blocking
      * @since 4.4