Skip to content

Commit 1ea73d2

Browse files
christophstroblchristophstrobl
committed
DATAES-504 - Update documentation.
Update documentation to cover newly added configuration options for the ReactiveElasticsearchClient. Make sure to apply postFilter correctly and set a default limit for unpaged search requests. Also fix some code format issues.
1 parent 2dcd1cf commit 1ea73d2

14 files changed

+221
-74
lines changed

‎src/main/asciidoc/reference/elasticsearch-clients.adoc

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,3 +81,43 @@ Mono<IndexResponse> response = client.index(request ->
8181
<1> Use the builder to provide cluster addresses, set default `HttpHeaders` or enbale SSL.
8282
====
8383

84+
NOTE: The ReactiveClient response, especially for search operations, is bound to the `from` (offset) & `size` (limit) options of the request.
85+
86+
[[elasticsearch.clients.configuration]]
87+
== Client Configuration
88+
89+
Client behaviour can be changed via the `ClientConfiguration` that allows to set options for SSL, connect and socket timeouts.
90+
91+
.Client Configuration
92+
====
93+
[source,java]
94+
----
95+
96+
ClientConfiguration clientConfiguration = ClientConfiguration.builder()
97+
.connectedTo("localhost:9200", "localhost:9291") <1>
98+
.withConnectTimeout(Duration.ofSeconds(5)) <2>
99+
.withSocketTimeout(Duration.ofSeconds(3)) <3>
100+
.useSsl()
101+
. // ... other options
102+
.build();
103+
104+
----
105+
<1> Use the builder to provide cluster addresses, set default `HttpHeaders` or enbale SSL.
106+
<2> Set the connection timeout. Default is 10 sec.
107+
<3> Set the socket timeout. Default is 5 sec.
108+
====
109+
110+
[[elasticsearch.clients.logging]]
111+
== Client Logging
112+
113+
To see what is actually sent to and received from the server `Request` / `Response` logging on the transport level needs
114+
to be turned on as outlined in the snippet below.
115+
116+
.Enable transport layer logging
117+
[source,xml]
118+
----
119+
<logger name="org.springframework.data.elasticsearch.client.WIRE" level="trace"/>
120+
----
121+
122+
NOTE: The above applies to both the `RestHighLevelClient` and `ReactiveElasticsearchClient` when obtained via `RestClients`
123+
respectively `ReactiveRestClients`.

‎src/main/asciidoc/reference/reactive-elasticsearch-operations.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ public class Config extends AbstractReactiveElasticsearchConfiguration {
3838
<1> Configure the client to use. This can be done by `ReactiveRestClients` or directly via `DefaultReactiveElasticsearchClient`.
3939
====
4040

41-
NOTE: If applicable set default `HttpHeaders` via the `ClientConfiguration` of the `ReactiveElasticsearchClient`.
41+
NOTE: If applicable set default `HttpHeaders` via the `ClientConfiguration` of the `ReactiveElasticsearchClient`. See <<elasticsearch.clients.configuration>>.
4242

4343
TIP: If needed the `ReactiveElasticsearchTemplate` can be configured with default `RefreshPolicy` and `IndicesOptions` that get applied to the related requests by overriding the defaults of `refreshPolicy()` and `indicesOptions()`.
4444

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

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -198,26 +198,48 @@ interface TerminalClientConfigurationBuilder {
198198
*/
199199
TerminalClientConfigurationBuilder withDefaultHeaders(HttpHeaders defaultHeaders);
200200

201+
/**
202+
* Configure the {@literal milliseconds} for the connect timeout.
203+
*
204+
* @param millis the timeout to use.
205+
* @return the {@link TerminalClientConfigurationBuilder}
206+
* @see #withConnectTimeout(Duration)
207+
*/
208+
default TerminalClientConfigurationBuilder withConnectTimeout(long millis) {
209+
return withConnectTimeout(Duration.ofMillis(millis));
210+
}
211+
201212
/**
202213
* Configure a {@link java.time.Duration} connect timeout.
203214
*
204-
* @param connectTimeout the timeout to use.
215+
* @param timeout the timeout to use. Must not be {@literal null}.
205216
* @return the {@link TerminalClientConfigurationBuilder}
206217
* @see java.net.Socket#connect(SocketAddress, int)
207218
* @see io.netty.channel.ChannelOption#CONNECT_TIMEOUT_MILLIS
208219
*/
209-
TerminalClientConfigurationBuilder withConnectTimeout(Duration connectTimeout);
220+
TerminalClientConfigurationBuilder withConnectTimeout(Duration timeout);
221+
222+
/**
223+
* Configure the {@literal milliseconds} for the socket timeout.
224+
*
225+
* @param millis the timeout to use.
226+
* @return the {@link TerminalClientConfigurationBuilder}
227+
* @see #withSocketTimeout(Duration)
228+
*/
229+
default TerminalClientConfigurationBuilder withSocketTimeout(long millis) {
230+
return withSocketTimeout(Duration.ofMillis(millis));
231+
}
210232

211233
/**
212234
* Configure a {@link java.time.Duration socket timeout} which is typically applied as SO-timeout/read timeout.
213235
*
214-
* @param soTimeout the timeout to use.
236+
* @param timeout the timeout to use. Must not be {@literal null}.
215237
* @return the {@link TerminalClientConfigurationBuilder}
216238
* @see java.net.Socket#setSoTimeout(int)
217239
* @see io.netty.handler.timeout.ReadTimeoutHandler
218240
* @see io.netty.handler.timeout.WriteTimeoutHandler
219241
*/
220-
TerminalClientConfigurationBuilder withSocketTimeout(Duration soTimeout);
242+
TerminalClientConfigurationBuilder withSocketTimeout(Duration timeout);
221243

222244
/**
223245
* Build the {@link ClientConfiguration} object.

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -118,11 +118,11 @@ public TerminalClientConfigurationBuilder withDefaultHeaders(HttpHeaders default
118118
* @see org.springframework.data.elasticsearch.client.ClientConfiguration.TerminalClientConfigurationBuilder#withConnectTimeout(java.time.Duration)
119119
*/
120120
@Override
121-
public TerminalClientConfigurationBuilder withConnectTimeout(Duration connectTimeout) {
121+
public TerminalClientConfigurationBuilder withConnectTimeout(Duration timeout) {
122122

123-
Assert.notNull(connectTimeout, "I/O timeout must not be null!");
123+
Assert.notNull(timeout, "I/O timeout must not be null!");
124124

125-
this.connectTimeout = connectTimeout;
125+
this.connectTimeout = timeout;
126126
return this;
127127
}
128128

@@ -131,11 +131,11 @@ public TerminalClientConfigurationBuilder withConnectTimeout(Duration connectTim
131131
* @see org.springframework.data.elasticsearch.client.ClientConfiguration.TerminalClientConfigurationBuilder#withTimeout(java.time.Duration)
132132
*/
133133
@Override
134-
public TerminalClientConfigurationBuilder withSocketTimeout(Duration soTimeout) {
134+
public TerminalClientConfigurationBuilder withSocketTimeout(Duration timeout) {
135135

136-
Assert.notNull(soTimeout, "Socket timeout must not be null!");
136+
Assert.notNull(timeout, "Socket timeout must not be null!");
137137

138-
this.soTimeout = soTimeout;
138+
this.soTimeout = timeout;
139139
return this;
140140
}
141141

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

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
* level.
2929
*
3030
* @author Mark Paluch
31+
* @author Christoph Strobl
3132
* @since 4.0
3233
*/
3334
public abstract class ClientLogger {
@@ -57,7 +58,8 @@ public static boolean isEnabled() {
5758
*/
5859
public static void logRequest(String logId, String method, String endpoint, Object parameters) {
5960

60-
if (WIRE_LOGGER.isTraceEnabled()) {
61+
if (isEnabled()) {
62+
6163
WIRE_LOGGER.trace("[{}] Sending request {} {} with parameters: {}", logId, method.toUpperCase(), endpoint,
6264
parameters);
6365
}
@@ -75,7 +77,8 @@ public static void logRequest(String logId, String method, String endpoint, Obje
7577
public static void logRequest(String logId, String method, String endpoint, Object parameters,
7678
Supplier<Object> body) {
7779

78-
if (WIRE_LOGGER.isTraceEnabled()) {
80+
if (isEnabled()) {
81+
7982
WIRE_LOGGER.trace("[{}] Sending request {} {} with parameters: {}{}Request body: {}", logId, method.toUpperCase(),
8083
endpoint, parameters, lineSeparator, body.get());
8184
}
@@ -89,7 +92,7 @@ public static void logRequest(String logId, String method, String endpoint, Obje
8992
*/
9093
public static void logRawResponse(String logId, HttpStatus statusCode) {
9194

92-
if (WIRE_LOGGER.isTraceEnabled()) {
95+
if (isEnabled()) {
9396
WIRE_LOGGER.trace("[{}] Received raw response: ", logId, statusCode);
9497
}
9598
}
@@ -103,7 +106,7 @@ public static void logRawResponse(String logId, HttpStatus statusCode) {
103106
*/
104107
public static void logResponse(String logId, HttpStatus statusCode, String body) {
105108

106-
if (WIRE_LOGGER.isTraceEnabled()) {
109+
if (isEnabled()) {
107110
WIRE_LOGGER.trace("[{}] Received response: {}{}Response body: {}", logId, statusCode, lineSeparator, body);
108111
}
109112
}
@@ -114,6 +117,11 @@ public static void logResponse(String logId, HttpStatus statusCode, String body)
114117
* @return a new, unique correlation Id.
115118
*/
116119
public static String newLogId() {
120+
121+
if (!isEnabled()) {
122+
return "-";
123+
}
124+
117125
return ObjectUtils.getIdentityHexString(new Object());
118126
}
119127
}

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
* Default {@link ClientConfiguration} implementation.
3232
*
3333
* @author Mark Paluch
34+
* @author Christoph Strobl
3435
* @since 4.0
3536
*/
3637
class DefaultClientConfiguration implements ClientConfiguration {
@@ -90,9 +91,9 @@ public Optional<SSLContext> getSslContext() {
9091
}
9192

9293
/*
93-
* (non-Javadoc)
94-
* @see org.springframework.data.elasticsearch.client.ClientConfiguration#getConnectTimeout()
95-
*/
94+
* (non-Javadoc)
95+
* @see org.springframework.data.elasticsearch.client.ClientConfiguration#getConnectTimeout()
96+
*/
9697
@Override
9798
public Duration getConnectTimeout() {
9899
return this.connectTimeout;

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

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -85,19 +85,25 @@ public static ElasticsearchRestClient create(ClientConfiguration clientConfigura
8585
}
8686

8787
builder.setHttpClientConfigCallback(clientBuilder -> {
88+
8889
Optional<SSLContext> sslContext = clientConfiguration.getSslContext();
8990
sslContext.ifPresent(clientBuilder::setSSLContext);
9091

9192
if (ClientLogger.isEnabled()) {
92-
clientBuilder.addInterceptorLast((HttpRequestInterceptor) LoggingInterceptors.INSTANCE);
93-
clientBuilder.addInterceptorLast((HttpResponseInterceptor) LoggingInterceptors.INSTANCE);
93+
94+
HttpLoggingInterceptor interceptor = new HttpLoggingInterceptor();
95+
96+
clientBuilder.addInterceptorLast((HttpRequestInterceptor) interceptor);
97+
clientBuilder.addInterceptorLast((HttpResponseInterceptor) interceptor);
9498
}
9599

96100
Duration connectTimeout = clientConfiguration.getConnectTimeout();
97101
Duration timeout = clientConfiguration.getSocketTimeout();
98102

99103
Builder requestConfigBuilder = RequestConfig.custom();
104+
100105
if (!connectTimeout.isNegative()) {
106+
101107
requestConfigBuilder.setConnectTimeout(Math.toIntExact(connectTimeout.toMillis()));
102108
requestConfigBuilder.setConnectionRequestTimeout(Math.toIntExact(connectTimeout.toMillis()));
103109
}
@@ -151,16 +157,17 @@ default void close() throws IOException {
151157
* Logging interceptors for Elasticsearch client logging.
152158
*
153159
* @see ClientLogger
160+
* @since 4.0
154161
*/
155-
enum LoggingInterceptors implements HttpResponseInterceptor, HttpRequestInterceptor {
156-
157-
INSTANCE;
162+
private static class HttpLoggingInterceptor implements HttpResponseInterceptor, HttpRequestInterceptor {
158163

159164
@Override
160165
public void process(HttpRequest request, HttpContext context) throws IOException {
161166

162167
String logId = (String) context.getAttribute(RestClients.LOG_ID_ATTRIBUTE);
168+
163169
if (logId == null) {
170+
164171
logId = ClientLogger.newLogId();
165172
context.setAttribute(RestClients.LOG_ID_ATTRIBUTE, logId);
166173
}

‎src/main/java/org/springframework/data/elasticsearch/client/reactive/DefaultReactiveElasticsearchClient.java

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -156,20 +156,20 @@ public static ReactiveElasticsearchClient create(ClientConfiguration clientConfi
156156

157157
private static WebClientProvider getWebClientProvider(ClientConfiguration clientConfiguration) {
158158

159-
WebClientProvider provider;
159+
Duration connectTimeout = clientConfiguration.getConnectTimeout();
160+
Duration soTimeout = clientConfiguration.getSocketTimeout();
160161

161162
TcpClient tcpClient = TcpClient.create();
162-
Duration connectTimeout = clientConfiguration.getConnectTimeout();
163-
Duration timeout = clientConfiguration.getSocketTimeout();
164163

165164
if (!connectTimeout.isNegative()) {
166165
tcpClient = tcpClient.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, Math.toIntExact(connectTimeout.toMillis()));
167166
}
168167

169-
if (!timeout.isNegative()) {
168+
if (!soTimeout.isNegative()) {
169+
170170
tcpClient = tcpClient.doOnConnected(connection -> connection //
171-
.addHandlerLast(new ReadTimeoutHandler(timeout.toMillis(), TimeUnit.MILLISECONDS))
172-
.addHandlerLast(new WriteTimeoutHandler(timeout.toMillis(), TimeUnit.MILLISECONDS)));
171+
.addHandlerLast(new ReadTimeoutHandler(soTimeout.toMillis(), TimeUnit.MILLISECONDS))
172+
.addHandlerLast(new WriteTimeoutHandler(soTimeout.toMillis(), TimeUnit.MILLISECONDS)));
173173
}
174174

175175
String scheme = "http";
@@ -187,7 +187,7 @@ private static WebClientProvider getWebClientProvider(ClientConfiguration client
187187
}
188188

189189
ReactorClientHttpConnector connector = new ReactorClientHttpConnector(httpClient);
190-
provider = WebClientProvider.create(scheme, connector);
190+
WebClientProvider provider = WebClientProvider.create(scheme, connector);
191191

192192
return provider.withDefaultHeaders(clientConfiguration.getDefaultHeaders());
193193
}
@@ -370,6 +370,7 @@ private Mono<ClientResponse> sendRequest(WebClient webClient, String logId, Requ
370370

371371
ClientLogger.logRequest(logId, request.getMethod().toUpperCase(), request.getEndpoint(), request.getParameters(),
372372
body::get);
373+
373374
requestBodySpec.contentType(MediaType.valueOf(request.getEntity().getContentType().getValue()));
374375
requestBodySpec.body(Mono.fromSupplier(body::get), String.class);
375376
} else {
@@ -397,21 +398,21 @@ private <T> Publisher<? extends T> readResponseBody(String logId, Request reques
397398
Class<T> responseType) {
398399

399400
if (RawActionResponse.class.equals(responseType)) {
400-
ClientLogger.logRawResponse(logId, response.statusCode());
401401

402+
ClientLogger.logRawResponse(logId, response.statusCode());
402403
return Mono.just(responseType.cast(RawActionResponse.create(response)));
403404
}
404405

405406
if (response.statusCode().is5xxServerError()) {
407+
406408
ClientLogger.logRawResponse(logId, response.statusCode());
407409
return handleServerError(request, response);
408410
}
409411

410412
return response.body(BodyExtractors.toMono(byte[].class)) //
411413
.map(it -> new String(it, StandardCharsets.UTF_8)) //
412-
.doOnNext(it -> {
413-
ClientLogger.logResponse(logId, response.statusCode(), it);
414-
}).flatMap(content -> doDecode(response, responseType, content));
414+
.doOnNext(it -> ClientLogger.logResponse(logId, response.statusCode(), it)) //
415+
.flatMap(content -> doDecode(response, responseType, content));
415416
}
416417

417418
private static <T> Mono<T> doDecode(ClientResponse response, Class<T> responseType, String content) {
@@ -435,7 +436,6 @@ private static <T> Mono<T> doDecode(ClientResponse response, Class<T> responseTy
435436
.error(new ElasticsearchStatusException(content, RestStatus.fromCode(response.statusCode().value())));
436437
}
437438
}
438-
439439
}
440440

441441
private static XContentParser createParser(String mediaType, String content) throws IOException {
@@ -446,6 +446,7 @@ private static XContentParser createParser(String mediaType, String content) thr
446446
}
447447

448448
private static <T> Publisher<? extends T> handleServerError(Request request, ClientResponse response) {
449+
449450
return Mono.error(
450451
new HttpServerErrorException(response.statusCode(), String.format("%s request to %s returned error code %s.",
451452
request.getMethod(), request.getEndpoint(), response.statusCode().value())));

0 commit comments

Comments
 (0)