com.allanbank.mongodb

Interface BatchedAsyncMongoCollection

All Superinterfaces:

AsyncMongoCollection, AutoCloseable, Closeable

All Known Implementing Classes:

BatchedAsyncMongoCollectionImpl

public interface BatchedAsyncMongoCollection
extends AsyncMongoCollection, Closeable

BatchedAsyncMongoCollection provides the interface for submitting batched requests to the MongoDB server. The behavior of the batching is different based on the lowest version member of the MongoDB cluster.

Pre MongoDB 2.6

For MongoDB servers prior to 2.6 each command is sent to the server exactly as it would have been using the non-batched interface except that the commands are sent using a single logical connection. Queries using different, non-primary, ReadPreferences may use different physical connections.

Post MongoDB 2.6

With the introduction of commands to batch inserts, updates and deletes we can now group each sequence of inserts, updates, and deletes within the batch. The actual logic for what writes can be grouped together is controlled by the mode. Users should be sure that they have read and understand the setMode(BatchedWriteMode) JavaDoc. Similar to the pre-2.6 case all of the operations are sent using a single logical connection. Queries using different, non-primary, ReadPreferences may use different physical connections.

Warning: In the case of BatchedWriteMode.SERIALIZE_AND_CONTINUE and BatchedWriteMode.REORDERED it is impossible to determine the number of documents each update and/or delete touched. In these cases each update in the batch will be returned the number of documents touched by the batch as a whole. For this reason the batching of updates and deletes is disabled. It can be enabled by setting setBatchUpdates(boolean) and setBatchDeletes(boolean) to true. We have written a bug report (SERVER-12858) to have the additional information added to the responses so we can remove this restriction.

See Also:

AsyncMongoCollection, MongoCollection

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

2014, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields inherited from interface com.allanbank.mongodb.AsyncMongoCollection

ALL, NONE

Method Summary

Methods

Modifier and Type	Method and Description
void	cancel() Cancels the pending batch of operations without sending them to the server.
void	close() Flushes the pending batch and submits all of the pending requests to the server.
void	flush() Flushes the pending batch and submits all of the pending requests to the server.
void	setBatchDeletes(boolean batchDeletes) Sets if deletes should be batched.
void	setBatchUpdates(boolean batchUpdates) Sets if updates should be batched.
void	setMode(BatchedWriteMode mode) Sets the default mode for batching of writes.

Methods inherited from interface com.allanbank.mongodb.AsyncMongoCollection

aggregateAsync, aggregateAsync, aggregateAsync, aggregateAsync, aggregateAsync, aggregateAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, distinctAsync, distinctAsync, distinctAsync, distinctAsync, distinctAsync, distinctAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, explainAsync, findAndModifyAsync, findAndModifyAsync, findAndModifyAsync, findAndModifyAsync, findAndModifyAsync, findAndModifyAsync, findAsync, findAsync, findAsync, findAsync, findAsync, findAsync, findAsync, findAsync, findAsync, findOneAsync, findOneAsync, findOneAsync, findOneAsync, findOneAsync, findOneAsync, findOneAsync, findOneAsync, findOneAsync, groupByAsync, groupByAsync, groupByAsync, groupByAsync, groupByAsync, groupByAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, mapReduceAsync, mapReduceAsync, mapReduceAsync, mapReduceAsync, mapReduceAsync, mapReduceAsync, parallelScanAsync, parallelScanAsync, parallelScanAsync, parallelScanAsync, parallelScanAsync, parallelScanAsync, saveAsync, saveAsync, saveAsync, saveAsync, saveAsync, saveAsync, stream, stream, stream, stream, stream, stream, stream, stream, streamingFind, streamingFind, streamingFind, streamingFind, streamingFind, streamingFind, textSearchAsync, textSearchAsync, textSearchAsync, textSearchAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, writeAsync, writeAsync, writeAsync, writeAsync, writeAsync, writeAsync

Method Detail

cancel

void cancel()
            throws MongoDbException

Cancels the pending batch of operations without sending them to the server.

After canceling the current batch you may continue to accumulate additional operations to be sent in a different batch.

Throws:

MongoDbException - If there is an error submitting the batched requests.

close

void close()
           throws MongoDbException

Flushes the pending batch and submits all of the pending requests to the server.

This method is equivalent to flush() and is only provided to implement the Closeable interface to support try-with-resource.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

MongoDbException - If there is an error submitting the batched requests.

flush

void flush()
           throws MongoDbException

Flushes the pending batch and submits all of the pending requests to the server.

After flushing the current batch you may continue to accumulate additional operations to be sent in a different batch.

Throws:

MongoDbException - If there is an error submitting the batched requests.

setBatchDeletes

void setBatchDeletes(boolean batchDeletes)

Sets if deletes should be batched. Set to true to batch deletes.

Defaults to false since there is no way to determine how many documents each deletes removed when they are batched.

This setting takes effect for a batch when it is closed or flushed. Intermediate changes between flushes have no effect.

Parameters:

batchDeletes - Set to true to batch deletes.

See Also:

SERVER-12858

setBatchUpdates

void setBatchUpdates(boolean batchUpdates)

Sets if updates should be batched. Set to true to batch updates.

Defaults to false since there is no way to determine how many documents each update touched when they are batched.

This setting takes effect for a batch when it is closed or flushed. Intermediate changes between flushes have no effect.

Parameters:

batchUpdates - Set to true to batch updates.

See Also:

SERVER-12858

setMode

void setMode(BatchedWriteMode mode)

Sets the default mode for batching of writes. This is only applicable to situations where the server supports the MongoDB write command (i.e., version 2.6 and later). There are two cases where the mode will be ignored:

• All inserts with continueOnError set to true will be executed as distinct batches.
• Any change in the durability within the sequence of writes will case the writes to be broken across batches sent to the server. This does not apply to Durability.ACK and Durability.NONE writes and they may be grouped with other writes. Users should be aware that this may cause unexpected write concern failures in those cases.

The default mode is BatchedWriteMode.SERIALIZE_AND_CONTINUE. This provides reasonable performance while maintaining the expected semantics. Note that this mode has the effect of coalescing sequences of inserts (where continueOnError is true), updates and deletes into single operations.

The BatchedWriteMode.SERIALIZE_AND_STOP will cause each insert, update, and delete to be sent as independent commands.

The BatchedWriteMode.REORDERED will cause each sequence of inserts, updates, and deletes without any other command or query to be groups together, reordered, and executed together. This includes the reordering writes within a type (one insert before another to better packet the messages) as well as reordering the writes across types (a delete before an insert to build larger batches).

The mode setting takes effect for a batch when it is closed or flushed. Intermediate changes between flushes have no effect.

Warning: In the case of BatchedWriteMode.SERIALIZE_AND_CONTINUE and BatchedWriteMode.REORDERED it is impossible to determine the number of documents each update and/or delete touched. In these cases each update in the batch will be returned the number of documents touched by the batch as a whole. For this reason the batching of updates and deletes is disabled. It can be enabled by setting setBatchUpdates(boolean) and setBatchDeletes(boolean) to true. We have written a bug report (SERVER-12858) to have the additional information added to the responses so we can remove this restriction.

Parameters:

mode - The default mode for

See Also:

SERVER-12858