All Implemented Interfaces:

Cursor, Closeable, AutoCloseable, Iterable<DBObject>, Iterator<DBObject>
```
@NotThreadSafe
public class DBCursor
extends Object
implements Cursor, Iterable<DBObject>
```
An iterator over database results. Doing a find() query on a collection returns a DBCursor.

An application should ensure that a cursor is closed in all circumstances, e.g. using a try-with-resources statement:
```
    try (DBCursor cursor = collection.find(query)) {
        while (cursor.hasNext()) {
            System.out.println(cursor.next();
        }
    }
 
```
Warning: Calling toArray or length on a DBCursor will irrevocably turn it into an array. This means that, if the cursor was iterating over ten million results (which it was lazily fetching from the database), suddenly there will be a ten-million element array in memory. Before converting to an array, make sure that there are a reasonable number of results using skip() and limit().
For example, to get an array of the 1000-1100th elements of a cursor, use
```
    List<DBObject> obj = collection.find(query).skip(1000).limit(100).toArray();
 
```
See MongoClient.getDB(String) for further information about the effective deprecation of this class.
MongoDB documentation
Read Operations

Constructor Summary

Constructors
Constructor	Description
`DBCursor(DBCollection collection, DBObject query, DBObject fields, ReadPreference readPreference)`	Initializes a new database cursor.
`DBCursor(DBCollection collection, DBObject query, DBObject fields, ReadPreference readPreference, boolean retryReads)`	Initializes a new database cursor.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`DBCursor`	`batchSize(int numberOfElements)`	Limits the number of elements returned in one batch.
`void`	`close()`	Terminates this cursor on the server.
`DBCursor`	`comment(String comment)`	Adds a comment to the query to identify queries in the database profiler output.
`DBCursor`	`copy()`	Creates a copy of an existing database cursor.
`int`	`count()`	Counts the number of objects matching the query.
`DBObject`	`curr()`	Returns the element the cursor is at.
`DBCursor`	`cursorType(CursorType cursorType)`	Sets the cursor type.
`DBObject`	`explain()`	Deprecated.
`int`	`getBatchSize()`	Gets the batch size.
`Collation`	`getCollation()`	Returns the collation options
`DBCollection`	`getCollection()`	Gets the collection.
`long`	`getCursorId()`	Gets the server's identifier for this Cursor.
`DBDecoderFactory`	`getDecoderFactory()`	Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.
`DBObject`	`getKeysWanted()`	Gets the fields to be returned.
`int`	`getLimit()`	Gets the query limit.
`DBObject`	`getQuery()`	Gets the query.
`ReadPreference`	`getReadPreference()`	Gets the default read preference.
`ServerAddress`	`getServerAddress()`	Gets the address of the server that data is pulled from.
`boolean`	`hasNext()`	Checks if there is another object available.
`DBCursor`	`hint(DBObject indexKeys)`	Informs the database of indexed fields of the collection in order to improve performance.
`DBCursor`	`hint(String indexName)`	Informs the database of an indexed field of the collection in order to improve performance.
`int`	`itcount()`	For testing only! Iterates cursor and counts objects
`Iterator<DBObject>`	`iterator()`	Creates a copy of this cursor object that can be iterated.
`int`	`length()`	Pulls back all items into an array and returns the number of objects.
`DBCursor`	`limit(int limit)`	Limits the number of elements returned.
`DBCursor`	`max(DBObject max)`	Specifies an exclusive upper limit for the index to use in a query.
`DBCursor`	`maxTime(long maxTime, TimeUnit timeUnit)`	Set the maximum execution time for operations on this cursor.
`DBCursor`	`min(DBObject min)`	Specifies an inclusive lower limit for the index to use in a query.
`DBObject`	`next()`	Returns the object the cursor is at and moves the cursor ahead by one.
`DBCursor`	`noCursorTimeout(boolean noCursorTimeout)`	The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use.
`int`	`numSeen()`	Returns the number of objects through which the cursor has iterated.
`DBObject`	`one()`	Returns the first document that matches the query.
`DBCursor`	`oplogReplay(boolean oplogReplay)`	Deprecated. oplogReplay has been deprecated in MongoDB 4.4.
`DBCursor`	`partial(boolean partial)`	Get partial results from a sharded cluster if one or more shards are unreachable (instead of throwing an error).
`void`	`remove()`
`DBCursor`	`returnKey()`	Forces the cursor to only return fields included in the index.
`DBCursor`	`setCollation(Collation collation)`	Sets the collation options
`DBCursor`	`setDecoderFactory(DBDecoderFactory factory)`	Sets the factory that will be used create a `DBDecoder` that will be used to decode BSON documents into DBObject instances.
`DBCursor`	`setReadPreference(ReadPreference readPreference)`	Sets the read preference for this cursor.
`int`	`size()`	Counts the number of objects matching the query this does take limit/skip into consideration
`DBCursor`	`skip(int numberOfElements)`	Discards a given number of elements at the beginning of the cursor.
`DBCursor`	`sort(DBObject orderBy)`	Sorts this cursor's elements.
`List<DBObject>`	`toArray()`	Converts this cursor to an array.
`List<DBObject>`	`toArray(int max)`	Converts this cursor to an array.
`String`	`toString()`
`DBObject`	`tryNext()`	Non blocking check for tailable cursors to see if another object is available.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

