com.allanbank.mongodb.client.callback

Class CursorStreamingCallback

java.lang.Object

com.allanbank.mongodb.client.callback.AbstractValidatingReplyCallback

com.allanbank.mongodb.client.callback.CursorStreamingCallback

All Implemented Interfaces:

Callback<Reply>, AddressAware, ReplyCallback, MongoCursorControl, Closeable, AutoCloseable

public final class CursorStreamingCallback
extends AbstractValidatingReplyCallback
implements MongoCursorControl, AddressAware

Callback to convert a CursorableMessage Reply into a series of callback for each document received.

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 ©:

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

Field Summary

Fields inherited from class com.allanbank.mongodb.client.callback.AbstractValidatingReplyCallback

ERROR_CODE_FIELD, ERROR_MESSAGE_FIELDS

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
CursorStreamingCallback(Client client, CursorableMessage originalMessage, boolean command, StreamCallback<Document> results) Create a new CursorCallback.
CursorStreamingCallback(Client client, Document cursorDocument, StreamCallback<Document> results) Create a new CursorCallback 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.
protected MongoDbException	asError(Reply reply, int okValue, int errorNumber, String errorMessage) Creates an exception from the parsed reply fields.
void	close() Overridden to close the iterator and send a KillCursors for the open cursor, if any.
void	exception(Throwable thrown) Called when the operation fails due to an exception.
String	getAddress() Returns the server the original request was sent to.
int	getBatchSize() Returns the size for batches of documents that are requested.
Client	getClient() Returns the client value.
String	getCollectionName() Returns the collection name.
long	getCursorId() Returns the cursor Id value.
String	getDatabaseName() Returns the database name value.
int	getLimit() Returns the limit value.
protected void	handle(Reply reply) Called once the Reply has been validated.
protected boolean	isCommand() Returns true if the callback should expect a command formated cursor reply.
boolean	isLightWeight() Returns true if the callback is lightweight and can be safely performed in the receive thread.
protected List<Document>	loadDocuments(Reply reply) Loads more documents.
protected int	nextBatchSize() Computes the size for the next batch of documents to get.
void	restart() Restarts the stream by sending a request for the next batch of documents.
protected void	sendKill() Sends a KillCursors message if there is an active cursor.
protected void	sendRequest() Sends a request to start the next match of documents.
void	setAddress(String address) Sets the value of the server the original request was sent to.
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 com.allanbank.mongodb.client.callback.AbstractValidatingReplyCallback

asError, asError, asError, asString, callback, checkForError, toInt, verify

Methods inherited from class java.lang.Object

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

Constructor Detail

CursorStreamingCallback

public CursorStreamingCallback(Client client,
                       CursorableMessage originalMessage,
                       boolean command,
                       StreamCallback<Document> results)

Create a new CursorCallback.

Parameters:

client - The client interface to the server.

originalMessage - The original message.

command - If true then the callback should expect a command formated cursor reply.

results - The callback to update with each document.

CursorStreamingCallback

public CursorStreamingCallback(Client client,
                       Document cursorDocument,
                       StreamCallback<Document> results)

Create a new CursorCallback from a cursor document.

Parameters:

client - The client interface to the server.

cursorDocument - The original query.

results - The callback to update with each document.

See Also:

MongoIteratorImpl.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 current state of the stream as a document.

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.

close

public void close()

Overridden to close the iterator and send a KillCursors for the open cursor, if any.

Specified by:

close in interface MongoCursorControl

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

exception

public void exception(Throwable thrown)

Called when the operation fails due to an exception.

Overridden to forward the error the the user.

Specified by:

exception in interface Callback<Reply>

Specified by:

exception in class AbstractValidatingReplyCallback

Parameters:

thrown - The thrown exception.

getAddress

public String getAddress()

Returns the server the original request was sent to.

Returns:

The server the original request was sent to.

getBatchSize

public int getBatchSize()

Returns the size for batches of documents that are requested.

Overridden to set the batch size.

Specified by:

getBatchSize in interface MongoCursorControl

Returns:

The size of the batches of documents that are requested.

getClient

public Client getClient()

Returns the client value.

Returns:

The client value.

getCollectionName

public String getCollectionName()

Returns the collection name.

Returns:

The collection name.

getCursorId

public long getCursorId()

Returns the cursor Id value.

Returns:

The cursor Id value.

getDatabaseName

public String getDatabaseName()

Returns the database name value.

Returns:

The database name value.

getLimit

public int getLimit()

Returns the limit value.

Returns:

The limit value.

isLightWeight

public boolean isLightWeight()

Returns true if the callback is lightweight and can be safely performed in the receive thread.

Overridden to return false.

Specified by:

isLightWeight in interface ReplyCallback

Returns:

True if the callback is lightweight and can be safely performed in the receive thread.

restart

public void restart()

Restarts the stream by sending a request for the next batch of documents.

Throws:

MongoDbException - On a failure to send the request for more document.

setAddress

public void setAddress(String address)

Sets the value of the server the original request was sent to.

Specified by:

setAddress in interface AddressAware

Parameters:

address - The new value for the server the original request was sent to.

setBatchSize

public void setBatchSize(int batchSize)

Sets the size for future batch sizes.

Overridden to get the batch size.

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. Even a MongoCursorControl.close() on this object will not close the cursor on the server. Users should persist the state of the cursor as returned from MongoCursorControl.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 MongoCursorControl.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.

Overridden to stop requesting more batches of documents.

Specified by:

stop in interface MongoCursorControl

asError

protected MongoDbException asError(Reply reply,
                       int okValue,
                       int errorNumber,
                       String errorMessage)

Creates an exception from the parsed reply fields.

Overridden to add the Query to the exception.

Overrides:

asError in class AbstractValidatingReplyCallback

Parameters:

reply - The raw reply.

okValue - The 'ok' field.

errorNumber - The 'errno' field.

errorMessage - The 'errmsg' field.

Returns:

The exception created.

See Also:

AbstractValidatingReplyCallback.asError(Reply, int, int, String)

handle

protected void handle(Reply reply)
               throws MongoDbException

Called once the Reply has been validated.

Overridden to push the documents to the application's callback.

Specified by:

handle in class AbstractValidatingReplyCallback

Parameters:

reply - The Reply to be handled.

Throws:

MongoDbException

See Also:

AbstractReplyCallback.convert(Reply)

isCommand

protected boolean isCommand()

Returns true if the callback should expect a command formated cursor reply.

Returns:

True if the callback should expect a command formated cursor reply.

loadDocuments

protected List<Document> loadDocuments(Reply reply)
                                throws RuntimeException

Loads more documents. This issues a get_more command as soon as the previous results start to be used.

Parameters:

reply - The last reply received.

Returns:

The list of loaded documents.

Throws:

RuntimeException - On a failure to load documents.

nextBatchSize

protected int nextBatchSize()

Computes the size for the next batch of documents to get.

Returns:

The returnNex

sendKill

protected void sendKill()
                 throws MongoDbException

Sends a KillCursors message if there is an active cursor.

Throws:

MongoDbException - On a failure to send the KillCursors message.

sendRequest

protected void sendRequest()
                    throws MongoDbException

Sends a request to start the next match of documents.

Throws:

MongoDbException - On a failure to send the request.