[DOCS] add docs for high level client get method (#25538)

Document high level client get method

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

@@ -19,6 +19,8 @@
 
 package org.elasticsearch.client.documentation;
 
+import org.apache.http.entity.ContentType;
+import org.apache.http.nio.entity.NStringEntity;
 import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.DocWriteRequest;
@@ -28,6 +30,8 @@ import org.elasticsearch.action.bulk.BulkRequest;
 import org.elasticsearch.action.bulk.BulkResponse;
 import org.elasticsearch.action.delete.DeleteRequest;
 import org.elasticsearch.action.delete.DeleteResponse;
+import org.elasticsearch.action.get.GetRequest;
+import org.elasticsearch.action.get.GetResponse;
 import org.elasticsearch.action.index.IndexRequest;
 import org.elasticsearch.action.index.IndexResponse;
 import org.elasticsearch.action.support.ActiveShardCount;
@@ -36,15 +40,19 @@ import org.elasticsearch.action.support.replication.ReplicationResponse;
 import org.elasticsearch.action.update.UpdateRequest;
 import org.elasticsearch.action.update.UpdateResponse;
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.Response;
 import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.common.Strings;
 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.VersionType;
 import org.elasticsearch.rest.RestStatus;
+import org.elasticsearch.search.fetch.subphase.FetchSourceContext;
 
 import java.io.IOException;
+import java.util.Collections;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
@@ -117,7 +125,7 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
                     "\"postDate\":\"2013-01-30\"," +
                     "\"message\":\"trying out Elasticsearch\"" +
                     "}";
-            request.source(jsonString, XContentType.JSON); //<4>
+            request.source(jsonString, XContentType.JSON); // <4>
             //end::index-request-string
 
             // tag::index-execute
@@ -250,7 +258,7 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
             long version = deleteResponse.getVersion();
             ReplicationResponse.ShardInfo shardInfo = deleteResponse.getShardInfo();
             if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
-                //<1>
+                // <1>
             }
             if (shardInfo.getFailed() > 0) {
                 for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
@@ -362,10 +370,10 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
 
                 if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.INDEX
                         || bulkItemResponse.getOpType() == DocWriteRequest.OpType.CREATE) { // <3>
-                    IndexResponse indexResponse = (IndexResponse)itemResponse;
+                    IndexResponse indexResponse = (IndexResponse) itemResponse;
 
                 } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.UPDATE) { // <4>
-                    UpdateResponse updateResponse = (UpdateResponse)itemResponse;
+                    UpdateResponse updateResponse = (UpdateResponse) itemResponse;
 
                 } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.DELETE) { // <5>
                     DeleteResponse deleteResponse = (DeleteResponse) itemResponse;
@@ -416,4 +424,171 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
             // end::bulk-execute-async
         }
     }
