net.vz.mongodb.jackson
Class DBCursor<T>

java.lang.Object
  net.vz.mongodb.jackson.DBQuery.AbstractBuilder<DBCursor<T>>
      net.vz.mongodb.jackson.DBCursor<T>

All Implemented Interfaces:

Iterable<T>, Iterator<T>

public class DBCursor<T>
extends DBQuery.AbstractBuilder<DBCursor<T>>
implements Iterator<T>, Iterable<T>

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

 DBCursor cursor = collection.find( query );
 if( cursor.hasNext() )
     T 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();
 

Since:

1.0

Author:

James Roper

Field Summary

Fields inherited from class net.vz.mongodb.jackson.DBQuery.AbstractBuilder

query

Constructor Summary

DBCursor(JacksonDBCollection<T,?> jacksonDBCollection, com.mongodb.DBCursor cursor)

Method Summary

DBCursor<T>	addOption(int option) adds a query option - see Bytes.QUERYOPTION_* for simpleList
DBCursor<T>	addSpecial(String name, Object o) adds a special operator like $maxScan or $returnKey e.g.
DBCursor<T>	batchSize(int n) Limits the number of elements returned in one batch.
void	close() kills the current cursor on the server.
DBCursor<T>	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
T	curr() Returns the element the cursor is at.
com.mongodb.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
JacksonDBCollection	getCollection() gets the collection
com.mongodb.DBCursor	getCursor() Get the underlying MongoDB cursor.
long	getCursorId() gets the cursor id.
com.mongodb.DBDecoderFactory	getDecoderFactory()
com.mongodb.DBObject	getKeysWanted() gets the fields to be returned
int	getOptions() gets the query options
com.mongodb.DBObject	getQuery() gets the query
com.mongodb.ReadPreference	getReadPreference() Gets the default read preference
com.mongodb.ServerAddress	getServerAddress() Gets the Server Address of the server that data is pulled from.
List<Integer>	getSizes() gets a simpleList containing the number of items received in each batch
boolean	hasNext() Checks if there is another object available
DBCursor<T>	hint(com.mongodb.DBObject indexKeys) Informs the database of indexed fields of the collection in order to improve performance.
DBCursor<T>	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<T>	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<T>	limit(int n) Limits the number of elements returned.
T	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.
protected DBCursor<T>	put(String field, String op, Object value)
protected DBCursor<T>	putGroup(String op, Object... expressions)
void	remove() Not implemented.
DBCursor<T>	resetOptions() resets the query options
DBCursor<T>	setDecoderFactory(com.mongodb.DBDecoderFactory fact)
DBCursor<T>	setOptions(int options) sets the query option - see Bytes.QUERYOPTION_* for simpleList
DBCursor<T>	setReadPreference(com.mongodb.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<T>	skip(int n) Discards a given number of elements at the beginning of the cursor.
DBCursor<T>	snapshot() Use snapshot mode for the query.
DBCursor<T>	sort(com.mongodb.DBObject orderBy) Sorts this cursor'string elements.
List<T>	toArray() Converts this cursor to an array.
List<T>	toArray(int max) Converts this cursor to an array.

Methods inherited from class net.vz.mongodb.jackson.DBQuery.AbstractBuilder

all, all, and, elemMatch, exists, greaterThan, greaterThanEquals, in, in, is, lessThan, lessThanEquals, mod, nor, notEquals, notExists, notIn, notIn, or, regex, size, where

Methods inherited from class java.lang.Object

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

Constructor Detail

DBCursor

public DBCursor(JacksonDBCollection<T,?> jacksonDBCollection,
                com.mongodb.DBCursor cursor)

Method Detail

copy

public DBCursor<T> 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<T> 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.

Specified by:

iterator in interface Iterable<T>

Returns:

The iterator

sort

public DBCursor<T> sort(com.mongodb.DBObject orderBy)

Sorts this cursor'string 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

addSpecial

public DBCursor<T> addSpecial(String name,
                              Object o)

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

Parameters:

name - The name

o - The object

Returns:

This object

hint

public DBCursor<T> hint(com.mongodb.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

hint

public DBCursor<T> 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 JacksonDBCursort for chaining operations

snapshot

public DBCursor<T> 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'string 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 JacksonDBCursor for chaining operations

explain

public com.mongodb.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

limit

public DBCursor<T> 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

batchSize

public DBCursor<T> 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

Returns:

This object

skip

public DBCursor<T> 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

getCursorId

public long getCursorId()

gets the cursor id.

Returns:

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

close

public void close()

kills the current cursor on the server.

addOption

public DBCursor<T> addOption(int option)

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

Parameters:

option - The option

Returns:

This object

setOptions

public DBCursor<T> setOptions(int options)

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

Parameters:

options - The options

Returns:

This object

resetOptions

public DBCursor<T> resetOptions()

resets the query options

Returns:

This object

getOptions

public int getOptions()

gets the query options

Returns:

The options

numGetMores

public int numGetMores()

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

Returns:

The number of get mores

getSizes

public List<Integer> getSizes()

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

Returns:

The sizes of each batch

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()
                throws com.mongodb.MongoException

Checks if there is another object available

Specified by:

hasNext in interface Iterator<T>

Returns:

true if there is another object available

Throws:

com.mongodb.MongoException

next

public T next()
       throws com.mongodb.MongoException

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

Specified by:

next in interface Iterator<T>

Returns:

the next element

Throws:

com.mongodb.MongoException

curr

public T curr()

Returns the element the cursor is at.

Returns:

the next element

remove

public void remove()

Not implemented.

Specified by:

remove in interface Iterator<T>

length

public int length()
           throws com.mongodb.MongoException

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:

com.mongodb.MongoException - Ig as error occurred

See Also:

count(), size()

toArray

public List<T> toArray()
                throws com.mongodb.MongoException

Converts this cursor to an array.

Returns:

an array of elements

Throws:

com.mongodb.MongoException - If an error occurred

toArray

public List<T> toArray(int max)
                throws com.mongodb.MongoException

Converts this cursor to an array.

Parameters:

max - the maximum number of objects to return

Returns:

an array of objects

Throws:

com.mongodb.MongoException - If an error occurred

itcount

public int itcount()

for testing only! Iterates cursor and counts objects

Returns:

num objects

See Also:

count()

count

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:

com.mongodb.MongoException

See Also:

size()

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:

com.mongodb.MongoException

See Also:

count()

getKeysWanted

public com.mongodb.DBObject getKeysWanted()

gets the fields to be returned

Returns:

The keys wanted

getQuery

public com.mongodb.DBObject getQuery()

gets the query

Returns:

The query

getCollection

public JacksonDBCollection getCollection()

gets the collection

Returns:

The collection

getServerAddress

public com.mongodb.ServerAddress getServerAddress()

Gets the Server Address of the server that data is pulled from. Note that this information is not available if no data has been retrieved yet. Availability is specific to underlying implementation and may vary.

Returns:

The server address

setReadPreference

public DBCursor<T> setReadPreference(com.mongodb.ReadPreference preference)

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

Parameters:

preference - Read Preference to use

Returns:

This object

getReadPreference

public com.mongodb.ReadPreference getReadPreference()

Gets the default read preference

Returns:

The read preference

setDecoderFactory

public DBCursor<T> setDecoderFactory(com.mongodb.DBDecoderFactory fact)

getDecoderFactory

public com.mongodb.DBDecoderFactory getDecoderFactory()

getCursor

public com.mongodb.DBCursor getCursor()

Get the underlying MongoDB cursor. Note, if this is an iterator cursor, calling next() on the underlying cursor will cause this iterator to also progress forward, however, curr() will still return the last object that was loaded by this cursor, not the underlying cursor.

Returns:

The underlying MongoDB cursor

put

protected DBCursor<T> put(String field,
                          String op,
                          Object value)

Overrides:

put in class DBQuery.AbstractBuilder<DBCursor<T>>

putGroup

protected DBCursor<T> putGroup(String op,
                               Object... expressions)

Overrides:

putGroup in class DBQuery.AbstractBuilder<DBCursor<T>>