DATAMONGO-2188 - Deprecate auto-index creation.

mp911de · mp911de · commit 76e7d297f1f3 · 2019-01-16T15:00:06.000+01:00
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java
@@ -55,21 +55,24 @@
 
 	/**
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/index-unique/">https://docs.mongodb.org/manual/core/index-unique/</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/index-unique/">https://docs.mongodb.org/manual/core/index-unique/</a>
 	 */
 	boolean unique() default false;
 
 	/**
 	 * If set to true index will skip over any document that is missing the indexed field.
 	 *
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/index-sparse/">https://docs.mongodb.org/manual/core/index-sparse/</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/index-sparse/">https://docs.mongodb.org/manual/core/index-sparse/</a>
 	 */
 	boolean sparse() default false;
 
 	/**
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping">https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping">https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping</a>
 	 * @deprecated since 2.1. No longer supported by MongoDB as of server version 3.0.
 	 */
 	@Deprecated
@@ -131,7 +134,8 @@
 	 * If {@literal true} the index will be created in the background.
 	 *
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/indexes/#background-construction">https://docs.mongodb.org/manual/core/indexes/#background-construction</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/indexes/#background-construction">https://docs.mongodb.org/manual/core/indexes/#background-construction</a>
 	 */
 	boolean background() default false;
 
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/IndexResolver.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/IndexResolver.java
@@ -28,8 +28,8 @@
 interface IndexResolver {
 
 	/**
-	 * Find and create {@link IndexDefinition}s for properties of given {@link TypeInformation}. {@link IndexDefinition}s are created
-	 * for properties and types with {@link Indexed}, {@link CompoundIndexes} or {@link GeoSpatialIndexed}.
+	 * Find and create {@link IndexDefinition}s for properties of given {@link TypeInformation}. {@link IndexDefinition}s
+	 * are created for properties and types with {@link Indexed}, {@link CompoundIndexes} or {@link GeoSpatialIndexed}.
 	 *
 	 * @param typeInformation
 	 * @return Empty {@link Iterable} in case no {@link IndexDefinition} could be resolved for type.
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Indexed.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Indexed.java
@@ -31,15 +31,16 @@
  * @author Christoph Strobl
  * @author Jordi Llach
  */
-@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD})
+@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Indexed {
 
 	/**
 	 * If set to true reject all documents that contain a duplicate value for the indexed field.
 	 *
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/index-unique/">https://docs.mongodb.org/manual/core/index-unique/</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/index-unique/">https://docs.mongodb.org/manual/core/index-unique/</a>
 	 */
 	boolean unique() default false;
 
@@ -49,13 +50,15 @@
 	 * If set to true index will skip over any document that is missing the indexed field.
 	 *
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/index-sparse/">https://docs.mongodb.org/manual/core/index-sparse/</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/index-sparse/">https://docs.mongodb.org/manual/core/index-sparse/</a>
 	 */
 	boolean sparse() default false;
 
 	/**
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping">https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping">https://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping</a>
 	 * @deprecated since 2.1. No longer supported by MongoDB as of server version 3.0.
 	 */
 	@Deprecated
@@ -115,15 +118,17 @@
 	 * If {@literal true} the index will be created in the background.
 	 *
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/core/indexes/#background-construction">https://docs.mongodb.org/manual/core/indexes/#background-construction</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/core/indexes/#background-construction">https://docs.mongodb.org/manual/core/indexes/#background-construction</a>
 	 */
 	boolean background() default false;
 
 	/**
 	 * Configures the number of seconds after which the collection should expire. Defaults to -1 for no expiry.
 	 *
 	 * @return
-	 * @see <a href="https://docs.mongodb.org/manual/tutorial/expire-data/">https://docs.mongodb.org/manual/tutorial/expire-data/</a>
+	 * @see <a href=
+	 *      "https://docs.mongodb.org/manual/tutorial/expire-data/">https://docs.mongodb.org/manual/tutorial/expire-data/</a>
 	 */
 	int expireAfterSeconds() default -1;
 }
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/MongoMappingEventPublisher.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/MongoMappingEventPublisher.java
@@ -36,7 +36,9 @@
  * @author Jon Brisbin
  * @author Oliver Gierke
  * @author Mark Paluch
+ * @deprecated since 2.2. Use {@link IndexOperations} to define and create indexes.
  */
