Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Update HighLevelRestClient migration docs #30544

Merged
merged 1 commit into from
May 14, 2018
Merged

Docs: Update HighLevelRestClient migration docs #30544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 9 additions & 44 deletions ...-level/src/test/java/org/elasticsearch/client/documentation/MigrationDocumentationIT.java
View file
Open in desktop
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
Open in desktop
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