com.allanbank.mongodb.client

Class MongoCollectionImpl

java.lang.Object

com.allanbank.mongodb.client.AbstractMongoCollection

com.allanbank.mongodb.client.MongoCollectionImpl

All Implemented Interfaces:

MongoCollection

public class MongoCollectionImpl
extends AbstractMongoCollection

Implementation of the MongoCollection interface.

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-2012, Allanbank Consulting, Inc., All Rights Reserved

Nested Class Summary

Nested classes/interfaces inherited from interface com.allanbank.mongodb.MongoCollection

MongoCollection.ValidateMode

Field Summary

Fields

Modifier and Type	Field and Description
static String	ID_FIELD_NAME The name of the canonical id field for MongoDB.

Fields inherited from class com.allanbank.mongodb.client.AbstractMongoCollection

DELETE_SINGLE_DELETE_DEFAULT, EMPTY_INDEX_OPTIONS, INSERT_CONTINUE_ON_ERROR_DEFAULT, myClient, myDatabase, myName, UNIQUE_INDEX_OPTIONS, UPDATE_MULTIUPDATE_DEFAULT, UPDATE_UPSERT_DEFAULT

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
void	aggregateAsync(Callback<List<Document>> results, Aggregate command) Invokes a aggregate command on the server.
void	countAsync(Callback<Long> results, DocumentAssignable query, ReadPreference readPreference) Counts the set of documents matching the query document in the collection.
void	createIndex(String name, DocumentAssignable options, Element... keys) Creates an index with a generated name, across the keys specified allowing duplicate entries.
protected Query	createQuery(Find query, int limit, int batchSize, boolean tailable) Creates a properly configured Query message.
void	deleteAsync(Callback<Long> results, DocumentAssignable query, boolean singleDelete, Durability durability) Deletes a set of documents matching a query from the collection.
void	distinctAsync(Callback<ArrayElement> results, Distinct command) Invokes a distinct command on the server.
boolean	drop() Drops the collection from the database.
boolean	dropIndex(String name) Deletes the indexes with the provided name.
void	explainAsync(Callback<Document> results, Find query) Explains the way that the document will be performed.
void	findAndModifyAsync(Callback<Document> results, FindAndModify command) Invokes a findAndModify command on the server.
void	findAsync(Callback<ClosableIterator<Document>> results, Find query) Finds the set of documents matching the query in the collection.
void	findOneAsync(Callback<Document> results, Find query) Finds a single matching document in the collection.
void	groupByAsync(Callback<ArrayElement> results, GroupBy command) Invokes a group command on the server.
void	insertAsync(Callback<Integer> results, boolean continueOnError, Durability durability, DocumentAssignable... documents) Inserts a set of documents into the collection.
boolean	isCapped() Returns true if the collection statistics indicate that the collection is a capped collection.
void	mapReduceAsync(Callback<List<Document>> results, MapReduce command) Invokes a mapReduce command on the server.
void	saveAsync(Callback<Integer> results, DocumentAssignable document, Durability durability) Saves the document to the collection.
Document	stats() Returns the statistics for the collection.
void	streamingFind(Callback<Document> results, Find query) Finds the set of documents matching the query in the collection and streams them to the provided callback one at a time.
void	updateAsync(Callback<Long> results, DocumentAssignable query, DocumentAssignable update, boolean multiUpdate, boolean upsert, Durability durability) Applies updates to a set of documents within the collection.
Document	updateOptions(DocumentAssignable options) Updates the collection's options or flags using the collMod command.
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.
Document	validate(MongoCollection.ValidateMode mode) Validates the collections contents.

Methods inherited from class com.allanbank.mongodb.client.AbstractMongoCollection

aggregate, aggregateAsync, asGetLastError, buildIndexName, count, count, count, count, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, countAsync, createIndex, createIndex, createIndex, createIndex, delete, delete, delete, delete, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, deleteAsync, distinct, distinctAsync, dropIndex, explain, explain, explainAsync, find, find, findAndModify, findAndModifyAsync, findAsync, findAsync, findAsync, findOne, findOne, findOneAsync, findOneAsync, findOneAsync, getDatabaseName, getDurability, getName, getReadPreference, groupBy, groupByAsync, insert, insert, insert, insert, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, insertAsync, mapReduce, mapReduceAsync, save, save, saveAsync, saveAsync, saveAsync, setDurability, setReadPreference, streamingFind, update, update, update, update, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync, updateAsync

Methods inherited from class java.lang.Object

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

Field Detail

ID_FIELD_NAME

public static final String ID_FIELD_NAME

The name of the canonical id field for MongoDB.

See Also:

Constant Field Values

Constructor Detail

MongoCollectionImpl

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

Create a new MongoDatabaseClient.

Parameters:

client - The client for interacting with MongoDB.

database - The database the collection is a part of.

name - The name of the collection we interact with.

