mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-22 21:05:23 +00:00
[Docs] Add migration notes for the high-level rest client (#25911)
This commit is contained in:
Tanguy Leroux
GitHub
parent
5f36bdfda0
commit
9c8d3d3569
@ -19,11 +19,9 @@
|
||||
|
||||
package org.elasticsearch.client.documentation;
|
||||
|
||||
import org.elasticsearch.client.http.HttpEntity;
|
||||
import org.elasticsearch.client.http.client.methods.HttpPost;
|
||||
import org.elasticsearch.client.http.entity.ContentType;
|
||||
import org.elasticsearch.client.http.nio.entity.NStringEntity;
|
||||
import org.elasticsearch.Build;
|
||||
import org.elasticsearch.ElasticsearchException;
|
||||
import org.elasticsearch.Version;
|
||||
import org.elasticsearch.action.ActionListener;
|
||||
import org.elasticsearch.action.DocWriteRequest;
|
||||
import org.elasticsearch.action.DocWriteResponse;
|
||||
@ -38,6 +36,7 @@ import org.elasticsearch.action.get.GetRequest;
|
||||
import org.elasticsearch.action.get.GetResponse;
|
||||
import org.elasticsearch.action.index.IndexRequest;
|
||||
import org.elasticsearch.action.index.IndexResponse;
|
||||
import org.elasticsearch.action.main.MainResponse;
|
||||
import org.elasticsearch.action.support.ActiveShardCount;
|
||||
import org.elasticsearch.action.support.WriteRequest;
|
||||
import org.elasticsearch.action.support.replication.ReplicationResponse;
|
||||
@ -46,6 +45,11 @@ import org.elasticsearch.action.update.UpdateResponse;
|
||||
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
|
||||
import org.elasticsearch.client.Response;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.client.http.HttpEntity;
|
||||
import org.elasticsearch.client.http.client.methods.HttpPost;
|
||||
import org.elasticsearch.client.http.entity.ContentType;
|
||||
import org.elasticsearch.client.http.nio.entity.NStringEntity;
|
||||
import org.elasticsearch.cluster.ClusterName;
|
||||
import org.elasticsearch.common.Strings;
|
||||
import org.elasticsearch.common.settings.Settings;
|
||||
import org.elasticsearch.common.unit.ByteSizeUnit;
|
||||
|
||||
@ -0,0 +1,68 @@
|
||||
/*
|
||||
* Licensed to Elasticsearch under one or more contributor
|
||||
* license agreements. See the NOTICE file distributed with
|
||||
* this work for additional information regarding copyright
|
||||
* ownership. Elasticsearch licenses this file to you under
|
||||
* the Apache License, Version 2.0 (the "License"); you may
|
||||
* not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing,
|
||||
* software distributed under the License is distributed on an
|
||||
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
* KIND, either express or implied. See the License for the
|
||||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
|
||||
package org.elasticsearch.client.documentation;
|
||||
|
||||
import org.elasticsearch.Build;
|
||||
import org.elasticsearch.Version;
|
||||
import org.elasticsearch.action.main.MainResponse;
|
||||
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.cluster.ClusterName;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
/**
|
||||
* This class is used to generate the Java Main API documentation.
|
||||
* You need to wrap your code between two tags like:
|
||||
* // tag::example[]
|
||||
* // end::example[]
|
||||
*
|
||||
* Where example is your tag name.
|
||||
*
|
||||
* Then in the documentation, you can extract what is between tag and end tags with
|
||||
* ["source","java",subs="attributes,callouts,macros"]
|
||||
* --------------------------------------------------
|
||||
* include-tagged::{doc-tests}/MainDocumentationIT.java[example]
|
||||
* --------------------------------------------------
|
||||
*/
|
||||
public class MainDocumentationIT extends ESRestHighLevelClientTestCase {
|
||||
|
||||
public void testMain() throws IOException {
|
||||
RestHighLevelClient client = highLevelClient();
|
||||
{
|
||||
//tag::main-execute
|
||||
MainResponse response = client.info();
|
||||
//end::main-execute
|
||||
assertTrue(response.isAvailable());
|
||||
//tag::main-response
|
||||
ClusterName clusterName = response.getClusterName(); // <1>
|
||||
String clusterUuid = response.getClusterUuid(); // <2>
|
||||
String nodeName = response.getNodeName(); // <3>
|
||||
Version version = response.getVersion(); // <4>
|
||||
Build build = response.getBuild(); // <5>
|
||||
//end::main-response
|
||||
assertNotNull(clusterName);
|
||||
assertNotNull(clusterUuid);
|
||||
assertNotNull(nodeName);
|
||||
assertNotNull(version);
|
||||
assertNotNull(build);
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,162 @@
|
||||
/*
|
||||
* Licensed to Elasticsearch under one or more contributor
|
||||
* license agreements. See the NOTICE file distributed with
|
||||
* this work for additional information regarding copyright
|
||||
* ownership. Elasticsearch licenses this file to you under
|
||||
* the Apache License, Version 2.0 (the "License"); you may
|
||||
* not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing,
|
||||
* software distributed under the License is distributed on an
|
||||
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
* KIND, either express or implied. See the License for the
|
||||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
|
||||
package org.elasticsearch.client.documentation;
|
||||
|
||||
import org.elasticsearch.action.ActionListener;
|
||||
import org.elasticsearch.action.delete.DeleteRequest;
|
||||
import org.elasticsearch.action.delete.DeleteResponse;
|
||||
import org.elasticsearch.action.index.IndexRequest;
|
||||
import org.elasticsearch.action.index.IndexRequestBuilder;
|
||||
import org.elasticsearch.action.index.IndexResponse;
|
||||
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
|
||||
import org.elasticsearch.client.Response;
|
||||
import org.elasticsearch.client.RestClient;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.client.http.HttpEntity;
|
||||
import org.elasticsearch.client.http.HttpStatus;
|
||||
import org.elasticsearch.client.http.entity.ContentType;
|
||||
import org.elasticsearch.client.http.nio.entity.NStringEntity;
|
||||
import org.elasticsearch.cluster.health.ClusterHealthStatus;
|
||||
import org.elasticsearch.common.settings.Settings;
|
||||
import org.elasticsearch.common.xcontent.XContentFactory;
|
||||
import org.elasticsearch.common.xcontent.XContentHelper;
|
||||
import org.elasticsearch.common.xcontent.XContentType;
|
||||
import org.elasticsearch.rest.RestStatus;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.util.Map;
|
||||
|
||||
import static java.util.Collections.emptyMap;
|
||||
import static org.elasticsearch.cluster.metadata.IndexMetaData.SETTING_NUMBER_OF_REPLICAS;
|
||||
import static org.elasticsearch.cluster.metadata.IndexMetaData.SETTING_NUMBER_OF_SHARDS;
|
||||
|
||||
/**
|
||||
* This class is used to generate the documentation for the
|
||||
* docs/java-rest/high-level/migration.asciidoc page.
|
||||
*
|
||||
* You need to wrap your code between two tags like:
|
||||
* // tag::example[]
|
||||
* // end::example[]
|
||||
*
|
||||
* Where example is your tag name.
|
||||
*
|
||||
* Then in the documentation, you can extract what is between tag and end tags with
|
||||
* ["source","java",subs="attributes,callouts,macros"]
|
||||
* --------------------------------------------------
|
||||
* include-tagged::{doc-tests}/MigrationDocumentationIT.java[example]
|
||||
* --------------------------------------------------
|
||||
*/
|
||||
public class MigrationDocumentationIT extends ESRestHighLevelClientTestCase {
|
||||
|
||||
public void testCreateIndex() throws IOException {
|
||||
RestClient restClient = client();
|
||||
{
|
||||
//tag::migration-create-inded
|
||||
Settings indexSettings = Settings.builder() // <1>
|
||||
.put(SETTING_NUMBER_OF_SHARDS, 1)
|
||||
.put(SETTING_NUMBER_OF_REPLICAS, 0)
|
||||
.build();
|
||||
|
||||
String payload = XContentFactory.jsonBuilder() // <2>
|
||||
.startObject()
|
||||
.startObject("settings") // <3>
|
||||
.value(indexSettings)
|
||||
.endObject()
|
||||
.startObject("mappings") // <4>
|
||||
.startObject("doc")
|
||||
.startObject("properties")
|
||||
.startObject("time")
|
||||
.field("type", "date")
|
||||
.endObject()
|
||||
.endObject()
|
||||
.endObject()
|
||||
.endObject()
|
||||
.endObject().string();
|
||||
|
||||
HttpEntity entity = new NStringEntity(payload, ContentType.APPLICATION_JSON); // <5>
|
||||
|
||||
Response response = restClient.performRequest("PUT", "my-index", emptyMap(), entity); // <6>
|
||||
if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
|
||||
// <7>
|
||||
}
|
||||
//end::migration-create-inded
|
||||
assertEquals(200, response.getStatusLine().getStatusCode());
|
||||
}
|
||||
}
|
||||
|
||||
public void testClusterHealth() throws IOException {
|
||||
RestClient restClient = client();
|
||||
{
|
||||
//tag::migration-cluster-health
|
||||
Response response = restClient.performRequest("GET", "/_cluster/health"); // <1>
|
||||
|
||||
ClusterHealthStatus healthStatus;
|
||||
try (InputStream is = response.getEntity().getContent()) { // <2>
|
||||
Map<String, Object> map = XContentHelper.convertToMap(XContentType.JSON.xContent(), is, true); // <3>
|
||||
healthStatus = ClusterHealthStatus.fromString((String) map.get("status")); // <4>
|
||||
}
|
||||
|
||||
if (healthStatus == ClusterHealthStatus.GREEN) {
|
||||
// <5>
|
||||
}
|
||||
//end::migration-cluster-health
|
||||
assertSame(ClusterHealthStatus.GREEN, healthStatus);
|
||||
}
|
||||
}
|
||||
|
||||
public void testRequests() throws IOException {
|
||||
RestHighLevelClient client = highLevelClient();
|
||||
{
|
||||
//tag::migration-request-ctor
|
||||
IndexRequest request = new IndexRequest("index", "doc", "id"); // <1>
|
||||
request.source("{\"field\":\"value\"}", XContentType.JSON);
|
||||
//end::migration-request-ctor
|
||||
|
||||
//tag::migration-request-ctor-execution
|
||||
IndexResponse response = client.index(request);
|
||||
//end::migration-request-ctor-execution
|
||||
assertEquals(RestStatus.CREATED, response.status());
|
||||
}
|
||||
{
|
||||
//tag::migration-request-sync-execution
|
||||
DeleteRequest request = new DeleteRequest("index", "doc", "id");
|
||||
DeleteResponse response = client.delete(request); // <1>
|
||||
//end::migration-request-sync-execution
|
||||
assertEquals(RestStatus.OK, response.status());
|
||||
}
|
||||
{
|
||||
//tag::migration-request-async-execution
|
||||
DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
|
||||
client.deleteAsync(request, new ActionListener<DeleteResponse>() { // <2>
|
||||
@Override
|
||||
public void onResponse(DeleteResponse deleteResponse) {
|
||||
// <3>
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onFailure(Exception e) {
|
||||
// <4>
|
||||
}
|
||||
});
|
||||
//end::migration-request-async-execution
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -23,6 +23,10 @@ cluster.
|
||||
|
||||
==============================
|
||||
|
||||
WARNING: The `TransportClient` is aimed to be replaced by the Java High Level REST
|
||||
Client, which executes HTTP requests instead of serialized Java requests. The
|
||||
`TransportClient` will be deprecated in upcoming versions of Elasticsearch and it
|
||||
is advised to use the Java High Level REST Client instead.
|
||||
|
||||
[[transport-client]]
|
||||
=== Transport Client
|
||||
|
||||
@ -17,6 +17,11 @@ Additionally, operations on a client may be accumulated and executed in
|
||||
Note, all the APIs are exposed through the
|
||||
Java API (actually, the Java API is used internally to execute them).
|
||||
|
||||
WARNING: Starting from version 5.6.0, a new Java client has been
|
||||
released: the {java-rest}/java-rest-high.html[Java High Level REST Client].
|
||||
This new client is designed to replace the `TransportClient` in Java
|
||||
applications which will be deprecated in future versions of Elasticsearch.
|
||||
|
||||
== Javadoc
|
||||
|
||||
The javadoc for the transport client can be found at {transport-client-javadoc}/index.html.
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
[[java-rest-high-supported-apis]]
|
||||
== Supported APIs
|
||||
|
||||
The Java High Level REST Client supports the following APIs:
|
||||
@ -15,3 +16,6 @@ The Java High Level REST Client supports the following APIs:
|
||||
* <<java-rest-high-search>>
|
||||
* <<java-rest-high-search-scroll>>
|
||||
* <<java-rest-high-clear-scroll>>
|
||||
|
||||
.Miscellaneous APIs
|
||||
* <<java-rest-high-main>>
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
|
||||
|
||||
include::_index.asciidoc[]
|
||||
include::get.asciidoc[]
|
||||
include::delete.asciidoc[]
|
||||
@ -7,5 +5,4 @@ include::update.asciidoc[]
|
||||
include::bulk.asciidoc[]
|
||||
include::search.asciidoc[]
|
||||
include::scroll.asciidoc[]
|
||||
|
||||
:doc-tests!:
|
||||
include::main.asciidoc[]
|
||||
|
||||
27
docs/java-rest/high-level/apis/main.asciidoc
Normal file
27
docs/java-rest/high-level/apis/main.asciidoc
Normal file
@ -0,0 +1,27 @@
|
||||
[[java-rest-high-main]]
|
||||
=== Info API
|
||||
|
||||
[[java-rest-high-main-request]]
|
||||
==== Execution
|
||||
|
||||
Cluster information can be retrieved using the `info()` method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MainDocumentationIT.java[main-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-main-response]]
|
||||
==== Response
|
||||
|
||||
The returned `MainResponse` provides various kinds of information about the cluster:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MainDocumentationIT.java[main-response]
|
||||
--------------------------------------------------
|
||||
<1> Retrieve the name of the cluster as a `ClusterName`
|
||||
<2> Retrieve the unique identifier of the cluster
|
||||
<3> Retrieve the name of the node the request has been executed on
|
||||
<4> Retrieve the version of the node the request has been executed on
|
||||
<5> Retrieve the build information of the node the request has been executed on
|
||||
@ -22,10 +22,16 @@ the same response objects.
|
||||
|
||||
--
|
||||
|
||||
:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
|
||||
|
||||
include::usage.asciidoc[]
|
||||
|
||||
include::apis.asciidoc[]
|
||||
|
||||
include::apis/index.asciidoc[]
|
||||
|
||||
include::migration.asciidoc[]
|
||||
|
||||
include::../license.asciidoc[]
|
||||
|
||||
:doc-tests!:
|
||||
|
||||
362
docs/java-rest/high-level/migration.asciidoc
Normal file
362
docs/java-rest/high-level/migration.asciidoc
Normal file
@ -0,0 +1,362 @@
|
||||
[[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-usage,Getting Started>> page shows
|
||||
typical configurations for Maven and Gradle and presents the
|
||||
<<java-rest-high-usage-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("host"), 9300));
|
||||
--------------------------------------------------
|
||||
|
||||
The initialization of a `RestHighLevelClient` is different. It first requires the initialization
|
||||
of a <<java-rest-low-usage-initialization,low-level client>>:
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
RestClient lowLevelRestClient = RestClient.builder(
|
||||
new HttpHost("host", 9200, "http")).build();
|
||||
--------------------------------------------------
|
||||
|
||||
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`.
|
||||
|
||||
Which is then passed to the constructor of the `RestHighLevelClient`:
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
RestHighLevelClient client =
|
||||
new RestHighLevelClient(lowLevelRestClient);
|
||||
--------------------------------------------------
|
||||
|
||||
Both `RestClient` and `RestHighLevelClient` are thread safe. They are
|
||||
typically instantiated by the application at startup time or when the
|
||||
first request is executed.
|
||||
|
||||
Once the `RestHighLevelClient` is initialized, it can then be used to
|
||||
execute any of the <<java-rest-high-supported-apis,supported APIs>>.
|
||||
|
||||
As with the `TransportClient`, the `RestClient` must be closed when it
|
||||
is not needed anymore or when the application is stopped.
|
||||
|
||||
So the code that closes the `TransportClient`:
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
transportClient.close();
|
||||
--------------------------------------------------
|
||||
|
||||
Must be replaced with:
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
lowLevelRestClient.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.
|
||||
<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].
|
||||
|
||||
|
||||
@ -4,6 +4,21 @@
|
||||
This section describes how to get started with the high-level REST client from
|
||||
getting the artifact to using it in an application.
|
||||
|
||||
[[java-rest-high-compatibility]]
|
||||
=== Compatibility
|
||||
The Java High Level REST Client requires Java 1.8 and depends on the Elasticsearch
|
||||
core project. The client version is the same as the Elasticsearch version that the
|
||||
client was developed for. It accepts the same request arguments as the `TransportClient`
|
||||
and returns the same response objects.
|
||||
|
||||
The High Level Client is backwards compatible but can only communicate with Elasticsearch
|
||||
version 5.5 and onwards. The High Level Client is forward compatible as well, meaning that
|
||||
it supports communicating with a later version of Elasticsearch than the one it was developed
|
||||
for. It is recommended to upgrade the High Level Client when upgrading the Elasticsearch
|
||||
cluster to a new major version, as REST API breaking changes may cause unexpected results,
|
||||
and newly added APIs will only be supported by the newer version of the client. The client
|
||||
should be updated last, once all of the nodes in the cluster have been upgraded.
|
||||
|
||||
[[java-rest-high-javadoc]]
|
||||
=== Javadoc
|
||||
|
||||
|
||||
@ -26,6 +26,7 @@ way to reindex old indices is to use the `reindex` API.
|
||||
|
||||
* <<breaking_60_aggregations_changes>>
|
||||
* <<breaking_60_cat_changes>>
|
||||
* <<breaking_60_clients_changes>>
|
||||
* <<breaking_60_cluster_changes>>
|
||||
* <<breaking_60_docs_changes>>
|
||||
* <<breaking_60_indices_changes>>
|
||||
@ -46,6 +47,7 @@ way to reindex old indices is to use the `reindex` API.
|
||||
include::migrate_6_0/aggregations.asciidoc[]
|
||||
include::migrate_6_0/analysis.asciidoc[]
|
||||
include::migrate_6_0/cat.asciidoc[]
|
||||
include::migrate_6_0/clients.asciidoc[]
|
||||
include::migrate_6_0/cluster.asciidoc[]
|
||||
include::migrate_6_0/docs.asciidoc[]
|
||||
include::migrate_6_0/indices.asciidoc[]
|
||||
|
||||
11
docs/reference/migration/migrate_6_0/clients.asciidoc
Normal file
11
docs/reference/migration/migrate_6_0/clients.asciidoc
Normal file
@ -0,0 +1,11 @@
|
||||
[[breaking_60_clients_changes]]
|
||||
=== Clients changes
|
||||
|
||||
==== Java High Level REST Client
|
||||
|
||||
Starting from version 5.6.0 a new Java client has been released: the Java High Level REST Client.
|
||||
This official high-level client (named like this to differentiate it from the existing low-level client) for
|
||||
Elasticsearch can be used to execute search, index, delete, update and bulk operations using the same Core
|
||||
Java classes as the `TransportClient` uses.
|
||||
|
||||
This Java High Level REST Client is designed to replace the `TransportClient` in a near future.
|
||||
Loading…
x
Reference in New Issue
Block a user