Package com.mongodb

Class DBCursor

  • All Implemented Interfaces:
    Cursor, java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<DBObject>, java.util.Iterator<DBObject>

    @NotThreadSafe
    @Deprecated(since="2021-05-27")
    public class DBCursor
    extends java.lang.Object
    implements Cursor, java.lang.Iterable<DBObject>
    Deprecated.
    Usage of this API is not supported in AEM as a Cloud Service.

    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 Mongo.getDB(String) for further information about the effective deprecation of this class.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      DBCursor addOption​(int option)
      Deprecated.
      Prefer per-option methods, e.g.
      DBCursor addSpecial​(java.lang.String name, java.lang.Object value)
      Deprecated.
      Prefer per-operator methods, e.g.
      DBCursor batchSize​(int numberOfElements)
      Deprecated.
      Limits the number of elements returned in one batch.
      void close()
      Deprecated.
      Terminates this cursor on the server.
      DBCursor comment​(java.lang.String comment)
      Deprecated.
      Adds a comment to the query to identify queries in the database profiler output.
      DBCursor copy()
      Deprecated.
      Creates a copy of an existing database cursor.
      int count()
      Deprecated.
      Counts the number of objects matching the query.
      DBObject curr()
      Deprecated.
      Returns the element the cursor is at.
      DBCursor cursorType​(CursorType cursorType)
      Deprecated.
      Sets the cursor type.
      DBObject explain()
      Deprecated.
      Replace with direct use of the explain command using the runCommand helper method
      int getBatchSize()
      Deprecated.
      Gets the batch size.
      Collation getCollation()
      Deprecated.
      Returns the collation options
      DBCollection getCollection()
      Deprecated.
      Gets the collection.
      long getCursorId()
      Deprecated.
      Gets the server's identifier for this Cursor.
      DBDecoderFactory getDecoderFactory()
      Deprecated.
      Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.
      DBObject getKeysWanted()
      Deprecated.
      Gets the fields to be returned.
      int getLimit()
      Deprecated.
      Gets the query limit.
      int getOptions()
      Deprecated.
      DBObject getQuery()
      Deprecated.
      Gets the query.
      ReadPreference getReadPreference()
      Deprecated.
      Gets the default read preference.
      ServerAddress getServerAddress()
      Deprecated.
      Gets the address of the server that data is pulled from.
      boolean hasNext()
      Deprecated.
      Checks if there is another object available.
      DBCursor hint​(DBObject indexKeys)
      Deprecated.
      Informs the database of indexed fields of the collection in order to improve performance.
      DBCursor hint​(java.lang.String indexName)
      Deprecated.
      int itcount()
      Deprecated.
      For testing only! Iterates cursor and counts objects
      java.util.Iterator<DBObject> iterator()
      Deprecated.
      Creates a copy of this cursor object that can be iterated.
      int length()
      Deprecated.
      Pulls back all items into an array and returns the number of objects.
      DBCursor limit​(int limit)
      Deprecated.
      Limits the number of elements returned.
      DBCursor max​(DBObject max)
      Deprecated.
      Specifies an exclusive upper limit for the index to use in a query.
      DBCursor maxScan​(int max)
      Deprecated.
      Deprecated as of MongoDB 4.0 release
      DBCursor maxTime​(long maxTime, java.util.concurrent.TimeUnit timeUnit)
      Deprecated.
      Set the maximum execution time for operations on this cursor.
      DBCursor min​(DBObject min)
      Deprecated.
      Specifies an inclusive lower limit for the index to use in a query.
      DBObject next()
      Deprecated.
      Returns the object the cursor is at and moves the cursor ahead by one.
      DBCursor noCursorTimeout​(boolean noCursorTimeout)
      Deprecated.
      The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use.
      int numSeen()
      Deprecated.
      Returns the number of objects through which the cursor has iterated.
      DBObject one()
      Deprecated.
      Returns the first document that matches the query.
      DBCursor oplogReplay​(boolean oplogReplay)
      Deprecated.
      Users should not set this under normal circumstances.
      DBCursor partial​(boolean partial)
      Deprecated.
      Get partial results from a sharded cluster if one or more shards are unreachable (instead of throwing an error).
      void remove()
      Deprecated.
       
      DBCursor resetOptions()
      Deprecated.
      DBCursor returnKey()
      Deprecated.
      Forces the cursor to only return fields included in the index.
      DBCursor setCollation​(Collation collation)
      Deprecated.
      Sets the collation options
      DBCursor setDecoderFactory​(DBDecoderFactory factory)
      Deprecated.
      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)
      Deprecated.
      DBCursor setReadPreference​(ReadPreference readPreference)
      Deprecated.
      Sets the read preference for this cursor.
      DBCursor showDiskLoc()
      Deprecated.
      showDiskLoc has been deprecated in the MongoDB server.
      int size()
      Deprecated.
      Counts the number of objects matching the query this does take limit/skip into consideration
      DBCursor skip​(int numberOfElements)
      Deprecated.
      Discards a given number of elements at the beginning of the cursor.
      DBCursor slaveOk()
      Deprecated.
      DBCursor snapshot()
      Deprecated.
      Deprecated in MongoDB 3.6 release and removed in MongoDB 4.0 release
      DBCursor sort​(DBObject orderBy)
      Deprecated.
      Sorts this cursor's elements.
      java.util.List<DBObject> toArray()
      Deprecated.
      Converts this cursor to an array.
      java.util.List<DBObject> toArray​(int max)
      Deprecated.
      Converts this cursor to an array.
      java.lang.String toString()
      Deprecated.
       
      DBObject tryNext()
      Deprecated.
      Non blocking check for tailable cursors to see if another object is available.
      • Methods inherited from class java.lang.Object

        equals, 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)
        Deprecated.
        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)
        Deprecated.
        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()
        Deprecated.
        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()
        Deprecated.
        Checks if there is another object available.

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

        Specified by:
        hasNext in interface java.util.Iterator<DBObject>
        Returns:
        true if there is another object available
      • tryNext

        @Nullable
        public DBObject tryNext()
        Deprecated.
        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
        java.lang.IllegalArgumentException - if the cursor is not tailable
      • curr

        public DBObject curr()
        Deprecated.
        Returns the element the cursor is at.
        Returns:
        the current element
      • remove

        public void remove()
        Deprecated.
        Specified by:
        remove in interface java.util.Iterator<DBObject>
      • addOption

        @Deprecated
        public DBCursor addOption​(int option)
        Deprecated.
        Prefer per-option methods, e.g. cursorType(CursorType), noCursorTimeout(boolean), etc.
        Adds a query option. See Bytes.QUERYOPTION_* for list.
        Parameters:
        option - the option to be added
        Returns:
        this so calls can be chained
        See Also:
        Bytes
      • setOptions

        @Deprecated
        public DBCursor setOptions​(int options)
        Deprecated.
        Sets the query option - see Bytes.QUERYOPTION_* for list.
        Parameters:
        options - the bitmask of options
        Returns:
        this so calls can be chained
        See Also:
        Bytes
      • resetOptions

        @Deprecated
        public DBCursor resetOptions()
        Deprecated.
        Resets the query options.
        Returns:
        this so calls can be chained
      • getOptions

        @Deprecated
        public int getOptions()
        Deprecated.
        Gets the query options.
        Returns:
        the bitmask of options
      • getLimit

        public int getLimit()
        Deprecated.
        Gets the query limit.
        Returns:
        the limit, or 0 if no limit is set
      • getBatchSize

        public int getBatchSize()
        Deprecated.
        Gets the batch size.
        Returns:
        the batch size
      • addSpecial

        @Deprecated
        public DBCursor addSpecial​(@Nullable
                                   java.lang.String name,
                                   @Nullable
                                   java.lang.Object value)
        Deprecated.
        Prefer per-operator methods, e.g. comment(String), explain(), etc.
        Adds a special operator like $comment or $returnKey. For example:
            addSpecial("$returnKey", 1)
            addSpecial("$comment", "this is a special query)
         
        Parameters:
        name - the name of the special query operator
        value - the value of the special query operator
        Returns:
        this so calls can be chained
      • comment

        public DBCursor comment​(java.lang.String comment)
        Deprecated.
        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
      • maxScan

        @Deprecated
        public DBCursor maxScan​(int max)
        Deprecated.
        Deprecated as of MongoDB 4.0 release
        Limits the number of documents a cursor will return for a query.
        Parameters:
        max - the maximum number of documents to return
        Returns:
        this so calls can be chained
        Since:
        2.12
        See Also:
        limit(int)
      • max

        public DBCursor max​(DBObject max)
        Deprecated.
        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
      • min

        public DBCursor min​(DBObject min)
        Deprecated.
        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
      • returnKey

        public DBCursor returnKey()
        Deprecated.
        Forces the cursor to only return fields included in the index.
        Returns:
        this so calls can be chained
        Since:
        2.12
      • showDiskLoc

        @Deprecated
        public DBCursor showDiskLoc()
        Deprecated.
        showDiskLoc has been deprecated in the MongoDB server. There is no replacement for it.
        Modifies the documents returned to include references to the on-disk location of each document. The location will be returned in a property named $diskLoc
        Returns:
        this so calls can be chained
        Since:
        2.12
      • hint

        public DBCursor hint​(DBObject indexKeys)
        Deprecated.
        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

        @Deprecated
        public DBCursor hint​(java.lang.String indexName)
        Deprecated.
        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
      • maxTime

        public DBCursor maxTime​(long maxTime,
                                java.util.concurrent.TimeUnit timeUnit)
        Deprecated.
        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. A non-zero value requires a server version >= 2.6
        timeUnit - the time unit
        Returns:
        same DBCursor for chaining operations
        Since:
        2.12.0
      • snapshot

        @Deprecated
        public DBCursor snapshot()
        Deprecated.
        Deprecated in MongoDB 3.6 release and removed in MongoDB 4.0 release
        Use snapshot mode for the query. Snapshot mode prevents the cursor from returning a document more than once because an intervening write operation results in a move of the document. Even in snapshot mode, documents inserted or deleted during the lifetime of the cursor may or may not be returned. Currently, snapshot mode may not be used with sorting or explicit hints.
        Returns:
        this so calls can be chained
        See Also:
        sort(DBObject), hint(DBObject)
      • explain

        @Deprecated
        public DBObject explain()
        Deprecated.
        Replace with direct use of the explain command using the runCommand helper method
        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
      • cursorType

        public DBCursor cursorType​(CursorType cursorType)
        Deprecated.
        Sets the cursor type.
        Parameters:
        cursorType - the cursor type, which may not be null
        Returns:
        this
        Since:
        3.9
      • oplogReplay

        public DBCursor oplogReplay​(boolean oplogReplay)
        Deprecated.
        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)
        Deprecated.
        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)
        Deprecated.
        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)
        Deprecated.
        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)
        Deprecated.
        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
      • batchSize

        public DBCursor batchSize​(int numberOfElements)
        Deprecated.

        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)
        Deprecated.
        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:
        java.lang.IllegalStateException - if the cursor has started to be iterated through
      • getCursorId

        public long getCursorId()
        Deprecated.
        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()
        Deprecated.
        Returns the number of objects through which the cursor has iterated.
        Returns:
        the number of objects seen
      • close

        public void close()
        Deprecated.
        Description copied from interface: Cursor
        Terminates this cursor on the server.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface Cursor
      • iterator

        public java.util.Iterator<DBObject> iterator()
        Deprecated.

        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 java.lang.Iterable<DBObject>
        Returns:
        an iterator
      • toArray

        public java.util.List<DBObject> toArray()
        Deprecated.
        Converts this cursor to an array.
        Returns:
        an array of elements
        Throws:
        MongoException - if failed
      • toArray

        public java.util.List<DBObject> toArray​(int max)
        Deprecated.
        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()
        Deprecated.
        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()
        Deprecated.
        Returns the first document that matches the query.
        Returns:
        the first matching document
        Since:
        2.12
      • length

        public int length()
        Deprecated.
        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()
        Deprecated.
        For testing only! Iterates cursor and counts objects
        Returns:
        num objects
        Throws:
        MongoException - if failed
        See Also:
        count()
      • size

        public int size()
        Deprecated.
        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()
        Deprecated.
        Gets the fields to be returned.
        Returns:
        the field selector that cursor used
      • getQuery

        public DBObject getQuery()
        Deprecated.
        Gets the query.
        Returns:
        the query that cursor used
      • getCollection

        public DBCollection getCollection()
        Deprecated.
        Gets the collection.
        Returns:
        the collection that data is pulled from
      • getServerAddress

        @Nullable
        public ServerAddress getServerAddress()
        Deprecated.
        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)
        Deprecated.
        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()
        Deprecated.
        Gets the default read preference.
        Returns:
        the readPreference used by this cursor
      • getCollation

        @Nullable
        public Collation getCollation()
        Deprecated.
        Returns the collation options
        Returns:
        the collation options
        Since:
        3.4
      • setCollation

        public DBCursor setCollation​(@Nullable
                                     Collation collation)
        Deprecated.
        Sets the collation options

        A null value represents the server default.

        Parameters:
        collation - the collation options to use
        Returns:
        this
        Since:
        3.4
      • setDecoderFactory

        public DBCursor setDecoderFactory​(DBDecoderFactory factory)
        Deprecated.
        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()
        Deprecated.
        Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.
        Returns:
        the decoder factory.
      • toString

        public java.lang.String toString()
        Deprecated.
        Overrides:
        toString in class java.lang.Object