OpenSearch/docs/java-rest/high-level/migration.asciidoc

[[java-rest-high-level-migration]]
== Migration Guide

This section describes how to migrate existing code from the `TransportClient`
to the new Java High Level REST Client released with the version 5.6.0
of Elasticsearch.

=== Motivations around a new Java client

The existing `TransportClient` has been part of Elasticsearch since https://github.com/elastic/elasticsearch/blob/b3337c312765e51cec7bde5883bbc0a08f56fb65/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/TransportClient.java[its very first commit].
 It is a special client as it uses the transport protocol to communicate with Elasticsearch,
 which causes compatibility problems if the client is not on the same version as the
 Elasticsearch instances it talks to.

We released a low-level REST client in 2016, which is based on the well known Apache HTTP
client and it allows to communicate with an Elasticsearch cluster in any version using HTTP.
On top of that we released the high-level REST client which is based on the low-level client
but takes care of request marshalling and response un-marshalling.

If you're interested in knowing more about these changes, we wrote a blog post about the
https://www.elastic.co/blog/state-of-the-official-elasticsearch-java-clients[state of the official Elasticsearch Java clients].

=== Prerequisite

The Java High Level Rest Client requires Java `1.8` and can be used to send requests
to an <<java-rest-high-compatibility,Elasticsearch cluster in a compatible version>>.

=== How to migrate

Adapting existing code to use the `RestHighLevelClient` instead of the `TransportClient`
requires the following steps:

- Update dependencies
- Update client initialization
- Update application code

=== Updating the dependencies

Java application that uses the `TransportClient` depends on the
`org.elasticsearch.client:transport` artifact. This dependency
must be replaced by a new dependency on the high-level client.

The <<java-rest-high-getting-started,Getting Started>> page shows
 typical configurations for Maven and Gradle and presents the
 <<java-rest-high-getting-started-dependencies, dependencies>> brought by the
 high-level client.

=== Changing the client's initialization code

The `TransportClient` is typically initialized as follows:
[source,java]
--------------------------------------------------
Settings settings = Settings.builder()
        .put("cluster.name", "prod").build();

TransportClient transportClient = new PreBuiltTransportClient(settings)
        .addTransportAddress(new TransportAddress(InetAddress.getByName("localhost"), 9300))
        .addTransportAddress(new TransportAddress(InetAddress.getByName("localhost"), 9301));
--------------------------------------------------

The initialization of a `RestHighLevelClient` is different. It requires to provide
a <<java-rest-low-usage-initialization,low-level client builder>> as a constructor
argument:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-init]
--------------------------------------------------

NOTE: The `RestClient` uses Elasticsearch's HTTP service which is
 bounded by default on `9200`. This port is different from the port
 used to connect to Elasticsearch with a `TransportClient`.

The `RestHighLevelClient` is thread-safe. It is typically instantiated by the
application at startup time or when the first request is executed.

Once the `RestHighLevelClient` is initialized, it can be used to execute any
of the <<java-rest-high-supported-apis,supported APIs>>.

As with the `TransportClient`, the `RestHighLevelClient` must be closed when it
is not needed anymore or when the application is stopped.

The code that closes the `TransportClient`:

[source,java]
--------------------------------------------------
transportClient.close();
--------------------------------------------------

must be replaced with:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-close]
--------------------------------------------------

=== Changing the application's code

