Skip to content

Commit 03f736f

Browse files
tlrxtlrx
authored
Add documentation for Clone Snapshot Java API (#70720) (#70819)
This commit adds some missing documentation about the Clone Snapshot Java API. Relates #63863
1 parent 2f848ba commit 03f736f

File tree

3 files changed

+175
-0
lines changed

3 files changed

+175
-0
lines changed

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

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
import org.elasticsearch.action.admin.cluster.repositories.put.PutRepositoryRequest;
1717
import org.elasticsearch.action.admin.cluster.repositories.verify.VerifyRepositoryRequest;
1818
import org.elasticsearch.action.admin.cluster.repositories.verify.VerifyRepositoryResponse;
19+
import org.elasticsearch.action.admin.cluster.snapshots.clone.CloneSnapshotRequest;
1920
import org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotRequest;
2021
import org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotResponse;
2122
import org.elasticsearch.action.admin.cluster.snapshots.delete.DeleteSnapshotRequest;
@@ -792,6 +793,83 @@ public void onFailure(Exception e) {
792793
}
793794
}
794795

796+
public void testCloneSnapshot() throws IOException {
797+
RestHighLevelClient client = highLevelClient();
798+
799+
createTestRepositories();
800+
createTestIndex();
801+
createTestSnapshots();
802+
803+
String sourceSnapshotName = snapshotName;
804+
String targetSnapshotName = snapshotName + "_clone";
805+
String[] indices = new String[]{indexName};
806+
807+
// tag::clone-snapshot-request
808+
CloneSnapshotRequest request = new CloneSnapshotRequest(repositoryName, sourceSnapshotName, targetSnapshotName, indices);
809+
// end::clone-snapshot-request
810+
811+
// tag::clone-snapshot-request-indices
812+
request.indices("test_index"); // <1>
813+
// end::clone-snapshot-request-indices
814+
815+
// tag::clone-snapshot-request-masterTimeout
816+
request.masterNodeTimeout(TimeValue.timeValueMinutes(1)); // <1>
817+
request.masterNodeTimeout("1m"); // <2>
818+
// end::clone-snapshot-request-masterTimeout
819+
820+
// tag::clone-snapshot-request-index-settings
821+
request.indicesOptions(new IndicesOptions(
822+
EnumSet.of(IndicesOptions.Option.IGNORE_UNAVAILABLE), // <1>
823+
EnumSet.of(
824+
IndicesOptions.WildcardStates.OPEN,
825+
IndicesOptions.WildcardStates.CLOSED,
826+
IndicesOptions.WildcardStates.HIDDEN))
827+
);
828+
// end::clone-snapshot-request-index-settings
829+
830+
// tag::clone-snapshot-execute
831+
AcknowledgedResponse response = client.snapshot().clone(request, RequestOptions.DEFAULT);
832+
// end::clone-snapshot-execute
833+
834+
// tag::clone-snapshot-response
835+
boolean acknowledged = response.isAcknowledged(); // <1>
836+
// end::clone-snapshot-response
837+
assertTrue(acknowledged);
838+
}
839+
840+
public void testCloneSnapshotAsync() throws InterruptedException {
841+
RestHighLevelClient client = highLevelClient();
842+
{
843+
String targetSnapshot = snapshotName + "_clone";
844+
CloneSnapshotRequest request = new CloneSnapshotRequest(repositoryName, snapshotName, targetSnapshot, new String[]{indexName});
845+
846+
// tag::clone-snapshot-execute-listener
847+
ActionListener<AcknowledgedResponse> listener =
848+
new ActionListener<AcknowledgedResponse>() {
849+
@Override
850+
public void onResponse(AcknowledgedResponse acknowledgedResponse) {
851+
// <1>
852+
}
853+
854+
@Override
855+
public void onFailure(Exception e) {
856+
// <2>
857+
}
858+
};
859+
// end::clone-snapshot-execute-listener
860+
861+
// Replace the empty listener by a blocking listener in test
862+
final CountDownLatch latch = new CountDownLatch(1);
863+
listener = new LatchedActionListener<>(listener, latch);
864+
865+
// tag::clone-snapshot-execute-async
866+
client.snapshot().cloneAsync(request, RequestOptions.DEFAULT, listener); // <1>
867+
// end::clone-snapshot-execute-async
868+
869+
assertTrue(latch.await(30L, TimeUnit.SECONDS));
870+
}
871+
}
872+
795873
private void createTestRepositories() throws IOException {
796874
PutRepositoryRequest request = new PutRepositoryRequest(repositoryName);
797875
request.type(FsRepository.TYPE);

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

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
[[java-rest-high-snapshot-clone-snapshot]]
2+
=== Clone Snapshot API
3+
4+
The Clone Snapshot API clones part or all of a snapshot into a new snapshot.
5+
6+
[[java-rest-high-snapshot-clone-snapshot-request]]
7+
==== Request
8+
9+
A `CloneSnapshotRequest`:
10+
11+
["source","java",subs="attributes,callouts,macros"]
12+
--------------------------------------------------
13+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request]
14+
--------------------------------------------------
15+
16+
==== Indices to Clone
17+
18+
Use `indices` to specify a list of indices from the source snapshot to include
19+
in the snapshot clone:
20+
21+
["source","java",subs="attributes,callouts,macros"]
22+
--------------------------------------------------
23+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request-indices]
24+
--------------------------------------------------
25+
<1> Include only `test_index` from the source snapshot.
26+
27+
==== Index Settings and Options
28+
29+
You can also customize index settings and options when cloning a snapshot:
30+
31+
["source","java",subs="attributes,callouts,macros"]
32+
--------------------------------------------------
33+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request-index-settings]
34+
--------------------------------------------------
35+
<1> Set `IndicesOptions.Option.IGNORE_UNAVAILABLE` in `#indicesOptions()` to
36+
have the clone succeed even if indices are missing in the source snapshot.
37+
38+
==== Further Arguments
39+
40+
You can also provide the following optional arguments:
41+
42+
["source","java",subs="attributes,callouts,macros"]
43+
--------------------------------------------------
44+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-request-masterTimeout]
45+
--------------------------------------------------
46+
<1> Timeout to connect to the master node as a `TimeValue`
47+
<2> Timeout to connect to the master node as a `String`
48+
49+
[[java-rest-high-snapshot-clone-snapshot-sync]]
50+
==== Synchronous Execution
51+
52+
["source","java",subs="attributes,callouts,macros"]
53+
--------------------------------------------------
54+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-execute]
55+
--------------------------------------------------
56+
57+
[[java-rest-high-snapshot-clone-snapshot-async]]
58+
==== Asynchronous Execution
59+
60+
The asynchronous execution of a clone snapshot request requires both the
61+
`CloneSnapshotRequest` instance and an `ActionListener` instance to be
62+
passed to the asynchronous method:
63+
64+
["source","java",subs="attributes,callouts,macros"]
65+
--------------------------------------------------
66+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-execute-async]
67+
--------------------------------------------------
68+
<1> The `CloneSnapshotRequest` to execute and the `ActionListener`
69+
to use when the execution completes
70+
71+
The asynchronous method does not block and returns immediately. Once it is
72+
completed the `ActionListener` is called back using the `onResponse` method
73+
if the execution successfully completed or using the `onFailure` method if
74+
it failed.
75+
76+
A typical listener for `AcknowledgedResponse` looks like:
77+
78+
["source","java",subs="attributes,callouts,macros"]
79+
--------------------------------------------------
80+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-execute-listener]
81+
--------------------------------------------------
82+
<1> Called when the execution is successfully completed. The response is
83+
provided as an argument.
84+
<2> Called in case of a failure. The raised exception is provided as an argument.
85+
86+
[[java-rest-high-cluster-clone-snapshot-response]]
87+
==== Response
88+
89+
`AcknowledgedResponse` indicates whether the request was received:
90+
91+
["source","java",subs="attributes,callouts,macros"]
92+
--------------------------------------------------
93+
include-tagged::{doc-tests}/SnapshotClientDocumentationIT.java[clone-snapshot-response]
94+
--------------------------------------------------
95+
<1> A boolean value of `true` if the clone successfully completed. Otherwise, the value is `false`.

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,7 @@ The Java High Level REST Client supports the following Snapshot APIs:
228228
* <<java-rest-high-snapshot-snapshots-status>>
229229
* <<java-rest-high-snapshot-delete-snapshot>>
230230
* <<java-rest-high-snapshot-restore-snapshot>>
231+
* <<java-rest-high-snapshot-clone-snapshot>>
231232

232233
include::snapshot/get_repository.asciidoc[]
233234
include::snapshot/create_repository.asciidoc[]
@@ -238,6 +239,7 @@ include::snapshot/get_snapshots.asciidoc[]
238239
include::snapshot/snapshots_status.asciidoc[]
239240
include::snapshot/delete_snapshot.asciidoc[]
240241
include::snapshot/restore_snapshot.asciidoc[]
242+
include::snapshot/clone_snapshot.asciidoc[]
241243

242244
== Tasks APIs
243245

0 commit comments

Comments
 (0)