Skip to content

Commit f712a9f

Browse files
tlrxtlrx
committed
[Docs] Add migration notes for the high-level rest client (#25911)
1 parent 1db52b4 commit f712a9f

File tree

13 files changed

+685
-8
lines changed

13 files changed

+685
-8
lines changed

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,9 @@
1919

2020
package org.elasticsearch.client.documentation;
2121

22-
import org.elasticsearch.client.http.HttpEntity;
23-
import org.elasticsearch.client.http.client.methods.HttpPost;
24-
import org.elasticsearch.client.http.entity.ContentType;
25-
import org.elasticsearch.client.http.nio.entity.NStringEntity;
22+
import org.elasticsearch.Build;
2623
import org.elasticsearch.ElasticsearchException;
24+
import org.elasticsearch.Version;
2725
import org.elasticsearch.action.ActionListener;
2826
import org.elasticsearch.action.DocWriteRequest;
2927
import org.elasticsearch.action.DocWriteResponse;
@@ -38,6 +36,7 @@
3836
import org.elasticsearch.action.get.GetResponse;
3937
import org.elasticsearch.action.index.IndexRequest;
4038
import org.elasticsearch.action.index.IndexResponse;
39+
import org.elasticsearch.action.main.MainResponse;
4140
import org.elasticsearch.action.support.ActiveShardCount;
4241
import org.elasticsearch.action.support.WriteRequest;
4342
import org.elasticsearch.action.support.replication.ReplicationResponse;
@@ -46,6 +45,11 @@
4645
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
4746
import org.elasticsearch.client.Response;
4847
import org.elasticsearch.client.RestHighLevelClient;
48+
import org.elasticsearch.client.http.HttpEntity;
49+
import org.elasticsearch.client.http.client.methods.HttpPost;
50+
import org.elasticsearch.client.http.entity.ContentType;
51+
import org.elasticsearch.client.http.nio.entity.NStringEntity;
52+
import org.elasticsearch.cluster.ClusterName;
4953
import org.elasticsearch.common.Strings;
5054
import org.elasticsearch.common.settings.Settings;
5155
import org.elasticsearch.common.unit.ByteSizeUnit;

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.elasticsearch.client.documentation;
21+
22+
import org.elasticsearch.Build;
23+
import org.elasticsearch.Version;
24+
import org.elasticsearch.action.main.MainResponse;
25+
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
26+
import org.elasticsearch.client.RestHighLevelClient;
27+
import org.elasticsearch.cluster.ClusterName;
28+
29+
import java.io.IOException;
30+
31+
/**
32+
* This class is used to generate the Java Main API documentation.
33+
* You need to wrap your code between two tags like:
34+
* // tag::example[]
35+
* // end::example[]
36+
*
37+
* Where example is your tag name.
38+
*
39+
* Then in the documentation, you can extract what is between tag and end tags with
40+
* ["source","java",subs="attributes,callouts,macros"]
41+
* --------------------------------------------------
42+
* include-tagged::{doc-tests}/MainDocumentationIT.java[example]
43+
* --------------------------------------------------
44+
*/
45+
public class MainDocumentationIT extends ESRestHighLevelClientTestCase {
46+
47+
public void testMain() throws IOException {
48+
RestHighLevelClient client = highLevelClient();
49+
{
50+
//tag::main-execute
51+
MainResponse response = client.info();
52+
//end::main-execute
53+
assertTrue(response.isAvailable());
54+
//tag::main-response
55+
ClusterName clusterName = response.getClusterName(); // <1>
56+
String clusterUuid = response.getClusterUuid(); // <2>
57+
String nodeName = response.getNodeName(); // <3>
58+
Version version = response.getVersion(); // <4>
59+
Build build = response.getBuild(); // <5>
60+
//end::main-response
61+
assertNotNull(clusterName);
62+
assertNotNull(clusterUuid);
63+
assertNotNull(nodeName);
64+
assertNotNull(version);
65+
assertNotNull(build);
66+
}
67+
}
68+
}

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationDocumentationIT.java‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.elasticsearch.client.documentation;
21+
22+
import org.elasticsearch.action.ActionListener;
23+
import org.elasticsearch.action.delete.DeleteRequest;
24+
import org.elasticsearch.action.delete.DeleteResponse;
25+
import org.elasticsearch.action.index.IndexRequest;
26+
import org.elasticsearch.action.index.IndexRequestBuilder;
27+
import org.elasticsearch.action.index.IndexResponse;
28+
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
29+
import org.elasticsearch.client.Response;
30+
import org.elasticsearch.client.RestClient;
31+
import org.elasticsearch.client.RestHighLevelClient;
32+
import org.elasticsearch.client.http.HttpEntity;
33+
import org.elasticsearch.client.http.HttpStatus;
34+
import org.elasticsearch.client.http.entity.ContentType;
35+
import org.elasticsearch.client.http.nio.entity.NStringEntity;
36+
import org.elasticsearch.cluster.health.ClusterHealthStatus;
37+
import org.elasticsearch.common.settings.Settings;
38+
import org.elasticsearch.common.xcontent.XContentFactory;
39+
import org.elasticsearch.common.xcontent.XContentHelper;
40+
import org.elasticsearch.common.xcontent.XContentType;
41+
import org.elasticsearch.rest.RestStatus;
42+
43+
import java.io.IOException;
44+
import java.io.InputStream;
45+
import java.util.Map;
46+
47+
import static java.util.Collections.emptyMap;
48+
import static org.elasticsearch.cluster.metadata.IndexMetaData.SETTING_NUMBER_OF_REPLICAS;
49+
import static org.elasticsearch.cluster.metadata.IndexMetaData.SETTING_NUMBER_OF_SHARDS;
50+
51+
/**
52+
* This class is used to generate the documentation for the
53+
* docs/java-rest/high-level/migration.asciidoc page.
54+
*
55+
* You need to wrap your code between two tags like:
56+
* // tag::example[]
57+
* // end::example[]
58+
*
59+
* Where example is your tag name.
60+
*
61+
* Then in the documentation, you can extract what is between tag and end tags with
62+
* ["source","java",subs="attributes,callouts,macros"]
63+
* --------------------------------------------------
64+
* include-tagged::{doc-tests}/MigrationDocumentationIT.java[example]
65+
* --------------------------------------------------
66+
*/
67+
public class MigrationDocumentationIT extends ESRestHighLevelClientTestCase {
68+
69+
public void testCreateIndex() throws IOException {
70+
RestClient restClient = client();
71+
{
72+
//tag::migration-create-inded
73+
Settings indexSettings = Settings.builder() // <1>
74+
.put(SETTING_NUMBER_OF_SHARDS, 1)
75+
.put(SETTING_NUMBER_OF_REPLICAS, 0)
76+
.build();
77+
78+
String payload = XContentFactory.jsonBuilder() // <2>
79+
.startObject()
80+
.startObject("settings") // <3>
81+
.value(indexSettings)
82+
.endObject()
83+
.startObject("mappings") // <4>
84+
.startObject("doc")
85+
.startObject("properties")
86+
.startObject("time")
87+
.field("type", "date")
88+
.endObject()
89+
.endObject()
90+
.endObject()
91+
.endObject()
92+
.endObject().string();
93+
94+
HttpEntity entity = new NStringEntity(payload, ContentType.APPLICATION_JSON); // <5>
95+
96+
Response response = restClient.performRequest("PUT", "my-index", emptyMap(), entity); // <6>
97+
if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
98+
// <7>
99+
}
100+
//end::migration-create-inded
101+
assertEquals(200, response.getStatusLine().getStatusCode());
102+
}
103+
}
104+
105+
public void testClusterHealth() throws IOException {
106+
RestClient restClient = client();
107+
{
108+
//tag::migration-cluster-health
109+
Response response = restClient.performRequest("GET", "/_cluster/health"); // <1>
110+
111+
ClusterHealthStatus healthStatus;
112+
try (InputStream is = response.getEntity().getContent()) { // <2>
113+
Map<String, Object> map = XContentHelper.convertToMap(XContentType.JSON.xContent(), is, true); // <3>
114+
healthStatus = ClusterHealthStatus.fromString((String) map.get("status")); // <4>
115+
}
116+
117+
if (healthStatus == ClusterHealthStatus.GREEN) {
118+
// <5>
119+
}
120+
//end::migration-cluster-health
121+
assertSame(ClusterHealthStatus.GREEN, healthStatus);
122+
}
123+
}
124+
125+
public void testRequests() throws IOException {
126+
RestHighLevelClient client = highLevelClient();
127+
{
128+
//tag::migration-request-ctor
129+
IndexRequest request = new IndexRequest("index", "doc", "id"); // <1>
130+
request.source("{\"field\":\"value\"}", XContentType.JSON);
131+
//end::migration-request-ctor
132+
133+
//tag::migration-request-ctor-execution
134+
IndexResponse response = client.index(request);
135+
//end::migration-request-ctor-execution
136+
assertEquals(RestStatus.CREATED, response.status());
137+
}
138+
{
139+
//tag::migration-request-sync-execution
140+
DeleteRequest request = new DeleteRequest("index", "doc", "id");
141+
DeleteResponse response = client.delete(request); // <1>
142+
//end::migration-request-sync-execution
143+
assertEquals(RestStatus.OK, response.status());
144+
}
145+
{
146+
//tag::migration-request-async-execution
147+
DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
148+
client.deleteAsync(request, new ActionListener<DeleteResponse>() { // <2>
149+
@Override
150+
public void onResponse(DeleteResponse deleteResponse) {
151+
// <3>
152+
}
153+
154+
@Override
155+
public void onFailure(Exception e) {
156+
// <4>
157+
}
158+
});
159+
//end::migration-request-async-execution
160+
}
161+
}
162+
}

