Skip to content

Commit 564e174

Browse files
author
Christoph Büscher
committed
[Docs] Fix Java Api index administration usage (#28133)
The Java API documentation for index administration currenty is wrong because the PutMappingRequestBuilder#setSource(Object... source) and CreateIndexRequestBuilder#addMapping(String type, Object... source) methods delegate to methods that check that the input arguments are valid key/value pairs: https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/java-admin-indices.html This changes the docs so the java api code examples are included from documentation integration tests so we detect compile and runtime issues earlier. Closes #28131
1 parent c281e80 commit 564e174

File tree

2 files changed

+77
-48
lines changed

2 files changed

+77
-48
lines changed

‎core/src/test/java/org/elasticsearch/action/admin/indices/create/CreateIndexIT.java

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,14 @@
2626
import org.elasticsearch.action.search.SearchResponse;
2727
import org.elasticsearch.action.support.ActiveShardCount;
2828
import org.elasticsearch.action.support.IndicesOptions;
29+
import org.elasticsearch.client.Client;
2930
import org.elasticsearch.cluster.ClusterState;
3031
import org.elasticsearch.cluster.metadata.IndexMetaData;
3132
import org.elasticsearch.cluster.metadata.MetaData;
3233
import org.elasticsearch.common.collect.ImmutableOpenMap;
3334
import org.elasticsearch.common.settings.Settings;
3435
import org.elasticsearch.common.unit.TimeValue;
36+
import org.elasticsearch.common.xcontent.XContentType;
3537
import org.elasticsearch.index.IndexNotFoundException;
3638
import org.elasticsearch.index.query.RangeQueryBuilder;
3739
import org.elasticsearch.test.ESIntegTestCase;
@@ -343,4 +345,70 @@ public void testIndexNameInResponse() {
343345

344346
assertEquals("Should have index name in response", "foo", response.index());
345347
}
348+
349+
/**
350+
* This test method is used to generate the Put Mapping Java Indices API documentation
351+
* at "docs/java-api/admin/indices/put-mapping.asciidoc" so the documentation gets tested
352+
* so that it compiles and runs without throwing errors at runtime.
353+
*/
354+
public void testPutMappingDocumentation() throws Exception {
355+
Client client = client();
356+
// tag::addMapping-create-index-request
357+
client.admin().indices().prepareCreate("twitter") // <1>
358+
.addMapping("tweet", "{\n" + // <2>
359+
" \"tweet\": {\n" +
360+
" \"properties\": {\n" +
361+
" \"message\": {\n" +
362+
" \"type\": \"text\"\n" +
363+
" }\n" +
364+
" }\n" +
365+
" }\n" +
366+
" }", XContentType.JSON)
367+
.get();
368+
// end::addMapping-create-index-request
369+
370+
// we need to delete in order to create a fresh new index with another type
371+
client.admin().indices().prepareDelete("twitter").get();
372+
client.admin().indices().prepareCreate("twitter").get();
373+
374+
// tag::putMapping-request-source
375+
client.admin().indices().preparePutMapping("twitter") // <1>
376+
.setType("user") // <2>
377+
.setSource("{\n" + // <3>
378+
" \"properties\": {\n" +
379+
" \"name\": {\n" +
380+
" \"type\": \"text\"\n" +
381+
" }\n" +
382+
" }\n" +
383+
"}", XContentType.JSON)
384+
.get();
385+
386+
// You can also provide the type in the source document
387+
client.admin().indices().preparePutMapping("twitter")
388+
.setType("user")
389+
.setSource("{\n" +
390+
" \"user\":{\n" + // <4>
391+
" \"properties\": {\n" +
392+
" \"name\": {\n" +
393+
" \"type\": \"text\"\n" +
394+
" }\n" +
395+
" }\n" +
396+
" }\n" +
397+
"}", XContentType.JSON)
398+
.get();
399+
// end::putMapping-request-source
400+
401+
// tag::putMapping-request-source-append
402+
client.admin().indices().preparePutMapping("twitter") // <1>
403+
.setType("user") // <2>
404+
.setSource("{\n" + // <3>
405+
" \"properties\": {\n" +
406+
" \"user_name\": {\n" +
407+
" \"type\": \"text\"\n" +
408+
" }\n" +
409+
" }\n" +
410+
"}", XContentType.JSON)
411+
.get();
412+
// end::putMapping-request-source-append
413+
}
346414
}