Methods inherited from interface java.util.Iterator
forEachRemaining

- Constructor Detail
  - DBCursor
```
public DBCursor(DBCollection collection,
                DBObject query,
                @Nullable
                DBObject fields,
                @Nullable
                ReadPreference readPreference)
```
    Initializes a new database cursor.
    
    Parameters:
    
    collection - collection to use
    
    query - the query filter to apply
    
    fields - keys to return from the query
    
    readPreference - the read preference for this query
  - DBCursor
```
public DBCursor(DBCollection collection,
                DBObject query,
                @Nullable
                DBObject fields,
                @Nullable
                ReadPreference readPreference,
                boolean retryReads)
```
    Initializes a new database cursor.
    
    Parameters:
    
    collection - collection to use
    
    query - the query filter to apply
    
    fields - keys to return from the query
    
    readPreference - the read preference for this query
    
    retryReads - true if reads should be retried
- Method Detail
  - copy
```
public DBCursor copy()
```
    Creates a copy of an existing database cursor. The new cursor is an iterator, even if the original was an array.
    
    Returns:
    
    the new cursor
  - hasNext
```
public boolean hasNext()
```
    Checks if there is another object available.
    Note: Automatically turns cursors of type Tailable to TailableAwait. For non blocking tailable cursors see tryNext().
    
    Specified by:
    
    hasNext in interface Iterator<DBObject>
    
    Returns:
    
    true if there is another object available
    
    MongoDB documentation
    Cursor Batches
  - next
```
public DBObject next()
```
    Returns the object the cursor is at and moves the cursor ahead by one.
    Note: Automatically turns cursors of type Tailable to TailableAwait. For non blocking tailable cursors see tryNext().
    
    Specified by:
    
    next in interface Iterator<DBObject>
    
    Returns:
    
    the next element
    
    MongoDB documentation
    Cursor Batches
  - tryNext
```
@Nullable
public DBObject tryNext()
```
    Non blocking check for tailable cursors to see if another object is available.
    Returns the object the cursor is at and moves the cursor ahead by one or return null if no documents is available.
    
    Returns:
    
    the next element or null
    
    Throws:
    
    MongoException - if failed
    
    IllegalArgumentException - if the cursor is not tailable
    
    MongoDB documentation
    Cursor Batches
  - curr
```
public DBObject curr()
```
    Returns the element the cursor is at.
    
    Returns:
    
    the current element
  - remove
