Skip to content

Commit 9954d4b

Browse files
javannajavanna
committed
[DOCS] add docs for REST high level client index method (#25501)
This commit restructures the existing high level client docs, adapts the existing delete method docs and adds docs for the index method.
1 parent b27383a commit 9954d4b

File tree

9 files changed

+613
-202
lines changed

9 files changed

+613
-202
lines changed

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

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
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.ElasticsearchException;
23+
import org.elasticsearch.action.ActionListener;
24+
import org.elasticsearch.action.DocWriteRequest;
25+
import org.elasticsearch.action.DocWriteResponse;
26+
import org.elasticsearch.action.delete.DeleteRequest;
27+
import org.elasticsearch.action.delete.DeleteResponse;
28+
import org.elasticsearch.action.index.IndexRequest;
29+
import org.elasticsearch.action.index.IndexResponse;
30+
import org.elasticsearch.action.support.WriteRequest;
31+
import org.elasticsearch.action.support.replication.ReplicationResponse;
32+
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
33+
import org.elasticsearch.client.RestHighLevelClient;
34+
import org.elasticsearch.common.unit.TimeValue;
35+
import org.elasticsearch.common.xcontent.XContentBuilder;
36+
import org.elasticsearch.common.xcontent.XContentFactory;
37+
import org.elasticsearch.common.xcontent.XContentType;
38+
import org.elasticsearch.index.VersionType;
39+
import org.elasticsearch.rest.RestStatus;
40+
41+
import java.io.IOException;
42+
import java.util.Date;
43+
import java.util.HashMap;
44+
import java.util.Map;
45+
46+
/**
47+
* This class is used to generate the Java CRUD API documentation.
48+
* You need to wrap your code between two tags like:
49+
* // tag::example[]
50+
* // end::example[]
51+
*
52+
* Where example is your tag name.
53+
*
54+
* Then in the documentation, you can extract what is between tag and end tags with
55+
* ["source","java",subs="attributes,callouts,macros"]
56+
* --------------------------------------------------
57+
* include-tagged::{doc-tests}/CRUDDocumentationIT.java[example]
58+
* --------------------------------------------------
59+
*/
60+
public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
61+
62+
public void testIndex() throws IOException {
63+
RestHighLevelClient client = highLevelClient();
64+
65+
{
66+
//tag::index-request-map
67+
Map<String, Object> jsonMap = new HashMap<>();
68+
jsonMap.put("user", "kimchy");
69+
jsonMap.put("postDate",new Date());
70+
jsonMap.put("message","trying out Elasticsearch");
71+
IndexRequest indexRequest = new IndexRequest("index", "type", "id")
72+
.source(jsonMap); // <1>
73+
//end::index-request-map
74+
IndexResponse indexResponse = client.index(indexRequest);
75+
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.CREATED);
76+
}
77+
{
78+
//tag::index-request-xcontent
79+
XContentBuilder builder = XContentFactory.jsonBuilder();
80+
builder.startObject();
81+
{
82+
builder.field("user", "kimchy");
83+
builder.field("postDate", new Date());
84+
builder.field("message", "trying out Elasticsearch");
85+
}
86+
builder.endObject();
87+
IndexRequest indexRequest = new IndexRequest("index", "type", "id")
88+
.source(builder); // <1>
89+
//end::index-request-xcontent
90+
IndexResponse indexResponse = client.index(indexRequest);
91+
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
92+
}
93+
{
94+
//tag::index-request-shortcut
95+
IndexRequest indexRequest = new IndexRequest("index", "type", "id")
96+
.source("user", "kimchy",
97+
"postDate", new Date(),
98+
"message", "trying out Elasticsearch"); // <1>
99+
//end::index-request-shortcut
100+
IndexResponse indexResponse = client.index(indexRequest);
101+
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
102+
}
103+
{
104+
//tag::index-request-string
105+
IndexRequest request = new IndexRequest(
106+
"index", // <1>
107+
"type", // <2>
108+
"id"); // <3>
109+
String jsonString = "{" +
110+
"\"user\":\"kimchy\"," +
111+
"\"postDate\":\"2013-01-30\"," +
112+
"\"message\":\"trying out Elasticsearch\"" +
113+
"}";
114+
request.source(jsonString, XContentType.JSON); //<4>
115+
//end::index-request-string
116+
117+
// tag::index-execute
118+
IndexResponse indexResponse = client.index(request);
119+
// end::index-execute
120+
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
121+
122+
// tag::index-response
123+
String index = indexResponse.getIndex();
124+
String type = indexResponse.getType();
125+
String id = indexResponse.getId();
126+
long version = indexResponse.getVersion();
127+
if (indexResponse.getResult() == DocWriteResponse.Result.CREATED) {
128+
// <1>
129+
} else if (indexResponse.getResult() == DocWriteResponse.Result.UPDATED) {
130+
// <2>
131+
}
132+
ReplicationResponse.ShardInfo shardInfo = indexResponse.getShardInfo();
133+
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
134+
// <3>
135+
}
136+
if (shardInfo.getFailed() > 0) {
137+
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
138+
String reason = failure.reason(); // <4>
139+
}
140+
}
141+
// end::index-response
142+
143+
// tag::index-execute-async
144+
client.indexAsync(request, new ActionListener<IndexResponse>() {
145+
@Override
146+
public void onResponse(IndexResponse indexResponse) {
147+
// <1>
148+
}
149+
150+
@Override
151+
public void onFailure(Exception e) {
152+
// <2>
153+
}
154+
});
155+
// end::index-execute-async
156+
}
157+
{
158+
IndexRequest request = new IndexRequest("index", "type", "id");
159+
// tag::index-request-routing
160+
request.routing("routing"); // <1>
161+
// end::index-request-routing
162+
// tag::index-request-parent
163+
request.parent("parent"); // <1>
164+
// end::index-request-parent
165+
// tag::index-request-timeout
166+
request.timeout(TimeValue.timeValueSeconds(1)); // <1>
167+
request.timeout("1s"); // <2>
168+
// end::index-request-timeout
169+
// tag::index-request-refresh
170+
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
171+
request.setRefreshPolicy("wait_for"); // <2>
172+
// end::index-request-refresh
173+
// tag::index-request-version
174+
request.version(2); // <1>
175+
// end::index-request-version
176+
// tag::index-request-version-type
177+
request.versionType(VersionType.EXTERNAL); // <1>
178+
// end::index-request-version-type
179+
// tag::index-request-op-type
180+
request.opType(DocWriteRequest.OpType.CREATE); // <1>
181+
request.opType("create"); // <2>
182+
// end::index-request-op-type
183+
// tag::index-request-pipeline
184+
request.setPipeline("pipeline"); // <1>
185+
// end::index-request-pipeline
186+
}
187+
{
188+
// tag::index-conflict
189+
IndexRequest request = new IndexRequest("index", "type", "id")
190+
.source("field", "value")
191+
.version(1);
192+
try {
193+
IndexResponse response = client.index(request);
194+
} catch(ElasticsearchException e) {
195+
if (e.status() == RestStatus.CONFLICT) {
196+
// <1>
197+
}
198+
}
199+
// end::index-conflict
200+
201+
}
202+
{
203+
// tag::index-optype
204+
IndexRequest request = new IndexRequest("index", "type", "id")
205+
.source("field", "value")
206+
.opType(DocWriteRequest.OpType.CREATE);
207+
try {
208+
IndexResponse response = client.index(request);
209+
} catch(ElasticsearchException e) {
210+
if (e.status() == RestStatus.CONFLICT) {
211+
// <1>
212+
}
213+
}
214+
// end::index-optype
215+
}
216+
}
217+
218+
public void testDelete() throws IOException {
219+
RestHighLevelClient client = highLevelClient();
220+
221+
{
222+
IndexRequest indexRequest = new IndexRequest("index", "type", "id").source("field", "value");
223+
IndexResponse indexResponse = client.index(indexRequest);
224+
assertSame(indexResponse.status(), RestStatus.CREATED);
225+
}
226+
227+
{
228+
// tag::delete-request
229+
DeleteRequest request = new DeleteRequest(
230+
"index", // <1>
231+
"type", // <2>
232+
"id"); // <3>
233+
// end::delete-request
234+
235+
// tag::delete-execute
236+
DeleteResponse deleteResponse = client.delete(request);
237+
// end::delete-execute
238+
assertSame(deleteResponse.getResult(), DocWriteResponse.Result.DELETED);
239+
240+
// tag::delete-response
241+
String index = deleteResponse.getIndex();
242+
String type = deleteResponse.getType();
243+
String id = deleteResponse.getId();
244+
long version = deleteResponse.getVersion();
245+
ReplicationResponse.ShardInfo shardInfo = deleteResponse.getShardInfo();
246+
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
247+
//<1>
248+
}
249+
if (shardInfo.getFailed() > 0) {
250+
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
251+
String reason = failure.reason(); // <2>
252+
}
253+
}
254+
// end::delete-response
255+
256+
// tag::delete-execute-async
257+
client.deleteAsync(request, new ActionListener<DeleteResponse>() {
258+
@Override
259+
public void onResponse(DeleteResponse deleteResponse) {
260+
// <1>
261+
}
262+
263+
@Override
264+
public void onFailure(Exception e) {
265+
// <2>
266+
}
267+
});
268+
// end::delete-execute-async
269+
}
270+
271+
{
272+
DeleteRequest request = new DeleteRequest("index", "type", "id");
273+
// tag::delete-request-routing
274+
request.routing("routing"); // <1>
275+
// end::delete-request-routing
276+
// tag::delete-request-parent
277+
request.parent("parent"); // <1>
278+
// end::delete-request-parent
279+
// tag::delete-request-timeout
280+
request.timeout(TimeValue.timeValueMinutes(2)); // <1>
281+
request.timeout("2m"); // <2>
282+
// end::delete-request-timeout
283+
// tag::delete-request-refresh
284+
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
285+
request.setRefreshPolicy("wait_for"); // <2>
286+
// end::delete-request-refresh
287+
// tag::delete-request-version
288+
request.version(2); // <1>
289+
// end::delete-request-version
290+
// tag::delete-request-version-type
291+
request.versionType(VersionType.EXTERNAL); // <1>
292+
// end::delete-request-version-type
293+
}
294+
295+
{
296+
// tag::delete-notfound
297+
DeleteRequest request = new DeleteRequest("index", "type", "does_not_exist");
298+
DeleteResponse deleteResponse = client.delete(request);
299+
if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
300+
// <1>
301+
}
302+
// end::delete-notfound
303+
}
304+
305+
{
306+
IndexResponse indexResponse = client.index(new IndexRequest("index", "type", "id").source("field", "value"));
307+
assertSame(indexResponse.status(), RestStatus.CREATED);
308+
309+
// tag::delete-conflict
310+
try {
311+
DeleteRequest request = new DeleteRequest("index", "type", "id").version(2);
312+
DeleteResponse deleteResponse = client.delete(request);
313+
} catch (ElasticsearchException exception) {
314+
if (exception.status() == RestStatus.CONFLICT) {
315+
// <1>
316+
}
317+
}
318+
// end::delete-conflict
319+
}
320+
}
321+
}

0 commit comments

Comments
 (0)