Configure index settings with @setting annotation.

Original Pull Request #1748
Closes #1719

Author: sothawo

Diff for: src/main/asciidoc/reference/elasticsearch-clients.adoc

@@ -8,7 +8,7 @@ Spring Data Elasticsearch operates upon an Elasticsearch client that is connecte
 [[elasticsearch.clients.transport]]
 == Transport Client
 
-WARNING: The well known `TransportClient` is deprecated as of Elasticsearch 7 and will be removed in Elasticsearch 8. (https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/transport-client.html[see the Elasticsearch documentation]). Spring Data Elasticsearch will support the `TransportClient` as long as it is available in the used
+WARNING: The `TransportClient` is deprecated as of Elasticsearch 7 and will be removed in Elasticsearch 8. (https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/transport-client.html[see the Elasticsearch documentation]). Spring Data Elasticsearch will support the `TransportClient` as long as it is available in the used
 Elasticsearch <<elasticsearch.versions,version>> but has deprecated the classes using it since version 4.0.
 
 We strongly recommend to use the <<elasticsearch.clients.rest>> instead of the `TransportClient`.

Diff for: src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc

@@ -6,6 +6,10 @@ This section describes breaking changes from version 4.1.x to 4.2.x and how remo
 [[elasticsearch-migration-guide-4.1-4.2.deprecations]]
 == Deprecations
 
+=== @Document parameters
+
+The parameters of the `@Document` annotation that are relevant for  the index settings (`useServerConfiguration`, `shards`. `replicas`, `refreshIntervall` and `indexStoretype`) have been moved to the `@Setting` annotation. Use in `@Document` is still possible but deprecated.
+
 [[elasticsearch-migration-guide-4.1-4.2.removal]]
 == Removals
 

Diff for: src/main/asciidoc/reference/elasticsearch-misc.adoc

@@ -4,6 +4,48 @@
 This chapter covers additional support for Elasticsearch operations that cannot be directly accessed via the repository interface.
 It is recommended to add those operations as custom implementation as described in <<repositories.custom-implementations>> .
 
+[[elasticsearc.misc.index.settings]]
+== Index settings
+
+When creating Elasticsearch indices with Spring Data Elasticsearch different index settings can be defined by using the `@Setting` annotation. The following arguments are available:
+
+* `useServerConfiguration` does not send any settings parameters, so the Elasticsearch server configuration determines them.
+* `settingPath` refers to a JSON file defining the settings that must be resolvable in the classpath
+* `shards` the number of shards to use, defaults to _1_
+* `replicas` the number of replicas, defaults to _1_
+* `refreshIntervall`, defaults to _"1s"_
+* `indexStoreType`, defaults to _"fs"_
+
+
+It is as well possible to define https://www.elastic.co/guide/en/elasticsearch/reference/7.11/index-modules-index-sorting.html[index sorting] (check the linked Elasticsearch documentation for the possible field types and values):
+
+====
+[source,java]
+----
+@Document(indexName = "entities")
+@Setting(
+  sortFields = { "secondField", "firstField" },                                  <.>
+  sortModes = { Setting.SortMode.max, Setting.SortMode.min },                    <.>
+  sortOrders = { Setting.SortOrder.desc, Setting.SortOrder.asc },
+  sortMissingValues = { Setting.SortMissing._last, Setting.SortMissing._first })
+class Entity {
+    @Nullable
+    @Id private String id;
+
+    @Nullable
+    @Field(name = "first_field", type = FieldType.Keyword)
+    private String firstField;
+
+    @Nullable @Field(name = "second_field", type = FieldType.Keyword)
+    private String secondField;
+
+    // getter and setter...
+}
+----
+<.> when defining sort fields, use the name of the Java property (_firstField_), not the name that might be defined for Elasticsearch (_first_field_)
+<.> `sortModes`, `sortOrders` and `sortMissingValues` are optional, but if they are set, the number of entries must match the number of `sortFields` elements
+====
+
 [[elasticsearch.misc.filter]]
 == Filter Builder
 
@@ -20,7 +62,7 @@ SearchQuery searchQuery = new NativeSearchQueryBuilder()
   .withQuery(matchAllQuery())
   .withFilter(boolFilter().must(termFilter("id", documentId)))
   .build();
-  
+
 Page<SampleEntity> sampleEntities = operations.searchForPage(searchQuery, SampleEntity.class, index);
 ----
 ====