```
public void remove()
```
    Specified by:
    
    remove in interface Iterator<DBObject>
  - getLimit
```
public int getLimit()
```
    Gets the query limit.
    
    Returns:
    
    the limit, or 0 if no limit is set
  - getBatchSize
```
public int getBatchSize()
```
    Gets the batch size.
    
    Returns:
    
    the batch size
  - comment
```
public DBCursor comment(String comment)
```
    Adds a comment to the query to identify queries in the database profiler output.
    
    Parameters:
    
    comment - the comment that is to appear in the profiler output
    
    Returns:
    
    this so calls can be chained
    
    Since:
    
    2.12
    
    MongoDB documentation
    $comment
  - max
```
public DBCursor max(DBObject max)
```
    Specifies an exclusive upper limit for the index to use in a query.
    
    Parameters:
    
    max - a document specifying the fields, and the upper bound values for those fields
    
    Returns:
    
    this so calls can be chained
    
    Since:
    
    2.12
    
    MongoDB documentation
    $max
  - min
```
public DBCursor min(DBObject min)
```
    Specifies an inclusive lower limit for the index to use in a query.
    
    Parameters:
    
    min - a document specifying the fields, and the lower bound values for those fields
    
    Returns:
    
    this so calls can be chained
    
    Since:
    
    2.12
    
    MongoDB documentation
    $min
  - returnKey
```
public DBCursor returnKey()
```
    Forces the cursor to only return fields included in the index.
    
    Returns:
    
    this so calls can be chained
    
    Since:
    
    2.12
    
    MongoDB documentation
    $returnKey
  - hint
```
public DBCursor hint(DBObject indexKeys)
```
    Informs the database of indexed fields of the collection in order to improve performance.
    
    Parameters:
    
    indexKeys - a DBObject with fields and direction
    
    Returns:
    
    same DBCursor for chaining operations
    
    MongoDB documentation
    $hint
  - hint
```
public DBCursor hint(String indexName)
```
    Informs the database of an indexed field of the collection in order to improve performance.
    
    Parameters:
    
    indexName - the name of an index
    
    Returns:
    
    same DBCursor for chaining operations
    
    Since:
    
    4.4
    
    MongoDB documentation
    $hint
  - maxTime
```
public DBCursor maxTime(long maxTime,
                        TimeUnit timeUnit)
```
    Set the maximum execution time for operations on this cursor.
    
    Parameters:
    
    maxTime - the maximum time that the server will allow the query to run, before killing the operation.
    
    timeUnit - the time unit
    
    Returns:
    
    same DBCursor for chaining operations
    
    Since:
    
    2.12.0
    
    MongoDB documentation
    $maxTimeMS
  - explain
```
@Deprecated
public DBObject explain()
```
    Deprecated.
    Returns an object containing basic information about the execution of the query that created this cursor. This creates a DBObject with a number of fields, including but not limited to:
    
    cursor: cursor type
    
    nScanned: number of records examined by the database for this query
    
    n: the number of records that the database returned
    
    millis: how long it took the database to execute the query
    Returns:
    
    a DBObject containing the explain output for this DBCursor's query
    
    Throws:
    
    MongoException - if the operation failed
    
    MongoDB documentation
    Explain Output
    Since server release
    3.0
  - cursorType
```
public DBCursor cursorType(CursorType cursorType)
```
    Sets the cursor type.
    
    Parameters:
    
    cursorType - the cursor type, which may not be null
    
    Returns:
    
    this
    
    Since:
    
    3.9
  - oplogReplay
```
@Deprecated
public DBCursor oplogReplay(boolean oplogReplay)
```
    Deprecated.
    oplogReplay has been deprecated in MongoDB 4.4.
    
    Users should not set this under normal circumstances.
    
    Parameters:
    
    oplogReplay - if oplog replay is enabled
    
    Returns:
    
    this
    
    Since:
    
    3.9
  - noCursorTimeout