‎docs/java-api/admin/indices/put-mapping.asciidoc

Lines changed: 9 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,23 @@
11
[[java-admin-indices-put-mapping]]
2+
:base-dir: {docdir}/../../core/src/test/java/org/elasticsearch/action/admin/indices/create
3+
24
==== Put Mapping
35

46
The PUT mapping API allows you to add a new type while creating an index:
57

6-
[source,java]
8+
["source","java",subs="attributes,callouts,macros"]
79
--------------------------------------------------
8-
client.admin().indices().prepareCreate("twitter") <1>
9-
.addMapping("tweet", "{\n" + <2>
10-
" \"tweet\": {\n" +
11-
" \"properties\": {\n" +
12-
" \"message\": {\n" +
13-
" \"type\": \"text\"\n" +
14-
" }\n" +
15-
" }\n" +
16-
" }\n" +
17-
" }")
18-
.get();
10+
include-tagged::{base-dir}/CreateIndexIT.java[addMapping-create-index-request]
1911
--------------------------------------------------
2012
<1> <<java-admin-indices-create-index,Creates an index>> called `twitter`
2113
<2> It also adds a `tweet` mapping type.
2214

2315

2416
The PUT mapping API also allows to add a new type to an existing index:
2517

26-
[source,java]
18+
["source","java",subs="attributes,callouts,macros"]
2719
--------------------------------------------------
28-
client.admin().indices().preparePutMapping("twitter") <1>
29-
.setType("user") <2>
30-
.setSource("{\n" + <3>
31-
" \"properties\": {\n" +
32-
" \"name\": {\n" +
33-
" \"type\": \"text\"\n" +
34-
" }\n" +
35-
" }\n" +
36-
"}")
37-
.get();
38-
39-
// You can also provide the type in the source document
40-
client.admin().indices().preparePutMapping("twitter")
41-
.setType("user")
42-
.setSource("{\n" +
43-
" \"user\":{\n" + <4>
44-
" \"properties\": {\n" +
45-
" \"name\": {\n" +
46-
" \"type\": \"text\"\n" +
47-
" }\n" +
48-
" }\n" +
49-
" }\n" +
50-
"}")
51-
.get();
20+
include-tagged::{base-dir}/CreateIndexIT.java[putMapping-request-source]
5221
--------------------------------------------------
5322
<1> Puts a mapping on existing index called `twitter`
5423
<2> Adds a `user` mapping type.
@@ -57,20 +26,12 @@ client.admin().indices().preparePutMapping("twitter")
5726

5827
You can use the same API to update an existing mapping:
5928

60-
[source,java]
29+
["source","java",subs="attributes,callouts,macros"]
6130
--------------------------------------------------
62-
client.admin().indices().preparePutMapping("twitter") <1>
63-
.setType("user") <2>
64-
.setSource("{\n" + <3>
65-
" \"properties\": {\n" +
66-
" \"user_name\": {\n" +
67-
" \"type\": \"text\"\n" +
68-
" }\n" +
69-
" }\n" +
70-
"}")
71-
.get();
31+
include-tagged::{base-dir}/CreateIndexIT.java[putMapping-request-source-append]
7232
--------------------------------------------------
7333
<1> Puts a mapping on existing index called `twitter`
7434
<2> Updates the `user` mapping type.
7535
<3> This `user` has now a new field `user_name`
7636

37+
:base-dir!:

0 commit comments

Comments
 (0)