/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
Java | 1620 lines | 217 code | 117 blank | 1286 comment | 2 complexity | 6f9060a3917ae48473bb637eeb4c3a7a MD5 | raw file
Large files files are truncated, but you can click here to view the full file
- /*
- * Copyright 2011-2021 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
- package org.springframework.data.mongodb.core;
- import java.util.Collection;
- import java.util.List;
- import java.util.Set;
- import java.util.function.Consumer;
- import java.util.function.Supplier;
- import org.bson.Document;
- import org.springframework.data.geo.GeoResults;
- import org.springframework.data.mongodb.core.BulkOperations.BulkMode;
- import org.springframework.data.mongodb.core.aggregation.Aggregation;
- import org.springframework.data.mongodb.core.aggregation.AggregationOptions;
- import org.springframework.data.mongodb.core.aggregation.AggregationResults;
- import org.springframework.data.mongodb.core.aggregation.AggregationUpdate;
- import org.springframework.data.mongodb.core.aggregation.TypedAggregation;
- import org.springframework.data.mongodb.core.convert.MappingMongoConverter;
- import org.springframework.data.mongodb.core.convert.MongoConverter;
- import org.springframework.data.mongodb.core.index.IndexOperations;
- import org.springframework.data.mongodb.core.mapreduce.GroupBy;
- import org.springframework.data.mongodb.core.mapreduce.GroupByResults;
- import org.springframework.data.mongodb.core.mapreduce.MapReduceOptions;
- import org.springframework.data.mongodb.core.mapreduce.MapReduceResults;
- import org.springframework.data.mongodb.core.query.BasicQuery;
- import org.springframework.data.mongodb.core.query.Criteria;
- import org.springframework.data.mongodb.core.query.NearQuery;
- import org.springframework.data.mongodb.core.query.Query;
- import org.springframework.data.mongodb.core.query.Update;
- import org.springframework.data.mongodb.core.query.UpdateDefinition;
- import org.springframework.data.util.CloseableIterator;
- import org.springframework.lang.Nullable;
- import org.springframework.util.Assert;
- import org.springframework.util.ClassUtils;
- import com.mongodb.ClientSessionOptions;
- import com.mongodb.ReadPreference;
- import com.mongodb.client.ClientSession;
- import com.mongodb.client.MongoCollection;
- import com.mongodb.client.result.DeleteResult;
- import com.mongodb.client.result.UpdateResult;
- /**
- * Interface that specifies a basic set of MongoDB operations. Implemented by {@link MongoTemplate}. Not often used but
- * a useful option for extensibility and testability (as it can be easily mocked, stubbed, or be the target of a JDK
- * proxy).
- * <br />
- * <strong>NOTE:</strong> Some operations cannot be executed within a MongoDB transaction. Please refer to the MongoDB
- * specific documentation to learn more about <a href="https://docs.mongodb.com/manual/core/transactions/">Multi
- * Document Transactions</a>.
- *
- * @author Thomas Risberg
- * @author Mark Pollack
- * @author Oliver Gierke
- * @author Tobias Trelle
- * @author Chuong Ngo
- * @author Christoph Strobl
- * @author Thomas Darimont
- * @author Maninder Singh
- * @author Mark Paluch
- */
- public interface MongoOperations extends FluentMongoOperations {
- /**
- * The collection name used for the specified class by this template.
- *
- * @param entityClass must not be {@literal null}.
- * @return never {@literal null}.
- */
- String getCollectionName(Class<?> entityClass);
- /**
- * Execute the a MongoDB command expressed as a JSON string. Parsing is delegated to {@link Document#parse(String)} to
- * obtain the {@link Document} holding the actual command. Any errors that result from executing this command will be
- * converted into Spring's DAO exception hierarchy.
- *
- * @param jsonCommand a MongoDB command expressed as a JSON string. Must not be {@literal null}.
- * @return a result object returned by the action.
- */
- Document executeCommand(String jsonCommand);
- /**
- * Execute a MongoDB command. Any errors that result from executing this command will be converted into Spring's DAO
- * exception hierarchy.
- *
- * @param command a MongoDB command.
- * @return a result object returned by the action.
- */
- Document executeCommand(Document command);
- /**
- * Execute a MongoDB command. Any errors that result from executing this command will be converted into Spring's data
- * access exception hierarchy.
- *
- * @param command a MongoDB command, must not be {@literal null}.
- * @param readPreference read preferences to use, can be {@literal null}.
- * @return a result object returned by the action.
- * @since 1.7
- */
- Document executeCommand(Document command, @Nullable ReadPreference readPreference);
- /**
- * Execute a MongoDB query and iterate over the query results on a per-document basis with a DocumentCallbackHandler.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification. Must not be {@literal null}.
- * @param collectionName name of the collection to retrieve the objects from.
- * @param dch the handler that will extract results, one document at a time.
- */
- void executeQuery(Query query, String collectionName, DocumentCallbackHandler dch);
- /**
- * Executes a {@link DbCallback} translating any exceptions as necessary.
- * <br />
- * Allows for returning a result object, that is a domain object or a collection of domain objects.
- *
- * @param action callback object that specifies the MongoDB actions to perform on the passed in DB instance. Must not
- * be {@literal null}.
- * @param <T> return type.
- * @return a result object returned by the action or {@literal null}.
- */
- @Nullable
- <T> T execute(DbCallback<T> action);
- /**
- * Executes the given {@link CollectionCallback} on the entity collection of the specified class.
- * <br />
- * Allows for returning a result object, that is a domain object or a collection of domain objects.
- *
- * @param entityClass class that determines the collection to use. Must not be {@literal null}.
- * @param action callback object that specifies the MongoDB action. Must not be {@literal null}.
- * @param <T> return type.
- * @return a result object returned by the action or {@literal null}.
- */
- @Nullable
- <T> T execute(Class<?> entityClass, CollectionCallback<T> action);
- /**
- * Executes the given {@link CollectionCallback} on the collection of the given name.
- * <br />
- * Allows for returning a result object, that is a domain object or a collection of domain objects.
- *
- * @param collectionName the name of the collection that specifies which {@link MongoCollection} instance will be
- * passed into. Must not be {@literal null} or empty.
- * @param action callback object that specifies the MongoDB action the callback action. Must not be {@literal null}.
- * @param <T> return type.
- * @return a result object returned by the action or {@literal null}.
- */
- @Nullable
- <T> T execute(String collectionName, CollectionCallback<T> action);
- /**
- * Obtain a {@link ClientSession session} bound instance of {@link SessionScoped} binding a new {@link ClientSession}
- * with given {@literal sessionOptions} to each and every command issued against MongoDB.
- *
- * @param sessionOptions must not be {@literal null}.
- * @return new instance of {@link SessionScoped}. Never {@literal null}.
- * @since 2.1
- */
- SessionScoped withSession(ClientSessionOptions sessionOptions);
- /**
- * Obtain a {@link ClientSession session} bound instance of {@link SessionScoped} binding the {@link ClientSession}
- * provided by the given {@link Supplier} to each and every command issued against MongoDB.
- * <br />
- * <strong>Note:</strong> It is up to the caller to manage the {@link ClientSession} lifecycle. Use the
- * {@link SessionScoped#execute(SessionCallback, Consumer)} hook to potentially close the {@link ClientSession}.
- *
- * @param sessionProvider must not be {@literal null}.
- * @since 2.1
- */
- default SessionScoped withSession(Supplier<ClientSession> sessionProvider) {
- Assert.notNull(sessionProvider, "SessionProvider must not be null!");
- return new SessionScoped() {
- private final Object lock = new Object();
- private @Nullable ClientSession session = null;
- @Override
- public <T> T execute(SessionCallback<T> action, Consumer<ClientSession> onComplete) {
- synchronized (lock) {
- if (session == null) {
- session = sessionProvider.get();
- }
- }
- try {
- return action.doInSession(MongoOperations.this.withSession(session));
- } finally {
- onComplete.accept(session);
- }
- }
- };
- }
- /**
- * Obtain a {@link ClientSession} bound instance of {@link MongoOperations}.
- * <br />
- * <strong>Note:</strong> It is up to the caller to manage the {@link ClientSession} lifecycle.
- *
- * @param session must not be {@literal null}.
- * @return {@link ClientSession} bound instance of {@link MongoOperations}.
- * @since 2.1
- */
- MongoOperations withSession(ClientSession session);
- /**
- * Executes the given {@link Query} on the entity collection of the specified {@code entityType} backed by a Mongo DB
- * {@link com.mongodb.client.FindIterable}.
- * <p>
- * Returns a {@link CloseableIterator} that wraps the a Mongo DB {@link com.mongodb.client.FindIterable} that needs to
- * be closed.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification. Must not be {@literal null}.
- * @param entityType must not be {@literal null}.
- * @param <T> element return type
- * @return will never be {@literal null}.
- * @since 1.7
- */
- <T> CloseableIterator<T> stream(Query query, Class<T> entityType);
- /**
- * Executes the given {@link Query} on the entity collection of the specified {@code entityType} and collection backed
- * by a Mongo DB {@link com.mongodb.client.FindIterable}.
- * <p>
- * Returns a {@link CloseableIterator} that wraps the a Mongo DB {@link com.mongodb.client.FindIterable} that needs to
- * be closed.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification. Must not be {@literal null}.
- * @param entityType must not be {@literal null}.
- * @param collectionName must not be {@literal null} or empty.
- * @param <T> element return type
- * @return will never be {@literal null}.
- * @since 1.10
- */
- <T> CloseableIterator<T> stream(Query query, Class<T> entityType, String collectionName);
- /**
- * Create an uncapped collection with a name based on the provided entity class.
- *
- * @param entityClass class that determines the collection to create.
- * @return the created collection.
- */
- <T> MongoCollection<Document> createCollection(Class<T> entityClass);
- /**
- * Create a collection with a name based on the provided entity class using the options.
- *
- * @param entityClass class that determines the collection to create. Must not be {@literal null}.
- * @param collectionOptions options to use when creating the collection.
- * @return the created collection.
- */
- <T> MongoCollection<Document> createCollection(Class<T> entityClass, @Nullable CollectionOptions collectionOptions);
- /**
- * Create an uncapped collection with the provided name.
- *
- * @param collectionName name of the collection.
- * @return the created collection.
- */
- MongoCollection<Document> createCollection(String collectionName);
- /**
- * Create a collection with the provided name and options.
- *
- * @param collectionName name of the collection. Must not be {@literal null} nor empty.
- * @param collectionOptions options to use when creating the collection.
- * @return the created collection.
- */
- MongoCollection<Document> createCollection(String collectionName, @Nullable CollectionOptions collectionOptions);
- /**
- * A set of collection names.
- *
- * @return list of collection names.
- */
- Set<String> getCollectionNames();
- /**
- * Get a {@link MongoCollection} by its name. The returned collection may not exists yet (except in local memory) and
- * is created on first interaction with the server. Collections can be explicitly created via
- * {@link #createCollection(Class)}. Please make sure to check if the collection {@link #collectionExists(Class)
- * exists} first.
- * <br />
- * Translate any exceptions as necessary.
- *
- * @param collectionName name of the collection. Must not be {@literal null}.
- * @return an existing collection or one created on first server interaction.
- */
- MongoCollection<Document> getCollection(String collectionName);
- /**
- * Check to see if a collection with a name indicated by the entity class exists.
- * <br />
- * Translate any exceptions as necessary.
- *
- * @param entityClass class that determines the name of the collection. Must not be {@literal null}.
- * @return true if a collection with the given name is found, false otherwise.
- */
- <T> boolean collectionExists(Class<T> entityClass);
- /**
- * Check to see if a collection with a given name exists.
- * <br />
- * Translate any exceptions as necessary.
- *
- * @param collectionName name of the collection. Must not be {@literal null}.
- * @return true if a collection with the given name is found, false otherwise.
- */
- boolean collectionExists(String collectionName);
- /**
- * Drop the collection with the name indicated by the entity class.
- * <br />
- * Translate any exceptions as necessary.
- *
- * @param entityClass class that determines the collection to drop/delete. Must not be {@literal null}.
- */
- <T> void dropCollection(Class<T> entityClass);
- /**
- * Drop the collection with the given name.
- * <br />
- * Translate any exceptions as necessary.
- *
- * @param collectionName name of the collection to drop/delete.
- */
- void dropCollection(String collectionName);
- /**
- * Returns the operations that can be performed on indexes
- *
- * @return index operations on the named collection
- */
- IndexOperations indexOps(String collectionName);
- /**
- * Returns the operations that can be performed on indexes
- *
- * @return index operations on the named collection associated with the given entity class
- */
- IndexOperations indexOps(Class<?> entityClass);
- /**
- * Returns the {@link ScriptOperations} that can be performed on {@link com.mongodb.client.MongoDatabase} level.
- *
- * @return never {@literal null}.
- * @since 1.7
- * @deprecated since 2.2. The {@code eval} command has been removed without replacement in MongoDB Server 4.2.0.
- */
- @Deprecated
- ScriptOperations scriptOps();
- /**
- * Returns a new {@link BulkOperations} for the given collection. <br />
- * <strong>NOTE:</strong> Any additional support for field mapping, etc. is not available for {@literal update} or
- * {@literal remove} operations in bulk mode due to the lack of domain type information. Use
- * {@link #bulkOps(BulkMode, Class, String)} to get full type specific support.
- *
- * @param mode the {@link BulkMode} to use for bulk operations, must not be {@literal null}.
- * @param collectionName the name of the collection to work on, must not be {@literal null} or empty.
- * @return {@link BulkOperations} on the named collection
- */
- BulkOperations bulkOps(BulkMode mode, String collectionName);
- /**
- * Returns a new {@link BulkOperations} for the given entity type.
- *
- * @param mode the {@link BulkMode} to use for bulk operations, must not be {@literal null}.
- * @param entityType the name of the entity class, must not be {@literal null}.
- * @return {@link BulkOperations} on the named collection associated of the given entity class.
- */
- BulkOperations bulkOps(BulkMode mode, Class<?> entityType);
- /**
- * Returns a new {@link BulkOperations} for the given entity type and collection name.
- *
- * @param mode the {@link BulkMode} to use for bulk operations, must not be {@literal null}.
- * @param entityType the name of the entity class. Can be {@literal null}.
- * @param collectionName the name of the collection to work on, must not be {@literal null} or empty.
- * @return {@link BulkOperations} on the named collection associated with the given entity class.
- */
- BulkOperations bulkOps(BulkMode mode, @Nullable Class<?> entityType, String collectionName);
- /**
- * Query for a list of objects of type T from the collection used by the entity class.
- * <br />
- * The object is converted from the MongoDB native representation using an instance of {@see MongoConverter}. Unless
- * configured otherwise, an instance of {@link MappingMongoConverter} will be used.
- * <br />
- * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient way
- * to map objects since the test for class type is done in the client and not on the server.
- *
- * @param entityClass the parametrized type of the returned list.
- * @return the converted collection.
- */
- <T> List<T> findAll(Class<T> entityClass);
- /**
- * Query for a list of objects of type T from the specified collection.
- * <br />
- * The object is converted from the MongoDB native representation using an instance of {@see MongoConverter}. Unless
- * configured otherwise, an instance of {@link MappingMongoConverter} will be used.
- * <br />
- * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient way
- * to map objects since the test for class type is done in the client and not on the server.
- *
- * @param entityClass the parametrized type of the returned list.
- * @param collectionName name of the collection to retrieve the objects from.
- * @return the converted collection.
- */
- <T> List<T> findAll(Class<T> entityClass, String collectionName);
- /**
- * Execute a group operation over the entire collection. The group operation entity class should match the 'shape' of
- * the returned object that takes int account the initial document structure as well as any finalize functions.
- *
- * @param inputCollectionName the collection where the group operation will read from
- * @param groupBy the conditions under which the group operation will be performed, e.g. keys, initial document,
- * reduce function.
- * @param entityClass The parametrized type of the returned list
- * @return The results of the group operation
- * @deprecated since 2.2. The {@code group} command has been removed in MongoDB Server 4.2.0. <br />
- * Please use {@link #aggregate(TypedAggregation, String, Class) } with a
- * {@link org.springframework.data.mongodb.core.aggregation.GroupOperation} instead.
- */
- @Deprecated
- <T> GroupByResults<T> group(String inputCollectionName, GroupBy groupBy, Class<T> entityClass);
- /**
- * Execute a group operation restricting the rows to those which match the provided Criteria. The group operation
- * entity class should match the 'shape' of the returned object that takes int account the initial document structure
- * as well as any finalize functions.
- *
- * @param criteria The criteria that restricts the row that are considered for grouping. If not specified all rows are
- * considered.
- * @param inputCollectionName the collection where the group operation will read from
- * @param groupBy the conditions under which the group operation will be performed, e.g. keys, initial document,
- * reduce function.
- * @param entityClass The parametrized type of the returned list
- * @return The results of the group operation
- * @deprecated since 2.2. The {@code group} command has been removed in MongoDB Server 4.2.0. <br />
- * Please use {@link #aggregate(TypedAggregation, String, Class) } with a
- * {@link org.springframework.data.mongodb.core.aggregation.GroupOperation} and
- * {@link org.springframework.data.mongodb.core.aggregation.MatchOperation} instead.
- */
- @Deprecated
- <T> GroupByResults<T> group(@Nullable Criteria criteria, String inputCollectionName, GroupBy groupBy,
- Class<T> entityClass);
- /**
- * Execute an aggregation operation. The raw results will be mapped to the given entity class. The name of the
- * inputCollection is derived from the inputType of the aggregation.
- *
- * @param aggregation The {@link TypedAggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param collectionName The name of the input collection to use for the aggreation.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 1.3
- */
- <O> AggregationResults<O> aggregate(TypedAggregation<?> aggregation, String collectionName, Class<O> outputType);
- /**
- * Execute an aggregation operation. The raw results will be mapped to the given entity class. The name of the
- * inputCollection is derived from the inputType of the aggregation.
- *
- * @param aggregation The {@link TypedAggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 1.3
- */
- <O> AggregationResults<O> aggregate(TypedAggregation<?> aggregation, Class<O> outputType);
- /**
- * Execute an aggregation operation. The raw results will be mapped to the given entity class.
- *
- * @param aggregation The {@link Aggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param inputType the inputType where the aggregation operation will read from, must not be {@literal null} or
- * empty.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 1.3
- */
- <O> AggregationResults<O> aggregate(Aggregation aggregation, Class<?> inputType, Class<O> outputType);
- /**
- * Execute an aggregation operation. The raw results will be mapped to the given entity class.
- *
- * @param aggregation The {@link Aggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param collectionName the collection where the aggregation operation will read from, must not be {@literal null} or
- * empty.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 1.3
- */
- <O> AggregationResults<O> aggregate(Aggregation aggregation, String collectionName, Class<O> outputType);
- /**
- * Execute an aggregation operation backed by a Mongo DB {@link com.mongodb.client.AggregateIterable}.
- * <p>
- * Returns a {@link CloseableIterator} that wraps the a Mongo DB {@link com.mongodb.client.AggregateIterable} that
- * needs to be closed. The raw results will be mapped to the given entity class. The name of the inputCollection is
- * derived from the inputType of the aggregation.
- * <p>
- * Aggregation streaming can't be used with {@link AggregationOptions#isExplain() aggregation explain}. Enabling
- * explanation mode will throw an {@link IllegalArgumentException}.
- *
- * @param aggregation The {@link TypedAggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param collectionName The name of the input collection to use for the aggreation.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 2.0
- */
- <O> CloseableIterator<O> aggregateStream(TypedAggregation<?> aggregation, String collectionName, Class<O> outputType);
- /**
- * Execute an aggregation operation backed by a Mongo DB {@link com.mongodb.client.AggregateIterable}.
- * <br />
- * Returns a {@link CloseableIterator} that wraps the a Mongo DB {@link com.mongodb.client.AggregateIterable} that
- * needs to be closed. The raw results will be mapped to the given entity class and are returned as stream. The name
- * of the inputCollection is derived from the inputType of the aggregation.
- * <br />
- * Aggregation streaming can't be used with {@link AggregationOptions#isExplain() aggregation explain}. Enabling
- * explanation mode will throw an {@link IllegalArgumentException}.
- *
- * @param aggregation The {@link TypedAggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 2.0
- */
- <O> CloseableIterator<O> aggregateStream(TypedAggregation<?> aggregation, Class<O> outputType);
- /**
- * Execute an aggregation operation backed by a Mongo DB {@link com.mongodb.client.AggregateIterable}.
- * <br />
- * Returns a {@link CloseableIterator} that wraps the a Mongo DB {@link com.mongodb.client.AggregateIterable} that
- * needs to be closed. The raw results will be mapped to the given entity class.
- * <br />
- * Aggregation streaming can't be used with {@link AggregationOptions#isExplain() aggregation explain}. Enabling
- * explanation mode will throw an {@link IllegalArgumentException}.
- *
- * @param aggregation The {@link Aggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param inputType the inputType where the aggregation operation will read from, must not be {@literal null} or
- * empty.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 2.0
- */
- <O> CloseableIterator<O> aggregateStream(Aggregation aggregation, Class<?> inputType, Class<O> outputType);
- /**
- * Execute an aggregation operation backed by a Mongo DB {@link com.mongodb.client.AggregateIterable}.
- * <br />
- * Returns a {@link CloseableIterator} that wraps the a Mongo DB {@link com.mongodb.client.AggregateIterable} that
- * needs to be closed. The raw results will be mapped to the given entity class.
- * <br />
- * Aggregation streaming can't be used with {@link AggregationOptions#isExplain() aggregation explain}. Enabling
- * explanation mode will throw an {@link IllegalArgumentException}.
- *
- * @param aggregation The {@link Aggregation} specification holding the aggregation operations, must not be
- * {@literal null}.
- * @param collectionName the collection where the aggregation operation will read from, must not be {@literal null} or
- * empty.
- * @param outputType The parametrized type of the returned list, must not be {@literal null}.
- * @return The results of the aggregation operation.
- * @since 2.0
- */
- <O> CloseableIterator<O> aggregateStream(Aggregation aggregation, String collectionName, Class<O> outputType);
- /**
- * Execute a map-reduce operation. The map-reduce operation will be formed with an output type of INLINE
- *
- * @param inputCollectionName the collection where the map-reduce will read from. Must not be {@literal null}.
- * @param mapFunction The JavaScript map function.
- * @param reduceFunction The JavaScript reduce function
- * @param entityClass The parametrized type of the returned list. Must not be {@literal null}.
- * @return The results of the map reduce operation
- */
- <T> MapReduceResults<T> mapReduce(String inputCollectionName, String mapFunction, String reduceFunction,
- Class<T> entityClass);
- /**
- * Execute a map-reduce operation that takes additional map-reduce options.
- *
- * @param inputCollectionName the collection where the map-reduce will read from. Must not be {@literal null}.
- * @param mapFunction The JavaScript map function
- * @param reduceFunction The JavaScript reduce function
- * @param mapReduceOptions Options that specify detailed map-reduce behavior.
- * @param entityClass The parametrized type of the returned list. Must not be {@literal null}.
- * @return The results of the map reduce operation
- */
- <T> MapReduceResults<T> mapReduce(String inputCollectionName, String mapFunction, String reduceFunction,
- @Nullable MapReduceOptions mapReduceOptions, Class<T> entityClass);
- /**
- * Execute a map-reduce operation that takes a query. The map-reduce operation will be formed with an output type of
- * INLINE
- *
- * @param query The query to use to select the data for the map phase. Must not be {@literal null}.
- * @param inputCollectionName the collection where the map-reduce will read from. Must not be {@literal null}.
- * @param mapFunction The JavaScript map function
- * @param reduceFunction The JavaScript reduce function
- * @param entityClass The parametrized type of the returned list. Must not be {@literal null}.
- * @return The results of the map reduce operation
- */
- <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName, String mapFunction, String reduceFunction,
- Class<T> entityClass);
- /**
- * Execute a map-reduce operation that takes a query and additional map-reduce options
- *
- * @param query The query to use to select the data for the map phase. Must not be {@literal null}.
- * @param inputCollectionName the collection where the map-reduce will read from. Must not be {@literal null}.
- * @param mapFunction The JavaScript map function
- * @param reduceFunction The JavaScript reduce function
- * @param mapReduceOptions Options that specify detailed map-reduce behavior
- * @param entityClass The parametrized type of the returned list. Must not be {@literal null}.
- * @return The results of the map reduce operation
- */
- <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName, String mapFunction, String reduceFunction,
- @Nullable MapReduceOptions mapReduceOptions, Class<T> entityClass);
- /**
- * Returns {@link GeoResults} for all entities matching the given {@link NearQuery}. Will consider entity mapping
- * information to determine the collection the query is ran against. Note, that MongoDB limits the number of results
- * by default. Make sure to add an explicit limit to the {@link NearQuery} if you expect a particular number of
- * results.
- * <p>
- * MongoDB 4.2 has removed the {@code geoNear} command. This method uses since version 2.2 aggregations and the
- * {@code $geoNear} aggregation command to emulate {@code geoNear} command functionality. We recommend using
- * aggregations directly:
- * </p>
- *
- * <pre class="code">
- * TypedAggregation<T> geoNear = TypedAggregation.newAggregation(entityClass, Aggregation.geoNear(near, "dis"))
- * .withOptions(AggregationOptions.builder().collation(near.getCollation()).build());
- * AggregationResults<Document> results = aggregate(geoNear, Document.class);
- * </pre>
- *
- * @param near must not be {@literal null}.
- * @param entityClass must not be {@literal null}.
- * @return
- * @deprecated since 2.2. The {@code eval} command has been removed in MongoDB Server 4.2.0. Use Aggregations with
- * {@link Aggregation#geoNear(NearQuery, String)} instead.
- */
- @Deprecated
- <T> GeoResults<T> geoNear(NearQuery near, Class<T> entityClass);
- /**
- * Returns {@link GeoResults} for all entities matching the given {@link NearQuery}. Note, that MongoDB limits the
- * number of results by default. Make sure to add an explicit limit to the {@link NearQuery} if you expect a
- * particular number of results.
- * <p>
- * MongoDB 4.2 has removed the {@code geoNear} command. This method uses since version 2.2 aggregations and the
- * {@code $geoNear} aggregation command to emulate {@code geoNear} command functionality. We recommend using
- * aggregations directly:
- * </p>
- *
- * <pre class="code">
- * TypedAggregation<T> geoNear = TypedAggregation.newAggregation(entityClass, Aggregation.geoNear(near, "dis"))
- * .withOptions(AggregationOptions.builder().collation(near.getCollation()).build());
- * AggregationResults<Document> results = aggregate(geoNear, Document.class);
- * </pre>
- *
- * @param near must not be {@literal null}.
- * @param entityClass must not be {@literal null}.
- * @param collectionName the collection to trigger the query against. If no collection name is given the entity class
- * will be inspected. Must not be {@literal null} nor empty.
- * @return
- * @deprecated since 2.2. The {@code eval} command has been removed in MongoDB Server 4.2.0. Use Aggregations with
- * {@link Aggregation#geoNear(NearQuery, String)} instead.
- */
- @Deprecated
- <T> GeoResults<T> geoNear(NearQuery near, Class<T> entityClass, String collectionName);
- /**
- * Map the results of an ad-hoc query on the collection for the entity class to a single instance of an object of the
- * specified type.
- * <br />
- * The object is converted from the MongoDB native representation using an instance of {@see MongoConverter}. Unless
- * configured otherwise, an instance of {@link MappingMongoConverter} will be used.
- * <br />
- * The query is specified as a {@link Query} which can be created either using the {@link BasicQuery} or the more
- * feature rich {@link Query}.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification.
- * @param entityClass the parametrized type of the returned list.
- * @return the converted object.
- */
- @Nullable
- <T> T findOne(Query query, Class<T> entityClass);
- /**
- * Map the results of an ad-hoc query on the specified collection to a single instance of an object of the specified
- * type.
- * <br />
- * The object is converted from the MongoDB native representation using an instance of {@see MongoConverter}. Unless
- * configured otherwise, an instance of {@link MappingMongoConverter} will be used.
- * <br />
- * The query is specified as a {@link Query} which can be created either using the {@link BasicQuery} or the more
- * feature rich {@link Query}.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification.
- * @param entityClass the parametrized type of the returned list.
- * @param collectionName name of the collection to retrieve the objects from.
- * @return the converted object.
- */
- @Nullable
- <T> T findOne(Query query, Class<T> entityClass, String collectionName);
- /**
- * Determine result of given {@link Query} contains at least one element. <br />
- * <strong>NOTE:</strong> Any additional support for query/field mapping, etc. is not available due to the lack of
- * domain type information. Use {@link #exists(Query, Class, String)} to get full type specific support.
- *
- * @param query the {@link Query} class that specifies the criteria used to find a record.
- * @param collectionName name of the collection to check for objects.
- * @return {@literal true} if the query yields a result.
- */
- boolean exists(Query query, String collectionName);
- /**
- * Determine result of given {@link Query} contains at least one element.
- *
- * @param query the {@link Query} class that specifies the criteria used to find a record.
- * @param entityClass the parametrized type.
- * @return {@literal true} if the query yields a result.
- */
- boolean exists(Query query, Class<?> entityClass);
- /**
- * Determine result of given {@link Query} contains at least one element.
- *
- * @param query the {@link Query} class that specifies the criteria used to find a record.
- * @param entityClass the parametrized type. Can be {@literal null}.
- * @param collectionName name of the collection to check for objects.
- * @return {@literal true} if the query yields a result.
- */
- boolean exists(Query query, @Nullable Class<?> entityClass, String collectionName);
- /**
- * Map the results of an ad-hoc query on the collection for the entity class to a List of the specified type.
- * <br />
- * The object is converted from the MongoDB native representation using an instance of {@see MongoConverter}. Unless
- * configured otherwise, an instance of {@link MappingMongoConverter} will be used.
- * <br />
- * The query is specified as a {@link Query} which can be created either using the {@link BasicQuery} or the more
- * feature rich {@link Query}.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification. Must not be {@literal null}.
- * @param entityClass the parametrized type of the returned list. Must not be {@literal null}.
- * @return the List of converted objects.
- */
- <T> List<T> find(Query query, Class<T> entityClass);
- /**
- * Map the results of an ad-hoc query on the specified collection to a List of the specified type.
- * <br />
- * The object is converted from the MongoDB native representation using an instance of {@see MongoConverter}. Unless
- * configured otherwise, an instance of {@link MappingMongoConverter} will be used.
- * <br />
- * The query is specified as a {@link Query} which can be created either using the {@link BasicQuery} or the more
- * feature rich {@link Query}.
- *
- * @param query the query class that specifies the criteria used to find a record and also an optional fields
- * specification. Must not be {@literal null}.
- * @param entityClass the parametrized type of the returned list. Must not be {@literal null}.
- * @param collectionName name of the collection to retrieve the objects from. Must not be {@literal null}.
- * @return the List of converted objects.
- */
- <T> List<T> find(Query query, Class<T> entityClass, String collectionName);
- /**
- * Returns a document with the given id mapped onto the given class. The collection the query is ran against will be
- * derived from the given target class as well.
- *
- * @param id the id of the document to return. Must not be {@literal null}.
- * @param entityClass the type the document shall be converted into. Must not be {@literal null}.
- * @return the document with the given id mapped onto the given target class.
- */
- @Nullable
- <T> T findById(Object id, Class<T> entityClass);
- /**
- * Returns the document with the given id from the given collection mapped onto the given target class.
- *
- * @param id the id of the document to return.
- * @param entityClass the type to convert the document to.
- * @param collectionName the collection to query for the document.
- * @return he converted object or {@literal null} if document does not exist.
- */
- @Nullable
- <T> T findById(Object id, Class<T> entityClass, String collectionName);
- /**
- * Finds the distinct values for a specified {@literal field} across a single {@link MongoCollection} or view and
- * returns the results in a {@link List}.
- *
- * @param field the name of the field to inspect for distinct values. Must not be {@literal null}.
- * @param entityClass the domain type used for determining the actual {@link MongoCollection}. Must not be
- * {@literal null}.
- * @param resultClass the result type. Must not be {@literal null}.
- * @return never {@literal null}.
- * @since 2.1
- */
- default <T> List<T> findDistinct(String field, Class<?> entityClass, Class<T> resultClass) {
- return findDistinct(new Query(), field, entityClass, resultClass);
- }
- /**
- * Finds the distinct values for a specified {@literal field} across a single {@link MongoCollection} or view and
- * returns the results in a {@link List}.
- *
- * @param query filter {@link Query} to restrict search. Must not be {@literal null}.
- * @param field the name of the field to inspect for distinct values. Must not be {@literal null}.
- * @param entityClass the domain type used for determining the actual {@link MongoCollection} and mapping the
- * {@link Query} to the domain type fields. Must not be {@literal null}.
- * @param resultClass the result type. Must not be {@literal null}.
- * @return never {@literal null}.
- * @since 2.1
- */
- <T> List<T> findDistinct(Query query, String field, Class<?> entityClass, Class<T> resultClass);
- /**
- * Finds the distinct values for a specified {@literal field} across a single {@link MongoCollection} or view and
- * returns the results in a {@link List}.
- *
- * @param query filter {@link Query} to restrict search. Must not be {@literal null}.
- * @param field the name of the field to inspect for distinct values. Must not be {@literal null}.
- * @param collectionName the explicit name of the actual {@link MongoCollection}. Must not be {@literal null}.
- * @param entityClass the domain type used for mapping the {@link Query} to the domain type fields.
- * @param resultClass the result type. Must not be {@literal null}.
- * @return never {@literal null}.
- * @since 2.1
- */
- <T> List<T> findDistinct(Query query, String field, String collectionName, Class<?> entityClass,
- Class<T> resultClass);
- /**
- * Finds the distinct values for a specified {@literal field} across a single {@link MongoCollection} or view and
- * returns the results in a {@link List}.
- *
- * @param query filter {@link Query} to restrict search. Must not be {@literal null}.
- * @param field the name of the field to inspect for distinct values. Must not be {@literal null}.
- * @param collection the explicit name of the actual {@link MongoCollection}. Must not be {@literal null}.
- * @param resultClass the result type. Must not be {@literal null}.
- * @return never {@literal null}.
- * @since 2.1
- */
- default <T> List<T> findDistinct(Query query, String field, String collection, Class<T> resultClass) {
- return findDistinct(query, field, collection, Object.class, resultClass);
- }
- /**
- * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
- * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification. Must not be {@literal null}.
- * @param update the {@link UpdateDefinition} to apply on matching documents. Must not be {@literal null}.
- * @param entityClass the parametrized type. Must not be {@literal null}.
- * @return the converted object that was updated before it was updated or {@literal null}, if not found.
- * @since 3.0
- * @see Update
- * @see AggregationUpdate
- */
- @Nullable
- <T> T findAndModify(Query query, UpdateDefinition update, Class<T> entityClass);
- /**
- * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
- * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification. Must not be {@literal null}.
- * @param update the {@link UpdateDefinition} to apply on matching documents. Must not be {@literal null}.
- * @param entityClass the parametrized type. Must not be {@literal null}.
- * @param collectionName the collection to query. Must not be {@literal null}.
- * @return the converted object that was updated before it was updated or {@literal null}, if not found.
- * @since 3.0
- * @see Update
- * @see AggregationUpdate
- */
- @Nullable
- <T> T findAndModify(Query query, UpdateDefinition update, Class<T> entityClass, String collectionName);
- /**
- * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
- * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking
- * {@link FindAndModifyOptions} into account.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification.
- * @param update the {@link UpdateDefinition} to apply on matching documents.
- * @param options the {@link FindAndModifyOptions} holding additional information.
- * @param entityClass the parametrized type.
- * @return the converted object that was updated or {@literal null}, if not found. Depending on the value of
- * {@link FindAndModifyOptions#isReturnNew()} this will either be the object as it was before the update or as
- * it is after the update.
- * @since 3.0
- * @see Update
- * @see AggregationUpdate
- */
- @Nullable
- <T> T findAndModify(Query query, UpdateDefinition update, FindAndModifyOptions options, Class<T> entityClass);
- /**
- * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
- * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking
- * {@link FindAndModifyOptions} into account.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification. Must not be {@literal null}.
- * @param update the {@link UpdateDefinition} to apply on matching documents. Must not be {@literal null}.
- * @param options the {@link FindAndModifyOptions} holding additional information. Must not be {@literal null}.
- * @param entityClass the parametrized type. Must not be {@literal null}.
- * @param collectionName the collection to query. Must not be {@literal null}.
- * @return the converted object that was updated or {@literal null}, if not found. Depending on the value of
- * {@link FindAndModifyOptions#isReturnNew()} this will either be the object as it was before the update or as
- * it is after the update.
- * @since 3.0
- * @see Update
- * @see AggregationUpdate
- */
- @Nullable
- <T> T findAndModify(Query query, UpdateDefinition update, FindAndModifyOptions options, Class<T> entityClass,
- String collectionName);
- /**
- * Triggers
- * <a href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/">findOneAndReplace</a>
- * to replace a single document matching {@link Criteria} of given {@link Query} with the {@code replacement}
- * document. <br />
- * The collection name is derived from the {@literal replacement} type. <br />
- * Options are defaulted to {@link FindAndReplaceOptions#empty()}. <br />
- * <strong>NOTE:</strong> The replacement entity must not hold an {@literal id}.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification. Must not be {@literal null}.
- * @param replacement the replacement document. Must not be {@literal null}.
- * @return the converted object that was updated or {@literal null}, if not found.
- * @since 2.1
- */
- @Nullable
- default <T> T findAndReplace(Query query, T replacement) {
- return findAndReplace(query, replacement, FindAndReplaceOptions.empty());
- }
- /**
- * Triggers
- * <a href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/">findOneAndReplace</a>
- * to replace a single document matching {@link Criteria} of given {@link Query} with the {@code replacement}
- * document.<br />
- * Options are defaulted to {@link FindAndReplaceOptions#empty()}. <br />
- * <strong>NOTE:</strong> The replacement entity must not hold an {@literal id}.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification. Must not be {@literal null}.
- * @param replacement the replacement document. Must not be {@literal null}.
- * @param collectionName the collection to query. Must not be {@literal null}.
- * @return the converted object that was updated or {@literal null}, if not found.
- * @since 2.1
- */
- @Nullable
- default <T> T findAndReplace(Query query, T replacement, String collectionName) {
- return findAndReplace(query, replacement, FindAndReplaceOptions.empty(), collectionName);
- }
- /**
- * Triggers
- * <a href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/">findOneAndReplace</a>
- * to replace a single document matching {@link Criteria} of given {@link Query} with the {@code replacement} document
- * taking {@link FindAndReplaceOptions} into account.<br />
- * <strong>NOTE:</strong> The replacement entity must not hold an {@literal id}.
- *
- * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional
- * fields specification. Must not be {@literal null}.
- * @param replacement the replacement document. Must not be {@literal null}.
- * @param options the {@link FindAndModifyOptions} holding additional information. Must not be {@literal null}.
- * @return the converted object that was updated or {@literal null}, if not found. Depending on the value of
- * {@link FindAndReplaceOptions#isReturnNew()} this will either be the object as it was before the update or
- * as it is after the update.
- * @since 2.1
- */
- @Nullable
- default <T> T findAndReplace(Query query, T replacement, FindAndReplaceOptions options) {
- return findAndReplace(query, replacement, options, getCollectionName(ClassUtils.getUserClass(replacement)));
- }
- /**
- * Triggers
- * <a href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/">findOneAndReplace</a>
- * to replace a single document matching {@link Criteria} of given {@link Query} with the {@code replacement} document
- * taking {@link FindAndReplaceOptions} into account.<br />
- * <strong>NOTE:</strong> The replacement entity must not hold an {@literal id}.
- *
- * @param query the {@link Query} class that specifies theā¦
Large files files are truncated, but you can click here to view the full file