```
public DBCursor noCursorTimeout(boolean noCursorTimeout)
```
    The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that.
    
    Parameters:
    
    noCursorTimeout - true if cursor timeout is disabled
    
    Returns:
    
    this
    
    Since:
    
    3.9
  - partial
```
public DBCursor partial(boolean partial)
```
    Get partial results from a sharded cluster if one or more shards are unreachable (instead of throwing an error).
    
    Parameters:
    
    partial - if partial results for sharded clusters is enabled
    
    Returns:
    
    this
    
    Since:
    
    3.9
  - sort
```
public DBCursor sort(DBObject orderBy)
```
    Sorts this cursor's elements. This method must be called before getting any object from the cursor.
    
    Parameters:
    
    orderBy - the fields by which to sort
    
    Returns:
    
    a cursor pointing to the first element of the sorted results
  - limit
```
public DBCursor limit(int limit)
```
    Limits the number of elements returned. Note: parameter limit should be positive, although a negative value is supported for legacy reason. Passing a negative value will call batchSize(int) which is the preferred method.
    
    Parameters:
    
    limit - the number of elements to return
    
    Returns:
    
    a cursor to iterate the results
    
    MongoDB documentation
    Limit
  - batchSize
```
public DBCursor batchSize(int numberOfElements)
```
    Limits the number of elements returned in one batch. A cursor typically fetches a batch of result objects and store them locally.
    
    If batchSize is positive, it represents the size of each batch of objects retrieved. It can be adjusted to optimize performance and limit data transfer.
    
    If batchSize is negative, it will limit of number objects returned, that fit within the max batch size limit (usually 4MB), and cursor will be closed. For example if batchSize is -10, then the server will return a maximum of 10 documents and as many as can fit in 4MB, then close the cursor. Note that this feature is different from limit() in that documents must fit within a maximum size, and it removes the need to send a request to close the cursor server-side.
    
    Parameters:
    
    numberOfElements - the number of elements to return in a batch
    
    Returns:
    
    this so calls can be chained
  - skip
```
public DBCursor skip(int numberOfElements)
```
    Discards a given number of elements at the beginning of the cursor.
    
    Parameters:
    
    numberOfElements - the number of elements to skip
    
    Returns:
    
    a cursor pointing to the new first element of the results
    
    Throws:
    
    IllegalStateException - if the cursor has started to be iterated through
  - getCursorId
```
public long getCursorId()
```
    Description copied from interface: Cursor
    
    Gets the server's identifier for this Cursor.
    
    Specified by:
    
    getCursorId in interface Cursor
    
    Returns:
    
    the cursor's ID, or 0 if there is no active cursor.
  - numSeen
```
public int numSeen()
```
    Returns the number of objects through which the cursor has iterated.
    
    Returns:
    
    the number of objects seen
  - close
```
public void close()
```
    Description copied from interface: Cursor
    
    Terminates this cursor on the server.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface Cursor
  - iterator
```
public Iterator<DBObject> iterator()
```
    Creates a copy of this cursor object that can be iterated. Note: - you can iterate the DBCursor itself without calling this method - no actual data is getting copied.
    
    Note that use of this method does not let you call close the underlying cursor in the case of either an exception or an early break. The preferred method of iteration is to use DBCursor as an Iterator, so that you can call close() on it in a finally block.
    
    Specified by:
    
    iterator in interface Iterable<DBObject>
    
    Returns:
    
    an iterator
  - toArray
```
public List<DBObject> toArray()
```
    Converts this cursor to an array.
    
    Returns:
    
    an array of elements
    
    Throws:
    
    MongoException - if failed
  - toArray
```
public List<DBObject> toArray(int max)
```
    Converts this cursor to an array.
    
    Parameters:
    
    max - the maximum number of objects to return
    
    Returns:
    
    an array of objects
    
    Throws:
    
    MongoException - if failed
  - count