The `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 like `new IndexRequest()` to create requests
 objects. The requests are then executed using synchronous or
 asynchronous dedicated methods like `client.index()` or `client.indexAsync()`.
- does not provide indices or cluster management APIs. Management
operations can be executed by external scripts or
<<java-rest-high-level-migration-manage-indices, using the low-level client>>.

==== How to migrate the way requests are built

The 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.

[[java-rest-high-level-migration-request-ctor]]
===== With request constructors

When request constructors are used, like in the following example:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-ctor]
--------------------------------------------------
<1> Create an `IndexRequest` using its constructor

The migration is very simple. The execution using the `TransportClient`:

[source,java]
--------------------------------------------------
IndexResponse response = transportClient.index(indexRequest).actionGet();
--------------------------------------------------

Can be easily replaced to use the `RestHighLevelClient`:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-ctor-execution]
--------------------------------------------------

[[java-rest-high-level-migration-request-builder]]
===== With request builders

The 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:

[source,java]
--------------------------------------------------
IndexRequestBuilder indexRequestBuilder   = transportClient.prepareIndex();  // <1>
DeleteRequestBuilder deleteRequestBuilder = transportClient.prepareDelete(); // <2>
SearchRequestBuilder searchRequestBuilder = transportClient.prepareSearch(); // <3>
--------------------------------------------------
<1> Create a `IndexRequestBuilder` using the `prepareIndex()` method from the `TransportClient`. The
request builder encapsulates the `IndexRequest` to be executed.
<2> Create a `DeleteRequestBuilder` using the `prepareDelete()` method from the `TransportClient`. The
request builder encapsulates the `DeleteRequest` to be executed.
<3> Create a `SearchRequestBuilder` using the `prepareSearch()` method from the `TransportClient`. The
request builder encapsulates the `SearchRequest` to be executed.

Since the Java High Level REST Client does not support request builders, applications that use
them must be changed to use <<java-rest-high-level-migration-request-ctor,requests constructors>> instead.

NOTE: 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

The `TransportClient` allows to execute requests in both synchronous and asynchronous ways. This is also
possible using the high-level client.

===== Synchronous execution

The following example shows how a `DeleteRequest` can be synchronously executed using the `TransportClient`:

[source,java]
--------------------------------------------------
DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
DeleteResponse response = transportClient.delete(request).actionGet(); // <2>
--------------------------------------------------
<1> Create the `DeleteRequest` using its constructor
<2> Execute the `DeleteRequest`. The `actionGet()` method blocks until a
response is returned by the cluster.

The same request synchronously executed using the high-level client is:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-sync-execution]
--------------------------------------------------
<1> Execute the `DeleteRequest`. The `delete()` method blocks until a
response is returned by the cluster.

===== Asynchronous execution

The following example shows how a `DeleteRequest` can be asynchronously executed using the `TransportClient`:

[source,java]
--------------------------------------------------
DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
transportClient.delete(request, new ActionListener<DeleteResponse>() { // <2>
    @Override
    public void onResponse(DeleteResponse deleteResponse) {
        // <3>
    }

    @Override
    public void onFailure(Exception e) {
        // <4>
    }
});
--------------------------------------------------
<1> Create the `DeleteRequest` using its constructor
<2> Execute the `DeleteRequest` by passing the request and a
`ActionListener` that gets called on execution completion or
failure. This method does not block and returns immediately.
<3> The `onResponse()` method is called when the response is
returned by the cluster.
<4> The `onFailure()` method is called when an error occurs
during the execution of the request.

The same request asynchronously executed using the high-level client is:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-async-execution]
--------------------------------------------------
<1> Create the `DeleteRequest` using its constructor
<2> Execute the `DeleteRequest` by passing the request and a
`ActionListener` that gets called on execution completion or
failure. This method does not block and returns immediately.
<3> The `onResponse()` method is called when the response is
returned by the cluster.
<4> The `onFailure()` method is called when an error occurs
during the execution of the request.

[[java-rest-high-level-migration-manage-indices]]
==== Manage Indices using the Low-Level REST Client

The low-level client is able to execute any kind of HTTP requests, and can
therefore be used to call the APIs that are not yet supported by the high level client.

For example, creating a new index with the `TransportClient` may look like this:

[source,java]
--------------------------------------------------
Settings settings = Settings.builder() // <1>
                                .put(SETTING_NUMBER_OF_SHARDS, 1)
                                .put(SETTING_NUMBER_OF_REPLICAS, 0)
                                .build();

String mappings = XContentFactory.jsonBuilder()  // <2>
                                .startObject()
                                    .startObject("doc")
                                        .startObject("properties")
                                            .startObject("time")
                                                .field("type", "date")
                                            .endObject()
                                        .endObject()
                                    .endObject()
                                .endObject()
                                .string();

CreateIndexResponse response = transportClient.admin().indices()  // <3>
        .prepareCreate("my-index")
        .setSettings(indexSettings)
        .addMapping("doc", docMapping, XContentType.JSON)
        .get();

if (response.isAcknowledged() == false) {
    // <4>
}
--------------------------------------------------
<1> Define the settings of the index
<2> Define the mapping for document of type `doc` using a
`XContentBuilder`
<3> Create the index with the previous settings and mapping
using the `prepareCreate()` method. The execution is synchronous
and blocks on the `get()` method until the remote cluster returns
a response.
<4> Handle the situation where the index has not been created

The same operation executed with the low-level client could be:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-create-inded]
--------------------------------------------------
<1> Define the settings of the index
<2> Define the body of the HTTP request using a `XContentBuilder` with JSON format
<3> Include the settings in the request body
<4> Include the mappings in the request body
<5> Convert the request body from `String` to a `HttpEntity` and
set its content type (here, JSON)
<6> Execute the request using the low-level client. The execution is synchronous
and blocks on the `performRequest()` method until the remote cluster returns
a response. The low-level client can be retrieved from an existing `RestHighLevelClient`
instance through the `getLowLevelClient` getter method.
<7> Handle the situation where the index has not been created


[[java-rest-high-level-migration-cluster-health]]
==== Checking Cluster Health using the Low-Level REST Client

Another common need is to check the cluster's health using the Cluster API. With
the `TransportClient` it can be done this way:

[source,java]
--------------------------------------------------
ClusterHealthResponse response = client.admin().cluster().prepareHealth().get(); // <1>

ClusterHealthStatus healthStatus = response.getStatus(); // <2>
if (healthStatus != ClusterHealthStatus.GREEN) {
    // <3>
}
--------------------------------------------------
<1> Execute a `ClusterHealth` with default parameters
<2> Retrieve the cluster's health status from the response
<3> Handle the situation where the cluster's health is not green

With the low-level client, the code can be changed to:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-cluster-health]
--------------------------------------------------
<1> Call the cluster's health REST endpoint using the default paramaters
and gets back a `Response` object.
<2> Retrieve an `InputStream` object in order to read the response's content
<3> Parse the response's content using Elasticsearch's helper class `XContentHelper`. This
 helper requires the content type of the response to be passed as an argument and returns
 a `Map` of objects. Values in the map can be of any type, including inner `Map` that are
 used to represent the JSON object hierarchy.
<4> Retrieve the value of the `status` field in the response map, casts it as a a `String`
object and use the `ClusterHealthStatus.fromString()` method to convert it as a `ClusterHealthStatus`
object. This method throws an exception if the value does not corresponds to a valid cluster
health status.
<5> 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.

=== Provide feedback

We love to hear from you! Please give us your feedback about your migration
experience and how to improve the Java High Level Rest Client on https://discuss.elastic.co/[our forum].