From ed4471ddb4f37df07ac0d4fcab0e4e1dd0171414 Mon Sep 17 00:00:00 2001 From: Tanguy Leroux Date: Wed, 24 Mar 2021 15:33:09 +0100 Subject: [PATCH] Add documentation for Clone Snapshot Java API (#70720) This commit adds some missing documentation about the Clone Snapshot Java API. Relates #63863 --- .../SnapshotClientDocumentationIT.java | 78 +++++++++++++++ .../snapshot/clone_snapshot.asciidoc | 95 +++++++++++++++++++ .../high-level/supported-apis.asciidoc | 2 + 3 files changed, 175 insertions(+) create mode 100644 docs/java-rest/high-level/snapshot/clone_snapshot.asciidoc diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java index 430908b81975d..eb158d509f289 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java @@ -16,6 +16,7 @@ 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 void onFailure(Exception e) { } } + 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 listener = + new ActionListener() { + @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); diff --git a/docs/java-rest/high-level/snapshot/clone_snapshot.asciidoc b/docs/java-rest/high-level/snapshot/clone_snapshot.asciidoc new file mode 100644 index 0000000000000..311f77ee95ff6 --- /dev/null +++ b/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`. diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index 6d5129e774e69..18f2ffa87789a 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -228,6 +228,7 @@ The Java High Level REST Client supports the following Snapshot APIs: * <> * <> * <> +* <> include::snapshot/get_repository.asciidoc[] include::snapshot/create_repository.asciidoc[] @@ -238,6 +239,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