com.allanbank.mongodb.client

Class MongoIteratorImpl

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-2013, 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(Document cursorDocument, Client client) Create a new MongoIteratorImpl from a cursor document.
MongoIteratorImpl(Query originalQuery, Client client, String server, Reply reply) Create a new MongoDBInterator.

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.

Methods inherited from class java.lang.Object

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

Constructor Detail

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

MongoIteratorImpl

public MongoIteratorImpl(Query 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.

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

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.