Skip to content

Commit e347a5f

Browse files
marko-bekhtamarko-bekhta
committed
HSEARCH-5464 Add a few notes on the new pluggable clients
1 parent ae10272 commit e347a5f

File tree

13 files changed

+461
-11
lines changed

13 files changed

+461
-11
lines changed

‎documentation/pom.xml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@
2222
<failsafe.lucene.summaryFile>${failsafe.lucene.reportsDirectory}/failsafe-summary.xml</failsafe.lucene.summaryFile>
2323
<failsafe.elasticsearch.reportsDirectory>${project.build.directory}/failsafe-reports/elasticsearch</failsafe.elasticsearch.reportsDirectory>
2424
<failsafe.elasticsearch.summaryFile>${failsafe.elasticsearch.reportsDirectory}/failsafe-summary.xml</failsafe.elasticsearch.summaryFile>
25+
<failsafe.elasticsearch.java.reportsDirectory>${project.build.directory}/failsafe-reports/elasticsearch-java</failsafe.elasticsearch.java.reportsDirectory>
26+
<failsafe.elasticsearch.java.summaryFile>${failsafe.elasticsearch.java.reportsDirectory}/failsafe-summary.xml</failsafe.elasticsearch.java.summaryFile>
27+
<failsafe.elasticsearch.opensearch.reportsDirectory>${project.build.directory}/failsafe-reports/elasticsearch-opensearch</failsafe.elasticsearch.opensearch.reportsDirectory>
28+
<failsafe.elasticsearch.opensearch.summaryFile>${failsafe.elasticsearch.opensearch.reportsDirectory}/failsafe-summary.xml</failsafe.elasticsearch.opensearch.summaryFile>
2529
<failsafe.jvm.args.jacoco.lucene></failsafe.jvm.args.jacoco.lucene>
2630
<failsafe.jvm.args.jacoco.elasticsearch></failsafe.jvm.args.jacoco.elasticsearch>
2731

