Skip to content

Commit 6324b72

Browse files
sothawosothawo
authored
Use the new Rest5Client as default, provide the old RestClient as optional.
Original Pull Request: #3125 Closes #3117 Signed-off-by: Peter-Josef Meisch <pj.meisch@sothawo.com>
1 parent 6e49980 commit 6324b72

25 files changed

+1654
-244
lines changed

‎pom.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@
132132
</exclusions>
133133
</dependency>
134134

135+
<!-- the old RestCLient is an optional dependency for user that still want to use it-->
135136
<dependency>
136137
<groupId>org.elasticsearch.client</groupId>
137138
<artifactId>elasticsearch-rest-client</artifactId>
@@ -142,6 +143,7 @@
142143
<artifactId>commons-logging</artifactId>
143144
</exclusion>
144145
</exclusions>
146+
<optional>true</optional>
145147
</dependency>
146148

147149
<dependency>

‎src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc

Lines changed: 181 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@ This chapter illustrates configuration and usage of supported Elasticsearch clie
66
Spring Data Elasticsearch operates upon an Elasticsearch client (provided by Elasticsearch client libraries) that is connected to a single Elasticsearch node or a cluster.
77
Although the Elasticsearch Client can be used directly to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of xref:elasticsearch/template.adoc[Elasticsearch Operations] and xref:elasticsearch/repositories/elasticsearch-repositories.adoc[Elasticsearch Repositories].
88

9-
[[elasticsearch.clients.restclient]]
10-
== Imperative Rest Client
9+
[[elasticsearch.clients.rest5client]]
10+
== Imperative Rest5Client
1111

12-
To use the imperative (non-reactive) client, a configuration bean must be configured like this:
12+
To use the imperative (non-reactive) Rest5Client, a configuration bean must be configured like this:
1313

1414
====
1515
[source,java]
@@ -31,7 +31,7 @@ public class MyClientConfig extends ElasticsearchConfiguration {
3131
<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
3232
====
3333

34-
The javadoc:org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration[]] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
34+
The javadoc:org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
3535

3636

3737
The following beans can then be injected in other Spring components:
@@ -46,7 +46,81 @@ ElasticsearchOperations operations; <.>
4646
ElasticsearchClient elasticsearchClient; <.>
4747
4848
@Autowired
49-
RestClient restClient; <.>
49+
Rest5Client rest5Client; <.>
50+
51+
@Autowired
52+
JsonpMapper jsonpMapper; <.>
53+
----
54+
55+
<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[]
56+
<.> the `co.elastic.clients.elasticsearch.ElasticsearchClient` that is used.
57+
<.> the low level `Rest5Client` from the Elasticsearch libraries
58+
<.> the `JsonpMapper` user by the Elasticsearch `Transport`
59+
====
60+
61+
Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] to interact with the Elasticsearch cluster.
62+
When using repositories, this instance is used under the hood as well.
63+
64+
[[elasticsearch.clients.restclient]]
65+
== Deprecated Imperative RestClient
66+
67+
To use the imperative (non-reactive) RestClient - deprecated since version 6 - , the following dependency needs to be added, adapt the correct version. The exclusion is needed in a Spring Boot application:
68+
====
69+
[source,xml]
70+
----
71+
<dependency>
72+
<groupId>org.elasticsearch.client</groupId>
73+
<artifactId>elasticsearch-rest-client</artifactId>
74+
<version>${elasticsearch-client.version}</version>
75+
<exclusions>
76+
<exclusion>
77+
<groupId>commons-logging</groupId>
78+
<artifactId>commons-logging</artifactId>
79+
</exclusion>
80+
</exclusions>
81+
</dependency>
82+
83+
----
84+
====
85+
86+
The configuration bean must be configured like this:
87+
88+
====
89+
[source,java]
90+
----
91+
import org.springframework.data.elasticsearch.client.elc.ElasticsearchLegacyRestClientConfiguration;
92+
93+
@Configuration
94+
public class MyClientConfig extends ElasticsearchLegacyRestClientConfiguration {
95+
96+
@Override
97+
public ClientConfiguration clientConfiguration() {
98+
return ClientConfiguration.builder() <.>
99+
.connectedTo("localhost:9200")
100+
.build();
101+
}
102+
}
103+
----
104+
105+
<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
106+
====
107+
108+
The javadoc:org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
109+
110+
111+
The following beans can then be injected in other Spring components:
112+
113+
====
114+
[source,java]
115+
----
116+
import org.springframework.beans.factory.annotation.Autowired;@Autowired
117+
ElasticsearchOperations operations; <.>
118+
119+
@Autowired
120+
ElasticsearchClient elasticsearchClient; <.>
121+
122+
@Autowired
123+
RestClient restClient; <.>
50124
51125
@Autowired
52126
JsonpMapper jsonpMapper; <.>
@@ -61,8 +135,8 @@ JsonpMapper jsonpMapper; <.>
61135
Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] to interact with the Elasticsearch cluster.
62136
When using repositories, this instance is used under the hood as well.
63137