Method Detail

aggregateAsync

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

Invokes a aggregate command on the server.

This is the canonical aggregate method that implementations must override.

Overridden to construct a aggregate command and send it to the server.

Specified by:

aggregateAsync in interface MongoCollection

Specified by:

aggregateAsync in class AbstractMongoCollection

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:

MongoCollection.aggregateAsync(Callback, Aggregate)

countAsync

public void countAsync(Callback<Long> results,
              DocumentAssignable query,
              ReadPreference readPreference)
                throws MongoDbException

Counts the set of documents matching the query document in the collection.

This is the canonical count method that implementations must override.

This is the canonical count method that implementations must override.

Specified by:

countAsync in interface MongoCollection

Specified by:

countAsync in class AbstractMongoCollection

Parameters:

results - The callback to notify of the results.

query - The query document.

readPreference - The preference for which servers to use to retrieve the results.

Throws:

MongoDbException - On an error finding the documents.

createIndex

public void createIndex(String name,
               DocumentAssignable options,
               Element... keys)
                 throws MongoDbException

Creates an index with a generated name, across the keys specified allowing duplicate entries.

This method is intended to be used with the Sort class's static methods:

 
 import static com.allanbank.mongodb.bson.builder.BuilderFactory.start;
 import static com.allanbank.mongodb.builder.Sort.asc;
 import static com.allanbank.mongodb.builder.Sort.desc;
 
 MongoCollection collection = ...;
 
 collection.createIndex("sparse_f", start().add("sparse", true), asc("f") );
 ...
 
 

This is the canonical createIndex method that implementations must override.

Overridden to insert the index document into the 'system.indexes' collection.

Specified by:

createIndex in interface MongoCollection

Specified by:

createIndex in class AbstractMongoCollection

Parameters:

name - The name of the index. If null then a name is generated based on the keys.

options - The options for the index.

keys - The keys to use for the index.

Throws:

MongoDbException - On a failure building the index.

See Also:

MongoCollection.createIndex(String,DocumentAssignable,Element...)

deleteAsync

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

Deletes a set of documents matching a query from the collection.

This is the canonical delete method that implementations must override.

Overridden to send a Delete message to the server.

Specified by:

deleteAsync in interface MongoCollection

Specified by:

deleteAsync in class AbstractMongoCollection

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:

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

distinctAsync

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

Invokes a distinct command on the server.

This is the canonical disitnct method that implementations must override.

Overridden to construct a 'distinct' command and send it to the server.

Specified by:

distinctAsync in interface MongoCollection

Specified by:

distinctAsync in class AbstractMongoCollection

Parameters:

results - Callback for the distinct results returned.

command - The details of the distinct request.

Throws:

MongoDbException - On an error finding the documents.

drop

public boolean drop()

Drops the collection from the database.

Overridden to issue a { "drop" : } command.

Returns:

True if the collection was successfully dropped.

See Also:

MongoCollection.drop()

dropIndex

public boolean dropIndex(String name)
                  throws MongoDbException

Deletes the indexes with the provided name.

This is the canonical dropIndex method that implementations must override.

Overridden to issue a { "deleteIndexes" : , index : } command.

Specified by:

dropIndex in interface MongoCollection

Specified by:

dropIndex in class AbstractMongoCollection

Parameters:

name - The name of the index.

Returns:

If any indexes were removed.

Throws:

MongoDbException - On an error deleting the indexes.

explainAsync

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

Explains the way that the document will be performed.

This is the canonical count method that implementations must override.

Overridden to send a Query message to the server to explain the Find's query.

Specified by:

explainAsync in interface MongoCollection

Specified by:

explainAsync in class AbstractMongoCollection

Parameters:

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

query - The query details.

Throws:

MongoDbException - On an error finding the documents.

findAndModifyAsync

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

Invokes a findAndModify command on the server. The query is used to locate a document to apply a set of updates to.

This is the canonical findAndModify method that implementations must override.

Overridden to send an Command findAndModify message to the server.

Specified by:

findAndModifyAsync in interface MongoCollection

Specified by:

findAndModifyAsync in class AbstractMongoCollection

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:

MongoCollection.findAndModifyAsync(Callback, FindAndModify)

findAsync

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

Finds the set of documents matching the query in the collection.

This is the canonical find method that implementations must override.

Overridden to send a Query message to the server.

Specified by:

findAsync in interface MongoCollection

Specified by:

findAsync in class AbstractMongoCollection

Parameters:

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

query - The query details.

Throws:

MongoDbException - On an error finding the documents.

See Also:

MongoCollection.findAsync(Callback, Find)

findOneAsync

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

Finds a single matching document in the collection.

Note that following options in the Find class do not make sense and are silently ignored by this method.

• Batch Size - Automatically set to 1.
• Limit - Automatically set to 1.
• Tailable - This method only returns 1 document.

