@NotThreadSafe public class DBCursor extends java.lang.Object implements Cursor, java.lang.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<DBObject> obj = collection.find( query ).skip( 1000 ).limit( 100 ).toArray();
| Modifier and Type | Class and Description |
|---|---|
(package private) static class |
DBCursor.CursorType
Types of cursors: iterator or array.
|
| Modifier and Type | Field and Description |
|---|---|
private java.util.ArrayList<DBObject> |
_all |
private int |
_batchSize |
private DBCollection |
_collection |
private DBObject |
_cur |
private DBCursor.CursorType |
_cursorType |
private DBDecoderFactory |
_decoderFact |
private boolean |
_disableBatchSizeTracking |
private boolean |
_explain |
private java.lang.String |
_hint |
private DBObject |
_hintDBObj |
private QueryResultIterator |
_it |
private DBObject |
_keysWanted |
private int |
_limit |
private long |
_maxTimeMS |
private int |
_num |
private int |
_options |
private DBObject |
_orderBy |
private DBObject |
_query |
private ReadPreference |
_readPref |
private int |
_skip |
private boolean |
_snapshot |
private DBObject |
_specialFields |
| Constructor and Description |
|---|
DBCursor(DBCollection collection,
DBObject q,
DBObject k,
ReadPreference preference)
Initializes a new database cursor.
|
| Modifier and Type | Method and Description |
|---|---|
private void |
_check() |
(package private) void |
_checkType(DBCursor.CursorType type) |
(package private) void |
_fill(int n) |
private boolean |
_hasNext() |
private void |
_lookForHints()
if there is a hint to use, use it
|
private DBObject |
_next() |
DBCursor |
addOption(int option)
Adds a query option.
|
DBCursor |
addSpecial(java.lang.String name,
java.lang.Object o)
Adds a special operator like $maxScan or $returnKey.
|
DBCursor |
batchSize(int numberOfElements)
Limits the number of elements returned in one batch.
|
void |
close()
Terminates this cursor on the server.
|
DBCursor |
comment(java.lang.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 |
disableBatchSizeTracking()
Deprecated.
This method is being added temporarily, and will be removed along with
getSizes() in the next major release |
DBObject |
explain()
Returns an object containing basic information about the execution of the query that created this cursor.
|
int |
getBatchSize()
Gets the batch size.
|
DBCollection |
getCollection()
Gets the collection.
|
long |
getCursorId()
Gets the server's identifier for this Cursor.
|
private DBDecoder |
getDecoder() |
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.
|
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.
|
java.util.List<java.lang.Integer> |
getSizes()
Deprecated.
there is no replacement for this method
|
(package private) boolean |
hasFinalizer() |
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(java.lang.String indexName)
Informs the database of an indexed field of the collection in order to improve performance.
|
boolean |
isBatchSizeTrackingDisabled()
Deprecated.
This method is being added temporarily, and will be removed along with
getSizes() in the next major release |
int |
itcount()
For testing only! Iterates cursor and counts objects
|
java.util.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 |
maxScan(int max)
Limits the number of documents a cursor will return for a query.
|
DBCursor |
maxTime(long maxTime,
java.util.concurrent.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.
|
int |
numGetMores()
Deprecated.
there is no replacement for this method
|
int |
numSeen()
Returns the number of objects through which the cursor has iterated.
|
DBObject |
one()
Returns the first document that matches the query.
|
void |
remove()
Not implemented.
|
DBCursor |
resetOptions()
Resets the query options.
|
DBCursor |
returnKey()
Forces the cursor to only return fields included in the index.
|
DBCursor |
setDecoderFactory(DBDecoderFactory fact)
Sets the factory that will be used create a
DBDecoder that will be used to decode BSON documents into DBObject instances. |
DBCursor |
setOptions(int options)
Sets the query option - see Bytes.QUERYOPTION_* for list.
|
DBCursor |
setReadPreference(ReadPreference readPreference)
Sets the read preference for this cursor.
|
DBCursor |
showDiskLoc()
Modifies the documents returned to include references to the on-disk location of each document.
|
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 |
slaveOk()
Deprecated.
Replaced with
ReadPreference.secondaryPreferred() |
DBCursor |
snapshot()
Use snapshot mode for the query.
|
DBCursor |
sort(DBObject orderBy)
Sorts this cursor's elements.
|
java.util.List<DBObject> |
toArray()
Converts this cursor to an array.
|
java.util.List<DBObject> |
toArray(int max)
Converts this cursor to an array.
|
java.lang.String |
toString() |
DBObject |
tryNext()
Non blocking check for tailable cursors to see if another object is available.
|
private final DBCollection _collection
private final DBObject _query
private final DBObject _keysWanted
private DBObject _orderBy
private java.lang.String _hint
private DBObject _hintDBObj
private boolean _explain
private int _limit
private int _batchSize
private int _skip
private boolean _snapshot
private int _options
private long _maxTimeMS
private ReadPreference _readPref
private DBDecoderFactory _decoderFact
private DBObject _specialFields
private QueryResultIterator _it
private DBCursor.CursorType _cursorType
private DBObject _cur
private int _num
private boolean _disableBatchSizeTracking
private final java.util.ArrayList<DBObject> _all
public DBCursor(DBCollection collection, DBObject q, DBObject k, ReadPreference preference)
collection - collection to useq - query to performk - keys to return from the querypreference - the Read Preference for this querypublic DBCursor comment(java.lang.String comment)
comment - the comment that is to appear in the profiler outputthis so calls can be chainedpublic DBCursor maxScan(int max)
max - the maximum number of documents to returnthis so calls can be chainedlimit(int)public DBCursor max(DBObject max)
max - a document specifying the fields, and the upper bound values for those fieldsthis so calls can be chainedpublic DBCursor min(DBObject min)
min - a document specifying the fields, and the lower bound values for those fieldsthis so calls can be chainedpublic DBCursor returnKey()
this so calls can be chainedpublic DBCursor showDiskLoc()
$diskLocthis so calls can be chainedpublic DBCursor copy()
public java.util.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.
iterator in interface java.lang.Iterable<DBObject>public DBCursor sort(DBObject orderBy)
orderBy - the fields by which to sortpublic DBCursor addSpecial(java.lang.String name, java.lang.Object o)
addSpecial("$returnKey", 1)
addSpecial("$maxScan", 100)
name - the name of the special query operatoro - the value of the special query operatorthis so calls can be chainedpublic DBCursor hint(DBObject indexKeys)
indexKeys - a DBObject with fields and directionpublic DBCursor hint(java.lang.String indexName)
indexName - the name of an indexpublic DBCursor maxTime(long maxTime, java.util.concurrent.TimeUnit timeUnit)
maxTime - the maximum time that the server will allow the query to run, before killing the operation. A non-zero value requires
a server version >= 2.6timeUnit - the time unitpublic DBCursor snapshot()
this so calls can be chainedsort(DBObject),
hint(DBObject)public DBObject explain()
DBObject with a number of fields, including but not limited to:
DBObject containing the explain output for this DBCursor's queryMongoExceptionpublic DBCursor limit(int limit)
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.limit - the number of elements to returnpublic 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.
numberOfElements - the number of elements to return in a batchthis so calls can be chainedpublic DBCursor skip(int numberOfElements)
numberOfElements - the number of elements to skipjava.lang.IllegalStateException - if the cursor has started to be iterated throughpublic long getCursorId()
CursorgetCursorId in interface Cursorpublic void close()
Cursor@Deprecated public DBCursor slaveOk()
ReadPreference.secondaryPreferred()ReadPreference.secondaryPreferred(),
ReadPreference.secondaryPreferred()public DBCursor addOption(int option)
option - the option to be addedthis so calls can be chainedBytespublic DBCursor setOptions(int options)
options - the bitmask of optionsthis so calls can be chainedBytespublic DBCursor resetOptions()
this so calls can be chainedpublic int getOptions()
public int getLimit()
public int getBatchSize()
private void _check()
private DBDecoder getDecoder()
private void _lookForHints()
void _checkType(DBCursor.CursorType type)
private DBObject _next()
@Deprecated public int numGetMores()
@Deprecated public java.util.List<java.lang.Integer> getSizes()
@Deprecated public DBCursor disableBatchSizeTracking()
getSizes() in the next major releasegetSizes()@Deprecated public boolean isBatchSizeTrackingDisabled()
getSizes() in the next major releasegetSizes(),
disableBatchSizeTracking()private boolean _hasNext()
public int numSeen()
public boolean hasNext()
Note: Automatically adds the Bytes.QUERYOPTION_AWAITDATA option to any cursors with the
Bytes.QUERYOPTION_TAILABLE option set. For non blocking tailable cursors see tryNext().
hasNext in interface java.util.Iterator<DBObject>MongoExceptionpublic DBObject tryNext()
Returns the object the cursor is at and moves the cursor ahead by one or return null if no documents is available.
MongoExceptionpublic DBObject next()
Note: Automatically adds the Bytes.QUERYOPTION_AWAITDATA option to any cursors with the
Bytes.QUERYOPTION_TAILABLE option set. For non blocking tailable cursors see tryNext().
next in interface java.util.Iterator<DBObject>public DBObject curr()
public void remove()
remove in interface java.util.Iterator<DBObject>void _fill(int n)
public int length()
MongoExceptioncount(),
size()public java.util.List<DBObject> toArray()
MongoExceptionpublic java.util.List<DBObject> toArray(int max)
max - the maximum number of objects to returnMongoExceptionpublic int itcount()
MongoExceptioncount()public int count()
MongoExceptionsize()public DBObject one()
public int size()
MongoExceptioncount()public DBObject getKeysWanted()
public DBObject getQuery()
public DBCollection getCollection()
public ServerAddress getServerAddress()
getServerAddress in interface Cursorpublic DBCursor setReadPreference(ReadPreference readPreference)
ReadPreference for more information.readPreference - read preference to usethis so calls can be chainedpublic ReadPreference getReadPreference()
public DBCursor setDecoderFactory(DBDecoderFactory fact)
DBDecoder that will be used to decode BSON documents into DBObject instances.fact - the DBDecoderFactorythis so calls can be chainedpublic DBDecoderFactory getDecoderFactory()
public java.lang.String toString()
toString in class java.lang.Objectboolean hasFinalizer()