+
+    public void testGet() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            String mappings = "{\n" +
+                    "    \"mappings\" : {\n" +
+                    "        \"doc\" : {\n" +
+                    "            \"properties\" : {\n" +
+                    "                \"message\" : {\n" +
+                    "                    \"type\": \"text\",\n" +
+                    "                    \"store\": true\n" +
+                    "                }\n" +
+                    "            }\n" +
+                    "        }\n" +
+                    "    }\n" +
+                    "}";
+
+            NStringEntity entity = new NStringEntity(mappings, ContentType.APPLICATION_JSON);
+            Response response = client().performRequest("PUT", "/posts", Collections.emptyMap(), entity);
+            assertEquals(200, response.getStatusLine().getStatusCode());
+
+            IndexRequest indexRequest = new IndexRequest("posts", "doc", "1")
+                    .source("user", "kimchy",
+                            "postDate", new Date(),
+                            "message", "trying out Elasticsearch");
+            IndexResponse indexResponse = client.index(indexRequest);
+            assertEquals(indexResponse.getResult(), DocWriteResponse.Result.CREATED);
+        }
+        {
+            //tag::get-request
+            GetRequest getRequest = new GetRequest(
+                    "posts", // <1>
+                    "doc",  // <2>
+                    "1");   // <3>
+            //end::get-request
+
+            //tag::get-execute
+            GetResponse getResponse = client.get(getRequest);
+            //end::get-execute
+            assertTrue(getResponse.isExists());
+            assertEquals(3, getResponse.getSourceAsMap().size());
+            //tag::get-response
+            String index = getResponse.getIndex();
+            String type = getResponse.getType();
+            String id = getResponse.getId();
+            if (getResponse.isExists()) {
+                long version = getResponse.getVersion();
+                String sourceAsString = getResponse.getSourceAsString();        // <1>
+                Map<String, Object> sourceAsMap = getResponse.getSourceAsMap(); // <2>
+                byte[] sourceAsBytes = getResponse.getSourceAsBytes();          // <3>
+            } else {
+                // <4>
+            }
+            //end::get-response
+        }
+        {
+            GetRequest request = new GetRequest("posts", "doc", "1");
+            //tag::get-request-no-source
+            request.fetchSourceContext(new FetchSourceContext(false)); // <1>
+            //end::get-request-no-source
+            GetResponse getResponse = client.get(request);
+            assertNull(getResponse.getSourceInternal());
+        }
+        {
+            GetRequest request = new GetRequest("posts", "doc", "1");
+            //tag::get-request-source-include
+            String[] includes = new String[]{"message", "*Date"};
+            String[] excludes = Strings.EMPTY_ARRAY;
+            FetchSourceContext fetchSourceContext = new FetchSourceContext(true, includes, excludes);
+            request.fetchSourceContext(fetchSourceContext); // <1>
+            //end::get-request-source-include
+            GetResponse getResponse = client.get(request);
+            Map<String, Object> sourceAsMap = getResponse.getSourceAsMap();
+            assertEquals(2, sourceAsMap.size());
+            assertEquals("trying out Elasticsearch", sourceAsMap.get("message"));
+            assertTrue(sourceAsMap.containsKey("postDate"));
+        }
+        {
+            GetRequest request = new GetRequest("posts", "doc", "1");
+            //tag::get-request-source-exclude
+            String[] includes = Strings.EMPTY_ARRAY;
+            String[] excludes = new String[]{"message"};
+            FetchSourceContext fetchSourceContext = new FetchSourceContext(true, includes, excludes);
+            request.fetchSourceContext(fetchSourceContext); // <1>
+            //end::get-request-source-exclude
+            GetResponse getResponse = client.get(request);
+            Map<String, Object> sourceAsMap = getResponse.getSourceAsMap();
+            assertEquals(2, sourceAsMap.size());
+            assertEquals("kimchy", sourceAsMap.get("user"));
+            assertTrue(sourceAsMap.containsKey("postDate"));
+        }
+        {
+            GetRequest request = new GetRequest("posts", "doc", "1");
+            //tag::get-request-stored
+            request.storedFields("message"); // <1>
+            GetResponse getResponse = client.get(request);
+            String message = getResponse.getField("message").getValue(); // <2>
+            //end::get-request-stored
+            assertEquals("trying out Elasticsearch", message);
+            assertEquals(1, getResponse.getFields().size());
+            assertNull(getResponse.getSourceInternal());
+        }
+        {
+            GetRequest request = new GetRequest("posts", "doc", "1");
+            //tag::get-request-routing
+            request.routing("routing"); // <1>
+            //end::get-request-routing
+            //tag::get-request-parent
+            request.parent("parent"); // <1>
+            //end::get-request-parent
+            //tag::get-request-preference
+            request.preference("preference"); // <1>
+            //end::get-request-preference
+            //tag::get-request-realtime
+            request.realtime(false); // <1>
+            //end::get-request-realtime
+            //tag::get-request-refresh
+            request.refresh(true); // <1>
+            //end::get-request-refresh
+            //tag::get-request-version
+            request.version(2); // <1>
+            //end::get-request-version
+            //tag::get-request-version-type
+            request.versionType(VersionType.EXTERNAL); // <1>
+            //end::get-request-version-type
+        }
+        {
+            GetRequest request = new GetRequest("posts", "doc", "1");
+            //tag::get-execute-async
+            client.getAsync(request, new ActionListener<GetResponse>() {
+                @Override
+                public void onResponse(GetResponse getResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            });
+            //end::get-execute-async
+        }
+        {
+            //tag::get-indexnotfound
+            GetRequest request = new GetRequest("does_not_exist", "doc", "1");
+            try {
+                GetResponse getResponse = client.get(request);
+            } catch (ElasticsearchException e) {
+                if (e.status() == RestStatus.NOT_FOUND) {
+                    // <1>
+                }
+            }
+            //end::get-indexnotfound
+        }
+        {
+            // tag::get-conflict
+            try {
+                GetRequest request = new GetRequest("posts", "doc", "1").version(2);
+                GetResponse getResponse = client.get(request);
+            } catch (ElasticsearchException exception) {
+                if (exception.status() == RestStatus.CONFLICT) {
+                    // <1>
+                }
+            }
+            // end::get-conflict
+        }
+    }
 }

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

