Address reviewer comments.

Convert the stats objects to objects instead of fragments.
Simplify unit tests.
Add more response uses to the documentation
Rename api method to 'status'

client/rest-high-level/src/main/java/org/elasticsearch/client/SnapshotClient.java

@@ -167,32 +167,30 @@ public void verifyRepositoryAsync(VerifyRepositoryRequest verifyRepositoryReques
     }
 
     /**
-     * Gets the status of any snapshots currently in progress. If snapshot names are provided, this will return detailed status information
-     * for them even if they are not currently running.
+     * Gets the status of requested snapshots.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html"> Snapshot and Restore
      * API on elastic.co</a>
      * @param snapshotsStatusRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
      * @throws IOException in case there is a problem sending the request or parsing back the response
      */
-    public SnapshotsStatusResponse snapshotsStatus(SnapshotsStatusRequest snapshotsStatusRequest, RequestOptions options)
+    public SnapshotsStatusResponse status(SnapshotsStatusRequest snapshotsStatusRequest, RequestOptions options)
         throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(snapshotsStatusRequest, RequestConverters::snapshotsStatus, options,
             SnapshotsStatusResponse::fromXContent, emptySet());
     }
 
     /**
-     * Asynchronously gets the status of any snapshots currently in progress. If snapshot names are provided, this will return detailed
-     * status information for them even if they are not currently running.
+     * Asynchronously gets the status of requested snapshots.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html"> Snapshot and Restore
      * API on elastic.co</a>
      * @param snapshotsStatusRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @param listener the listener to be notified upon request completion
      */