@@ -61,6 +65,16 @@
6165
<artifactId>hibernate-search-backend-elasticsearch</artifactId>
6266
<scope>test</scope>
6367
</dependency>
68+
<dependency>
69+
<groupId>org.hibernate.search</groupId>
70+
<artifactId>hibernate-search-backend-elasticsearch-client-opensearch</artifactId>
71+
<scope>test</scope>
72+
</dependency>
73+
<dependency>
74+
<groupId>org.hibernate.search</groupId>
75+
<artifactId>hibernate-search-backend-elasticsearch-client-java</artifactId>
76+
<scope>test</scope>
77+
</dependency>
6478
<dependency>
6579
<groupId>${project.groupId}</groupId>
6680
<artifactId>hibernate-search-processor</artifactId>
@@ -195,15 +209,67 @@
195209
<summaryFile>${failsafe.elasticsearch.summaryFile}</summaryFile>
196210
<classpathDependencyExcludes>
197211
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-lucene</classpathDependencyExclude>
212+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch-client-java</classpathDependencyExclude>
213+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch-client-opensearch</classpathDependencyExclude>
198214
</classpathDependencyExcludes>
199215
<systemPropertyVariables>
200216
<org.hibernate.search.integrationtest.backend.type>elasticsearch</org.hibernate.search.integrationtest.backend.type>
201217
</systemPropertyVariables>
202218
<excludes>
203219
<exclude>**/Lucene*IT</exclude>
220+
<exclude>**/client/java/*IT</exclude>
221+
<exclude>**/client/opensearch/*IT</exclude>
204222
</excludes>
205223
</configuration>
206224
</execution>
225+
<execution>
226+
<id>it-elasticsearch-java</id>
227+
<goals>
228+
<goal>integration-test</goal>
229+
</goals>
230+
<configuration>
231+
<skip>${test.elasticsearch.skip}</skip>
232+
<argLine>${failsafe.jvm.args.no-jacoco} @{failsafe.jvm.args.jacoco.elasticsearch}</argLine>
233+
<reportNameSuffix>${surefire.executionIdentifier}-elasticsearch-java</reportNameSuffix>
234+
<reportsDirectory>${failsafe.elasticsearch.java.reportsDirectory}</reportsDirectory>
235+
<summaryFile>${failsafe.elasticsearch.java.summaryFile}</summaryFile>
236+
<classpathDependencyExcludes>
237+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-lucene</classpathDependencyExclude>
238+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch-client-rest</classpathDependencyExclude>
239+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch-client-opensearch</classpathDependencyExclude>
240+
</classpathDependencyExcludes>
241+
<systemPropertyVariables>
242+
<org.hibernate.search.integrationtest.backend.type>elasticsearch</org.hibernate.search.integrationtest.backend.type>
243+
</systemPropertyVariables>
244+
<includes>
245+
<include>**/client/java/*IT</include>
246+
</includes>
247+
</configuration>
248+
</execution>
249+
<execution>
250+
<id>it-elasticsearch-opensearch</id>
251+
<goals>
252+
<goal>integration-test</goal>
253+
</goals>
254+
<configuration>
255+
<skip>${test.elasticsearch.skip}</skip>
256+
<argLine>${failsafe.jvm.args.no-jacoco} @{failsafe.jvm.args.jacoco.elasticsearch}</argLine>
257+
<reportNameSuffix>${surefire.executionIdentifier}-elasticsearch-opensearch</reportNameSuffix>
258+
<reportsDirectory>${failsafe.elasticsearch.opensearch.reportsDirectory}</reportsDirectory>
259+
<summaryFile>${failsafe.elasticsearch.opensearch.summaryFile}</summaryFile>
260+
<classpathDependencyExcludes>
261+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-lucene</classpathDependencyExclude>
262+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch-client-rest</classpathDependencyExclude>
263+
<classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch-client-java</classpathDependencyExclude>
264+
</classpathDependencyExcludes>
265+
<systemPropertyVariables>
266+
<org.hibernate.search.integrationtest.backend.type>elasticsearch</org.hibernate.search.integrationtest.backend.type>
267+
</systemPropertyVariables>
268+
<includes>
269+
<include>**/client/opensearch/*IT</include>
270+
</includes>
271+
</configuration>
272+
</execution>
207273
<execution>
208274
<id>it-verify</id>
209275
<goals>
@@ -213,6 +279,8 @@
213279
<summaryFiles>
214280
<summaryFile>${failsafe.lucene.summaryFile}</summaryFile>
215281
<summaryFile>${failsafe.elasticsearch.summaryFile}</summaryFile>
282+
<summaryFile>${failsafe.elasticsearch.java.summaryFile}</summaryFile>
283+
<summaryFile>${failsafe.elasticsearch.opensearch.summaryFile}</summaryFile>
216284
</summaryFiles>
217285
</configuration>
218286
</execution>

‎documentation/src/main/asciidoc/migration/index.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,13 @@ are backward-compatible with Hibernate Search {hibernateSearchPreviousStableVers
8484
The https://hibernate.org/community/compatibility-policy/#code-categorization[API]
8585
in Hibernate Search {hibernateSearchVersion}
8686
is, in general, backward-compatible with Hibernate Search {hibernateSearchPreviousStableVersionShort}.
87+
But, there are some deprecations:
88+
89+
* `org.hibernate.search.backend.elasticsearch.client.ElasticsearchHttpClientConfigurer` is deprecated for removal.
90+
With introduction of the pluggable Elasticsearch backend clients, configurers are a part of the particular client
91+
and expose client-specific configuration knobs.
92+
* `org.hibernate.search.backend.elasticsearch.client.ElasticsearchHttpClientConfigurationContext` is also up for removal,
93+
as it's a part of the configurer API.
8794

8895
[[spi]]
8996
== SPI

‎documentation/src/main/asciidoc/public/components/elasticsearch-client-compatibility/_all.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// Copyright Red Hat Inc. and Hibernate Authors
3+
[NOTE]
4+
====
5+
Configuration properties from this section are applicable to the following clients:
6+
7+
[cols="3,2",options="header"]
8+
|===
9+
|Client |Configuration property applicability
10+
11+
|<<backend-elasticsearch-configuration-client-elasticsearch-client-rest,Elasticsearch low level client>>
12+
^| ✔
13+
14+
|<<backend-elasticsearch-configuration-client-elasticsearch-client-java,Elasticsearch Java client>>
15+
^| ✔
16+
17+
|<<backend-elasticsearch-configuration-client-elasticsearch-client-opensearch,OpenSearch low level client>>
18+
^| ✔
19+
20+
|===
21+
====

‎documentation/src/main/asciidoc/public/reference/_backend-elasticsearch.adoc‎

Lines changed: 136 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,25 @@ which needs to be enabled explicitly.
163163
== Client configuration
164164

165165
An Elasticsearch backend communicates with an Elasticsearch cluster through a REST client.
166-
Below are the options that affect this client.
166+
Hibernate Search comes with a range of pluggable Elasticsearch REST clients that the user can pick from:
167+
168+
[[backend-elasticsearch-configuration-client-elasticsearch-client-rest]]
169+
`hibernate-search-backend-elasticsearch-client-rest`::
170+
Description::: The Elasticsearch low level client based implementation (`org.elasticsearch.client:elasticsearch-rest-client`).
171+
Currently, the default REST client used by the Elasticsearch backend.
172+
Underlying HTTP Client::: Apache HTTP Client 4
173+
174+
[[backend-elasticsearch-configuration-client-elasticsearch-client-java]]
175+
`hibernate-search-backend-elasticsearch-client-java`::
176+
Description::: The Elasticsearch Java client based implementation (`co.elastic.clients:elasticsearch-java`).
177+
Underlying HTTP Client::: Apache HTTP Client 5
178+
179+
[[backend-elasticsearch-configuration-client-elasticsearch-client-opensearch]]
180+
`hibernate-search-backend-elasticsearch-client-opensearch`::
181+
Description::: The OpenSearch low level client based implementation (`org.opensearch.client:opensearch-rest-client`).
182+
Underlying HTTP Client::: Apache HTTP Client 5
183+
184+
Below are the options that affect these clients.
167185

168186
[[backend-elasticsearch-configuration-hosts]]
169187
=== Target hosts
@@ -212,6 +230,8 @@ There are some constraints regarding the use of this property:
212230
* The provided list of URIs must not be empty.
213231
====
214232

233+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
234+
215235
[[backend-elasticsearch-configuration-path-prefix]]
216236
=== Path prefix
217237

@@ -231,6 +251,8 @@ hibernate.search.backend.path_prefix = my/path
231251
With the above, a search query targeting all indexes will be sent to path `/my/path/_search` instead of `/_search`.
232252
The path will be prefixed similarly for all requests sent to Elasticsearch.
233253

254+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
255+
234256
[[backend-elasticsearch-configuration-discovery]]
235257
=== Node discovery
236258

@@ -250,6 +272,8 @@ Expects a boolean value. The default for this property is `false`.
250272
* `discovery.refresh_interval` defines the interval between two executions of the automatic discovery.
251273
Expects a positive integer, in seconds. The default for this property is `10`.
252274

275+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
276+
253277
[[backend-elasticsearch-authentication-http]]
254278
=== HTTP authentication
255279

@@ -271,6 +295,8 @@ If you use HTTP instead of HTTPS (see above),
271295
your password will be transmitted in clear text over the network.
272296
====
273297

298+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
299+
274300
[[backend-elasticsearch-configuration-aws]]
275301
=== [[elasticsearch-integration-configuration-aws]] Authentication on Amazon Web Services
276302

@@ -339,6 +365,8 @@ http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html[secre
339365
Expects a string value.
340366
This property has no default and must be provided when the credentials type is set to `static`.
341367

368+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
369+
342370
[[backend-elasticsearch-configuration-connection-tuning]]
343371
=== [[_connection_tuning]] Connection tuning
344372

@@ -362,6 +390,9 @@ The default for this property is `30000`.
362390
+
363391
These properties expect a positive <<configuration-property-types,Integer value>> in milliseconds, such as `3000`.
364392

393+
+
394+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
395+
365396
Connection pool::
366397
+
367398
[source, properties]
@@ -396,6 +427,9 @@ as those would be struggling to get a connection.
396427
To prevent that from happening consider having the maximum number of connections greater than the number of active indexing queues.
397428
====
398429

430+
+
431+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
432+
399433
Keep Alive::
400434
+
401435
[source, properties]
@@ -412,29 +446,39 @@ the duration from the `Keep-Alive` header or the value of this property (if set)
412446
+
413447
If this property is not set, only the `Keep-Alive` header is considered,
414448
and if it's absent, idle connections will be kept forever.
449+
+
450+
include::../components/elasticsearch-client-compatibility/_all.adoc[]
415451

416452
[[backend-elasticsearch-configuration-http-client]]
417453
=== [[_custom_http_client_configurations]] Custom HTTP client configurations
418454

419-
It is possible to configure the HTTP client directly
455+
Each of the pluggable REST clients allow for additional configuration of the underlying
456+
HTTP client through configurers.
457+
458+
See the following sections to learn how each of the clients can be configured.
459+
460+
[[backend-elasticsearch-configuration-http-client-elasticsearch-rest]]
461+
=== Elasticsearch low level client
462+
It is possible to directly configure the underlying Apache HTTP 4 client of the
463+
<<backend-elasticsearch-configuration-client-elasticsearch-client-rest,Elasticsearch low level client>>
420464
using an instance of `org.apache.http.impl.nio.client.HttpAsyncClientBuilder`.
421465

422466
With this API you can add interceptors, change the keep alive, the max connections,
423467
the SSL key/trust store settings and many other client configurations.
424468

425-
Configure the HTTP client directly requires two steps:
469+
Configuring the HTTP client directly requires two steps:
426470

427-
. Define a class that implements the `org.hibernate.search.backend.elasticsearch.client.ElasticsearchHttpClientConfigurer` interface.
471+
. Define a class that implements the `org.hibernate.search.backend.elasticsearch.client.rest.ElasticsearchHttpClientConfigurer` interface.
428472
. Configure Hibernate Search to use that implementation by setting the configuration property
429473
`hibernate.search.backend.client.configurer`
430474
to a <<configuration-bean-reference-parsing,bean reference>> pointing to the implementation,
431-
for example `class:org.hibernate.search.documentation.backend.elasticsearch.client.HttpClientConfigurer`.
475+
for example `class:org.hibernate.search.documentation.backend.elasticsearch.client.rest.HttpClientConfigurer`.
432476

433477
.Implementing and using a `ElasticsearchHttpClientConfigurer`
434478
====
435479
[source, java, indent=0, subs="+callouts"]
436480
----
437-
include::{sourcedir}/org/hibernate/search/documentation/backend/elasticsearch/client/HttpClientConfigurer.java[tags=include]
481+
include::{sourcedir}/org/hibernate/search/documentation/backend/elasticsearch/client/rest/HttpClientConfigurer.java[tags=include]
438482
----
439483
<1> The class has to implement the `ElasticsearchHttpClientConfigurer` interface.
440484
<2> The `configure` method provides the access to the `ElasticsearchHttpClientConfigurationContext`.
@@ -456,6 +500,92 @@ include::{resourcesdir}/configuration/http-client-configurer.properties[tags=inc
456500
Any setting defined by a custom http client configurer will override any other setting defined by Hibernate Search.
457501
====
458502

503+
[[backend-elasticsearch-configuration-http-client-elasticsearch-java]]
504+
=== Elasticsearch java client
505+
It is possible to directly configure the underlying Apache HTTP 5 client of the
506+
<<backend-elasticsearch-configuration-client-elasticsearch-client-java,Elasticsearch java client>>
507+
using an instance of `org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder`.
508+
509+
With this API you can add interceptors, change the keep alive, the max connections,
510+
the SSL key/trust store settings and many other client configurations.
511+
512+
Configuring the HTTP client directly requires two steps:
513+
514+
. Define a class that implements the `org.hibernate.search.backend.elasticsearch.client.java.ElasticsearchHttpClientConfigurer` interface.
515+
. Configure Hibernate Search to use that implementation by setting the configuration property
516+
`hibernate.search.backend.client.configurer`
517+
to a <<configuration-bean-reference-parsing,bean reference>> pointing to the implementation,
518+
for example `class:org.hibernate.search.documentation.backend.elasticsearch.client.java.HttpClientConfigurer`.
519+
520+
.Implementing and using a `ElasticsearchHttpClientConfigurer`
521+
====
522+
[source, java, indent=0, subs="+callouts"]
523+
----
524+
include::{sourcedir}/org/hibernate/search/documentation/backend/elasticsearch/client/java/HttpClientConfigurer.java[tags=include]
525+
----
526+
<1> The class has to implement the `ElasticsearchHttpClientConfigurer` interface.
527+
<2> The `configure` method provides the access to the `ElasticsearchHttpClientConfigurationContext`.
528+
<3> From the context it is possible to get the `HttpAsyncClientBuilder`.
529+
<4> Finally, you can use the builder to configure the client with your custom settings.
530+
====
531+
532+
.Define a custom http client configurer in the properties
533+
====
534+
[source, xml, indent=0, subs="+callouts"]
535+
----
536+
include::{resourcesdir}/configuration/http-client-configurer-java.properties[tags=include]
537+
----
538+
<1> Specify the HTTP client configurer.
539+
====
540+
541+
[NOTE]
542+
====
543+
Any setting defined by a custom http client configurer will override any other setting defined by Hibernate Search.
544+
====
545+
546+
[[backend-elasticsearch-configuration-http-client-elasticsearch-opensearch]]
547+
=== OpenSearch low level client
548+
It is possible to directly configure the underlying Apache HTTP 5 client of the
549+
<<backend-elasticsearch-configuration-client-elasticsearch-client-java,OpenSearch low level client>>
550+
using an instance of `org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder`.
551+
552+
With this API you can add interceptors, change the keep alive, the max connections,
553+
the SSL key/trust store settings and many other client configurations.
554+
555+
Configuring the HTTP client directly requires two steps:
556+
557+
. Define a class that implements the `org.hibernate.search.backend.elasticsearch.client.opensearch.ElasticsearchHttpClientConfigurer` interface.
558+
. Configure Hibernate Search to use that implementation by setting the configuration property
559+
`hibernate.search.backend.client.configurer`
560+
to a <<configuration-bean-reference-parsing,bean reference>> pointing to the implementation,
561+
for example `class:org.hibernate.search.documentation.backend.elasticsearch.client.opensearch.HttpClientConfigurer`.
562+
563+
.Implementing and using a `ElasticsearchHttpClientConfigurer`
564+
====
565+
[source, java, indent=0, subs="+callouts"]
566+
----
567+
include::{sourcedir}/org/hibernate/search/documentation/backend/elasticsearch/client/java/HttpClientConfigurer.java[tags=include]
568+
----
569+
<1> The class has to implement the `ElasticsearchHttpClientConfigurer` interface.
570+
<2> The `configure` method provides the access to the `ElasticsearchHttpClientConfigurationContext`.
571+
<3> From the context it is possible to get the `HttpAsyncClientBuilder`.
572+
<4> Finally, you can use the builder to configure the client with your custom settings.
573+
====
574+
575+
.Define a custom http client configurer in the properties
576+
====
577+
[source, xml, indent=0, subs="+callouts"]
578+
----
579+
include::{resourcesdir}/configuration/http-client-configurer-opensearch.properties[tags=include]
580+
----
581+
<1> Specify the HTTP client configurer.
582+
====
583+
584+
[NOTE]
585+
====
586+
Any setting defined by a custom http client configurer will override any other setting defined by Hibernate Search.
587+
====
588+
459589
[[backend-elasticsearch-configuration-version]]
460590
== [[backend-elasticsearch-configuration-dialect]] Version compatibility
461591

0 commit comments

Comments
 (0)