[DOCS] expand examples on providing mappings for create index and put mapping (#28483)

* [DOCS] expand examples on providing mappings for create index and put mapping

The create index API and put mappings API docs the for high-level Java REST client didn't have a lot of info on how to provide mappings. This commit adds some examples.

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

@@ -46,10 +46,14 @@ import org.elasticsearch.client.ESRestHighLevelClientTestCase;
 import org.elasticsearch.client.RestHighLevelClient;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.common.xcontent.XContentFactory;
 import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.index.query.QueryBuilders;
 import org.elasticsearch.rest.RestStatus;
 
 import java.io.IOException;
+import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
@@ -172,6 +176,7 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             );
             // end::create-index-request-settings
 
+            {
                 // tag::create-index-request-mappings
                 request.mapping("tweet", // <1>
                         "{\n" +
@@ -185,11 +190,64 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                         "}", // <2>
                         XContentType.JSON);
                 // end::create-index-request-mappings
+                CreateIndexResponse createIndexResponse = client.indices().create(request);
+                assertTrue(createIndexResponse.isAcknowledged());
+            }
 
+            {
+                request = new CreateIndexRequest("twitter2");
+                //tag::create-index-mappings-map
+                Map<String, Object> jsonMap = new HashMap<>();
+                Map<String, Object> message = new HashMap<>();
+                message.put("type", "text");
+                Map<String, Object> properties = new HashMap<>();
+                properties.put("message", message);
+                Map<String, Object> tweet = new HashMap<>();
+                tweet.put("properties", properties);
+                jsonMap.put("tweet", tweet);
+                request.mapping("tweet", jsonMap); // <1>
+                //end::create-index-mappings-map
+                CreateIndexResponse createIndexResponse = client.indices().create(request);
+                assertTrue(createIndexResponse.isAcknowledged());
+            }
+            {
+                request = new CreateIndexRequest("twitter3");
+                //tag::create-index-mappings-xcontent
+                XContentBuilder builder = XContentFactory.jsonBuilder();
+                builder.startObject();
+                {
+                    builder.startObject("tweet");
+                    {
+                        builder.startObject("properties");
+                        {
+                            builder.startObject("message");
+                            {
+                                builder.field("type", "text");
+                            }
+                            builder.endObject();
+                        }
+                        builder.endObject();
+                    }
+                    builder.endObject();
+                }
+                builder.endObject();
+                request.mapping("tweet", builder); // <1>
+                //end::create-index-mappings-xcontent
+                CreateIndexResponse createIndexResponse = client.indices().create(request);
+                assertTrue(createIndexResponse.isAcknowledged());
+            }
+            {
+                request = new CreateIndexRequest("twitter4");
+                //tag::create-index-mappings-shortcut
+                request.mapping("tweet", "message", "type=text"); // <1>
+                //end::create-index-mappings-shortcut
+                CreateIndexResponse createIndexResponse = client.indices().create(request);
+                assertTrue(createIndexResponse.isAcknowledged());
+            }
+
+            request = new CreateIndexRequest("twitter5");
             // tag::create-index-request-aliases
-            request.alias(
+            request.alias(new Alias("twitter_alias").filter(QueryBuilders.termQuery("user", "kimchy")));  // <1>
-                new Alias("twitter_alias")  // <1>
-            );
             // end::create-index-request-aliases
 
             // tag::create-index-request-timeout
@@ -204,6 +262,30 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             request.waitForActiveShards(2); // <1>
             request.waitForActiveShards(ActiveShardCount.DEFAULT); // <2>
             // end::create-index-request-waitForActiveShards
+            {
+                CreateIndexResponse createIndexResponse = client.indices().create(request);
+                assertTrue(createIndexResponse.isAcknowledged());
+            }
+
+            request = new CreateIndexRequest("twitter6");
+            // tag::create-index-whole-source
+            request.source("{\n" +
+                    "    \"settings\" : {\n" +
+                    "        \"number_of_shards\" : 1,\n" +
+                    "        \"number_of_replicas\" : 0\n" +
+                    "    },\n" +
+                    "    \"mappings\" : {\n" +
+                    "        \"tweet\" : {\n" +
+                    "            \"properties\" : {\n" +
+                    "                \"message\" : { \"type\" : \"text\" }\n" +
+                    "            }\n" +
+                    "        }\n" +
+                    "    },\n" +
+                    "    \"aliases\" : {\n" +
+                    "        \"twitter_alias\" : {}\n" +
+                    "    }\n" +
+                    "}", XContentType.JSON); // <1>
+            // end::create-index-whole-source
 
             // tag::create-index-execute
             CreateIndexResponse createIndexResponse = client.indices().create(request);
