com.mongodb
Class DBCursor

java.lang.Object
  com.mongodb.DBCursor

All Implemented Interfaces:

Iterable<DBObject>, Iterator<DBObject>

public class DBCursor
extends Object
implements Iterator<DBObject>, Iterable<DBObject>

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();
 

MongoDB Doc Links

• cursors

Constructor Summary

DBCursor(DBCollection collection, DBObject q, DBObject k)
Initializes a new database cursor

Method Summary

DBCursor	addOption(int option) adds an option - see Bytes.QUERYOPTION_* for list
DBCursor	batchSize(int n) Limits the number of elements returned in one batch
DBCursor	copy() Creates a copy of an existing database cursor.
int	count() Counts the number of elements in this cursor.
DBObject	curr() Returns the element the cursor is at.
DBObject	explain() Returns an object containing basic information about the exectution 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
DBObject	getKeysWanted()
DBObject	getQuery()
List<Integer>	getSizes()
boolean	hasNext() Checks if there is another element.
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()
int	length() Finds the number of elements in the array.
DBCursor	limit(int n) Limits the number of elements returned.
DBObject	next() Returns the element the cursor is at and moves the cursor ahead by one.
int	numGetMores()
int	numSeen() Returns the number of objects through which the cursor has iterated.
void	remove() Unimplemented.
DBCursor	skip(int n) Discards a given number of elements at the beginning of the cursor.
DBCursor	snapshot() Use snapshot mode for the query.
DBCursor	sort(DBObject orderBy) Sorts this cursor's elements.
List<DBObject>	toArray() Converts this cursor to an array.
List<DBObject>	toArray(int min) Converts this cursor to an array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DBCursor

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

Initializes a new database cursor

Parameters:

collection - collection to use

q - query to perform

k - keys to return from the query

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

iterator

public Iterator<DBObject> iterator()

Specified by:

iterator in interface Iterable<DBObject>

sort

public DBCursor sort(DBObject orderBy)

Sorts this cursor's elements.

Parameters:

orderBy - the fields on which to sort

Returns:

a cursor pointing to the first element of the sorted results

hint

public DBCursor hint(DBObject indexKeys)

Informs the database of indexed fields of the collection in order to improve performance.

Parameters:

indexKeys - an DBObject with index names as keys

Returns:

same DBCursor for chaining operations

snapshot

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

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

explain

public DBObject explain()

Returns an object containing basic information about the exectution 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

MongoDB Doc Links

• explain

limit

public DBCursor limit(int n)

Limits the number of elements returned.

Parameters:

n - the number of elements to return

Returns:

a cursor pointing to the first element of the limited results

MongoDB Doc Links

• limit

batchSize

public DBCursor batchSize(int n)

Limits the number of elements returned in one batch

Parameters:

n - the number of elements to return in a batch

skip

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

addOption

public DBCursor addOption(int option)

adds an option - see Bytes.QUERYOPTION_* for list

numGetMores

public int numGetMores()

getSizes

public List<Integer> getSizes()

numSeen

public int numSeen()

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

Returns:

the number of objects seen

hasNext

public boolean hasNext()

Checks if there is another element.

Specified by:

hasNext in interface Iterator<DBObject>

Returns:

if there is another element

next

public DBObject next()

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

Specified by:

next in interface Iterator<DBObject>

Returns:

the next element

curr

public DBObject curr()

Returns the element the cursor is at.

Returns:

the next element

remove

public void remove()

Unimplemented.

Specified by:

remove in interface Iterator<DBObject>

length

public int length()
           throws MongoException

Finds the number of elements in the array.

Returns:

the number of elements in the array

Throws:

MongoException

toArray

public List<DBObject> toArray()
                       throws MongoException

Converts this cursor to an array.

Returns:

an array of elements

Throws:

MongoException

toArray

public List<DBObject> toArray(int min)
                       throws MongoException

Converts this cursor to an array. If there are more than a given number of elements in the resulting array, only return the first min.

Parameters:

min - the minimum size of the array to return

Returns:

an array of elements

Throws:

MongoException

itcount

public int itcount()

for testing only! iterates cursor and counts objects

Returns:

num objects

count

public int count()
          throws MongoException

Counts the number of elements in this cursor.

Returns:

the number of elements

Throws:

MongoException

getKeysWanted

public DBObject getKeysWanted()

getQuery

public DBObject getQuery()