@@ -31,6 +73,7 @@ Page<SampleEntity> sampleEntities = operations.searchForPage(searchQuery, Sample
 Elasticsearch has a scroll API for getting big result set in chunks.
 This is internally used by Spring Data Elasticsearch to provide the implementations of the `<T> SearchHitsIterator<T> SearchOperations.searchForStream(Query query, Class<T> clazz, IndexCoordinates index)` method.
 
+====
 [source,java]
 ----
 IndexCoordinates index = IndexCoordinates.of("sample-index");
@@ -50,9 +93,11 @@ while (stream.hasNext()) {
 
 stream.close();
 ----
+====
 
 There are no methods in the `SearchOperations` API to access the scroll id, if it should be necessary to access this, the following methods of the `ElasticsearchRestTemplate` can be used:
 
+====
 [source,java]
 ----
 
@@ -77,10 +122,12 @@ while (scroll.hasSearchHits()) {
 }
 template.searchScrollClear(scrollId);
 ----
+====
 
 To use the Scroll API with repository methods, the return type must defined as `Stream` in the Elasticsearch Repository.
 The implementation of the method will then use the scroll methods from the ElasticsearchTemplate.
 
+====
 [source,java]
 ----
 interface SampleEntityRepository extends Repository<SampleEntity, String> {
@@ -89,6 +136,7 @@ interface SampleEntityRepository extends Repository<SampleEntity, String> {
 
 }
 ----
+====
 
 [[elasticsearch.misc.sorts]]
 == Sort options
@@ -97,7 +145,9 @@ In addition to the default sort options described <<repositories.paging-and-sort
 
 If the class to be retrieved has a `GeoPoint` property named _location_, the following `Sort` would sort the results by distance to the given point:
 
+====
 [source,java]
 ----
 Sort.by(new GeoDistanceOrder("location", new GeoPoint(48.137154, 11.5761247)))
 ----
+====

Diff for: src/main/asciidoc/reference/elasticsearch-object-mapping.adoc

@@ -36,14 +36,6 @@ The most important attributes are:
 This can contain a SpEL template expression like `"log-#{T(java.time.LocalDate).now().toString()}"`
 ** `type`: [line-through]#the mapping type.
 If not set, the lowercased simple name of the class is used.# (deprecated since version 4.0)
-** `shards`: the number of shards for the index.
-** `replicas`: the number of replicas for the index.
-** `refreshIntervall`: Refresh interval for the index.
-Used for index creation.
-Default value is _"1s"_.
-** `indexStoreType`: Index storage type for the index.
-Used for index creation.
-Default value is _"fs"_.
 ** `createIndex`: flag whether to create an index on repository bootstrapping.
 Default value is _true_.
 See <<elasticsearch.repositories.autocreation>>
@@ -71,13 +63,13 @@ The mapping metadata infrastructure is defined in a separate spring-data-commons
 ==== Date format mapping
 
 Properties that derive from `TemporalAccessor` or are of type `java.util.Date` must either have a `@Field` annotation
-of type `FieldType.Date` or a custom converter must be registered for this type. This paragraph describes the use of 
+of type `FieldType.Date` or a custom converter must be registered for this type. This paragraph describes the use of
 `FieldType.Date`.
 
-There are two attributes of the `@Field` annotation that define which date format information is written to the 
+There are two attributes of the `@Field` annotation that define which date format information is written to the
 mapping (also see https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#built-in-date-formats[Elasticsearch Built In Formats] and https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#custom-date-formats[Elasticsearch Custom Date Formats])
 
-The `format` attributes is used to define at least one of the predefined formats. If it is not defined, then a 
+The `format` attributes is used to define at least one of the predefined formats. If it is not defined, then a
 default value of  __date_optional_time_ and _epoch_millis_ is used.
 
 The `pattern` attribute can be used to add additional custom format strings. If you want to use only custom date formats, you must set the `format` property to empty `{}`.

Diff for: src/main/asciidoc/reference/elasticsearch-operations.adoc

@@ -21,7 +21,8 @@ The default implementations of the interfaces offer:
 ====
 .Index management and automatic creation of indices and mappings.
 
-The `IndexOperations` interface and the provided implementation which can be obtained from an `ElasticsearchOperations` instance - for example with a call to `operations.indexOps(clazz)`- give the user the ability to create indices, put mappings or store template and alias information in the Elasticsearch cluster.
+The `IndexOperations` interface and the provided implementation which can be obtained from an `ElasticsearchOperations` instance - for example with a call to `operations.indexOps(clazz)`- give the user the ability to create indices, put mappings or store template and alias information in the Elasticsearch cluster. Details of the index that will be created
+can be set by using the `@Setting` annotation, refer to <<elasticsearc.misc.index.settings>> for further information.
 
 **None of these operations are done automatically** by the implementations of `IndexOperations` or `ElasticsearchOperations`. It is the user's responsibility to call the methods.
 

Diff for: src/main/asciidoc/reference/elasticsearch-repositories.adoc

@@ -31,7 +31,7 @@ class Book {
 
 The `@Document` annotation has an argument `createIndex`. If this argument is set to true - which is the default value  - Spring Data Elasticsearch will during bootstrapping the repository support on application startup check if the index defined by the `@Document` annotation exists.
 
-If it does not exist, the index will be created and the mappings derived from the entity's annotations (see <<elasticsearch.mapping>>) will be written to the newly created index.
+If it does not exist, the index will be created and the mappings derived from the entity's annotations (see <<elasticsearch.mapping>>) will be written to the newly created index. Details of the index that will be created can be set by using the `@Setting` annotation, refer to <<elasticsearc.misc.index.settings>> for further information.
 
 include::elasticsearch-repository-queries.adoc[leveloffset=+1]
 
@@ -131,7 +131,7 @@ class ProductService {
   public void setRepository(ProductRepository repository) {
     this.repository = repository;
   }
-}                
+}
 ----
 <1> Create a component by using the same calls as are used in the <<elasticsearch.operations>> chapter.
 <2> Let the CDI framework inject the Repository into your class.

Diff for: src/main/java/org/springframework/data/elasticsearch/ResourceFailureException.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 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.elasticsearch;
+
+import org.springframework.core.NestedRuntimeException;
+
+/**
+ * @author Peter-Josef Meisch
+ */
+public class ResourceFailureException extends NestedRuntimeException {
+	public ResourceFailureException(String msg) {
+		super(msg);
+	}
+
+	public ResourceFailureException(String msg, Throwable cause) {
+		super(msg, cause);
+	}
+}

Diff for: src/main/java/org/springframework/data/elasticsearch/annotations/Document.java

@@ -55,29 +55,45 @@
 
 	/**
 	 * Use server-side settings when creating the index.
+	 *
+	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
 	 */
+	@Deprecated
 	boolean useServerConfiguration() default false;
 
 	/**
 	 * Number of shards for the index {@link #indexName()}. Used for index creation. <br/>
 	 * With version 4.0, the default value is changed from 5 to 1 to reflect the change in the default settings of
 	 * Elasticsearch which changed to 1 as well in Elasticsearch 7.0.
+	 * ComposableAnnotationsUnitTest.documentAnnotationShouldBeComposable:60
+	 *
+	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
 	 */
+	@Deprecated
 	short shards() default 1;
 
 	/**
 	 * Number of replicas for the index {@link #indexName()}. Used for index creation.
+	 *
+	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
 	 */
+	@Deprecated
 	short replicas() default 1;
 
 	/**
 	 * Refresh interval for the index {@link #indexName()}. Used for index creation.
+	 *
+	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
 	 */
+	@Deprecated
 	String refreshInterval() default "1s";
 
 	/**
 	 * Index storage type for the index {@link #indexName()}. Used for index creation.
+	 *
+	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
 	 */
+	@Deprecated
 	String indexStoreType() default "fs";
 
 	/**

Diff for: src/main/java/org/springframework/data/elasticsearch/annotations/Setting.java

@@ -15,22 +15,96 @@
  */
 package org.springframework.data.elasticsearch.annotations;
 
-import java.lang.annotation.*;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 import org.springframework.data.annotation.Persistent;
 
 /**
  * Elasticsearch Setting
  *
  * @author Mohsin Husen
+ * @author Peter-Josef Meisch
  */
 
 @Persistent
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.TYPE})
+@Target({ ElementType.TYPE })
 public @interface Setting {
 
+	/**
+	 * Resource path for a settings configuration
+	 */
 	String settingPath() default "";
 
+	/**
+	 * Use server-side settings when creating the index.
+	 */
+	boolean useServerConfiguration() default false;
+
+	/**
+	 * Number of shards for the index. Used for index creation. <br/>
+	 * With version 4.0, the default value is changed from 5 to 1 to reflect the change in the default settings of
+	 * Elasticsearch which changed to 1 as well in Elasticsearch 7.0.
+	 */
+	short shards() default 1;
+
+	/**
+	 * Number of replicas for the index. Used for index creation.
+	 */
+	short replicas() default 1;
+
+	/**
+	 * Refresh interval for the index. Used for index creation.
+	 */
+	String refreshInterval() default "1s";
+
+	/**
+	 * Index storage type for the index. Used for index creation.
+	 */
+	String indexStoreType() default "fs";
+
+	/**
+	 * fields to define an index sorting
+	 *
+	 * @since 4.2
+	 */
+	String[] sortFields() default {};
+
+	/**
+	 * defines the order for {@link #sortFields()}. If present, it must have the same number of elements
+	 *
+	 * @since 4.2
+	 */
+	SortOrder[] sortOrders() default {};
+
+	/**
+	 * defines the mode for {@link #sortFields()}. If present, it must have the same number of elements
+	 *
+	 * @since 4.2
+	 */
+	SortMode[] sortModes() default {};
+
+	/**
+	 * defines the missing value for {@link #sortFields()}. If present, it must have the same number of elements
+	 *
+	 * @since 4.2
+	 */
+	SortMissing[] sortMissingValues() default {};
+
+	enum SortOrder {
+		asc, desc
+	}
+
+	enum SortMode {
+		min, max
+	}
+
+	enum SortMissing {
+		_last, _first
+	}
 }