Refine createCollection(…) documentation and explore CollectionOptions customization

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-mongodb-parent</artifactId>
-	<version>5.0.0-SNAPSHOT</version>
+	<version>5.0.0-GH-4978-SNAPSHOT</version>
 	<packaging>pom</packaging>
 
 	<name>Spring Data MongoDB</name>

spring-data-mongodb-distribution/pom.xml

@@ -15,7 +15,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-mongodb-parent</artifactId>
-		<version>5.0.0-SNAPSHOT</version>
+		<version>5.0.0-GH-4978-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-mongodb/pom.xml

@@ -13,7 +13,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-mongodb-parent</artifactId>
-		<version>5.0.0-SNAPSHOT</version>
+		<version>5.0.0-GH-4978-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java

@@ -20,6 +20,7 @@
 import java.util.Set;
 import java.util.concurrent.locks.ReentrantLock;
 import java.util.function.Consumer;
+import java.util.function.Function;
 import java.util.function.Supplier;
 import java.util.stream.Stream;
 
@@ -260,12 +261,48 @@ default SessionScoped withSession(Supplier<ClientSession> sessionProvider) {
 
 	/**
 	 * Create an uncapped collection with a name based on the provided entity class.
+	 * <p>
+	 * This method derives {@link CollectionOptions} from the given {@code entityClass} using
+	 * {@link org.springframework.data.mongodb.core.mapping.Document} and
+	 * {@link org.springframework.data.mongodb.core.mapping.TimeSeries} annotations to determine:
+	 * <ul>
+	 * <li>Collation</li>
+	 * <li>TimeSeries time and meta fields, granularity and {@code expireAfter}</li>
+	 * </ul>
+	 * Any other options such as change stream options, schema-based details (validation, encryption) are not considered
+	 * and must be provided through {@link #createCollection(Class, Function)} or
+	 * {@link #createCollection(Class, CollectionOptions)}.
 	 *
 	 * @param entityClass class that determines the collection to create.
 	 * @return the created collection.
+	 * @see #createCollection(Class, Function)
+	 * @see #createCollection(Class, CollectionOptions)
 	 */
 	<T> MongoCollection<Document> createCollection(Class<T> entityClass);
 
+	/**
+	 * Create an uncapped collection with a name based on the provided entity class allowing to customize derived
+	 * {@link CollectionOptions}.
+	 * <p>
+	 * This method derives {@link CollectionOptions} from the given {@code entityClass} using
+	 * {@link org.springframework.data.mongodb.core.mapping.Document} and
+	 * {@link org.springframework.data.mongodb.core.mapping.TimeSeries} annotations to determine:
+	 * <ul>
+	 * <li>Collation</li>
+	 * <li>TimeSeries time and meta fields, granularity and {@code expireAfter}</li>
+	 * </ul>
+	 * Any other options such as change stream options, schema-based details (validation, encryption) are not considered
+	 * and must be provided through {@link CollectionOptions}.
+	 *
+	 * @param entityClass class that determines the collection to create.
+	 * @param collectionOptionsCustomizer customizer function to customize the derived {@link CollectionOptions}.
+	 * @return the created collection.
+	 * @see #createCollection(Class, CollectionOptions)
+	 * @since 5.0
+	 */
+	<T> MongoCollection<Document> createCollection(Class<T> entityClass,
+			Function<? super CollectionOptions, ? extends CollectionOptions> collectionOptionsCustomizer);
+
 	/**
 	 * Create a collection with a name based on the provided entity class using the options.
 	 *
@@ -998,7 +1035,8 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	 * @see Update
 	 * @see AggregationUpdate
 	 */
-	<T> @Nullable T findAndModify(Query query, UpdateDefinition update, FindAndModifyOptions options, Class<T> entityClass);
+	<T> @Nullable 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>
@@ -1021,8 +1059,8 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	 * @see Update
 	 * @see AggregationUpdate
 	 */
-	<T> @Nullable T findAndModify(Query query, UpdateDefinition update, FindAndModifyOptions options, Class<T> entityClass,
-			String collectionName);
+	<T> @Nullable T findAndModify(Query query, UpdateDefinition update, FindAndModifyOptions options,
+			Class<T> entityClass, String collectionName);
 
 	/**
 	 * Triggers
@@ -1102,7 +1140,8 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	 *         as it is after the update.
 	 * @since 2.1
 	 */
-	default <T> @Nullable T findAndReplace(Query query, T replacement, FindAndReplaceOptions options, String collectionName) {
+	default <T> @Nullable T findAndReplace(Query query, T replacement, FindAndReplaceOptions options,
+			String collectionName) {
 
 		Assert.notNull(replacement, "Replacement must not be null");
 		return findAndReplace(query, replacement, options, (Class<T>) ClassUtils.getUserClass(replacement), collectionName);
@@ -1154,8 +1193,8 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	 *           {@link #getCollectionName(Class) derived} from the given replacement value.
 	 * @since 2.1
 	 */
-	default <S, T> @Nullable T findAndReplace(Query query, S replacement, FindAndReplaceOptions options, Class<S> entityType,
-			Class<T> resultType) {
+	default <S, T> @Nullable T findAndReplace(Query query, S replacement, FindAndReplaceOptions options,
+			Class<S> entityType, Class<T> resultType) {
 
 		return findAndReplace(query, replacement, options, entityType,
 				getCollectionName(ClassUtils.getUserClass(entityType)), resultType);

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoTemplate.java

@@ -23,6 +23,7 @@
 import java.util.*;
 import java.util.concurrent.TimeUnit;
 import java.util.function.BiPredicate;
+import java.util.function.Function;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -650,7 +651,17 @@ public void setSessionSynchronization(SessionSynchronization sessionSynchronizat
 
 	@Override
 	public <T> MongoCollection<Document> createCollection(Class<T> entityClass) {
-		return createCollection(entityClass, operations.forType(entityClass).getCollectionOptions());
+		return createCollection(entityClass, Function.identity());
+	}
+
+	@Override
+	public <T> MongoCollection<Document> createCollection(Class<T> entityClass,
+			Function<? super CollectionOptions, ? extends CollectionOptions> collectionOptionsCustomizer) {
+
+		Assert.notNull(collectionOptionsCustomizer, "CollectionOptions customizer function must not be null");
+
+		return createCollection(entityClass,
+				collectionOptionsCustomizer.apply(operations.forType(entityClass).getCollectionOptions()));
 	}
 
 	@Override

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java

@@ -20,6 +20,7 @@
 
 import java.util.Collection;
 import java.util.function.Consumer;
+import java.util.function.Function;
 import java.util.function.Supplier;
 
 import org.bson.Document;
@@ -214,12 +215,48 @@ default ReactiveSessionScoped withSession(Supplier<ClientSession> sessionProvide
 
 	/**
 	 * Create an uncapped collection with a name based on the provided entity class.
+	 * <p>
+	 * This method derives {@link CollectionOptions} from the given {@code entityClass} using
+	 * {@link org.springframework.data.mongodb.core.mapping.Document} and
+	 * {@link org.springframework.data.mongodb.core.mapping.TimeSeries} annotations to determine:
+	 * <ul>
+	 * <li>Collation</li>
+	 * <li>TimeSeries time and meta fields, granularity and {@code expireAfter}</li>
+	 * </ul>
+	 * Any other options such as change stream options, schema-based details (validation, encryption) are not considered
+	 * and must be provided through {@link #createCollection(Class, Function)} or
+	 * {@link #createCollection(Class, CollectionOptions)}.
 	 *
 	 * @param entityClass class that determines the collection to create.
 	 * @return the created collection.
+	 * @see #createCollection(Class, Function)
+	 * @see #createCollection(Class, CollectionOptions)
 	 */
 	<T> Mono<MongoCollection<Document>> createCollection(Class<T> entityClass);
 
+	/**
+	 * Create an uncapped collection with a name based on the provided entity class allowing to customize derived
+	 * {@link CollectionOptions}.
+	 * <p>
+	 * This method derives {@link CollectionOptions} from the given {@code entityClass} using
+	 * {@link org.springframework.data.mongodb.core.mapping.Document} and
+	 * {@link org.springframework.data.mongodb.core.mapping.TimeSeries} annotations to determine:
+	 * <ul>
+	 * <li>Collation</li>
+	 * <li>TimeSeries time and meta fields, granularity and {@code expireAfter}</li>
+	 * </ul>
+	 * Any other options such as change stream options, schema-based details (validation, encryption) are not considered
+	 * and must be provided through {@link CollectionOptions}.
+	 *
+	 * @param entityClass class that determines the collection to create.
+	 * @param collectionOptionsCustomizer customizer function to customize the derived {@link CollectionOptions}.
+	 * @return the created collection.
+	 * @see #createCollection(Class, CollectionOptions)
+	 * @since 5.0
+	 */
+	<T> Mono<MongoCollection<Document>> createCollection(Class<T> entityClass,
+			Function<? super CollectionOptions, ? extends CollectionOptions> collectionOptionsCustomizer);
+
 	/**
 	 * Create a collection with a name based on the provided entity class using the options.
 	 *

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoTemplate.java

@@ -659,7 +659,17 @@ public <T> Mono<T> createMono(String collectionName, ReactiveCollectionCallback<
 
 	@Override
 	public <T> Mono<MongoCollection<Document>> createCollection(Class<T> entityClass) {
-		return createCollection(entityClass, operations.forType(entityClass).getCollectionOptions());
+		return createCollection(entityClass, Function.identity());
+	}
+
+	@Override
+	public <T> Mono<MongoCollection<Document>> createCollection(Class<T> entityClass,
+			Function<? super CollectionOptions, ? extends CollectionOptions> collectionOptionsCustomizer) {
+
+		Assert.notNull(collectionOptionsCustomizer, "CollectionOptions customizer function must not be null");
+
+		return createCollection(entityClass,
+				collectionOptionsCustomizer.apply(operations.forType(entityClass).getCollectionOptions()));
 	}
 
 	@Override
@@ -740,11 +750,10 @@ public <T> Mono<Boolean> collectionExists(Class<T> entityClass) {
 
 	@Override
 	public Mono<Boolean> collectionExists(String collectionName) {
-		return createMono(
-				db -> Flux.from(db.listCollectionNames()) //
-						.filter(s -> s.equals(collectionName)) //
-						.map(s -> true) //
-						.single(false));
+		return createMono(db -> Flux.from(db.listCollectionNames()) //
+				.filter(s -> s.equals(collectionName)) //
+				.map(s -> true) //
+				.single(false));
 	}
 
 	@Override
@@ -2293,7 +2302,7 @@ protected <T> Flux<T> doFindAndDelete(String collectionName, Query query, Class<
 						.flatMapSequential(deleteResult -> Flux.fromIterable(list)));
 	}
 
-	@SuppressWarnings({"rawtypes", "unchecked", "NullAway"})
+	@SuppressWarnings({ "rawtypes", "unchecked", "NullAway" })
 	<S, T> Flux<T> doFindAndDelete(String collectionName, Query query, Class<S> entityClass,
 			QueryResultConverter<? super S, ? extends T> resultConverter) {
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/Document.java

@@ -42,8 +42,8 @@
 	/**
 	 * The collection the document representing the entity is supposed to be stored in. If not configured, a default
 	 * collection name will be derived from the type's name. The attribute supports SpEL expressions to dynamically
-	 * calculate the collection to based on a per operation basis.
-	 * 
+	 * calculate the collection to based on a per-operation basis.
+	 *
 	 * @return the name of the collection to be used.
 	 */
 	@AliasFor("collection")
@@ -53,7 +53,7 @@
 	 * The collection the document representing the entity is supposed to be stored in. If not configured, a default
 	 * collection name will be derived from the type's name. The attribute supports SpEL expressions to dynamically
 	 * calculate the collection to based on a per operation basis.
-	 * 
+	 *
 	 * @return the name of the collection to be used.
 	 */
 	@AliasFor("value")

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/TimeSeries.java

@@ -41,7 +41,7 @@
 	/**
 	 * The collection the document representing the entity is supposed to be stored in. If not configured, a default
 	 * collection name will be derived from the type's name. The attribute supports SpEL expressions to dynamically
-	 * calculate the collection based on a per operation basis.
+	 * calculate the collection based on a per-operation basis.
 	 *
 	 * @return the name of the collection to be used.
 	 * @see Document#collection()