Add documentation for Clone Snapshot Java API (#70720)

This commit adds some missing documentation about 
the Clone Snapshot Java API.

Relates #63863

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

@@ -16,6 +16,7 @@ import org.elasticsearch.action.admin.cluster.repositories.get.GetRepositoriesRe
 import org.elasticsearch.action.admin.cluster.repositories.put.PutRepositoryRequest;
 import org.elasticsearch.action.admin.cluster.repositories.verify.VerifyRepositoryRequest;
 import org.elasticsearch.action.admin.cluster.repositories.verify.VerifyRepositoryResponse;
+import org.elasticsearch.action.admin.cluster.snapshots.clone.CloneSnapshotRequest;
 import org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotRequest;
 import org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotResponse;
 import org.elasticsearch.action.admin.cluster.snapshots.delete.DeleteSnapshotRequest;
@@ -792,6 +793,83 @@ public class SnapshotClientDocumentationIT extends ESRestHighLevelClientTestCase
         }
     }
 
+    public void testCloneSnapshot() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+
+        createTestRepositories();
+        createTestIndex();
+        createTestSnapshots();
+
+        String sourceSnapshotName = snapshotName;
+        String targetSnapshotName = snapshotName + "_clone";
+        String[] indices = new String[]{indexName};
+
+        // tag::clone-snapshot-request
+        CloneSnapshotRequest request = new CloneSnapshotRequest(repositoryName, sourceSnapshotName, targetSnapshotName, indices);
+        // end::clone-snapshot-request
+
+        // tag::clone-snapshot-request-indices
+        request.indices("test_index"); // <1>
+        // end::clone-snapshot-request-indices
+
+        // tag::clone-snapshot-request-masterTimeout
+        request.masterNodeTimeout(TimeValue.timeValueMinutes(1)); // <1>
+        request.masterNodeTimeout("1m"); // <2>
+        // end::clone-snapshot-request-masterTimeout
+
+        // tag::clone-snapshot-request-index-settings
+        request.indicesOptions(new IndicesOptions(
+            EnumSet.of(IndicesOptions.Option.IGNORE_UNAVAILABLE),  // <1>
+            EnumSet.of(
+                IndicesOptions.WildcardStates.OPEN,
+                IndicesOptions.WildcardStates.CLOSED,
+                IndicesOptions.WildcardStates.HIDDEN))
+        );
+        // end::clone-snapshot-request-index-settings
+
+        // tag::clone-snapshot-execute
+        AcknowledgedResponse response = client.snapshot().clone(request, RequestOptions.DEFAULT);
+        // end::clone-snapshot-execute
+
+        // tag::clone-snapshot-response
+        boolean acknowledged = response.isAcknowledged();  // <1>
+        // end::clone-snapshot-response
+        assertTrue(acknowledged);
+    }
+
+    public void testCloneSnapshotAsync() throws InterruptedException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            String targetSnapshot = snapshotName + "_clone";
+            CloneSnapshotRequest request = new CloneSnapshotRequest(repositoryName, snapshotName, targetSnapshot, new String[]{indexName});
+
+            // tag::clone-snapshot-execute-listener
+            ActionListener<AcknowledgedResponse> listener =
+                new ActionListener<AcknowledgedResponse>() {
+                    @Override
+                    public void onResponse(AcknowledgedResponse acknowledgedResponse) {
+                        // <1>
+                    }
+
+                    @Override
+                    public void onFailure(Exception e) {
+                        // <2>
+                    }
+                };
+            // end::clone-snapshot-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::clone-snapshot-execute-async
+            client.snapshot().cloneAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            // end::clone-snapshot-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+    }
+
     private void createTestRepositories() throws IOException {
         PutRepositoryRequest request = new PutRepositoryRequest(repositoryName);
         request.type(FsRepository.TYPE);

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

@@ -0,0 +1,95 @@
+[[java-rest-high-snapshot-clone-snapshot]]
+=== Clone Snapshot API
+
+The Clone Snapshot API clones part or all of a snapshot into a new snapshot.
+
+[[java-rest-high-snapshot-clone-snapshot-request]]
+==== Request
+
+A `CloneSnapshotRequest`:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request]
+--------------------------------------------------
+
+==== Indices to Clone
+
+Use `indices` to specify a list of indices from the source snapshot to include
+in the snapshot clone:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request-indices]
+--------------------------------------------------
+<1> Include only `test_index` from the source snapshot.
+
+==== Index Settings and Options
+
+You can also customize index settings and options when cloning a snapshot:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request-index-settings]
+--------------------------------------------------
+<1> Set `IndicesOptions.Option.IGNORE_UNAVAILABLE` in `#indicesOptions()` to
+    have the clone succeed even if indices are missing in the source snapshot.
+
+==== Further Arguments
+
+You can also provide the following optional arguments:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request-masterTimeout]
+--------------------------------------------------
+<1> Timeout to connect to the master node as a `TimeValue`
+<2> Timeout to connect to the master node as a `String`
+
+[[java-rest-high-snapshot-clone-snapshot-sync]]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-execute]
+--------------------------------------------------
+
+[[java-rest-high-snapshot-clone-snapshot-async]]
+==== Asynchronous Execution
+
+The asynchronous execution of a clone snapshot request requires both the
+`CloneSnapshotRequest` instance and an `ActionListener` instance to be
+passed to the asynchronous method:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-execute-async]
+--------------------------------------------------
+<1> The `CloneSnapshotRequest` to execute and the `ActionListener`
+to use when the execution completes
+
+The asynchronous method does not block and returns immediately. Once it is
+completed the `ActionListener` is called back using the `onResponse` method
+if the execution successfully completed or using the `onFailure` method if
+it failed.
+
+A typical listener for `AcknowledgedResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+    provided as an argument.
+<2> Called in case of a failure. The raised exception is provided as an argument.
+
+[[java-rest-high-cluster-clone-snapshot-response]]
+==== Response
+
+`AcknowledgedResponse` indicates whether the request was received:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-response]
+--------------------------------------------------
+<1> A boolean value of `true` if the clone successfully completed. Otherwise, the value is `false`.

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

@@ -226,6 +226,7 @@ The Java High Level REST Client supports the following Snapshot APIs:
 * <<java-rest-high-snapshot-snapshots-status>>
 * <<java-rest-high-snapshot-delete-snapshot>>
 * <<java-rest-high-snapshot-restore-snapshot>>
+* <<java-rest-high-snapshot-clone-snapshot>>
 
 include::snapshot/get_repository.asciidoc[]
 include::snapshot/create_repository.asciidoc[]
@@ -236,6 +237,7 @@ include::snapshot/get_snapshots.asciidoc[]
 include::snapshot/snapshots_status.asciidoc[]
 include::snapshot/delete_snapshot.asciidoc[]
 include::snapshot/restore_snapshot.asciidoc[]
+include::snapshot/clone_snapshot.asciidoc[]
 
 == Tasks APIs