Changing the application’s code
editChanging the application’s code
editThe RestHighLevelClient
supports the same request and response objects
as the TransportClient
, but exposes slightly different methods to
send the requests.
More importantly, the high-level client:
-
does not support request builders. The legacy methods like
client.prepareIndex()
must be changed to use request constructors likenew IndexRequest()
to create requests objects. The requests are then executed using synchronous or asynchronous dedicated methods likeclient.index()
orclient.indexAsync()
.
How to migrate the way requests are built
editThe Java API provides two ways to build a request: by using the request’s constructor or by using
a request builder. Migrating from the TransportClient
to the high-level client can be
straightforward if application’s code uses the former, while changing usages of the latter can
require more work.
With request constructors
editWhen request constructors are used, like in the following example:
IndexRequest request = new IndexRequest("index").id("id"); request.source("{\"field\":\"value\"}", XContentType.JSON);
The migration is very simple. The execution using the TransportClient
:
IndexResponse response = transportClient.index(indexRequest).actionGet();
Can be easily replaced to use the RestHighLevelClient
:
IndexResponse response = client.index(request, RequestOptions.DEFAULT);
With request builders
editThe Java API provides a request builder for every type of request. They are exposed by the
TransportClient
through the many prepare()
methods. Here are some examples:
IndexRequestBuilder indexRequestBuilder = transportClient.prepareIndex(); DeleteRequestBuilder deleteRequestBuilder = transportClient.prepareDelete(); SearchRequestBuilder searchRequestBuilder = transportClient.prepareSearch();
Create a |
|
Create a |
|
Create a |
Since the Java High Level REST Client does not support request builders, applications that use them must be changed to use requests constructors instead.
While you are incrementally migrating your application and you have both the transport client
and the high level client available you can always get the Request
object from the Builder
object
by calling Builder.request()
. We do not advise continuing to depend on the builders in the long run
but it should be possible to use them during the transition from the transport client to the high
level rest client.
How to migrate the way requests are executed
editThe TransportClient
allows to execute requests in both synchronous and asynchronous ways. This is also
possible using the high-level client.
Synchronous execution
editThe following example shows how a DeleteRequest
can be synchronously executed using the TransportClient
:
DeleteRequest request = new DeleteRequest("index", "doc", "id"); DeleteResponse response = transportClient.delete(request).actionGet();
Create the |
|
Execute the |
The same request synchronously executed using the high-level client is:
Asynchronous execution
editThe following example shows how a DeleteRequest
can be asynchronously executed using the TransportClient
:
DeleteRequest request = new DeleteRequest("index", "doc", "id"); transportClient.delete(request, new ActionListener<DeleteResponse>() { @Override public void onResponse(DeleteResponse deleteResponse) { } @Override public void onFailure(Exception e) { } });
Create the |
|
Execute the |
|
The |
|
The |
The same request asynchronously executed using the high-level client is:
DeleteRequest request = new DeleteRequest("index", "id"); client.deleteAsync(request, RequestOptions.DEFAULT, new ActionListener<DeleteResponse>() { @Override public void onResponse(DeleteResponse deleteResponse) { } @Override public void onFailure(Exception e) { } });
Create the |
|
Execute the |
|
The |
|
The |
Checking Cluster Health using the Low-Level REST Client
editAnother common need is to check the cluster’s health using the Cluster API. With
the TransportClient
it can be done this way:
ClusterHealthResponse response = client.admin().cluster().prepareHealth().get(); ClusterHealthStatus healthStatus = response.getStatus(); if (healthStatus != ClusterHealthStatus.GREEN) { }
Execute a |
|
Retrieve the cluster’s health status from the response |
|
Handle the situation where the cluster’s health is not green |
With the low-level client, the code can be changed to:
Request request = new Request("GET", "/_cluster/health"); request.addParameter("wait_for_status", "green"); Response response = client.getLowLevelClient().performRequest(request); ClusterHealthStatus healthStatus; try (InputStream is = response.getEntity().getContent()) { Map<String, Object> map = XContentHelper.convertToMap(XContentType.JSON.xContent(), is, true); healthStatus = ClusterHealthStatus.fromStringString) map.get("status"; } if (healthStatus != ClusterHealthStatus.GREEN) { }
Set up the request to wait for the cluster’s health to become green if it isn’t already. |
|
Make the request and the get back a |
|
Retrieve an |
|
Parse the response’s content using Elasticsearch’s helper class |
|
Retrieve the value of the |
|
Handle the situation where the cluster’s health is not green |
Note that for convenience this example uses Elasticsearch’s helpers to parse the JSON response body, but any other JSON parser could have been use instead.