@@ -279,6 +361,54 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 XContentType.JSON);
             // end::put-mapping-request-source
 
+            {
+                //tag::put-mapping-map
+                Map<String, Object> jsonMap = new HashMap<>();
+                Map<String, Object> message = new HashMap<>();
+                message.put("type", "text");
+                Map<String, Object> properties = new HashMap<>();
+                properties.put("message", message);
+                Map<String, Object> tweet = new HashMap<>();
+                tweet.put("properties", properties);
+                jsonMap.put("tweet", tweet);
+                request.source(jsonMap); // <1>
+                //end::put-mapping-map
+                PutMappingResponse putMappingResponse = client.indices().putMapping(request);
+                assertTrue(putMappingResponse.isAcknowledged());
+            }
+            {
+                //tag::put-mapping-xcontent
+                XContentBuilder builder = XContentFactory.jsonBuilder();
+                builder.startObject();
+                {
+                    builder.startObject("tweet");
+                    {
+                        builder.startObject("properties");
+                        {
+                            builder.startObject("message");
+                            {
+                                builder.field("type", "text");
+                            }
+                            builder.endObject();
+                        }
+                        builder.endObject();
+                    }
+                    builder.endObject();
+                }
+                builder.endObject();
+                request.source(builder); // <1>
+                //end::put-mapping-xcontent
+                PutMappingResponse putMappingResponse = client.indices().putMapping(request);
+                assertTrue(putMappingResponse.isAcknowledged());
+            }
+            {
+                //tag::put-mapping-shortcut
+                request.source("message", "type=text"); // <1>
+                //end::put-mapping-shortcut
+                PutMappingResponse putMappingResponse = client.indices().putMapping(request);
+                assertTrue(putMappingResponse.isAcknowledged());
+            }
+
             // tag::put-mapping-request-timeout
             request.timeout(TimeValue.timeValueMinutes(2)); // <1>
             request.timeout("2m"); // <2>

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

@@ -16,7 +16,8 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-string]
 <4> Document source provided as a `String`
 
 ==== Providing the document source
-The document source can be provided in different ways:
+The document source can be provided in different ways in addition to the
+`String` example shown above:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------

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

@@ -31,6 +31,30 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-reque
 <1> The type to define
 <2> The mapping for this type, provided as a JSON string
 
+The mapping source can be provided in different ways in addition to the
+`String` example shown above:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-mappings-map]
+--------------------------------------------------
+<1> Mapping source provided as a `Map` which gets automatically converted
+to JSON format
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-mappings-xcontent]
+--------------------------------------------------
+<1> Mapping source provided as an `XContentBuilder` object, the Elasticsearch
+built-in helpers to generate JSON content
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-mappings-shortcut]
+--------------------------------------------------
+<1> Mapping source provided as `Object` key-pairs, which gets converted to
+JSON format
+
 ==== Index aliases
 Aliases can be set at index creation time
 
@@ -40,6 +64,18 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-reque
 --------------------------------------------------
 <1> The alias to define
 
+==== Providing the whole source
+
+The whole source including all of its sections (mappings, settings and aliases)
+can also be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-whole-source]
+--------------------------------------------------
+<1> The source provided as a JSON string. It can also be provided as a `Map`
+or an `XContentBuilder`.
+
 ==== Optional arguments
 The following arguments can optionally be provided:
 

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

@@ -20,7 +20,32 @@ A description of the fields to create on the mapping; if not defined, the mappin
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-request-source]
 --------------------------------------------------
-<1> The mapping source
+<1> The mapping source provided as a `String`
+
+==== Providing the mapping source
+The mapping source can be provided in different ways in addition to
+the `String` example shown above:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-map]
+--------------------------------------------------
+<1> Mapping source provided as a `Map` which gets automatically converted
+to JSON format
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-xcontent]
+--------------------------------------------------
+<1> Mapping source provided as an `XContentBuilder` object, the Elasticsearch
+built-in helpers to generate JSON content
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-shortcut]
+--------------------------------------------------
+<1> Mapping source provided as `Object` key-pairs, which gets converted to
+JSON format
 
 ==== Optional arguments
 The following arguments can optionally be provided: