com.allanbank.mongodb.client

Class AbstractMongoOperations

java.lang.Object

com.allanbank.mongodb.client.AbstractMongoOperations

Direct Known Subclasses:

AbstractAsyncMongoCollection

public abstract class AbstractMongoOperations
extends Object

AbstractMongoOperations provides the core functionality for the operations on a MongoDB collection.

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

2014, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DELETE_SINGLE_DELETE_DEFAULT The default for if a delete should only delete the first document it matches.
static Document	EMPTY_INDEX_OPTIONS The default empty index options.
static String	ID_FIELD_NAME The name of the canonical id field for MongoDB.
static boolean	INSERT_CONTINUE_ON_ERROR_DEFAULT The default for if an insert should continue on an error.
protected Client	myClient The client for interacting with MongoDB.
protected MongoDatabase	myDatabase The name of the database we interact with.
protected String	myName The name of the collection we interact with.
static Document	UNIQUE_INDEX_OPTIONS The default for a UNIQUE index options.
static boolean	UPDATE_MULTIUPDATE_DEFAULT The default for doing a multiple-update on an update.
static boolean	UPDATE_UPSERT_DEFAULT The default for doing an upsert on an update.

Constructor Summary

Constructors

Constructor and Description
AbstractMongoOperations(Client client, MongoDatabase database, String name) Create a new AbstractAsyncMongoCollection.

Method Summary

Methods

Modifier and Type	Method and Description
void	aggregateAsync(Callback<MongoIterator<Document>> results, Aggregate command) Constructs a aggregate command and sends it to the server via the Client.
protected GetLastError	asGetLastError(Durability durability) Converts the Durability into a GetLastError command.
void	countAsync(Callback<Long> results, Count count) Constructs a count command and sends it to the server via the Client.
protected Query	createQuery(Find query, int limit, int batchSize, boolean tailable, boolean awaitData, boolean immortal) Creates a properly configured Query message.
void	deleteAsync(Callback<Long> results, DocumentAssignable query, boolean singleDelete, Durability durability) Constructs a Delete message and sends it to the server via the Client.
void	distinctAsync(Callback<MongoIterator<Element>> results, Distinct command) Constructs a distinct command and sends it to the server via the Client.
protected void	doInsertAsync(Callback<Integer> results, boolean continueOnError, Durability durability, Version requiredServerVersion, DocumentAssignable... documents) Sends an Insert message to the server.
protected void	doWriteAsync(ClusterStats stats, Callback<Long> results, BatchedWrite write) Performs a async write operation.
void	explainAsync(Callback<Document> results, Aggregate aggregation) Constructs a AggregateCommand and sends it to the server via the Client.
void	explainAsync(Callback<Document> results, Find query) Constructs a Query message and sends it to the server via the Client.
void	findAndModifyAsync(Callback<Document> results, FindAndModify command) Constructs a findAndModify command and sends it to the server via the Client.
void	findAsync(Callback<MongoIterator<Document>> results, Find query) Constructs a Query message and sends it to the server via the Client.
void	findOneAsync(Callback<Document> results, Find query) Constructs a Query message and sends it to the server via the Client.
String	getDatabaseName() Returns the name of the database.
Durability	getDurability() Returns the durability to use when no durability is specified for the write operation.
String	getName() Returns the name of the collection.
ReadPreference	getReadPreference() Returns the read preference to use when no read preference is specified for the read operation.
void	groupByAsync(Callback<MongoIterator<Element>> results, GroupBy command) Constructs a group command and sends it to the server via the Client.
void	insertAsync(Callback<Integer> results, boolean continueOnError, Durability durability, DocumentAssignable... documents) Constructs a Insert message and sends it to the server via the Client.
protected boolean	isWriteCommandsSupported(ClusterStats stats) Determines if all of the servers in the cluster support the write commands.
void	mapReduceAsync(Callback<MongoIterator<Document>> results, MapReduce command) Constructs a mapreduce command and sends it to the server via the Client.
void	parallelScanAsync(Callback<Collection<MongoIterator<Document>>> results, ParallelScan parallelScan) Constructs a parallelCollectionScan command and sends it to the server via the Client.
void	saveAsync(Callback<Integer> results, DocumentAssignable document, Durability durability) Constructs a Insert of Update message based on if the document contains a ID_FIELD_NAME and sends it to the server via the Client.
void	setDurability(Durability durability) Sets the durability to use when no durability is specified for the write operation.
void	setReadPreference(ReadPreference readPreference) Sets the read preference to use when no read preference is specified for the read operation.
MongoCursorControl	stream(StreamCallback<Document> results, Aggregate aggregation) Constructs a aggregate command and sends it to the server via the Client.
MongoCursorControl	stream(StreamCallback<Document> results, Find query) Constructs a Query message and sends it to the server via the Client.
void	textSearchAsync(Callback<MongoIterator<TextResult>> results, Text command) Deprecated. Support for the text command was deprecated in the 2.6 version of MongoDB. Use the $text query operator instead. This method will not be removed until two releases after the MongoDB 2.6 release (e.g. 2.10 if the releases are 2.8 and 2.10).
protected AggregateCommand	toCommand(Aggregate command, boolean explain) Converts the Aggregate object to an AggregateCommand.
void	updateAsync(Callback<Long> results, DocumentAssignable query, DocumentAssignable update, boolean multiUpdate, boolean upsert, Durability durability) Constructs a Update message and sends it to the server via the Client.
protected ReadPreference	updateReadPreference(DocumentBuilder builder, ReadPreference commandReadPreference, boolean createQueryElement) Determines the ReadPreference to be used based on the command's ReadPreference or the collection's if the command's ReadPreference is null.
protected boolean	useWriteCommand() Extension point for derived classes to force the insertAsync(Callback, boolean, Durability, DocumentAssignable...) , updateAsync(Callback, DocumentAssignable, DocumentAssignable, boolean, boolean, Durability) , and deleteAsync(Callback, DocumentAssignable, boolean, Durability) methods to use the legacy Insert, Update, and Delete messages regardless of the server version.
void	writeAsync(Callback<Long> results, BatchedWrite write) Constructs the appropriate set of write commands to send to the server.

Methods inherited from class java.lang.Object

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

Field Detail

DELETE_SINGLE_DELETE_DEFAULT

public static final boolean DELETE_SINGLE_DELETE_DEFAULT

The default for if a delete should only delete the first document it matches.

See Also:

Constant Field Values

EMPTY_INDEX_OPTIONS

public static final Document EMPTY_INDEX_OPTIONS

The default empty index options.

ID_FIELD_NAME

public static final String ID_FIELD_NAME

The name of the canonical id field for MongoDB.

See Also:

Constant Field Values

INSERT_CONTINUE_ON_ERROR_DEFAULT

public static final boolean INSERT_CONTINUE_ON_ERROR_DEFAULT

The default for if an insert should continue on an error.

See Also:

Constant Field Values

UNIQUE_INDEX_OPTIONS

public static final Document UNIQUE_INDEX_OPTIONS

The default for a UNIQUE index options.

UPDATE_MULTIUPDATE_DEFAULT

public static final boolean UPDATE_MULTIUPDATE_DEFAULT

The default for doing a multiple-update on an update.

See Also:

Constant Field Values

UPDATE_UPSERT_DEFAULT

public static final boolean UPDATE_UPSERT_DEFAULT

The default for doing an upsert on an update.

See Also:

Constant Field Values

myClient

protected final Client myClient

The client for interacting with MongoDB.

myDatabase

protected final MongoDatabase myDatabase

The name of the database we interact with.

myName

protected final String myName

The name of the collection we interact with.

Constructor Detail

AbstractMongoOperations

public AbstractMongoOperations(Client client,
                       MongoDatabase database,
                       String name)

Create a new AbstractAsyncMongoCollection.

Parameters:

client - The client for interacting with MongoDB.

database - The database we interact with.

name - The name of the collection we interact with.

Method Detail

aggregateAsync

public void aggregateAsync(Callback<MongoIterator<Document>> results,
                  Aggregate command)
                    throws MongoDbException

Constructs a aggregate command and sends it to the server via the Client.

Parameters:

results - Callback for the aggregation results returned.

command - The details of the aggregation request.

Throws:

MongoDbException - On an error executing the aggregate command.

See Also:

AsyncMongoCollection.aggregateAsync(Callback, Aggregate)

countAsync

public void countAsync(Callback<Long> results,
              Count count)
                throws MongoDbException

Constructs a count command and sends it to the server via the Client.

Parameters:

results - The callback to notify of the results.

count - The count command.

Throws:

MongoDbException - On an error counting the documents.

See Also:

AsyncMongoCollection.countAsync(Callback, Count)

deleteAsync

public void deleteAsync(Callback<Long> results,
               DocumentAssignable query,
               boolean singleDelete,
               Durability durability)
                 throws MongoDbException

Constructs a Delete message and sends it to the server via the Client.

Parameters:

results - Callback that will be notified of the results of the query. If the durability of the operation is NONE then this will be -1.

query - Query to locate the documents to be deleted.

singleDelete - If true then only a single document will be deleted. If running in a sharded environment then this field must be false or the query must contain the shard key.

durability - The durability for the delete.

Throws:

MongoDbException - On an error deleting the documents.

See Also:

AsyncMongoCollection.deleteAsync(Callback, DocumentAssignable, boolean, Durability)

distinctAsync

public void distinctAsync(Callback<MongoIterator<Element>> results,
                 Distinct command)
                   throws MongoDbException

Constructs a distinct command and sends it to the server via the Client.

Parameters:

results - Callback for the distinct results returned.

command - The details of the distinct request.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.distinctAsync(Callback, Distinct)

explainAsync

public void explainAsync(Callback<Document> results,
                Aggregate aggregation)
                  throws MongoDbException

Constructs a AggregateCommand and sends it to the server via the Client.

Parameters:

aggregation - The aggregation details.

results - Callback that will be notified of the results of the explain.

Throws:

MongoDbException - On an error finding the documents.

Since:

MongoDB 2.6

See Also:

AsyncMongoCollection.explainAsync(Callback, Aggregate)

explainAsync

public void explainAsync(Callback<Document> results,
                Find query)
                  throws MongoDbException

Constructs a Query message and sends it to the server via the Client.

Parameters:

query - The query details.

results - Callback that will be notified of the results of the explain.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.explainAsync(Callback, Find)

findAndModifyAsync

public void findAndModifyAsync(Callback<Document> results,
                      FindAndModify command)
                        throws MongoDbException

Constructs a findAndModify command and sends it to the server via the Client.

Parameters:

results - Callback for the the found document.

command - The details of the find and modify request.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.findAndModifyAsync(Callback, FindAndModify)

findAsync

public void findAsync(Callback<MongoIterator<Document>> results,
             Find query)
               throws MongoDbException

Constructs a Query message and sends it to the server via the Client.

Parameters:

query - The query details.

results - Callback that will be notified of the results of the find.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.findAsync(Callback, Find)

findOneAsync

public void findOneAsync(Callback<Document> results,
                Find query)
                  throws MongoDbException

Constructs a Query message and sends it to the server via the Client.

Parameters:

query - The query details.

results - Callback that will be notified of the results of the find.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.findOneAsync(Callback, Find)

getDatabaseName

public String getDatabaseName()

Returns the name of the database.

Returns:

The name of the database.

getDurability

public Durability getDurability()

Returns the durability to use when no durability is specified for the write operation.

Returns:

The durability to use when no durability is specified for the write operation.

getName

public String getName()

Returns the name of the collection.

Returns:

The name of the collection.

getReadPreference

public ReadPreference getReadPreference()

Returns the read preference to use when no read preference is specified for the read operation.

Returns:

The read preference to use when no read preference is specified for the read operation.

groupByAsync

public void groupByAsync(Callback<MongoIterator<Element>> results,
                GroupBy command)
                  throws MongoDbException

Constructs a group command and sends it to the server via the Client.

Parameters:

results - Callback for the group results returned.

command - The details of the group request.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.groupByAsync(Callback, GroupBy)

insertAsync

public void insertAsync(Callback<Integer> results,
               boolean continueOnError,
               Durability durability,
               DocumentAssignable... documents)
                 throws MongoDbException

Constructs a Insert message and sends it to the server via the Client.

Parameters:

results - Callback that will be notified with the results of the insert. Currently, the value is always zero. Once SERVER-4381 is fixed then expected to be the number of documents inserted. If the durability is NONE then returns -1.

continueOnError - If the insert should continue if one of the documents causes an error.

durability - The durability for the insert.

documents - The documents to add to the collection.

Throws:

MongoDbException - On an error inserting the documents.

See Also:

AsyncMongoCollection.insertAsync(Callback, boolean, Durability, DocumentAssignable...)

mapReduceAsync

public void mapReduceAsync(Callback<MongoIterator<Document>> results,
                  MapReduce command)
                    throws MongoDbException

Constructs a mapreduce command and sends it to the server via the Client.

Parameters:

results - Callback for the map/reduce results returned. Note this might be empty if the output type is not inline.

command - The details of the map/reduce request.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.mapReduceAsync(Callback, MapReduce)

parallelScanAsync

public void parallelScanAsync(Callback<Collection<MongoIterator<Document>>> results,
                     ParallelScan parallelScan)
                       throws MongoDbException

Constructs a parallelCollectionScan command and sends it to the server via the Client.

Parameters:

results - Callback for the collection of iterators.

parallelScan - The details on the scan.

Throws:

MongoDbException - On an error initializing the parallel scan.

See Also:

AsyncMongoCollection.parallelScanAsync(Callback, ParallelScan), parallelCollectionScan Command

saveAsync

public void saveAsync(Callback<Integer> results,
             DocumentAssignable document,
             Durability durability)
               throws MongoDbException

Constructs a Insert of Update message based on if the document contains a ID_FIELD_NAME and sends it to the server via the Client.

Parameters:

results - Callback that will be notified with the results of the insert. If the durability of the operation is NONE then this will be -1.

document - The document to save to the collection.

durability - The durability for the save.

Throws:

MongoDbException - On an error saving the documents.

See Also:

AsyncMongoCollection.saveAsync(Callback, DocumentAssignable, Durability)

setDurability

public void setDurability(Durability durability)

Sets the durability to use when no durability is specified for the write operation.

Parameters:

durability - The durability to use when no durability is specified for the write operation.

setReadPreference

public void setReadPreference(ReadPreference readPreference)

Sets the read preference to use when no read preference is specified for the read operation.

Parameters:

readPreference - The read preference to use when no read preference is specified for the read operation.

stream

public MongoCursorControl stream(StreamCallback<Document> results,
                        Aggregate aggregation)
                          throws MongoDbException

Constructs a aggregate command and sends it to the server via the Client.

Parameters:

results - Callback that will be notified of the results of the query.

aggregation - The aggregation details.

Returns:

A MongoCursorControl to control the cursor streaming documents to the caller. This includes the ability to stop the cursor and persist its state.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.stream(StreamCallback, Aggregate)

stream

public MongoCursorControl stream(StreamCallback<Document> results,
                        Find query)
                          throws MongoDbException

Constructs a Query message and sends it to the server via the Client.

Parameters:

results - Callback that will be notified of the results of the query.

query - The query details.

Returns:

A MongoCursorControl to control the cursor streaming documents to the caller. This includes the ability to stop the cursor and persist its state.

Throws:

MongoDbException - On an error finding the documents.

See Also:

AsyncMongoCollection.stream(StreamCallback, Find)

textSearchAsync

@Deprecated
public void textSearchAsync(Callback<MongoIterator<TextResult>> results,
                              Text command)
                     throws MongoDbException

Deprecated. Support for the text command was deprecated in the 2.6 version of MongoDB. Use the $text query operator instead. This method will not be removed until two releases after the MongoDB 2.6 release (e.g. 2.10 if the releases are 2.8 and 2.10).

Constructs a text command and sends it to the server via the Client.

Parameters:

results - Callback for the text results returned.

command - The details of the text request.

Throws:

MongoDbException - On an error executing the text command.

Since:

MongoDB 2.4

See Also:

MongoDB Text Queries, AsyncMongoCollection.textSearchAsync(Callback, com.allanbank.mongodb.builder.Text)

updateAsync

public void updateAsync(Callback<Long> results,
               DocumentAssignable query,
               DocumentAssignable update,
               boolean multiUpdate,
               boolean upsert,
               Durability durability)
                 throws MongoDbException

Constructs a Update message and sends it to the server via the Client.

Parameters:

results - The Callback that will be notified of the number of documents updated. If the durability of the operation is NONE then this will be -1.

query - The query to select the documents to update.

update - The updates to apply to the selected documents.

multiUpdate - If true then the update is applied to all of the matching documents, otherwise only the first document found is updated.

upsert - If true then if no document is found then a new document is created and updated, otherwise no operation is performed.

durability - The durability for the update.

Throws:

MongoDbException - On an error updating the documents.

See Also:

AsyncMongoCollection.updateAsync(Callback, DocumentAssignable, DocumentAssignable, boolean, boolean, Durability)

writeAsync

public void writeAsync(Callback<Long> results,
              BatchedWrite write)
                throws MongoDbException

Constructs the appropriate set of write commands to send to the server.

Parameters:

results - The Callback that will be notified of the number of documents inserted, updated, and deleted. If the durability of the operation is NONE then this will be -1.

write - The batched writes

Throws:

MongoDbException - On an error submitting the write operations.

Since:

MongoDB 2.6

See Also:

AsyncMongoCollection.writeAsync(Callback,BatchedWrite)

asGetLastError

protected GetLastError asGetLastError(Durability durability)

Converts the Durability into a GetLastError command.

Parameters:

durability - The Durability to convert.

Returns:

The GetLastError command.

createQuery

protected Query createQuery(Find query,
                int limit,
                int batchSize,
                boolean tailable,
                boolean awaitData,
                boolean immortal)

Creates a properly configured Query message.

Parameters:

query - The Find to construct the Query from.

limit - The limit for the query.

batchSize - The batch size for the query.

tailable - If the query should create a tailable cursor.

awaitData - If the query should await data.

immortal - If the query should create a cursor that does not timeout, e.g., immortal.

Returns:

The Query message.

doInsertAsync

protected void doInsertAsync(Callback<Integer> results,
                 boolean continueOnError,
                 Durability durability,
                 Version requiredServerVersion,
                 DocumentAssignable... documents)
                      throws MongoDbException

Sends an Insert message to the server. This version is private to this class since most inserts do not need the server version.

Parameters:

results - Callback that will be notified with the results of the insert.

continueOnError - If the insert should continue if one of the documents causes an error.

durability - The durability for the insert.

requiredServerVersion - The required version of the server to support processing the message.

documents - The documents to add to the collection.

Throws:

MongoDbException - On an error inserting the documents.

doWriteAsync

protected void doWriteAsync(ClusterStats stats,
                Callback<Long> results,
                BatchedWrite write)

Performs a async write operation.

Parameters:

stats - The stats for verifying the server support write commands.

results - The callback for the write.

write - The write to send.

isWriteCommandsSupported

protected boolean isWriteCommandsSupported(ClusterStats stats)

Determines if all of the servers in the cluster support the write commands.

Parameters:

stats - The cluster stats if they have already been retrieved.

Returns:

True if all servers in the cluster are at least the BatchedWrite.REQUIRED_VERSION.

toCommand

protected AggregateCommand toCommand(Aggregate command,
                         boolean explain)

Converts the Aggregate object to an AggregateCommand.

Parameters:

command - The Aggregate to convert.

explain - If rue then have the server explain the aggregation instead of performing the aggregation.

Returns:

The command to send to the server for the Aggregate.

updateReadPreference

protected ReadPreference updateReadPreference(DocumentBuilder builder,
                                  ReadPreference commandReadPreference,
                                  boolean createQueryElement)

Determines the ReadPreference to be used based on the command's ReadPreference or the collection's if the command's ReadPreference is null. Updates the command's DocumentBuilder with the ReadPreference details if connected to a sharded cluster and the resulting ReadPreference is not supported by the legacy settings.

Parameters:

builder - The builder for the command document to augment with the read preferences if connected to a sharded cluster.

commandReadPreference - The read preferences from the command.

createQueryElement - If true then the existing builder's contents will be pushed into a $query sub-document. This is required to ensure the command is not rejected by the mongod after processing by the mongos.

Returns:

The ReadPreference to use.

useWriteCommand

protected boolean useWriteCommand()

Extension point for derived classes to force the insertAsync(Callback, boolean, Durability, DocumentAssignable...) , updateAsync(Callback, DocumentAssignable, DocumentAssignable, boolean, boolean, Durability) , and deleteAsync(Callback, DocumentAssignable, boolean, Durability) methods to use the legacy Insert, Update, and Delete messages regardless of the server version.

This version of the method always returns true.

Returns:

Return true to allow the use of the write commands added in MongoDB 2.6. Use false to force the use of the Insert, Update, and Delete