Skip to content

Commit 0ff3ece

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 f535d96 commit 0ff3ece

File tree

2 files changed

+77
-48
lines changed

2 files changed

+77
-48
lines changed

‎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!:

‎server/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
@@ -20,6 +20,7 @@
2020
package org.elasticsearch.action.admin.indices.create;
2121

2222
import com.carrotsearch.hppc.cursors.ObjectCursor;
23+
2324
import org.elasticsearch.ElasticsearchException;
2425
import org.elasticsearch.action.ActionListener;
2526
import org.elasticsearch.action.UnavailableShardsException;
@@ -28,13 +29,15 @@
2829
import org.elasticsearch.action.search.SearchResponse;
2930
import org.elasticsearch.action.support.ActiveShardCount;
3031
import org.elasticsearch.action.support.IndicesOptions;
32+
import org.elasticsearch.client.Client;
3133
import org.elasticsearch.cluster.ClusterState;
3234
import org.elasticsearch.cluster.metadata.IndexMetaData;
3335
import org.elasticsearch.cluster.metadata.MetaData;
3436
import org.elasticsearch.cluster.node.DiscoveryNode;
3537
import org.elasticsearch.common.collect.ImmutableOpenMap;
3638
import org.elasticsearch.common.settings.Settings;
3739
import org.elasticsearch.common.unit.TimeValue;
40+
import org.elasticsearch.common.xcontent.XContentType;
3841
import org.elasticsearch.env.NodeEnvironment;
3942
import org.elasticsearch.index.IndexNotFoundException;
4043
import org.elasticsearch.index.query.RangeQueryBuilder;
@@ -399,4 +402,69 @@ public Settings onNodeStopped(String nodeName) throws Exception {
399402
assertThat(e, hasToString(containsString("unknown setting [index.foo]")));
400403
}
401404

405+
/**
406+
* This test method is used to generate the Put Mapping Java Indices API documentation
407+
* at "docs/java-api/admin/indices/put-mapping.asciidoc" so the documentation gets tested
408+
* so that it compiles and runs without throwing errors at runtime.
409+
*/
410+
public void testPutMappingDocumentation() throws Exception {
411+
Client client = client();
412+
// tag::addMapping-create-index-request
413+
client.admin().indices().prepareCreate("twitter") // <1>
414+
.addMapping("tweet", "{\n" + // <2>
415+
" \"tweet\": {\n" +
416+
" \"properties\": {\n" +
417+
" \"message\": {\n" +
418+
" \"type\": \"text\"\n" +
419+
" }\n" +
420+
" }\n" +
421+
" }\n" +
422+
" }", XContentType.JSON)
423+
.get();
424+
// end::addMapping-create-index-request
425+
426+
// we need to delete in order to create a fresh new index with another type
427+
client.admin().indices().prepareDelete("twitter").get();
428+
client.admin().indices().prepareCreate("twitter").get();
429+
430+
// tag::putMapping-request-source
431+
client.admin().indices().preparePutMapping("twitter") // <1>
432+
.setType("user") // <2>
433+
.setSource("{\n" + // <3>
434+
" \"properties\": {\n" +
435+
" \"name\": {\n" +
436+
" \"type\": \"text\"\n" +
437+
" }\n" +
438+
" }\n" +
439+
"}", XContentType.JSON)
440+
.get();
441+
442+
// You can also provide the type in the source document
443+
client.admin().indices().preparePutMapping("twitter")
444+
.setType("user")
445+
.setSource("{\n" +
446+
" \"user\":{\n" + // <4>
447+
" \"properties\": {\n" +
448+
" \"name\": {\n" +
449+
" \"type\": \"text\"\n" +
450+
" }\n" +
451+
" }\n" +
452+
" }\n" +
453+
"}", XContentType.JSON)
454+
.get();
455+
// end::putMapping-request-source
456+
457+
// tag::putMapping-request-source-append
458+
client.admin().indices().preparePutMapping("twitter") // <1>
459+
.setType("user") // <2>
460+
.setSource("{\n" + // <3>
461+
" \"properties\": {\n" +
462+
" \"user_name\": {\n" +
463+
" \"type\": \"text\"\n" +
464+
" }\n" +
465+
" }\n" +
466+
"}", XContentType.JSON)
467+
.get();
468+
// end::putMapping-request-source-append
469+
}
402470
}

0 commit comments

Comments
 (0)