This is the canonical findOne method that implementations must override.

Overridden to send a Query message to the server.

Specified by:

findOneAsync in interface MongoCollection

Specified by:

findOneAsync in class AbstractMongoCollection

Parameters:

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

query - The query details.

Throws:

MongoDbException - On an error finding the document.

See Also:

MongoCollection.findOneAsync(Callback, DocumentAssignable)

groupByAsync

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

Invokes a group command on the server.

This is the canonical groupBy method that implementations must override.

Overridden to construct a group command and send it to the server.

Specified by:

groupByAsync in interface MongoCollection

Specified by:

groupByAsync in class AbstractMongoCollection

Parameters:

results - Callback for the group results returned.

command - The details of the group request.

Throws:

MongoDbException - On an error finding the documents.

insertAsync

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

Inserts a set of documents into the collection.

This is the canonical insert method that implementations must override.

Overridden to send an Insert message to the server.

Specified by:

insertAsync in interface MongoCollection

Specified by:

insertAsync in class AbstractMongoCollection

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.

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:

MongoCollection.insertAsync(Callback, boolean, Durability, DocumentAssignable[])

isCapped

public boolean isCapped()
                 throws MongoDbException

Returns true if the collection statistics indicate that the collection is a capped collection.

Overridden to send a collStats command to the MongoDB server and look for the capped field to determine if the collection is capped or not.

Returns:

True if the collection statistics indicate that the collection is a capped collection.

Throws:

MongoDbException - On an error collecting the collection statistics.

See Also:

MongoCollection.isCapped()

mapReduceAsync

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

Invokes a mapReduce command on the server.

This is the canonical mapReduce method that implementations must override.

Overridden to construct a mapReduce command and send it to the server.

Specified by:

mapReduceAsync in interface MongoCollection

Specified by:

mapReduceAsync in class AbstractMongoCollection

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:

MongoCollection.mapReduceAsync(Callback, MapReduce)

saveAsync

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

Saves the document to the collection.

If the document does not contain an _id field then this method is equivalent to: insertAsync(results, durability, document).

If the document does contain an _id field then this method is equivalent to: updateAsync(results, BuilderFactory.start().add(document.get("_id")), document, false, true, durability).

This is the canonical save method that implementations must override.

Overridden to save the document.

Specified by:

saveAsync in interface MongoCollection

Specified by:

saveAsync in class AbstractMongoCollection

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.

stats

public Document stats()
               throws MongoDbException

Returns the statistics for the collection.

Overridden to send a collStats command to the MongoDB server.

Returns:

The results document with the collection statistics.

Throws:

MongoDbException - On an error collecting the collection statistics.

See Also:

MongoCollection.stats()

streamingFind

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

Finds the set of documents matching the query in the collection and streams them to the provided callback one at a time.

The sequence of callbacks will be terminated by either calling the results.callback(...) method with null or by calling the results.exception(...) method on an error.

Applications can terminate the stream by throwing a RuntimeException from the Callback.callback(V) method (which will then call the Callback.exception(java.lang.Throwable) method).

Only a single thread will invoke the callback at a time but that thread may change over time.

If the callback processing requires any signifigant time (including I/O) it is recommended that an Executor be configured within the MongoClientConfiguration to offload the processing from the receive thread.

This is the canonical streamingFind method that implementations must override.

Overridden to send a Query message to the server and setup the streaming query callback.

Specified by:

streamingFind in interface MongoCollection

Specified by:

streamingFind in class AbstractMongoCollection

Parameters:

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

query - The query details.

Throws:

MongoDbException - On an error finding the documents.

updateAsync

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

Applies updates to a set of documents within the collection. The documents to update are selected by the query and the updates are describe by the update document.

This is the canonical update method that implementations must override.

Overridden to send an Update message to the server.

Specified by:

updateAsync in interface MongoCollection

Specified by:

updateAsync in class AbstractMongoCollection

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:

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

updateOptions

public Document updateOptions(DocumentAssignable options)
                       throws MongoDbException

Updates the collection's options or flags using the collMod command. The return value is the response from the MongoDB server and normally contains a <name>_old field for each successfully set option on the collection.

 
 MongoCollection collection = ...;
 
 collection.updateOptions( BuilderFactory.start().add( "usePowerOf2Sizes", true ) );
 
 

Overridden to send a collMod command to the server.

Parameters:

options - The collection options to be set.

Returns:

The results document from the database.

Throws:

MongoDbException - On an error validating the collection.

See Also:

collMod Command Reference

validate

public Document validate(MongoCollection.ValidateMode mode)
                  throws MongoDbException

Validates the collections contents.

Overridden to send a validate command to the server.

Parameters:

mode - The validation mode to use.

Returns:

The results document from the database.

Throws:

MongoDbException - On an error validating the collection.

See Also:

validate Command Reference

createQuery

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

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.

Returns:

The Query message.

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.