diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java index 5b02ec6b35c..8329712c91f 100644 --- a/client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java @@ -58,10 +58,10 @@ import org.elasticsearch.action.update.UpdateRequest; import org.elasticsearch.action.update.UpdateResponse; import org.elasticsearch.client.core.CountRequest; import org.elasticsearch.client.core.CountResponse; -import org.elasticsearch.client.core.TermVectorsResponse; -import org.elasticsearch.client.core.TermVectorsRequest; import org.elasticsearch.client.core.MultiTermVectorsRequest; import org.elasticsearch.client.core.MultiTermVectorsResponse; +import org.elasticsearch.client.core.TermVectorsRequest; +import org.elasticsearch.client.core.TermVectorsResponse; import org.elasticsearch.client.tasks.TaskSubmissionResponse; import org.elasticsearch.common.CheckedConsumer; import org.elasticsearch.common.CheckedFunction; @@ -139,6 +139,7 @@ import org.elasticsearch.search.aggregations.metrics.InternalHDRPercentiles; import org.elasticsearch.search.aggregations.metrics.InternalTDigestPercentileRanks; import org.elasticsearch.search.aggregations.metrics.InternalTDigestPercentiles; import org.elasticsearch.search.aggregations.metrics.MaxAggregationBuilder; +import org.elasticsearch.search.aggregations.metrics.MedianAbsoluteDeviationAggregationBuilder; import org.elasticsearch.search.aggregations.metrics.MinAggregationBuilder; import org.elasticsearch.search.aggregations.metrics.ParsedAvg; import org.elasticsearch.search.aggregations.metrics.ParsedCardinality; @@ -148,6 +149,7 @@ import org.elasticsearch.search.aggregations.metrics.ParsedGeoCentroid; import org.elasticsearch.search.aggregations.metrics.ParsedHDRPercentileRanks; import org.elasticsearch.search.aggregations.metrics.ParsedHDRPercentiles; import org.elasticsearch.search.aggregations.metrics.ParsedMax; +import org.elasticsearch.search.aggregations.metrics.ParsedMedianAbsoluteDeviation; import org.elasticsearch.search.aggregations.metrics.ParsedMin; import org.elasticsearch.search.aggregations.metrics.ParsedScriptedMetric; import org.elasticsearch.search.aggregations.metrics.ParsedStats; @@ -161,20 +163,18 @@ import org.elasticsearch.search.aggregations.metrics.StatsAggregationBuilder; import org.elasticsearch.search.aggregations.metrics.SumAggregationBuilder; import org.elasticsearch.search.aggregations.metrics.TopHitsAggregationBuilder; import org.elasticsearch.search.aggregations.metrics.ValueCountAggregationBuilder; -import org.elasticsearch.search.aggregations.metrics.MedianAbsoluteDeviationAggregationBuilder; -import org.elasticsearch.search.aggregations.metrics.ParsedMedianAbsoluteDeviation; -import org.elasticsearch.search.aggregations.pipeline.InternalSimpleValue; -import org.elasticsearch.search.aggregations.pipeline.ParsedSimpleValue; -import org.elasticsearch.search.aggregations.pipeline.InternalBucketMetricValue; -import org.elasticsearch.search.aggregations.pipeline.ParsedBucketMetricValue; -import org.elasticsearch.search.aggregations.pipeline.ParsedPercentilesBucket; -import org.elasticsearch.search.aggregations.pipeline.PercentilesBucketPipelineAggregationBuilder; -import org.elasticsearch.search.aggregations.pipeline.ParsedStatsBucket; -import org.elasticsearch.search.aggregations.pipeline.StatsBucketPipelineAggregationBuilder; -import org.elasticsearch.search.aggregations.pipeline.ExtendedStatsBucketPipelineAggregationBuilder; -import org.elasticsearch.search.aggregations.pipeline.ParsedExtendedStatsBucket; import org.elasticsearch.search.aggregations.pipeline.DerivativePipelineAggregationBuilder; +import org.elasticsearch.search.aggregations.pipeline.ExtendedStatsBucketPipelineAggregationBuilder; +import org.elasticsearch.search.aggregations.pipeline.InternalBucketMetricValue; +import org.elasticsearch.search.aggregations.pipeline.InternalSimpleValue; +import org.elasticsearch.search.aggregations.pipeline.ParsedBucketMetricValue; import org.elasticsearch.search.aggregations.pipeline.ParsedDerivative; +import org.elasticsearch.search.aggregations.pipeline.ParsedExtendedStatsBucket; +import org.elasticsearch.search.aggregations.pipeline.ParsedPercentilesBucket; +import org.elasticsearch.search.aggregations.pipeline.ParsedSimpleValue; +import org.elasticsearch.search.aggregations.pipeline.ParsedStatsBucket; +import org.elasticsearch.search.aggregations.pipeline.PercentilesBucketPipelineAggregationBuilder; +import org.elasticsearch.search.aggregations.pipeline.StatsBucketPipelineAggregationBuilder; import org.elasticsearch.search.suggest.Suggest; import org.elasticsearch.search.suggest.completion.CompletionSuggestion; import org.elasticsearch.search.suggest.completion.CompletionSuggestionBuilder; @@ -203,13 +203,33 @@ import static java.util.Collections.singleton; import static java.util.stream.Collectors.toList; /** - * High level REST client that wraps an instance of the low level {@link RestClient} and allows to build requests and read responses. - * The {@link RestClient} instance is internally built based on the provided {@link RestClientBuilder} and it gets closed automatically - * when closing the {@link RestHighLevelClient} instance that wraps it. + * High level REST client that wraps an instance of the low level {@link RestClient} and allows to build requests and read responses. The + * {@link RestClient} instance is internally built based on the provided {@link RestClientBuilder} and it gets closed automatically when + * closing the {@link RestHighLevelClient} instance that wraps it. + *

+ * * In case an already existing instance of a low-level REST client needs to be provided, this class can be subclassed and the - * {@link #RestHighLevelClient(RestClient, CheckedConsumer, List)} constructor can be used. - * This class can also be sub-classed to expose additional client methods that make use of endpoints added to Elasticsearch through - * plugins, or to add support for custom response sections, again added to Elasticsearch through plugins. + * {@link #RestHighLevelClient(RestClient, CheckedConsumer, List)} constructor can be used. + *

+ * + * This class can also be sub-classed to expose additional client methods that make use of endpoints added to Elasticsearch through plugins, + * or to add support for custom response sections, again added to Elasticsearch through plugins. + *

+ * + * The majority of the methods in this class come in two flavors, a blocking and an asynchronous version (e.g. + * {@link #search(SearchRequest, RequestOptions)} and {@link #searchAsync(SearchRequest, RequestOptions, ActionListener)}, where the later + * takes an implementation of an {@link ActionListener} as an argument that needs to implement methods that handle successful responses and + * failure scenarios. Most of the blocking calls can throw an {@link IOException} or an unchecked {@link ElasticsearchException} in the + * following cases: + * + *

+ * */ public class RestHighLevelClient implements Closeable { @@ -448,7 +468,6 @@ public class RestHighLevelClient implements Closeable { * @param bulkRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final BulkResponse bulk(BulkRequest bulkRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(bulkRequest, RequestConverters::bulk, options, BulkResponse::fromXContent, emptySet()); @@ -471,7 +490,6 @@ public class RestHighLevelClient implements Closeable { * @param reindexRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final BulkByScrollResponse reindex(ReindexRequest reindexRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity( @@ -485,7 +503,6 @@ public class RestHighLevelClient implements Closeable { * @param reindexRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the submission response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final TaskSubmissionResponse submitReindexTask(ReindexRequest reindexRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity( @@ -513,7 +530,6 @@ public class RestHighLevelClient implements Closeable { * @param updateByQueryRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final BulkByScrollResponse updateByQuery(UpdateByQueryRequest updateByQueryRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity( @@ -543,7 +559,6 @@ public class RestHighLevelClient implements Closeable { * @param deleteByQueryRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final BulkByScrollResponse deleteByQuery(DeleteByQueryRequest deleteByQueryRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity( @@ -573,7 +588,6 @@ public class RestHighLevelClient implements Closeable { * @param rethrottleRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final ListTasksResponse deleteByQueryRethrottle(RethrottleRequest rethrottleRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(rethrottleRequest, RequestConverters::rethrottleDeleteByQuery, options, @@ -601,7 +615,6 @@ public class RestHighLevelClient implements Closeable { * @param rethrottleRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final ListTasksResponse updateByQueryRethrottle(RethrottleRequest rethrottleRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(rethrottleRequest, RequestConverters::rethrottleUpdateByQuery, options, @@ -630,7 +643,6 @@ public class RestHighLevelClient implements Closeable { * @param rethrottleRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final ListTasksResponse reindexRethrottle(RethrottleRequest rethrottleRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(rethrottleRequest, RequestConverters::rethrottleReindex, options, @@ -656,7 +668,6 @@ public class RestHighLevelClient implements Closeable { * Pings the remote Elasticsearch cluster and returns true if the ping succeeded, false otherwise * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return true if the ping succeeded, false otherwise - * @throws IOException in case there is a problem sending the request */ public final boolean ping(RequestOptions options) throws IOException { return performRequest(new MainRequest(), (request) -> RequestConverters.ping(), options, RestHighLevelClient::convertExistsResponse, @@ -667,7 +678,6 @@ public class RestHighLevelClient implements Closeable { * Get the cluster info otherwise provided when sending an HTTP request to '/' * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final MainResponse info(RequestOptions options) throws IOException { return performRequestAndParseEntity(new MainRequest(), (request) -> RequestConverters.info(), options, @@ -680,7 +690,6 @@ public class RestHighLevelClient implements Closeable { * @param getRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final GetResponse get(GetRequest getRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(getRequest, RequestConverters::get, options, GetResponse::fromXContent, singleton(404)); @@ -704,7 +713,6 @@ public class RestHighLevelClient implements Closeable { * @param multiGetRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response * @deprecated use {@link #mget(MultiGetRequest, RequestOptions)} instead */ @Deprecated @@ -719,7 +727,6 @@ public class RestHighLevelClient implements Closeable { * @param multiGetRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final MultiGetResponse mget(MultiGetRequest multiGetRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(multiGetRequest, RequestConverters::multiGet, options, MultiGetResponse::fromXContent, @@ -757,7 +764,6 @@ public class RestHighLevelClient implements Closeable { * @param getRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return true if the document exists, false otherwise - * @throws IOException in case there is a problem sending the request */ public final boolean exists(GetRequest getRequest, RequestOptions options) throws IOException { return performRequest(getRequest, RequestConverters::exists, options, RestHighLevelClient::convertExistsResponse, emptySet()); @@ -777,20 +783,19 @@ public class RestHighLevelClient implements Closeable { /** * Checks for the existence of a document with a "_source" field. Returns true if it exists, false otherwise. - * See Source exists API + * See Source exists API * on elastic.co * @param getRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return true if the document and _source field exists, false otherwise - * @throws IOException in case there is a problem sending the request */ public boolean existsSource(GetRequest getRequest, RequestOptions options) throws IOException { return performRequest(getRequest, RequestConverters::sourceExists, options, RestHighLevelClient::convertExistsResponse, emptySet()); - } - + } + /** * Asynchronously checks for the existence of a document with a "_source" field. Returns true if it exists, false otherwise. - * See Source exists API + * See Source exists API * on elastic.co * @param getRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized @@ -799,15 +804,14 @@ public class RestHighLevelClient implements Closeable { public final void existsSourceAsync(GetRequest getRequest, RequestOptions options, ActionListener listener) { performRequestAsync(getRequest, RequestConverters::sourceExists, options, RestHighLevelClient::convertExistsResponse, listener, emptySet()); - } - + } + /** * Index a document using the Index API. * See Index API on elastic.co * @param indexRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final IndexResponse index(IndexRequest indexRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(indexRequest, RequestConverters::index, options, IndexResponse::fromXContent, emptySet()); @@ -831,7 +835,6 @@ public class RestHighLevelClient implements Closeable { * @param countRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final CountResponse count(CountRequest countRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(countRequest, RequestConverters::count, options, CountResponse::fromXContent, @@ -856,7 +859,6 @@ public class RestHighLevelClient implements Closeable { * @param updateRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final UpdateResponse update(UpdateRequest updateRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(updateRequest, RequestConverters::update, options, UpdateResponse::fromXContent, emptySet()); @@ -877,10 +879,9 @@ public class RestHighLevelClient implements Closeable { /** * Deletes a document by id using the Delete API. * See Delete API on elastic.co - * @param deleteRequest the reuqest + * @param deleteRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final DeleteResponse delete(DeleteRequest deleteRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(deleteRequest, RequestConverters::delete, options, DeleteResponse::fromXContent, @@ -905,7 +906,6 @@ public class RestHighLevelClient implements Closeable { * @param searchRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final SearchResponse search(SearchRequest searchRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(searchRequest, RequestConverters::search, options, SearchResponse::fromXContent, emptySet()); @@ -930,7 +930,6 @@ public class RestHighLevelClient implements Closeable { * @param multiSearchRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response * @deprecated use {@link #msearch(MultiSearchRequest, RequestOptions)} instead */ @Deprecated @@ -945,7 +944,6 @@ public class RestHighLevelClient implements Closeable { * @param multiSearchRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final MultiSearchResponse msearch(MultiSearchRequest multiSearchRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(multiSearchRequest, RequestConverters::multiSearch, options, MultiSearchResponse::fromXContext, @@ -988,7 +986,6 @@ public class RestHighLevelClient implements Closeable { * @param searchScrollRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response * @deprecated use {@link #scroll(SearchScrollRequest, RequestOptions)} instead */ @Deprecated @@ -1003,7 +1000,6 @@ public class RestHighLevelClient implements Closeable { * @param searchScrollRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final SearchResponse scroll(SearchScrollRequest searchScrollRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(searchScrollRequest, RequestConverters::searchScroll, options, SearchResponse::fromXContent, @@ -1046,7 +1042,6 @@ public class RestHighLevelClient implements Closeable { * @param clearScrollRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final ClearScrollResponse clearScroll(ClearScrollRequest clearScrollRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(clearScrollRequest, RequestConverters::clearScroll, options, ClearScrollResponse::fromXContent, @@ -1057,7 +1052,7 @@ public class RestHighLevelClient implements Closeable { * Asynchronously clears one or more scroll ids using the Clear Scroll API. * See * Clear Scroll API on elastic.co - * @param clearScrollRequest the reuqest + * @param clearScrollRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @param listener the listener to be notified upon request completion */ @@ -1074,7 +1069,6 @@ public class RestHighLevelClient implements Closeable { * @param searchTemplateRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final SearchTemplateResponse searchTemplate(SearchTemplateRequest searchTemplateRequest, RequestOptions options) throws IOException { @@ -1100,7 +1094,6 @@ public class RestHighLevelClient implements Closeable { * @param explainRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final ExplainResponse explain(ExplainRequest explainRequest, RequestOptions options) throws IOException { return performRequest(explainRequest, RequestConverters::explain, options, @@ -1198,7 +1191,6 @@ public class RestHighLevelClient implements Closeable { * @param rankEvalRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final RankEvalResponse rankEval(RankEvalRequest rankEvalRequest, RequestOptions options) throws IOException { return performRequestAndParseEntity(rankEvalRequest, RequestConverters::rankEval, options, RankEvalResponse::fromXContent, @@ -1251,7 +1243,6 @@ public class RestHighLevelClient implements Closeable { * @param fieldCapabilitiesRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public final FieldCapabilitiesResponse fieldCaps(FieldCapabilitiesRequest fieldCapabilitiesRequest, RequestOptions options) throws IOException { @@ -1266,7 +1257,6 @@ public class RestHighLevelClient implements Closeable { * @param request the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public GetStoredScriptResponse getScript(GetStoredScriptRequest request, RequestOptions options) throws IOException { return performRequestAndParseEntity(request, RequestConverters::getScript, options, @@ -1294,7 +1284,6 @@ public class RestHighLevelClient implements Closeable { * @param request the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public AcknowledgedResponse deleteScript(DeleteStoredScriptRequest request, RequestOptions options) throws IOException { return performRequestAndParseEntity(request, RequestConverters::deleteScript, options, @@ -1322,7 +1311,6 @@ public class RestHighLevelClient implements Closeable { * @param putStoredScriptRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized * @return the response - * @throws IOException in case there is a problem sending the request or parsing back the response */ public AcknowledgedResponse putScript(PutStoredScriptRequest putStoredScriptRequest, RequestOptions options) throws IOException { @@ -1450,9 +1438,9 @@ public class RestHighLevelClient implements Closeable { throw new IOException("Unable to parse response body for " + response, e); } } - + /** - * Defines a helper method for requests that can 404 and in which case will return an empty Optional + * Defines a helper method for requests that can 404 and in which case will return an empty Optional * otherwise tries to parse the response body */ protected final Optional performRequestAndParseOptionalEntity(Req request, @@ -1481,7 +1469,7 @@ public class RestHighLevelClient implements Closeable { } catch (Exception e) { throw new IOException("Unable to parse response body for " + response, e); } - } + } /** * @deprecated If creating a new HLRC ReST API call, consider creating new actions instead of reusing server actions. The Validation @@ -1603,9 +1591,9 @@ public class RestHighLevelClient implements Closeable { } }; } - + /** - * Async request which returns empty Optionals in the case of 404s or parses entity into an Optional + * Asynchronous request which returns empty {@link Optional}s in the case of 404s or parses entity into an Optional */ protected final void performRequestAsyncAndParseOptionalEntity(Req request, CheckedFunction requestConverter, @@ -1625,11 +1613,11 @@ public class RestHighLevelClient implements Closeable { return; } req.setOptions(options); - ResponseListener responseListener = wrapResponseListener404sOptional(response -> parseEntity(response.getEntity(), + ResponseListener responseListener = wrapResponseListener404sOptional(response -> parseEntity(response.getEntity(), entityParser), listener); - client.performRequestAsync(req, responseListener); - } - + client.performRequestAsync(req, responseListener); + } + final ResponseListener wrapResponseListener404sOptional(CheckedFunction responseConverter, ActionListener> actionListener) { return new ResponseListener() { @@ -1658,7 +1646,7 @@ public class RestHighLevelClient implements Closeable { } } }; - } + } /** * Converts a {@link ResponseException} obtained from the low level REST client into an {@link ElasticsearchException}. diff --git a/docs/java-rest/high-level/execution.asciidoc b/docs/java-rest/high-level/execution.asciidoc index 4dfb11e196d..1028d9b6975 100644 --- a/docs/java-rest/high-level/execution.asciidoc +++ b/docs/java-rest/high-level/execution.asciidoc @@ -18,6 +18,15 @@ for the +{response}+ to be returned before continuing with code execution: include-tagged::{doc-tests-file}[{api}-execute] -------------------------------------------------- +Synchronous calls may throw an `IOException` in case of either failing to +parse the REST response in the high-level REST client, the request times out +or similar cases where there is no response coming back from the server. + +In cases where the server returns a `4xx` or `5xx` error code, the high-level +client tries to parse the response body error details instead and then throws +a generic `ElasticsearchException` and adds the original `ResponseException` as a +suppressed exception to it. + [id="{upid}-{api}-async"] ==== Asynchronous Execution @@ -36,7 +45,8 @@ the execution completes The asynchronous method does not block and returns immediately. Once it is completed the `ActionListener` is called back using the `onResponse` method if the execution successfully completed or using the `onFailure` method if -it failed. +it failed. Failure scenarios and expected exceptions are the same as in the +synchronous execution case. A typical listener for +{api}+ looks like: @@ -45,4 +55,4 @@ A typical listener for +{api}+ looks like: include-tagged::{doc-tests-file}[{api}-execute-listener] -------------------------------------------------- <1> Called when the execution is successfully completed. -<2> Called when the whole +{request}+ fails. \ No newline at end of file +<2> Called when the whole +{request}+ fails.