‎docs/java-api/client.asciidoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ cluster.
2323
2424
==============================
2525

26+
WARNING: The `TransportClient` is aimed to be replaced by the Java High Level REST
27+
Client, which executes HTTP requests instead of serialized Java requests. The
28+
`TransportClient` will be deprecated in upcoming versions of Elasticsearch and it
29+
is advised to use the Java High Level REST Client instead.
2630

2731
[[transport-client]]
2832
=== Transport Client

‎docs/java-api/index.asciidoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ Additionally, operations on a client may be accumulated and executed in
1717
Note, all the APIs are exposed through the
1818
Java API (actually, the Java API is used internally to execute them).
1919

20+
WARNING: Starting from version 5.6.0, a new Java client has been
21+
released: the {java-rest}/java-rest-high.html[Java High Level REST Client].
22+
This new client is designed to replace the `TransportClient` in Java
23+
applications which will be deprecated in future versions of Elasticsearch.
24+
25+
== Javadoc
26+
27+
The javadoc for the transport client can be found at {transport-client-javadoc}/index.html.
2028

2129
== Maven Repository
2230

‎docs/java-rest/high-level/apis.asciidoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
[[java-rest-high-supported-apis]]
12
== Supported APIs
23

34
The Java High Level REST Client supports the following APIs:
@@ -15,3 +16,6 @@ The Java High Level REST Client supports the following APIs:
1516
* <<java-rest-high-search>>
1617
* <<java-rest-high-search-scroll>>
1718
* <<java-rest-high-clear-scroll>>
19+
20+
.Miscellaneous APIs
21+
* <<java-rest-high-main>>