@@ -4,7 +4,7 @@ The Java High Level REST Client supports the following APIs:
 
 * <<java-rest-high-document-index>>
 
-* Get API
+* <<java-rest-high-document-get>>
 
 * <<java-rest-high-document-delete>>
 

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

@@ -109,8 +109,8 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-async]
 --------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
-provided as an argument.
+provided as an argument
-<2> Called in case of failure. The raised exception is provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument
 
 [[java-rest-high-document-index-response]]
 ==== Index Response
@@ -137,7 +137,7 @@ be thrown:
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-conflict]
 --------------------------------------------------
-<1> The raised exception indicates that a version conflict error was returned.
+<1> The raised exception indicates that a version conflict error was returned
 
 Same will happen in case `opType` was set to `create` and a document with
 same index, type and id already existed:
@@ -146,6 +146,6 @@ same index, type and id already existed:
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype]
 --------------------------------------------------
-<1> The raised exception indicates that a version conflict error was returned.
+<1> The raised exception indicates that a version conflict error was returned
 
 

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

@@ -71,8 +71,8 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async]
 --------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
-provided as an argument.
+provided as an argument
-<2> Called in case of failure. The raised exception is provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument
 
 [[java-rest-high-document-delete-response]]
 ==== Delete Response
@@ -104,5 +104,5 @@ be thrown:
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-conflict]
 --------------------------------------------------
-<1> The raised exception indicates that a version conflict error was returned.
+<1> The raised exception indicates that a version conflict error was returned
 

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

@@ -0,0 +1,143 @@
+[[java-rest-high-document-get]]
+=== Get API
+
+[[java-rest-high-document-get-request]]
+==== Get Request
+
+A `GetRequest` requires the following arguments:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request]
+--------------------------------------------------
+<1> Index
+<2> Type
+<3> Document id
+
+==== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-no-source]
+--------------------------------------------------
+<1> Disable source retrieval, enabled by default
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-source-include]
+--------------------------------------------------
+<1> Configure source inclusion for specific fields
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-source-exclude]
+--------------------------------------------------
+<1> Configure source exclusion for specific fields
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-stored]
+--------------------------------------------------
+<1> Configure retrieval for specific stored fields (requires fields to be
+stored separately in the mappings)
+<2> Retrieve the `message` stored field (requires the field to be stored
+separately in the mappings)
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-routing]
+--------------------------------------------------
+<1> Routing value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-parent]
+--------------------------------------------------
+<1> Parent value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-preference]
+--------------------------------------------------
+<1> Preference value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-realtime]
+--------------------------------------------------
+<1> Set realtime flag to `false` (`true` by default)
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-refresh]
+--------------------------------------------------
+<1> Perform a refresh before retrieving the document (`false` by default)
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-version]
+--------------------------------------------------
+<1> Version
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-version-type]
+--------------------------------------------------
+<1> Version type
+
+[[java-rest-high-document-get-sync]]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute]
+--------------------------------------------------
+
+[[java-rest-high-document-get-async]]
+==== Asynchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute-async]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument.
+
+[[java-rest-high-document-get-response]]
+==== Get Response
+
+The returned `GetResponse` allows to retrieve the requested document along with
+its metadata and eventually stored fields.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-response]
+--------------------------------------------------
+<1> Retrieve the document as a `String`
+<2> Retrieve the document as a `Map<String, Object>`
+<3> Retrieve the document as a `byte[]`
+<4> Handle the scenario where the document was not found. Note that although
+the returned response has `404` status code, a valid `GetResponse` is
+returned rather than an exception thrown. Such response does not hold any
+source document and its `isExists` method returns `false`.
+
+When a get request is performed against an index that does not exist, the
+response has `404` status code, an `ElasticsearchException` gets thrown
+which needs to be handled as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-indexnotfound]
+--------------------------------------------------
+<1> Handle the exception thrown because the index does not exist
+
+In case a specific document version has been requested, and the existing
+document has a different version number, a version conflict is raised:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-conflict]
+--------------------------------------------------
+<1> The raised exception indicates that a version conflict error was returned

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

@@ -2,6 +2,7 @@
 
 include::_index.asciidoc[]
 include::update.asciidoc[]
+include::get.asciidoc[]
 include::delete.asciidoc[]
 include::bulk.asciidoc[]