64-
[[elasticsearch.clients.reactiverestclient]]
65-
== Reactive Rest Client
138+
[[elasticsearch.clients.reactiverest5client]]
139+
== Reactive Rest5Client
66140

67141
When working with the reactive stack, the configuration must be derived from a different class:
68142

@@ -99,6 +173,65 @@ ReactiveElasticsearchOperations operations; <.>
99173
@Autowired
100174
ReactiveElasticsearchClient elasticsearchClient; <.>
101175
176+
@Autowired
177+
Rest5Client rest5Client; <.>
178+
179+
@Autowired
180+
JsonpMapper jsonpMapper; <.>
181+
----
182+
183+
the following can be injected:
184+
185+
<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[]
186+
<.> the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient` that is used.
187+
This is a reactive implementation based on the Elasticsearch client implementation.
188+
<.> the low level `RestClient` from the Elasticsearch libraries
189+
<.> the `JsonpMapper` user by the Elasticsearch `Transport`
190+
====
191+
192+
Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[] to interact with the Elasticsearch cluster.
193+
When using repositories, this instance is used under the hood as well.
194+
195+
[[elasticsearch.clients.reactiverestclient]]
196+
== Deprecated Reactive RestClient
197+
198+
See the section above for the imperative code to use the deprecated RestClient for the necessary dependencies to include.
199+
200+
When working with the reactive stack, the configuration must be derived from a different class:
201+
202+
====
203+
[source,java]
204+
----
205+
import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchLegacyRestClientConfiguration;
206+
207+
@Configuration
208+
public class MyClientConfig extends ReactiveElasticsearchLegacyRestClientConfiguration {
209+
210+
@Override
211+
public ClientConfiguration clientConfiguration() {
212+
return ClientConfiguration.builder() <.>
213+
.connectedTo("localhost:9200")
214+
.build();
215+
}
216+
}
217+
----
218+
219+
<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
220+
====
221+
222+
The javadoc:org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
223+
224+
The following beans can then be injected in other Spring components:
225+
226+
====
227+
[source,java]
228+
----
229+
@Autowired
230+
ReactiveElasticsearchOperations operations; <.>
231+
232+
@Autowired
233+
ReactiveElasticsearchClient elasticsearchClient; <.>
234+
102235
@Autowired
103236
RestClient restClient; <.>
104237
@@ -183,8 +316,25 @@ In the case this is not enough, the user can add callback functions by using the
183316

184317
The following callbacks are provided:
185318

319+
[[elasticsearch.clients.configuration.callbacks.rest5]]
320+
==== Configuration of the low level Elasticsearch `Rest5Client`:
321+
322+
This callback provides a `org.elasticsearch.client.RestClientBuilder` that can be used to configure the Elasticsearch
323+
`RestClient`:
324+
====
325+
[source,java]
326+
----
327+
ClientConfiguration.builder()
328+
.connectedTo("localhost:9200", "localhost:9291")
329+
.withClientConfigurer(Rest5Clients.ElasticsearchRest5ClientConfigurationCallback.from(restClientBuilder -> {
330+
// configure the Elasticsearch Rest5Client
331+
return restClientBuilder;
332+
}))
333+
.build();
334+
----
335+
====
186336
[[elasticsearch.clients.configuration.callbacks.rest]]
187-
==== Configuration of the low level Elasticsearch `RestClient`:
337+
==== Configuration of the deprecated low level Elasticsearch `RestClient`:
188338

189339
This callback provides a `org.elasticsearch.client.RestClientBuilder` that can be used to configure the Elasticsearch
190340
`RestClient`:
@@ -193,26 +343,45 @@ This callback provides a `org.elasticsearch.client.RestClientBuilder` that can b
193343
----
194344
ClientConfiguration.builder()
195345
.connectedTo("localhost:9200", "localhost:9291")
196-
.withClientConfigurer(ElasticsearchClients.ElasticsearchRestClientConfigurationCallback.from(restClientBuilder -> {
346+
.withClientConfigurer(RestClients.ElasticsearchRestClientConfigurationCallback.from(restClientBuilder -> {
197347
// configure the Elasticsearch RestClient
198348
return restClientBuilder;
199349
}))
200350
.build();
201351
----
202352
====
203353

354+
[[elasticsearch.clients.configurationcallbacks.httpasync5]]
355+
==== Configuration of the HttpAsyncClient used by the low level Elasticsearch `Rest5Client`:
356+
357+
This callback provides a `org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder` to configure the HttpClient that is
358+
used by the `Rest5Client`.
359+
360+
====
361+
[source,java]
362+
----
363+
ClientConfiguration.builder()
364+
.connectedTo("localhost:9200", "localhost:9291")
365+
.withClientConfigurer(Rest5Clients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
366+
// configure the HttpAsyncClient
367+
return httpAsyncClientBuilder;
368+
}))
369+
.build();
370+
----
371+
====
372+
204373
[[elasticsearch.clients.configurationcallbacks.httpasync]]
205-
==== Configuration of the HttpAsyncClient used by the low level Elasticsearch `RestClient`:
374+
==== Configuration of the HttpAsyncClient used by the deprecated low level Elasticsearch `RestClient`:
206375

207-
This callback provides a `org.apache.http.impl.nio.client.HttpAsyncClientBuilder` to configure the HttpCLient that is
376+
This callback provides a `org.apache.http.impl.nio.client.HttpAsyncClientBuilder` to configure the HttpClient that is
208377
used by the `RestClient`.
209378

210379
====
211380
[source,java]
212381
----
213382
ClientConfiguration.builder()
214383
.connectedTo("localhost:9200", "localhost:9291")
215-
.withClientConfigurer(ElasticsearchClients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
384+
.withClientConfigurer(RestClients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
216385
// configure the HttpAsyncClient
217386
return httpAsyncClientBuilder;
218387
}))

‎src/main/antora/modules/ROOT/pages/elasticsearch/elasticsearch-new.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
* Upgarde to Spring 7
88
* Switch to jspecify nullability annotations
99
* Upgrade to Elasticsearch 9.0.3
10+
* Use the new Elasticsearch Rest5Client as default
1011

1112

1213
[[new-features.5-5-0]]

‎src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.5-6.0.adoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@ This section describes breaking changes from version 5.5.x to 6.0.x and how remo
66
[[elasticsearch-migration-guide-5.5-6.0.breaking-changes]]
77
== Breaking Changes
88

9+
From version 6.0 on, Spring Data Elasticsearch uses the Elasticsearch 9 libraries and as default the new `Rest5Client` provided by these libraries. It is still possible to use the old `RestClient`, check xref:elasticsearch/clients.adoc[Elasticsearch clients] for information. The configuration callbacks for this `RestClient` have been moved from `org.springframework.data.elasticsearch.client.elc.ElasticsearchClients` to the `org.springframework.data.elasticsearch.client.elc.rest_client.RestClients` class.
10+
911
[[elasticsearch-migration-guide-5.5-6.0.deprecations]]
1012
== Deprecations
1113

14+
All the code using the old `RestClient` has been moved to the `org.springframework.data.elasticsearch.client.elc.rest_client` package and has been deprecated. Users should switch to the classes from the `org.springframework.data.elasticsearch.client.elc.rest5_client` package.
15+
1216

1317
=== Removals
1418

‎src/main/java/org/springframework/data/elasticsearch/client/ClientConfiguration.java

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,10 +127,16 @@ static ClientConfiguration create(InetSocketAddress socketAddress) {
127127
Optional<String> getCaFingerprint();
128128

129129
/**
130-
* Returns the {@link HostnameVerifier} to use. Can be {@link Optional#empty()} if not configured.
130+
* Returns the {@link HostnameVerifier} to use. Must be {@link Optional#empty()} if not configured.
131+
* Cannot be used with the Rest5Client used from Elasticsearch 9 on as the underlying Apache http components 5 does not offer a way
132+
* to set this. Users that need a hostname verifier must integrate this in a SSLContext.
133+
* Returning a value here is ignored in this case
131134
*
132135
* @return the {@link HostnameVerifier} to use. Can be {@link Optional#empty()} if not configured.
136+
* @deprecated since 6.0
133137
*/
138+
// todo #3117 document this
139+
@Deprecated(since = "6.0", forRemoval=true)
134140
Optional<HostnameVerifier> getHostNameVerifier();
135141

136142
/**

0 commit comments

Comments
 (0)