Skip to content

Commit

Permalink
Docs: Update HighLevelRestClient migration docs
Browse files Browse the repository at this point in the history 
The High Level REST Client's documentation suggested that users should
use the Low Level REST Client for index management activities. This
change removes that suggestion because the high level REST client
supports those APIs now.

This also changes the examples in the migration docs to that still use
the Low Level REST Client to use the non-deprecated varieats of
`performRequest`.
  • Loading branch information
@nik9000
nik9000 committed May 11, 2018
1 parent 07b962f commit dba07c1
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 119 deletions.
53 changes: 9 additions & 44 deletions ...-level/src/test/java/org/elasticsearch/client/documentation/MigrationDocumentationIT.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
import org.elasticsearch.action.index.IndexRequest;
import org.elasticsearch.action.index.IndexResponse;
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
import org.elasticsearch.client.Request;
import org.elasticsearch.client.Response;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.cluster.health.ClusterHealthStatus;
Expand Down Expand Up @@ -66,58 +67,22 @@
* --------------------------------------------------
*/
public class MigrationDocumentationIT extends ESRestHighLevelClientTestCase {

public void testCreateIndex() throws IOException {
RestHighLevelClient client = highLevelClient();
{
//tag::migration-create-index
Settings indexSettings = Settings.builder() // <1>
.put(SETTING_NUMBER_OF_SHARDS, 1)
.put(SETTING_NUMBER_OF_REPLICAS, 0)
.build();

String payload = Strings.toString(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());

HttpEntity entity = new NStringEntity(payload, ContentType.APPLICATION_JSON); // <5>

Response response = client.getLowLevelClient().performRequest("PUT", "my-index", emptyMap(), entity); // <6>
if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
// <7>
}
//end::migration-create-index
assertEquals(200, response.getStatusLine().getStatusCode());
}
}

public void testClusterHealth() throws IOException {
RestHighLevelClient client = highLevelClient();
{
//tag::migration-cluster-health
Map<String, String> parameters = singletonMap("wait_for_status", "green");
Response response = client.getLowLevelClient().performRequest("GET", "/_cluster/health", parameters); // <1>
Request request = new Request("GET", "/_cluster/health");
request.addParameter("wait_for_status", "green"); // <1>
Response response = client.getLowLevelClient().performRequest(request); // <2>

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>
try (InputStream is = response.getEntity().getContent()) { // <3>
Map<String, Object> map = XContentHelper.convertToMap(XContentType.JSON.xContent(), is, true); // <4>
healthStatus = ClusterHealthStatus.fromString((String) map.get("status")); // <5>
}

if (healthStatus == ClusterHealthStatus.GREEN) {
// <5>
if (healthStatus != ClusterHealthStatus.GREEN) {
// <6>
}
//end::migration-cluster-health
assertSame(ClusterHealthStatus.GREEN, healthStatus);
Expand Down
82 changes: 7 additions & 75 deletions docs/java-rest/high-level/migration.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
== 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
to the Java High Level REST Client released with the version 5.6.0
of Elasticsearch.

=== Motivations around a new Java client
Expand Down Expand Up @@ -107,9 +107,6 @@ More importantly, the high-level client:
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

Expand Down Expand Up @@ -241,71 +238,6 @@ 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-index]
--------------------------------------------------
<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

Expand All @@ -331,18 +263,18 @@ With the low-level client, the code can be changed to:
--------------------------------------------------
include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-cluster-health]
--------------------------------------------------
<1> Call the cluster's health REST endpoint and wait for the cluster health to become green,
then get 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
<1> Set up the request to wait for the cluster's health to become green if it isn't already.
<2> Make the request and the get back a `Response` object.
<3> Retrieve an `InputStream` object in order to read the response's content
<4> 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`
<5> 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
<6> 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.
Expand Down

0 comments on commit dba07c1

Please sign in to comment.