MongoIteratorImpl (mongodb-async-driver 2.0.1 API)

java.lang.Object
- com.allanbank.mongodb.client.MongoIteratorImpl

All Implemented Interfaces:

ClosableIterator<Document>, MongoCursorControl, MongoIterator<Document>, Closeable, AutoCloseable, Iterable<Document>, Iterator<Document>
```
public class MongoIteratorImpl
extends Object
implements MongoIterator<Document>
```
Iterator over the results of the MongoDB cursor.

API Warning:

This class is NOT part of the drivers API. This class may be mutated in incompatible ways between any two releases of the driver.

Copyright ©:

2011-2014, Allanbank Consulting, Inc., All Rights Reserved

Field Summary
- Fields inherited from interface com.allanbank.mongodb.MongoCursorControl
  BATCH_SIZE_FIELD, CURSOR_ID_FIELD, LIMIT_FIELD, NAME_SPACE_FIELD, SERVER_FIELD

Constructor Summary

Constructors
Constructor and Description
`MongoIteratorImpl(CursorableMessage originalQuery, Client client, String server, Reply reply)` Create a new MongoDBInterator.
`MongoIteratorImpl(Document cursorDocument, Client client)` Create a new MongoIteratorImpl from a cursor document.

Method Summary

Methods
Modifier and Type	Method and Description
`Document`	`asDocument()` Returns a `Document` that can be used to restart the cursor/iterator.
`void`	`close()` Close the iterator and release any resources it is holding.
`int`	`getBatchSize()` Returns the size for batches of documents that are requested.
`protected Client`	`getClient()` Returns the client value.
`protected String`	`getCollectionName()` Returns the collection name.
`protected long`	`getCursorId()` Returns the cursor Id value.
`protected String`	`getDatabaseName()` Returns the database name value.
`protected int`	`getLimit()` Returns the limit value.
`ReadPreference`	`getReadPerference()` Returns the iterator's read preference which points to the original server performing the query.
`boolean`	`hasNext()`
`Iterator<Document>`	`iterator()`
`protected void`	`loadDocuments()` Loads more documents into the iterator.
`protected List<Document>`	`loadDocuments(boolean blockForTailable)` Loads more documents into the iterator.
`Document`	`next()`
`int`	`nextBatchSize()` Computes the size for the next batch of documents to get.
`void`	`remove()`
`void`	`restart()` Restarts the iterator by sending a request for more documents.
`protected long`	`retreiveCursorIdFromPendingRequest(long cursorId, Future<Reply> replyFuture)` If the current cursor id is zero then waits for the response from the pending request to determine the real cursor id.
`protected void`	`sendRequest()` Sends a request for more documents.
`void`	`setBatchSize(int batchSize)` Sets the size for future batch sizes.
`void`	`stop()` Stops the iterator after consuming any received and/or requested batches.
`Object[]`	`toArray()` Consumes all of the elements in the iterator and returns them in a single array.
`<S> S[]`	`toArray(S[] to)` Consumes all of the elements in the iterator and returns them in a single array.
`List<Document>`	`toList()` Consumes all of the elements in the iterator and returns them in a single mutable list.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MongoIteratorImpl
```
public MongoIteratorImpl(CursorableMessage originalQuery,
                 Client client,
                 String server,
                 Reply reply)
```
    Create a new MongoDBInterator.
    
    Parameters:
    originalQuery - The original query being iterated over.
    client - The client for issuing more requests.
    server - The server that received the original query request.
    reply - The initial results of the query that are available.
  - MongoIteratorImpl
```
public MongoIteratorImpl(Document cursorDocument,
                 Client client)
```
    Create a new MongoIteratorImpl from a cursor document.
    
    Parameters:
    client - The client interface to the server.
    cursorDocument - The original query.
    See Also:
    asDocument()
- Method Detail
  - asDocument
```
public Document asDocument()
```
    Returns a Document that can be used to restart the cursor/iterator.
    If this iterator is exhausted or closed then the cursor is also closed on the server and this method will return null.
    
    If the cursor/Find was not created with out a timeout then eventually the server will automatically remove the cursor and the restart will fail.
    
    Returns the active cursor in the form:
    { "ns" : '<database_name>.$lt;collection_name>', "cursor_id" : <cursor_id>, "server" : '<server>', "limit" : <remaining_limit> "batch_size" : <batch_size> }
    Overridden to return the active cursor in the defined format.
    Specified by:
    
    asDocument in interface MongoCursorControl
    
    Returns:
    A document that can be used to restart the cursor. null if the server's cursor has been exhausted or closed.
    See Also:
    ClientImpl.isCursorDocument(Document)
  - close
```
public void close()
```
    Close the iterator and release any resources it is holding.
    Overridden to close the iterator and send a KillCursors for the open cursor, if any.
    
    Specified by:
    
    close in interface ClosableIterator<Document>
    
    Specified by:
    
    close in interface MongoCursorControl
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
  - getBatchSize
```
public int getBatchSize()
```
    Returns the size for batches of documents that are requested.
    Overridden to get the batch size from the original query or set explicitly.
    
    Specified by:
    
    getBatchSize in interface ClosableIterator<Document>
    
    Specified by:
    
    getBatchSize in interface MongoCursorControl
    
    Returns:
    The size of the batches of documents that are requested.
  - getReadPerference
```
public ReadPreference getReadPerference()
```
    Returns the iterator's read preference which points to the original server performing the query.
    
    Returns:
    The iterator's read preference which points to the original server performing the query.
  - hasNext
```
public boolean hasNext()
```
    Overridden to return true if there are more documents.
    
    Specified by:
    
    hasNext in interface Iterator<Document>
  - iterator
