com.allanbank.mongodb

Interface MongoCursorControl

All Superinterfaces:

AutoCloseable, Closeable

All Known Subinterfaces:

MongoIterator<T>

All Known Implementing Classes:

CursorStreamingCallback, MongoIteratorImpl, SimpleMongoIteratorImpl

public interface MongoCursorControl
extends Closeable

MongoCursorControl provides the controls for a MongoDB cursor interaction. Normally this interface is used via a MongoIterator but in the case of streaming only the controls are returned.

API Notice:

This interface is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2013, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields

Modifier and Type	Field and Description
static String	BATCH_SIZE_FIELD The batch size field in the cursor document.
static String	CURSOR_ID_FIELD The cursor id field in the cursor document.
static String	LIMIT_FIELD The remaining limit field in the cursor document.
static String	NAME_SPACE_FIELD The name space field in the cursor document.
static String	SERVER_FIELD The server name field in the 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.
void	setBatchSize(int batchSize) Sets the size for future batch sizes.
void	stop() Stops the iterator after consuming any received and/or requested batches.

Field Detail

BATCH_SIZE_FIELD

static final String BATCH_SIZE_FIELD

The batch size field in the cursor document.

See Also:

Constant Field Values

CURSOR_ID_FIELD

static final String CURSOR_ID_FIELD

The cursor id field in the cursor document.

See Also:

Constant Field Values

LIMIT_FIELD

static final String LIMIT_FIELD

The remaining limit field in the cursor document.

See Also:

Constant Field Values

NAME_SPACE_FIELD

static final String NAME_SPACE_FIELD

The name space field in the cursor document.

See Also:

Constant Field Values

SERVER_FIELD

static final String SERVER_FIELD

The server name field in the cursor document.

See Also:

Constant Field Values

Method Detail

asDocument

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>
 }
 

Returns:

A document that can be used to restart the cursor. null if the server's cursor has been exhausted or closed.

close

void close()

Close the iterator and release any resources it is holding.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

getBatchSize

int getBatchSize()

Returns the size for batches of documents that are requested.

Returns:

The size of the batches of documents that are requested.

setBatchSize

void setBatchSize(int batchSize)

Sets the size for future batch sizes.

Parameters:

batchSize - The size to request for future batch sizes.

stop

void stop()

Stops the iterator after consuming any received and/or requested batches.

WARNING: This will leave the cursor open on the server. Even a close() on this object will not close the cursor 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(StreamCallback, com.allanbank.mongodb.bson.DocumentAssignable) methods. Use stop() with extreme caution.

The iterator or stream will naturally stop ( Iterator.hasNext() will return false or the stream's call back StreamCallback.done() method will be called) when the current batch and any batches already requested are exhausted.