```
public int count()
```
    Counts the number of objects matching the query. This does not take limit/skip into consideration, and does initiate a call to the server.
    
    Returns:
    
    the number of objects
    
    Throws:
    
    MongoException - if the operation failed
    
    See Also:
    
    size()
  - one
```
@Nullable
public DBObject one()
```
    Returns the first document that matches the query.
    
    Returns:
    
    the first matching document
    
    Since:
    
    2.12
  - length
```
public int length()
```
    Pulls back all items into an array and returns the number of objects. Note: this can be resource intensive.
    
    Returns:
    
    the number of elements in the array
    
    Throws:
    
    MongoException - if failed
    
    See Also:
    
    count(), size()
  - itcount
```
public int itcount()
```
    For testing only! Iterates cursor and counts objects
    
    Returns:
    
    num objects
    
    Throws:
    
    MongoException - if failed
    
    See Also:
    
    count()
  - size
```
public int size()
```
    Counts the number of objects matching the query this does take limit/skip into consideration
    
    Returns:
    
    the number of objects
    
    Throws:
    
    MongoException - if the operation failed
    
    See Also:
    
    count()
  - getKeysWanted
```
@Nullable
public DBObject getKeysWanted()
```
    Gets the fields to be returned.
    
    Returns:
    
    the field selector that cursor used
  - getQuery
```
public DBObject getQuery()
```
    Gets the query.
    
    Returns:
    
    the query that cursor used
  - getCollection
```
public DBCollection getCollection()
```
    Gets the collection.
    
    Returns:
    
    the collection that data is pulled from
  - getServerAddress
```
@Nullable
public ServerAddress getServerAddress()
```
    Description copied from interface: Cursor
    
    Gets the address of the server that data is pulled from. Note that this information may not be available until hasNext() or next() is called.
    
    Specified by:
    
    getServerAddress in interface Cursor
    
    Returns:
    
    the address of the server that data is pulled from
  - setReadPreference
```
public DBCursor setReadPreference(ReadPreference readPreference)
```
    Sets the read preference for this cursor. See the documentation for ReadPreference for more information.
    
    Parameters:
    
    readPreference - read preference to use
    
    Returns:
    
    this so calls can be chained
  - getReadPreference
```
public ReadPreference getReadPreference()
```
    Gets the default read preference.
    
    Returns:
    
    the readPreference used by this cursor
  - getCollation
```
@Nullable
public Collation getCollation()
```
    Returns the collation options
    
    Returns:
    
    the collation options
    
    Since:
    
    3.4
    
    Since server release
    3.4
  - setCollation
```
public DBCursor setCollation(@Nullable
                             Collation collation)
```
    Sets the collation options
    A null value represents the server default.
    
    Parameters:
    
    collation - the collation options to use
    
    Returns:
    
    this
    
    Since:
    
    3.4
    
    Since server release
    3.4
  - setDecoderFactory
```
public DBCursor setDecoderFactory(DBDecoderFactory factory)
```
    Sets the factory that will be used create a DBDecoder that will be used to decode BSON documents into DBObject instances.
    
    Parameters:
    
    factory - the DBDecoderFactory
    
    Returns:
    
    this so calls can be chained
  - getDecoderFactory
```
public DBDecoderFactory getDecoderFactory()
```
    Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.
    
    Returns:
    
    the decoder factory.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class DBCursor

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Methods inherited from interface java.util.Iterator

Constructor Detail

DBCursor

DBCursor

Method Detail

copy

hasNext

next

tryNext

curr

remove

getLimit

getBatchSize

comment

max

min

returnKey

hint

hint

maxTime

explain

cursorType

oplogReplay

noCursorTimeout

partial

sort

limit

batchSize

skip

getCursorId

numSeen

close

iterator

toArray

toArray

count

one

length

itcount

size

getKeysWanted

getQuery

getCollection

getServerAddress

setReadPreference

getReadPreference

getCollation

setCollation

setDecoderFactory

getDecoderFactory

toString