diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java index 585dc2c6d0eac..f69742f78cfd3 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java @@ -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.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.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; diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java new file mode 100644 index 0000000000000..877ae910e83fa --- /dev/null +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java @@ -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); + } + } +} diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationDocumentationIT.java new file mode 100644 index 0000000000000..d0f191c4ca348 --- /dev/null +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationDocumentationIT.java @@ -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 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() { // <2> + @Override + public void onResponse(DeleteResponse deleteResponse) { + // <3> + } + + @Override + public void onFailure(Exception e) { + // <4> + } + }); + //end::migration-request-async-execution + } + } +} diff --git a/docs/java-api/client.asciidoc b/docs/java-api/client.asciidoc index cef50717a3c69..83889bda49ac5 100644 --- a/docs/java-api/client.asciidoc +++ b/docs/java-api/client.asciidoc @@ -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 diff --git a/docs/java-api/index.asciidoc b/docs/java-api/index.asciidoc index 6630045f9f3a1..9c6a786c78ed7 100644 --- a/docs/java-api/index.asciidoc +++ b/docs/java-api/index.asciidoc @@ -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. diff --git a/docs/java-rest/high-level/apis.asciidoc b/docs/java-rest/high-level/apis.asciidoc index e5c6c9c90e272..b294974bacd75 100644 --- a/docs/java-rest/high-level/apis.asciidoc +++ b/docs/java-rest/high-level/apis.asciidoc @@ -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: * <> * <> * <> + +.Miscellaneous APIs +* <> diff --git a/docs/java-rest/high-level/apis/index.asciidoc b/docs/java-rest/high-level/apis/index.asciidoc index e0a8c9425e304..b4dcf7e9d8037 100644 --- a/docs/java-rest/high-level/apis/index.asciidoc +++ b/docs/java-rest/high-level/apis/index.asciidoc @@ -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[] diff --git a/docs/java-rest/high-level/apis/main.asciidoc b/docs/java-rest/high-level/apis/main.asciidoc new file mode 100644 index 0000000000000..b37e85ee8bd7b --- /dev/null +++ b/docs/java-rest/high-level/apis/main.asciidoc @@ -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 diff --git a/docs/java-rest/high-level/index.asciidoc b/docs/java-rest/high-level/index.asciidoc index 0dbab938469f3..ec7a1bdaf7d9a 100644 --- a/docs/java-rest/high-level/index.asciidoc +++ b/docs/java-rest/high-level/index.asciidoc @@ -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!: diff --git a/docs/java-rest/high-level/migration.asciidoc b/docs/java-rest/high-level/migration.asciidoc new file mode 100644 index 0000000000000..20b6472a32e49 --- /dev/null +++ b/docs/java-rest/high-level/migration.asciidoc @@ -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 <>. + +=== 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 <> page shows + typical configurations for Maven and Gradle and presents the + <> 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 <>: + +[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 <>. + +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 +<>. + +==== 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 <> 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() { // <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]. + + diff --git a/docs/java-rest/high-level/usage.asciidoc b/docs/java-rest/high-level/usage.asciidoc index 541a3808bb376..bf1db1ff31312 100644 --- a/docs/java-rest/high-level/usage.asciidoc +++ b/docs/java-rest/high-level/usage.asciidoc @@ -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 diff --git a/docs/reference/migration/migrate_6_0.asciidoc b/docs/reference/migration/migrate_6_0.asciidoc index b61ce25578d95..ffebfd9cfe7c6 100644 --- a/docs/reference/migration/migrate_6_0.asciidoc +++ b/docs/reference/migration/migrate_6_0.asciidoc @@ -26,6 +26,7 @@ way to reindex old indices is to use the `reindex` API. * <> * <> +* <> * <> * <> * <> @@ -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[] diff --git a/docs/reference/migration/migrate_6_0/clients.asciidoc b/docs/reference/migration/migrate_6_0/clients.asciidoc new file mode 100644 index 0000000000000..55d1675e5dda0 --- /dev/null +++ b/docs/reference/migration/migrate_6_0/clients.asciidoc @@ -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.