Skip to content

Commit 96862b9

Browse files
author
Christoph Büscher
committed
[Docs] Fix Java Api index administration usage (#28260)
The Java API documentation for index administration currenty is wrong because the PutMappingRequestBuilder#setSource(Object... source) an CreateIndexRequestBuilder#addMapping(String type, Object... source) methods delegate to methods that check that the input arguments are valid key/value pairs. 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 42d9bbf commit 96862b9

File tree

3 files changed

+115
-49
lines changed

3 files changed

+115
-49
lines changed

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

Lines changed: 6 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,52 +3,19 @@
33

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

6-
[source,java]
6+
["source","java",subs="attributes,callouts,macros"]
77
--------------------------------------------------
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();
8+
include-tagged::{client-tests}/IndicesDocumentationIT.java[index-with-mapping]
199
--------------------------------------------------
2010
<1> <<java-admin-indices-create-index,Creates an index>> called `twitter`
2111
<2> It also adds a `tweet` mapping type.
2212

2313

2414
The PUT mapping API also allows to add a new type to an existing index:
2515

26-
[source,java]
16+
["source","java",subs="attributes,callouts,macros"]
2717
--------------------------------------------------
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();
18+
include-tagged::{client-tests}/IndicesDocumentationIT.java[putMapping-request-source]
5219
--------------------------------------------------
5320
<1> Puts a mapping on existing index called `twitter`
5421
<2> Adds a `user` mapping type.
@@ -57,20 +24,10 @@ client.admin().indices().preparePutMapping("twitter")
5724

5825
You can use the same API to update an existing mapping:
5926

60-
[source,java]
27+
["source","java",subs="attributes,callouts,macros"]
6128
--------------------------------------------------
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();
29+
include-tagged::{client-tests}/IndicesDocumentationIT.java[putMapping-request-source-append]
7230
--------------------------------------------------
7331
<1> Puts a mapping on existing index called `twitter`
7432
<2> Updates the `user` mapping type.
7533
<3> This `user` has now a new field `user_name`
76-

‎docs/java-api/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,8 @@ and add it as a dependency. As an example, we will use the `slf4j-simple` logger
150150
</dependency>
151151
--------------------------------------------------
152152

153+
:client-tests: {docdir}/../../server/src/test/java/org/elasticsearch/client/documentation
154+
153155
include::client.asciidoc[]
154156

155157
include::docs.asciidoc[]

‎server/src/test/java/org/elasticsearch/client/documentation/IndicesDocumentationIT.java

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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.client.Client;
23+
import org.elasticsearch.common.xcontent.XContentType;
24+
import org.elasticsearch.test.ESIntegTestCase;
25+
26+
/**
27+
* This class is used to generate the Java indices administration documentation.
28+
* You need to wrap your code between two tags like:
29+
* // tag::example[]
30+
* // end::example[]
31+
*
32+
* Where example is your tag name.
33+
*
34+
* Then in the documentation, you can extract what is between tag and end tags
35+
* with ["source","java",subs="attributes,callouts,macros"]
36+
* --------------------------------------------------
37+
* include-tagged::{client-tests}/IndicesDocumentationIT.java[your-example-tag-here]
38+
* --------------------------------------------------
39+
*/
40+
public class IndicesDocumentationIT extends ESIntegTestCase {
41+
42+
/**
43+
* This test method is used to generate the Put Mapping Java Indices API documentation
44+
* at "docs/java-api/admin/indices/put-mapping.asciidoc" so the documentation gets tested
45+
* so that it compiles and runs without throwing errors at runtime.
46+
*/
47+
public void testPutMappingDocumentation() throws Exception {
48+
Client client = client();
49+
50+
// tag::index-with-mapping
51+
client.admin().indices().prepareCreate("twitter") // <1>
52+
.addMapping("\"tweet\": {\n" + // <2>
53+
" \"properties\": {\n" +
54+
" \"message\": {\n" +
55+
" \"type\": \"text\"\n" +
56+
" }\n" +
57+
" }\n" +
58+
"}")
59+
.get();
60+
// end::index-with-mapping
61+
62+
// we need to delete in order to create a fresh new index with another type
63+
client.admin().indices().prepareDelete("twitter").get();
64+
client.admin().indices().prepareCreate("twitter").get();
65+
66+
// tag::putMapping-request-source
67+
client.admin().indices().preparePutMapping("twitter") // <1>
68+
.setType("user") // <2>
69+
.setSource("{\n" + // <3>
70+
" \"properties\": {\n" +
71+
" \"name\": {\n" +
72+
" \"type\": \"text\"\n" +
73+
" }\n" +
74+
" }\n" +
75+
"}", XContentType.JSON)
76+
.get();
77+
78+
// You can also provide the type in the source document
79+
client.admin().indices().preparePutMapping("twitter")
80+
.setType("user")
81+
.setSource("{\n" +
82+
" \"user\":{\n" + // <4>
83+
" \"properties\": {\n" +
84+
" \"name\": {\n" +
85+
" \"type\": \"text\"\n" +
86+
" }\n" +
87+
" }\n" +
88+
" }\n" +
89+
"}", XContentType.JSON)
90+
.get();
91+
// end::putMapping-request-source
92+
93+
// tag::putMapping-request-source-append
94+
client.admin().indices().preparePutMapping("twitter") // <1>
95+
.setType("user") // <2>
96+
.setSource("{\n" + // <3>
97+
" \"properties\": {\n" +
98+
" \"user_name\": {\n" +
99+
" \"type\": \"text\"\n" +
100+
" }\n" +
101+
" }\n" +
102+
"}", XContentType.JSON)
103+
.get();
104+
// end::putMapping-request-source-append
105+
}
106+
107+
}

0 commit comments

Comments
 (0)