Skip to content

Commit 094e79d

Browse files
sothawosothawo
authored
Make the new client the default.
Original Pull Request #2208 Closes #2159
1 parent 81e2613 commit 094e79d

16 files changed

+277
-184
lines changed

Diff for: ‎pom.xml

+5-1
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,14 @@
2222
<elasticsearch-rhlc>7.17.4</elasticsearch-rhlc>
2323
<!-- version of the new ElasticsearchClient -->
2424
<elasticsearch-java>8.2.3</elasticsearch-java>
25+
2526
<log4j>2.17.2</log4j>
2627
<netty>4.1.65.Final</netty>
28+
2729
<springdata.commons>3.0.0-SNAPSHOT</springdata.commons>
2830
<testcontainers>1.16.2</testcontainers>
2931
<blockhound-junit>1.0.6.RELEASE</blockhound-junit>
32+
3033
<java-module-name>spring.data.elasticsearch</java-module-name>
3134

3235
<!--
@@ -137,11 +140,12 @@
137140
<scope>test</scope>
138141
</dependency>
139142

140-
<!-- Elasticsearch RestHighLevelClient, will be removed probably in SDE 5 -->
143+
<!-- optional Elasticsearch RestHighLevelClient, deprecated in SDE 5.0 -->
141144
<dependency>
142145
<groupId>org.elasticsearch.client</groupId>
143146
<artifactId>elasticsearch-rest-high-level-client</artifactId>
144147
<version>${elasticsearch-rhlc}</version>
148+
<optional>true</optional>
145149
<exclusions>
146150
<exclusion>
147151
<groupId>commons-logging</groupId>

Diff for: ‎src/main/asciidoc/preface.adoc

+2-1
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,5 @@ built and tested.
4949
| Ingallsfootnote:oom[] | 2.1.xfootnote:oom[] | 2.4.0 | 4.3.25 | 1.5.x
5050
|===
5151

52-
Support for upcoming versions of Elasticsearch is being tracked and general compatibility should be given assuming the usage of the <<elasticsearch.clients.rest,high-level REST client>>.
52+
Support for upcoming versions of Elasticsearch is being tracked and general compatibility should be given assuming
53+
the usage of the <<elasticsearch.operations,ElasticsearchOperations interface>>.

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

+104-18
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,104 @@ This chapter illustrates configuration and usage of supported Elasticsearch clie
66
Spring Data Elasticsearch operates upon an Elasticsearch client that is connected to a single Elasticsearch node or a cluster.
77
Although the Elasticsearch Client can be used to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of <<elasticsearch.operations>> and <<elasticsearch.repositories>>.
88

9-
[[elasticsearch.clients.rest]]
10-
== High Level REST Client
9+
[[elasticsearch.clients.restclient]]
10+
== Imperative Rest Client
1111

12-
The Java High Level REST Client is the default client of Elasticsearch, it is configured like shown:
12+
To use the imperative (non-reactive) client, a configuration bean must be configured like this:
1313