-    public void snapshotsStatusAsync(SnapshotsStatusRequest snapshotsStatusRequest, RequestOptions options,
-                                     ActionListener<SnapshotsStatusResponse> listener) {
+    public void statusAsync(SnapshotsStatusRequest snapshotsStatusRequest, RequestOptions options,
+                            ActionListener<SnapshotsStatusResponse> listener) {
         restHighLevelClient.performRequestAsyncAndParseEntity(snapshotsStatusRequest, RequestConverters::snapshotsStatus, options,
             SnapshotsStatusResponse::fromXContent, listener, emptySet());
     }

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

@@ -19,8 +19,6 @@
 
 package org.elasticsearch.client;
 
-import org.apache.http.entity.ContentType;
-import org.apache.http.nio.entity.NStringEntity;
 import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.action.admin.cluster.repositories.delete.DeleteRepositoryRequest;
 import org.elasticsearch.action.admin.cluster.repositories.delete.DeleteRepositoryResponse;
@@ -58,7 +56,7 @@ private PutRepositoryResponse createTestRepository(String repository, String typ
     private Response createTestSnapshot(String repository, String snapshot, String index) throws IOException {
         Request createSnapshot = new Request("put", String.format(Locale.ROOT, "_snapshot/%s/%s", repository, snapshot));
         createSnapshot.addParameter("wait_for_completion", "true");
-        createSnapshot.setEntity(new NStringEntity("{\"indices\":\""+index+"\"}", ContentType.APPLICATION_JSON));
+        createSnapshot.setJsonEntity("{\"indices\":\""+index+"\"}");
         return highLevelClient().getLowLevelClient().performRequest(createSnapshot);
     }
 
@@ -141,8 +139,8 @@ public void testSnapshotsStatus() throws IOException {
         SnapshotsStatusRequest request = new SnapshotsStatusRequest();
         request.repository(testRepository);
         request.snapshots(new String[]{testSnapshot});
-        SnapshotsStatusResponse response = execute(request, highLevelClient().snapshot()::snapshotsStatus,
-            highLevelClient().snapshot()::snapshotsStatusAsync);
+        SnapshotsStatusResponse response = execute(request, highLevelClient().snapshot()::status,
+            highLevelClient().snapshot()::statusAsync);
         assertThat(response.getSnapshots().size(), equalTo(1));
         assertThat(response.getSnapshots().get(0).getSnapshot().getRepository(), equalTo(testRepository));
         assertThat(response.getSnapshots().get(0).getSnapshot().getSnapshotId().getName(), equalTo(testSnapshot));

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

@@ -31,6 +31,7 @@
 import org.elasticsearch.action.admin.cluster.repositories.verify.VerifyRepositoryResponse;
 import org.elasticsearch.action.admin.cluster.snapshots.delete.DeleteSnapshotRequest;
 import org.elasticsearch.action.admin.cluster.snapshots.delete.DeleteSnapshotResponse;
+import org.elasticsearch.action.admin.cluster.snapshots.status.SnapshotStats;
 import org.elasticsearch.action.admin.cluster.snapshots.status.SnapshotStatus;
 import org.elasticsearch.action.admin.cluster.snapshots.status.SnapshotsStatusRequest;
 import org.elasticsearch.action.admin.cluster.snapshots.status.SnapshotsStatusResponse;
@@ -39,6 +40,7 @@
 import org.elasticsearch.client.RequestOptions;
 import org.elasticsearch.client.Response;
 import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.cluster.SnapshotsInProgress;
 import org.elasticsearch.cluster.metadata.RepositoryMetaData;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.TimeValue;
@@ -77,6 +79,7 @@ public class SnapshotClientDocumentationIT extends ESRestHighLevelClientTestCase
 
     private static final String repositoryName = "test_repository";
     private static final String snapshotName = "test_snapshot";
+    private static final String indexName = "test_index";
 
     public void testSnapshotCreateRepository() throws IOException {
         RestHighLevelClient client = highLevelClient();
@@ -372,6 +375,7 @@ public void onFailure(Exception e) {
     public void testSnapshotSnapshotsStatus() throws IOException {
         RestHighLevelClient client = highLevelClient();
         createTestRepositories();
+        createTestIndex();
         createTestSnapshots();
 
         // tag::snapshots-status-request
@@ -394,15 +398,19 @@ public void testSnapshotSnapshotsStatus() throws IOException {
         // end::snapshots-status-request-masterTimeout
 
         // tag::snapshots-status-execute
-        SnapshotsStatusResponse response = client.snapshot().snapshotsStatus(request, RequestOptions.DEFAULT);
+        SnapshotsStatusResponse response = client.snapshot().status(request, RequestOptions.DEFAULT);
         // end::snapshots-status-execute
 
         // tag::snapshots-status-response
         List<SnapshotStatus> snapshotStatusesResponse = response.getSnapshots();
+        SnapshotStatus snapshotStatus = snapshotStatusesResponse.get(0); // <1>
+        SnapshotsInProgress.State snapshotState = snapshotStatus.getState(); // <2>
+        SnapshotStats shardStats = snapshotStatus.getIndices().get(indexName).getShards().get(0).getStats(); // <3>
         // end::snapshots-status-response
         assertThat(snapshotStatusesResponse.size(), equalTo(1));
-        assertThat(snapshotStatusesResponse.get(0).getSnapshot().getRepository(), equalTo(repositoryName));
+        assertThat(snapshotStatusesResponse.get(0).getSnapshot().getRepository(), equalTo(SnapshotClientDocumentationIT.repositoryName));
         assertThat(snapshotStatusesResponse.get(0).getSnapshot().getSnapshotId().getName(), equalTo(snapshotName));
+        assertThat(snapshotState.completed(), equalTo(true));
     }
 
     public void testSnapshotSnapshotsStatusAsync() throws InterruptedException {
@@ -430,7 +438,7 @@ public void onFailure(Exception e) {
             listener = new LatchedActionListener<>(listener, latch);
 
             // tag::snapshots-status-execute-async
-            client.snapshot().snapshotsStatusAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            client.snapshot().statusAsync(request, RequestOptions.DEFAULT, listener); // <1>
             // end::snapshots-status-execute-async
 
             assertTrue(latch.await(30L, TimeUnit.SECONDS));
@@ -441,6 +449,7 @@ public void testSnapshotDeleteSnapshot() throws IOException {
         RestHighLevelClient client = highLevelClient();
 
         createTestRepositories();
+        createTestIndex();
         createTestSnapshots();
 
         // tag::delete-snapshot-request
@@ -502,9 +511,14 @@ private void createTestRepositories() throws IOException {
         assertTrue(highLevelClient().snapshot().createRepository(request, RequestOptions.DEFAULT).isAcknowledged());
     }
 
+    private void createTestIndex() throws IOException {
+        createIndex(indexName, Settings.EMPTY);
+    }
+
     private void createTestSnapshots() throws IOException {
         Request createSnapshot = new Request("put", String.format(Locale.ROOT, "_snapshot/%s/%s", repositoryName, snapshotName));
         createSnapshot.addParameter("wait_for_completion", "true");
+        createSnapshot.setJsonEntity("{\"indices\":\"" + indexName + "\"}");
         Response response = highLevelClient().getLowLevelClient().performRequest(createSnapshot);
         // check that the request went ok without parsing JSON here. When using the high level client, check acknowledgement instead.
         assertEquals(200, response.getStatusLine().getStatusCode());

docs/java-rest/high-level/snapshot/snapshots_status.asciidoc

@@ -13,21 +13,23 @@ A `SnapshotsStatusRequest`:
 include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[snapshots-status-request]
 --------------------------------------------------
 
-==== Optional Arguments
-The following arguments can optionally be provided:
+==== Required Arguments
+The following arguments must be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[snapshots-status-request-repository]
 --------------------------------------------------
-<1> Sets the repository to check for snapshot statuses currently in progress
+<1> Sets the repository to check for snapshot statuses
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[snapshots-status-request-snapshots]
 --------------------------------------------------
-<1> The list of snapshot names to check the status of. If this is set, the status for the snapshots
-is returned, even if they are not currently in progress
+<1> The list of snapshot names to check the status of
+
+==== Optional Arguments
+The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -90,3 +92,6 @@ executed operation as follows:
 --------------------------------------------------
 include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[snapshots-status-response]
 --------------------------------------------------
+<1> Request contains a list of snapshot statuses
+<2> Each status contains information about the snapshot
+<3> Example of reading snapshot statistics about a specific index and shard

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/status/SnapshotIndexShardStatus.java

@@ -162,7 +162,7 @@ static final class Fields {
     public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
         builder.startObject(Integer.toString(getShardId().getId()));
         builder.field(Fields.STAGE, getStage());
-        stats.toXContent(builder, params);
+        builder.field(SnapshotStats.Fields.STATS, stats, params);
         if (getNodeId() != null) {
             builder.field(Fields.NODE, getNodeId());
         }

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/status/SnapshotIndexStatus.java

@@ -112,8 +112,8 @@ static final class Fields {
     @Override
     public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
         builder.startObject(getIndex());
-        shardsStats.toXContent(builder, params);
-        stats.toXContent(builder, params);
+        builder.field(SnapshotShardsStats.Fields.SHARDS_STATS, shardsStats, params);
+        builder.field(SnapshotStats.Fields.STATS, stats, params);
         builder.startObject(Fields.SHARDS);
         for (SnapshotIndexShardStatus shard : indexShards.values()) {
             shard.toXContent(builder, params);

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/status/SnapshotShardsStats.java

@@ -22,7 +22,7 @@
 import org.elasticsearch.common.ParseField;
 import org.elasticsearch.common.xcontent.ConstructingObjectParser;
 import org.elasticsearch.common.xcontent.ToXContent;
-import org.elasticsearch.common.xcontent.ToXContentFragment;
+import org.elasticsearch.common.xcontent.ToXContentObject;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentParser;
 
@@ -34,7 +34,7 @@
 /**
  * Status of a snapshot shards
  */
-public class SnapshotShardsStats implements ToXContentFragment {
+public class SnapshotShardsStats implements ToXContentObject {
 
     private int initializingShards;
     private int startedShards;
@@ -132,13 +132,15 @@ static final class Fields {
 
     @Override
     public XContentBuilder toXContent(XContentBuilder builder, ToXContent.Params params) throws IOException {
-        builder.startObject(Fields.SHARDS_STATS);
-        builder.field(Fields.INITIALIZING, getInitializingShards());
-        builder.field(Fields.STARTED, getStartedShards());
-        builder.field(Fields.FINALIZING, getFinalizingShards());
-        builder.field(Fields.DONE, getDoneShards());
-        builder.field(Fields.FAILED, getFailedShards());
-        builder.field(Fields.TOTAL, getTotalShards());
+        builder.startObject();
+        {
+            builder.field(Fields.INITIALIZING, getInitializingShards());
+            builder.field(Fields.STARTED, getStartedShards());
+            builder.field(Fields.FINALIZING, getFinalizingShards());
+            builder.field(Fields.DONE, getDoneShards());
+            builder.field(Fields.FAILED, getFailedShards());
+            builder.field(Fields.TOTAL, getTotalShards());
+        }
         builder.endObject();
         return builder;
     }

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/status/SnapshotStats.java

@@ -26,14 +26,14 @@
 import org.elasticsearch.common.unit.ByteSizeValue;
 import org.elasticsearch.common.unit.TimeValue;
 import org.elasticsearch.common.xcontent.ToXContent;
-import org.elasticsearch.common.xcontent.ToXContentFragment;
+import org.elasticsearch.common.xcontent.ToXContentObject;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentParser;
 import org.elasticsearch.common.xcontent.XContentParserUtils;
 
 import java.io.IOException;
 
-public class SnapshotStats implements Streamable, ToXContentFragment {
+public class SnapshotStats implements Streamable, ToXContentObject {
 
     private long startTime;
     private long time;
@@ -178,32 +178,35 @@ static final class Fields {
 
     @Override
     public XContentBuilder toXContent(XContentBuilder builder, ToXContent.Params params) throws IOException {
-        builder.startObject(Fields.STATS)
-            //  incremental starts
-            .startObject(Fields.INCREMENTAL)
-            .field(Fields.FILE_COUNT, getIncrementalFileCount())
-            .humanReadableField(Fields.SIZE_IN_BYTES, Fields.SIZE, new ByteSizeValue(getIncrementalSize()))
-            //  incremental ends
-            .endObject();
-
-        if (getProcessedFileCount() != getIncrementalFileCount()) {
-            //  processed starts
-            builder.startObject(Fields.PROCESSED)
-                .field(Fields.FILE_COUNT, getProcessedFileCount())
-                .humanReadableField(Fields.SIZE_IN_BYTES, Fields.SIZE, new ByteSizeValue(getProcessedSize()))
-                //  processed ends
-                .endObject();
-        }
-        //  total starts
-        builder.startObject(Fields.TOTAL)
-            .field(Fields.FILE_COUNT, getTotalFileCount())
-            .humanReadableField(Fields.SIZE_IN_BYTES, Fields.SIZE, new ByteSizeValue(getTotalSize()))
-            //  total ends
-            .endObject();
-       // timings stats
-       builder.field(Fields.START_TIME_IN_MILLIS, getStartTime())
-            .humanReadableField(Fields.TIME_IN_MILLIS, Fields.TIME, new TimeValue(getTime()));
+        builder.startObject();
+        {
+            builder.startObject(Fields.INCREMENTAL);
+            {
+                builder.field(Fields.FILE_COUNT, getIncrementalFileCount());
+                builder.humanReadableField(Fields.SIZE_IN_BYTES, Fields.SIZE, new ByteSizeValue(getIncrementalSize()));
+            }
+            builder.endObject();
+
+            if (getProcessedFileCount() != getIncrementalFileCount()) {
+                builder.startObject(Fields.PROCESSED);
+                {
+                    builder.field(Fields.FILE_COUNT, getProcessedFileCount());
+                    builder.humanReadableField(Fields.SIZE_IN_BYTES, Fields.SIZE, new ByteSizeValue(getProcessedSize()));
+                }
+                builder.endObject();
+            }
+
+            builder.startObject(Fields.TOTAL);
+            {
+                builder.field(Fields.FILE_COUNT, getTotalFileCount());
+                builder.humanReadableField(Fields.SIZE_IN_BYTES, Fields.SIZE, new ByteSizeValue(getTotalSize()));
+            }
+            builder.endObject();
 
+            // timings stats
+            builder.field(Fields.START_TIME_IN_MILLIS, getStartTime());
+            builder.humanReadableField(Fields.TIME_IN_MILLIS, Fields.TIME, new TimeValue(getTime()));
+        }
         return builder.endObject();
     }
 

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/status/SnapshotStatus.java

@@ -230,8 +230,8 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
         if (includeGlobalState != null) {
             builder.field(INCLUDE_GLOBAL_STATE, includeGlobalState);
         }
-        shardsStats.toXContent(builder, params);
-        stats.toXContent(builder, params);
+        builder.field(SnapshotShardsStats.Fields.SHARDS_STATS, shardsStats, params);
+        builder.field(SnapshotStats.Fields.STATS, stats, params);
         builder.startObject(INDICES);
         for (SnapshotIndexStatus indexStatus : getIndices().values()) {
             indexStatus.toXContent(builder, params);
@@ -255,12 +255,7 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
             @SuppressWarnings("unchecked") List<SnapshotIndexStatus> indices = ((List<SnapshotIndexStatus>) parsedObjects[i]);
 
             Snapshot snapshot = new Snapshot(repository, new SnapshotId(name, uuid));
-            SnapshotsInProgress.State state;
-            try {
-                state = SnapshotsInProgress.State.valueOf(rawState);
-            } catch (IllegalArgumentException iae) {
-                throw new ElasticsearchParseException("failed to parse snapshot status, unknown state value [{}]", iae, rawState);
-            }
+            SnapshotsInProgress.State state = SnapshotsInProgress.State.valueOf(rawState);
             Map<String, SnapshotIndexStatus> indicesStatus;
             List<SnapshotIndexShardStatus> shards;
             if (indices == null || indices.isEmpty()) {