‎docs/java-rest/high-level/apis/index.asciidoc‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,8 @@
1-
:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
2-
31
include::_index.asciidoc[]
42
include::get.asciidoc[]
53
include::delete.asciidoc[]
64
include::update.asciidoc[]
75
include::bulk.asciidoc[]
86
include::search.asciidoc[]
97
include::scroll.asciidoc[]
10-
11-
:doc-tests!:
8+
include::main.asciidoc[]

‎docs/java-rest/high-level/apis/main.asciidoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[[java-rest-high-main]]
2+
=== Info API
3+
4+
[[java-rest-high-main-request]]
5+
==== Execution
6+
7+
Cluster information can be retrieved using the `info()` method:
8+
9+
["source","java",subs="attributes,callouts,macros"]
10+
--------------------------------------------------
11+
include-tagged::{doc-tests}/MainDocumentationIT.java[main-execute]
12+
--------------------------------------------------
13+
14+
[[java-rest-high-main-response]]
15+
==== Response
16+
17+
The returned `MainResponse` provides various kinds of information about the cluster:
18+
19+
["source","java",subs="attributes,callouts,macros"]
20+
--------------------------------------------------
21+
include-tagged::{doc-tests}/MainDocumentationIT.java[main-response]
22+
--------------------------------------------------
23+
<1> Retrieve the name of the cluster as a `ClusterName`
24+
<2> Retrieve the unique identifier of the cluster
25+
<3> Retrieve the name of the node the request has been executed on
26+
<4> Retrieve the version of the node the request has been executed on
27+
<5> Retrieve the build information of the node the request has been executed on

‎docs/java-rest/high-level/index.asciidoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,16 @@ the same response objects.
2020

2121
--
2222

23+
:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
24+
2325
include::usage.asciidoc[]
2426

2527
include::apis.asciidoc[]
2628

2729
include::apis/index.asciidoc[]
2830

31+
include::migration.asciidoc[]
32+
2933
include::../license.asciidoc[]
34+
35+
:doc-tests!:

0 commit comments

Comments
 (0)