14-
.High Level REST Client
1514
====
1615
[source,java]
1716
----
17+
import org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration;
18+
19+
@Configuration
20+
public class MyClientConfig extends ElasticsearchConfiguration {
21+
22+
@Override
23+
public ClientConfiguration clientConfiguration() {
24+
return ClientConfiguration.builder() //
25+
.connectedTo("localhost:9200") //
26+
.build();
27+
}
28+
}
29+
30+
// ...
31+
32+
@Autowired
33+
ElasticsearchOperations operations; <.>
34+
35+
@Autowired
36+
ElasticsearchClient elasticsearchClient; <.>
37+
38+
@Autowired
39+
RestClient restClient; <.>
40+
----
41+
the following can be injected:
42+
43+
<.> an implementation of `ElasticsearchOperations`
44+
<.> the `co.elastic.clients.elasticsearch.ElasticsearchClient` that is used. This is new Elasticsearch client
45+
implementation.
46+
<.> the low level `RestClient` from the Elasticsearch libraries
47+
====
48+
49+
Basically one should just use the `ElasticsearchOperations` to interact with the Elasticsearch cluster. When using
50+
repositories, this instance is used under the hood as well.
51+
52+
[[elasticsearch.clients.reactiverestclient]]
53+
== Reactive Rest Client
54+
55+
When working with the reactive stack, the configuration must be derived from a different class:
56+
57+
====
58+
[source,java]
59+
----
60+
import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration;
61+
62+
@Configuration
63+
public class MyClientConfig extends ElasticsearchConfiguration {
64+
65+
@Override
66+
public ClientConfiguration clientConfiguration() {
67+
return ClientConfiguration.builder() //
68+
.connectedTo("localhost:9200") //
69+
.build();
70+
}
71+
}
72+
73+
// ...
74+
75+
@Autowired
76+
ReactiveElasticsearchOperations operations; <.>
77+
78+
@Autowired
79+
ReactiveElasticsearchClient elasticsearchClient; <.>
80+
81+
@Autowired
82+
RestClient restClient; <.>
83+
----
84+
the following can be injected:
85+
86+
<.> an implementation of `ElasticsearchOperations`
87+
<.> the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient` that is used. This is based
88+
on the new Elasticsearch client implementation.
89+
<.> the low level `RestClient` from the Elasticsearch libraries
90+
====
91+
92+
Basically one should just use the `ReactiveElasticsearchOperations` to interact with the Elasticsearch cluster. When
93+
using repositories, this instance is used under the hood as well.
94+
95+
[[elasticsearch.clients.resthighlevelclient]]
96+
== High Level REST Client (deprecated)
97+
98+
The Java RestHighLevelClient is deprecated, but still can be configured like shown (read
99+
<<elasticsearch-migration-guide-4.4-5.0.old-client>> as well):
100+
101+
.RestHighLevelClient
102+
====
103+
[source,java]
104+
----
105+
import org.springframework.data.elasticsearch.client.erhlc.AbstractElasticsearchConfiguration;
106+
18107
@Configuration
19108
public class RestClientConfig extends AbstractElasticsearchConfiguration {
20109
@@ -53,16 +142,21 @@ IndexResponse response = highLevelClient.index(request,RequestOptions.DEFAULT);
53142
====
54143

55144
[[elasticsearch.clients.reactive]]
56-
== Reactive Client
145+
== Reactive Client (deprecated)
57146

58-
The `ReactiveElasticsearchClient` is a non official driver based on `WebClient`.
147+
The `org.springframework.data.elasticsearch.client.erhlc.ReactiveElasticsearchClient` is a non official driver based on `WebClient`.
59148
It uses the request/response objects provided by the Elasticsearch core project.
60149
Calls are directly operated on the reactive stack, **not** wrapping async (thread pool bound) responses into reactive types.
61150

62-
.Reactive REST Client
151+
This was the first reactive implementation Spring Data Elasticsearch provided, but now is deprecated in favour of the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient`
152+
which uses the functionality offered by the new Elasticsearch client libraries.
153+
154+
.Reactive REST Client (deprecated)
63155
====
64156
[source,java]
65157
----
158+
import org.springframework.data.elasticsearch.client.erhlc.AbstractReactiveElasticsearchConfiguration;
159+
66160
@Configuration
67161
public class ReactiveRestClientConfig extends AbstractReactiveElasticsearchConfiguration {
68162
@@ -89,8 +183,6 @@ Mono<IndexResponse> response = client.index(request ->
89183
<.> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
90184
====
91185

92-
NOTE: The ReactiveClient response, especially for search operations, is bound to the `from` (offset) & `size` (limit) options of the request.
93-
94186
[[elasticsearch.clients.configuration]]
95187
== Client Configuration
96188

@@ -118,12 +210,7 @@ ClientConfiguration clientConfiguration = ClientConfiguration.builder()
118210
return headers;
119211
})
120212
.withClientConfigurer( <.>
121-
ReactiveRestClients.WebClientConfigurationCallback.from(webClient -> {
122-
// ...
123-
return webClient;
124-
}))
125-
.withClientConfigurer( <.>
126-
RestClients.RestClientConfigurationCallback.from(clientBuilder -> {
213+
ElasticsearchClients.ElasticsearchClientConfigurationCallback.from(clientBuilder -> {
127214
// ...
128215
return clientBuilder;
129216
}))
@@ -144,16 +231,15 @@ Default is 5 sec.
144231
<.> Optionally set headers.
145232
<.> Add basic authentication.
146233
<.> A `Supplier<Header>` function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header.
147-
<.> for reactive setup a function configuring the `WebClient`
148-
<.> for non-reactive setup a function configuring the REST client
234+
<.> a function configuring the low level REST client (the same for the imperative and reactive stack)
149235
====
150236

151237
IMPORTANT: Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens.
152238
If this is used in the reactive setup, the supplier function *must not* block!
153239

154240
=== Elasticsearch 7 compatibility headers
155241

156-
When using Spring Data Elasticsearch 4 - which uses the Elasticsearch 7 client libraries - and accessing an Elasticsearch cluster that is running on version 8, it is necessary to set the compatibility headers
242+
When using the deprecated `RestHighLevelClient` and accessing an Elasticsearch cluster that is running on version 8, it is necessary to set the compatibility headers
157243
https://www.elastic.co/guide/en/elasticsearch/reference/8.0/rest-api-compatibility.html[see Elasticsearch
158244
documentation].
159245

Diff for: ‎src/main/asciidoc/reference/elasticsearch-join-types.adoc

+11-5
Original file line numberDiff line numberDiff line change
@@ -211,19 +211,25 @@ void init() {
211211

212212
== Retrieving data
213213

214-
Currently native search queries must be used to query the data, so there is no support from standard repository methods. <<repositories.custom-implementations>> can be used instead.
214+
Currently native queries must be used to query the data, so there is no support from standard repository methods. <<repositories.custom-implementations>> can be used instead.
215215

216216
The following code shows as an example how to retrieve all entries that have a _vote_ (which must be _answers_, because only answers can have a vote) using an `ElasticsearchOperations` instance:
217217

218218
====
219219
[source,java]
220220
----
221221
SearchHits<Statement> hasVotes() {
222-
NativeSearchQuery query = new NativeSearchQueryBuilder()
223-
.withQuery(hasChildQuery("vote", matchAllQuery(), ScoreMode.None))
224-
.build();
225222
226-
return operations.search(query, Statement.class);
223+
Query query = NativeQuery.builder()
224+
.withQuery(co.elastic.clients.elasticsearch._types.query_dsl.Query.of(qb -> qb //
225+
.hasChild(hc -> hc
226+
.queryName("vote") //
227+
.query(matchAllQueryAsQuery()) //
228+
.scoreMode(ChildScoreMode.None)//
229+
)))
230+
.build();
231+
232+
return operations.search(query, Statement.class);
227233
}
228234
----
229235
====

Diff for: ‎src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc

+33-53
Original file line numberDiff line numberDiff line change
@@ -32,65 +32,19 @@ using the old deprecated Elasticsearch libraries, code using the new Elasticsear
3232
independent of the client implementation. Also the reactive implementation that was provided up to now has been moved
3333
here, as this implementation contains code that was copied and adapted from Elasticsearch libraries.
3434

35+
If you are using `ElasticsearchRestTemplate` directly and not the `ElasticsearchOperations` interface you'll need to
36+
adjust your imports as well.
37+
38+
When working with the `NativeSearchQuery` class, you'll need to switch to the `NativeQuery` class, which can take a
39+
`Query` instance comign from the new Elasticsearch client libraries. You'll find plenty of examples in the test code.
3540

3641
[[elasticsearch-migration-guide-4.4-5.0.new-clients]]
3742
== New Elasticsearch client
3843

3944
Spring Data Elasticsearch now uses the new `ElasticsearchClient` and has
4045
deprecated the use of the previous `RestHighLevelClient`.
4146

42-
=== How to use the new client
43-
44-
In order to use the new client the following steps are necessary:
45-
46-
==== Add dependencies
47-
48-
The dependencies for the new Elasticsearch client are still optional in Spring Data Elasticsearch so they need to be added explicitly:
49-
50-
====
51-
[source,xml]
52-
----
53-
<dependencies>
54-
<dependency>
55-
<groupId>co.elastic.clients</groupId>
56-
<artifactId>elasticsearch-java</artifactId>
57-
<version>7.17.3</version>
58-
<exclusions>
59-
<exclusion>
60-
<groupId>commons-logging</groupId>
61-
<artifactId>commons-logging</artifactId>
62-
</exclusion>
63-
</exclusions>
64-
</dependency>
65-
<dependency>
66-
<groupId>org.elasticsearch.client</groupId>
67-
<artifactId>elasticsearch-rest-client</artifactId> <!-- is Apache 2-->
68-
<version>7.17.3</version>
69-
<exclusions>
70-
<exclusion>
71-
<groupId>commons-logging</groupId>
72-
<artifactId>commons-logging</artifactId>
73-
</exclusion>
74-
</exclusions>
75-
</dependency>
76-
</dependencies>
77-
----
78-
====
79-
80-
When using Spring Boot, it is necessary to set the following property in the _pom.xml_.
81-
82-
====
83-
[source,xml]
84-
----
85-
<properties>
86-
<jakarta-json.version>2.0.1</jakarta-json.version>
87-
</properties>
88-
----
89-
====
90-
91-
==== New configuration classes
92-
93-
===== Imperative style
47+
=== Imperative style configuration
9448

9549
To configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that
9650
derives from `org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration`:
@@ -118,7 +72,7 @@ With this configuration, the following beans will be available in the Spring app
11872
* an `ElasticsearchClient` bean, this is the new client that uses the `RestClient`
11973
* an `ElasticsearchOperations` bean, available with the bean names _elasticsearchOperations_ and _elasticsearchTemplate_, this uses the `ElasticsearchClient`
12074

121-
===== Reactive style
75+
=== Reactive style configuration
12276

12377
To use the new client in a reactive environment the only difference is the class from which to derive the configuration:
12478

@@ -143,3 +97,29 @@ With this configuration, the following beans will be available in the Spring app
14397
* a `RestClient` bean, that is the configured low level `RestClient` that is used by the Elasticsearch client
14498
* an `ReactiveElasticsearchClient` bean, this is the new reactive client that uses the `RestClient`
14599
* an `ReactiveElasticsearchOperations` bean, available with the bean names _reactiveElasticsearchOperations_ and _reactiveElasticsearchTemplate_, this uses the `ReactiveElasticsearchClient`
100+
101+
[[elasticsearch-migration-guide-4.4-5.0.old-client]]
102+
=== Still want to use the old client?
103+
104+
The old deprecated `RestHighLevelClient` can still be used, but you will need to add the dependency explicitly to
105+
your application as Spring Data Elasticsearch does not pull it in automatically anymore:
106+
107+
====
108+
[source,xml]
109+
----
110+
<!-- include the RHLC, specify version explicitly -->
111+
<dependency>
112+
<groupId>org.elasticsearch.client</groupId>
113+
<artifactId>elasticsearch-rest-high-level-client</artifactId>
114+
<version>7.17.4</version>
115+
<exclusions>
116+
<exclusion>
117+
<groupId>commons-logging</groupId>
118+
<artifactId>commons-logging</artifactId>
119+
</exclusion>
120+
</exclusions>
121+
</dependency>
122+
----
123+
====
124+
125+
Make sure to specify the version 7.17.4 explicitly, otherwise maven will resolve to 8.2.3, and this does not exist.

0 commit comments

Comments
 (0)