public class

DBCursor

extends Object
implements Closeable Iterable<T> Iterator<E>
java.lang.Object
   ↳ com.mongodb.DBCursor

Class Overview

An iterator over database results. Doing a find() query on a collection returns a DBCursor thus 

 DBCursor cursor = collection.find( query );
 if( cursor.hasNext() )
     DBObject obj = 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 obj = collection.find( query ).skip( 1000 ).limit( 100 ).toArray();

Summary

Public Constructors
DBCursor(DBCollection collection, DBObject q, DBObject k, ReadPreference preference)
Initializes a new database cursor
Public Methods
DBCursor addOption(int option)
adds a query option - see Bytes.QUERYOPTION_* for list
DBCursor addSpecial(String name, Object o)
adds a special operator like $maxScan or $returnKey e.g.
DBCursor batchSize(int n)
Limits the number of elements returned in one batch.
void close()
kills the current cursor on the server.
DBCursor copy()
Creates a copy of an existing database cursor.
int count()
Counts the number of objects matching the query This does not take limit/skip into consideration
DBObject curr()
Returns the element the cursor is at.
DBObject explain()
Returns an object containing basic information about the execution of the query that created this cursor This creates a DBObject with the key/value pairs: "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
DBCollection getCollection()
gets the collection
long getCursorId()
gets the cursor id.
DBDecoderFactory getDecoderFactory()
DBObject getKeysWanted()
gets the fields to be returned
int getOptions()
gets the query options
DBObject getQuery()
gets the query
ReadPreference getReadPreference()
Gets the default read preference
ServerAddress getServerAddress()
Gets the Server Address of the server that data is pulled from.
List<Integer> getSizes()
gets a list containing the number of items received in each batch
boolean hasNext()
Checks if there is another object available@return
DBCursor hint(String indexName)
Informs the database of an indexed field of the collection in order to improve performance.
DBCursor hint(DBObject indexKeys)
Informs the database of indexed fields 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 n)
Limits the number of elements returned.
DBObject next()
Returns the object the cursor is at and moves the cursor ahead by one.
int numGetMores()
gets the number of times, so far, that the cursor retrieved a batch from the database
int numSeen()
Returns the number of objects through which the cursor has iterated.
void remove()
Not implemented.
DBCursor resetOptions()
resets the query options
DBCursor setDecoderFactory(DBDecoderFactory fact)
DBCursor setOptions(int options)
sets the query option - see Bytes.QUERYOPTION_* for list
DBCursor setReadPreference(ReadPreference preference)
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 n)
Discards a given number of elements at the beginning of the cursor.
DBCursor slaveOk()
This method is deprecated. Replaced with ReadPreference.SECONDARY
DBCursor snapshot()
Use snapshot mode for the query.
DBCursor sort(DBObject orderBy)
Sorts this cursor's elements.
List<DBObject> toArray(int max)
Converts this cursor to an array.
List<DBObject> toArray()
Converts this cursor to an array.
String toString()
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.Iterable
From interface java.util.Iterator

Public Constructors

public DBCursor (DBCollection collection, DBObject q, DBObject k, ReadPreference preference)

Initializes a new database cursor

Parameters
collection collection to use
q query to perform
k keys to return from the query
preference the Read Preference for this query

Public Methods

public DBCursor addOption (int option)

adds a query option - see Bytes.QUERYOPTION_* for list

public DBCursor addSpecial (String name, Object o)

adds a special operator like $maxScan or $returnKey e.g. addSpecial( "$returnKey" , 1 ) e.g. addSpecial( "$maxScan" , 100 )@return

public DBCursor batchSize (int n)

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. The batch size can be changed even after a cursor is iterated, in which case the setting will apply on the next batch retrieval.

Parameters
n the number of elements to return in a batch

public void close ()

kills the current cursor on the server.

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

public int count ()

Counts the number of objects matching the query This does not take limit/skip into consideration

Returns
  • the number of objects
Throws
MongoException
See Also

public DBObject curr ()

Returns the element the cursor is at.

Returns
  • the next element

public DBObject explain ()

Returns an object containing basic information about the execution of the query that created this cursor This creates a DBObject with the key/value pairs: "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

public DBCollection getCollection ()

gets the collection

public long getCursorId ()

gets the cursor id.

Returns
  • the cursor id, or 0 if there is no active cursor.

public DBDecoderFactory getDecoderFactory ()

public DBObject getKeysWanted ()

gets the fields to be returned

public int getOptions ()

gets the query options

public DBObject getQuery ()

gets the query

public ReadPreference getReadPreference ()

Gets the default read preference

public ServerAddress getServerAddress ()

Gets the Server Address of the server that data is pulled from. Note that this information may not be available until hasNext() or next() is called.

public List<Integer> getSizes ()

gets a list containing the number of items received in each batch

public boolean hasNext ()

Checks if there is another object available@return

Throws
MongoException

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 DBCursort for chaining operations

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

public int itcount ()

for testing only! Iterates cursor and counts objects

Returns
  • num objects
See Also

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.

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
See Also

public DBCursor limit (int n)

Limits the number of elements returned. Note: parameter n 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
n the number of elements to return
Returns
  • a cursor to iterate the results

public DBObject next ()

Returns the object the cursor is at and moves the cursor ahead by one.

Returns
  • the next element
Throws
MongoException

public int numGetMores ()

gets the number of times, so far, that the cursor retrieved a batch from the database

public int numSeen ()

Returns the number of objects through which the cursor has iterated.

Returns
  • the number of objects seen

public void remove ()

Not implemented.

public DBCursor resetOptions ()

resets the query options

public DBCursor setDecoderFactory (DBDecoderFactory fact)

public DBCursor setOptions (int options)

sets the query option - see Bytes.QUERYOPTION_* for list

public DBCursor setReadPreference (ReadPreference preference)

Sets the read preference for this cursor. See the * documentation for ReadPreference for more information.

Parameters
preference Read Preference to use

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
See Also

public DBCursor skip (int n)

Discards a given number of elements at the beginning of the cursor.

Parameters
n the number of elements to skip
Returns
  • a cursor pointing to the new first element of the results
Throws
RuntimeException if the cursor has started to be iterated through

public DBCursor slaveOk ()

This method is deprecated.
Replaced with ReadPreference.SECONDARY

makes this query ok to run on a slave node

Returns
  • a copy of the same cursor (for chaining)
See Also
  • com.mongodb.ReadPreference.SECONDARY

public DBCursor snapshot ()

Use snapshot mode for the query. Snapshot mode assures no duplicates are returned, or objects missed, which were present at both the start and end of the query's execution (if an object is new during the query, or deleted during the query, it may or may not be returned, even with snapshot mode). Note that short query responses (less than 1MB) are always effectively snapshotted. Currently, snapshot mode may not be used with sorting or explicit hints.

Returns
  • same DBCursor for chaining operations

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

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

public List<DBObject> toArray ()

Converts this cursor to an array.

Returns
  • an array of elements
Throws
MongoException

public String toString ()