+@Deprecated
 public class MongoMappingEventPublisher implements ApplicationEventPublisher {
 
 	private final ApplicationListener<MappingContextEvent<?, ?>> indexCreator;
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/MongoPersistentEntityIndexCreator.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/MongoPersistentEntityIndexCreator.java
@@ -63,10 +63,12 @@ public class MongoPersistentEntityIndexCreator implements ApplicationListener<Ma
 	/**
 	 * Creates a new {@link MongoPersistentEntityIndexCreator} for the given {@link MongoMappingContext} and
 	 * {@link MongoDbFactory}.
-	 *  @param mappingContext must not be {@literal null}.
+	 *
+	 * @param mappingContext must not be {@literal null}.
 	 * @param indexOperationsProvider must not be {@literal null}.
 	 */
-	public MongoPersistentEntityIndexCreator(MongoMappingContext mappingContext, IndexOperationsProvider indexOperationsProvider) {
+	public MongoPersistentEntityIndexCreator(MongoMappingContext mappingContext,
+			IndexOperationsProvider indexOperationsProvider) {
 		this(mappingContext, indexOperationsProvider, new MongoPersistentEntityIndexResolver(mappingContext));
 	}
 
@@ -78,8 +80,8 @@ public MongoPersistentEntityIndexCreator(MongoMappingContext mappingContext, Ind
 	 * @param mongoDbFactory must not be {@literal null}.
 	 * @param indexResolver must not be {@literal null}.
 	 */
-	public MongoPersistentEntityIndexCreator(MongoMappingContext mappingContext, IndexOperationsProvider indexOperationsProvider,
-											 IndexResolver indexResolver) {
+	public MongoPersistentEntityIndexCreator(MongoMappingContext mappingContext,
+			IndexOperationsProvider indexOperationsProvider, IndexResolver indexResolver) {
 
 		Assert.notNull(mappingContext, "MongoMappingContext must not be null!");
 		Assert.notNull(indexOperationsProvider, "IndexOperationsProvider must not be null!");
@@ -146,8 +148,8 @@ void createIndex(IndexDefinitionHolder indexDefinition) {
 
 		} catch (UncategorizedMongoDbException ex) {
 
-			if (ex.getCause() instanceof MongoException &&
-					MongoDbErrorCodes.isDataIntegrityViolationCode(((MongoException) ex.getCause()).getCode())) {
+			if (ex.getCause() instanceof MongoException
+					&& MongoDbErrorCodes.isDataIntegrityViolationCode(((MongoException) ex.getCause()).getCode())) {
 
 				IndexInfo existingIndex = fetchIndexInformation(indexDefinition);
 				String message = "Cannot create index for '%s' in collection '%s' with keys '%s' and options '%s'.";
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/support/IndexEnsuringQueryCreationListener.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/support/IndexEnsuringQueryCreationListener.java
@@ -42,7 +42,10 @@
  * @author Oliver Gierke
  * @author Mark Paluch
  * @author Christoph Strobl
+ * @deprecated since 2.2. Use {@link org.springframework.data.mongodb.core.index.IndexOperations} to define and create
+ *             indexes.
  */
+@Deprecated
 class IndexEnsuringQueryCreationListener implements QueryCreationListener<PartTreeMongoQuery> {
 
 	private static final Set<Type> GEOSPATIAL_TYPES = new HashSet<Type>(Arrays.asList(Type.NEAR, Type.WITHIN));
diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc
@@ -378,7 +378,7 @@ public class Person {
 
 IMPORTANT: The `@Id` annotation tells the mapper which property you want to use for the MongoDB `_id` property, and the `@Indexed` annotation tells the mapping framework to call `createIndex(…)` on that property of your document, making searches faster.
 
-IMPORTANT: Automatic index creation is only done for types annotated with `@Document`.
+IMPORTANT: Automatic index creation is deprecated since version 2.2 because controlling the actual time of index creation is rather difficult. Index creation can be part of the application startup, happen during runtime or an out of band process. Therefore, Spring Data MongoDB backs off entirely and recommends index creation to happen either out of band or as part of the application startup using `IndexOperations`. Automatic index creation is still available and is is only done for types annotated with `@Document`.
 
 [[mapping-usage-annotations]]
 === Mapping Annotation Overview