```
public Iterator<Document> iterator()
```
    Overridden to return this iterator.
    
    Specified by:
    
    iterator in interface Iterable<Document>
  - next
```
public Document next()
```
    Overridden to return the next document from the query.
    
    Specified by:
    
    next in interface Iterator<Document>
    
    See Also:
    Iterator.next()
  - nextBatchSize
```
public int nextBatchSize()
```
    Computes the size for the next batch of documents to get.
    
    Returns:
    The returnNex
  - remove
```
public void remove()
```
    Overridden to throw and UnsupportedOperationException.
    
    Specified by:
    
    remove in interface Iterator<Document>
    
    See Also:
    Iterator.remove()
  - restart
```
public void restart()
             throws MongoDbException
```
    Restarts the iterator by sending a request for more documents.
    
    Throws:
    
    MongoDbException - On a failure to send the request for more document.
  - setBatchSize
```
public void setBatchSize(int batchSize)
```
    Sets the size for future batch sizes.
    Overridden to set the batch size.
    
    Specified by:
    
    setBatchSize in interface ClosableIterator<Document>
    
    Specified by:
    
    setBatchSize in interface MongoCursorControl
    
    Parameters:
    batchSize - The size to request for future batch sizes.
  - stop
```
public void stop()
```
    Stops the iterator after consuming any received and/or requested batches.
    WARNING: This will leave the cursor open on the server. Users should persist the state of the cursor as returned from asDocument() and restart the cursor using one of the MongoClient.restart(com.allanbank.mongodb.bson.DocumentAssignable) or MongoClient.restart(com.allanbank.mongodb.StreamCallback, com.allanbank.mongodb.bson.DocumentAssignable) methods. Use with extreme caution.
    
    The iterator will naturally stop (hasNext() will return false) when the current batch and any already requested batches are finished.
    
    Specified by:
    
    stop in interface MongoCursorControl
  - toArray
```
public Object[] toArray()
```
    Consumes all of the elements in the iterator and returns them in a single array.
    WARNING: This method loads all of the iterator results into memory and may cause an OutOfMemoryError.
    
    Overridden to return the remaining elements as a array.
    
    Specified by:
    
    toArray in interface MongoIterator<Document>
    
    Returns:
    The remaining elements in the iterator.
  - toArray
```
public <S> S[] toArray(S[] to)
```
    Consumes all of the elements in the iterator and returns them in a single array.
    WARNING: This method loads all of the iterator results into memory and may cause an OutOfMemoryError.
    
    Overridden to return the remaining elements as a array.
    
    Specified by:
    
    toArray in interface MongoIterator<Document>
    
    Type Parameters:
    S - The type of elements in the array.
    Parameters:
    to - The array to copy into. If not the right size a new array will be allocated of the right size.
    
    Returns:
    The remaining elements in the iterator.
  - toList
```
public List<Document> toList()
```
    Consumes all of the elements in the iterator and returns them in a single mutable list.
    WARNING: This method loads all of the iterator results into memory and may cause an OutOfMemoryError.
    
    Overridden to return the remaining elements as a list.
    
    Specified by:
    
    toList in interface MongoIterator<Document>
    
    Returns:
    The remaining elements in the iterator.
  - getClient
```
protected Client getClient()
```
    Returns the client value.
    
    Returns:
    The client value.
  - getCollectionName
```
protected String getCollectionName()
```
    Returns the collection name.
    
    Returns:
    The collection name.
  - getCursorId
```
protected long getCursorId()
```
    Returns the cursor Id value.
    
    Returns:
    The cursor Id value.
  - getDatabaseName
```
protected String getDatabaseName()
```
    Returns the database name value.
    
    Returns:
    The database name value.
  - getLimit
```
protected int getLimit()
```
    Returns the limit value.
    
    Returns:
    The limit value.
  - loadDocuments
```
protected void loadDocuments()
                      throws RuntimeException
```
    Loads more documents into the iterator. This iterator issues a get_more command as soon as the previous results start to be used.
    
    Throws:
    
    RuntimeException - On a failure to load documents.
  - loadDocuments
```
protected List<Document> loadDocuments(boolean blockForTailable)
                                throws RuntimeException
```
    Loads more documents into the iterator. This iterator issues a get_more command as soon as the previous results start to be used.
    
    Parameters:
    blockForTailable - If true then the method will recursively call itself on a tailable cursor with no results. This makes the call blocking. It false then the call will not block. This is used by the method to ensure that the outermost load blocks but the recursion is not inifinite.
    
    Returns:
    The list of loaded documents.
    
    Throws:
    
    RuntimeException - On a failure to load documents.
  - retreiveCursorIdFromPendingRequest
```
protected long retreiveCursorIdFromPendingRequest(long cursorId,
                                      Future<Reply> replyFuture)
```
    If the current cursor id is zero then waits for the response from the pending request to determine the real cursor id.
    
    Parameters:
    cursorId - The presumed cursor id.
    replyFuture - The pending reply's future.
    
    Returns:
    The best known cursor id.
  - sendRequest
```
protected void sendRequest()
                    throws MongoDbException
```
    Sends a request for more documents.
    
    Throws:
    
    MongoDbException - On a failure to send the request for more document.

Class MongoIteratorImpl

Field Summary

Fields inherited from interface com.allanbank.mongodb.MongoCursorControl

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MongoIteratorImpl

MongoIteratorImpl

Method Detail

asDocument

close

getBatchSize

getReadPerference

hasNext

iterator

next

nextBatchSize

remove

restart

setBatchSize

stop

toArray

toArray

toList

getClient

getCollectionName

getCursorId

getDatabaseName

getLimit

loadDocuments

loadDocuments

retreiveCursorIdFromPendingRequest

sendRequest