[ILM] HLRC-ILM Retry Lifecycle Policy docs (#35715)

this adds documentation for the retry method in the
high-level-ilm-rest-client.

this PR also renames retryLifecycleStep to retryLifecyclePolicy in the index-lifecycle-client

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

@@ -282,7 +282,7 @@ public class IndexLifecycleClient {
      * @return the response
      * @throws IOException in case there is a problem sending the request or parsing back the response
      */
-    public AcknowledgedResponse retryLifecycleStep(RetryLifecyclePolicyRequest request, RequestOptions options) throws IOException {
+    public AcknowledgedResponse retryLifecyclePolicy(RetryLifecyclePolicyRequest request, RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(request, IndexLifecycleRequestConverters::retryLifecycle, options,
             AcknowledgedResponse::fromXContent, emptySet());
     }
@@ -295,8 +295,8 @@ public class IndexLifecycleClient {
      * @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 retryLifecycleStepAsync(RetryLifecyclePolicyRequest request, RequestOptions options,
-        ActionListener<AcknowledgedResponse> listener) {
+    public void retryLifecyclePolicyAsync(RetryLifecyclePolicyRequest request, RequestOptions options,
+                                          ActionListener<AcknowledgedResponse> listener) {
         restHighLevelClient.performRequestAsyncAndParseEntity(request, IndexLifecycleRequestConverters::retryLifecycle, options,
             AcknowledgedResponse::fromXContent, listener, emptySet());
     }

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

@@ -272,8 +272,8 @@ public class IndexLifecycleIT extends ESRestHighLevelClientTestCase {
         RetryLifecyclePolicyRequest retryRequest = new RetryLifecyclePolicyRequest("retry");
         ElasticsearchStatusException ex = expectThrows(ElasticsearchStatusException.class,
             () -> execute(
-                retryRequest, highLevelClient().indexLifecycle()::retryLifecycleStep,
-                highLevelClient().indexLifecycle()::retryLifecycleStepAsync
+                retryRequest, highLevelClient().indexLifecycle()::retryLifecyclePolicy,
+                highLevelClient().indexLifecycle()::retryLifecyclePolicyAsync
             )
         );
         assertEquals(400, ex.status().getStatus());

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

@@ -22,6 +22,7 @@ package org.elasticsearch.client.documentation;
 import org.apache.http.util.EntityUtils;
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.LatchedActionListener;
+import org.elasticsearch.action.admin.indices.create.CreateIndexRequest;
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
 import org.elasticsearch.client.RequestOptions;
 import org.elasticsearch.client.Response;
@@ -29,6 +30,7 @@ import org.elasticsearch.client.RestHighLevelClient;
 import org.elasticsearch.client.core.AcknowledgedResponse;
 import org.elasticsearch.client.indexlifecycle.DeleteAction;
 import org.elasticsearch.client.indexlifecycle.DeleteLifecyclePolicyRequest;
+import org.elasticsearch.client.indexlifecycle.ExplainLifecycleRequest;
 import org.elasticsearch.client.indexlifecycle.GetLifecyclePolicyRequest;
 import org.elasticsearch.client.indexlifecycle.GetLifecyclePolicyResponse;
 import org.elasticsearch.client.indexlifecycle.LifecycleAction;
@@ -39,11 +41,14 @@ import org.elasticsearch.client.indexlifecycle.OperationMode;
 import org.elasticsearch.client.indexlifecycle.LifecyclePolicyMetadata;
 import org.elasticsearch.client.indexlifecycle.Phase;
 import org.elasticsearch.client.indexlifecycle.PutLifecyclePolicyRequest;
+import org.elasticsearch.client.indexlifecycle.RetryLifecyclePolicyRequest;
 import org.elasticsearch.client.indexlifecycle.RolloverAction;
 import org.elasticsearch.client.indexlifecycle.StartILMRequest;
 import org.elasticsearch.client.indexlifecycle.StopILMRequest;
 import org.elasticsearch.client.indexlifecycle.ShrinkAction;
+import org.elasticsearch.cluster.metadata.IndexMetaData;
 import org.elasticsearch.common.collect.ImmutableOpenMap;
+import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.ByteSizeUnit;
 import org.elasticsearch.common.unit.ByteSizeValue;
 import org.elasticsearch.common.unit.TimeValue;
@@ -72,14 +77,14 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase {
                 new ByteSizeValue(50, ByteSizeUnit.GB), null, null));
         phases.put("hot", new Phase("hot", TimeValue.ZERO, hotActions)); // <1>
 
-        Map<String, LifecycleAction> deleteActions = 
+        Map<String, LifecycleAction> deleteActions =
                 Collections.singletonMap(DeleteAction.NAME, new DeleteAction());
-        phases.put("delete", new Phase("delete", 
+        phases.put("delete", new Phase("delete",
                 new TimeValue(90, TimeUnit.DAYS), deleteActions)); // <2>
 
         LifecyclePolicy policy = new LifecyclePolicy("my_policy",
                 phases); // <3>
-        PutLifecyclePolicyRequest request = 
+        PutLifecyclePolicyRequest request =
                 new PutLifecyclePolicyRequest(policy);
         // end::ilm-put-lifecycle-policy-request
 
@@ -96,10 +101,10 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase {
 
         // Delete the policy so it can be added again
         {
-            DeleteLifecyclePolicyRequest deleteRequest = 
+            DeleteLifecyclePolicyRequest deleteRequest =
                     new DeleteLifecyclePolicyRequest("my_policy");
             AcknowledgedResponse deleteResponse = client.indexLifecycle()
-                    .deleteLifecyclePolicy(deleteRequest, 
+                    .deleteLifecyclePolicy(deleteRequest,
                             RequestOptions.DEFAULT);
             assertTrue(deleteResponse.isAcknowledged());
         }
@@ -124,7 +129,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase {
         listener = new LatchedActionListener<>(listener, latch);
 
         // tag::ilm-put-lifecycle-policy-execute-async
-        client.indexLifecycle().putLifecyclePolicyAsync(request, 
+        client.indexLifecycle().putLifecyclePolicyAsync(request,
                 RequestOptions.DEFAULT, listener); // <1>
         // end::ilm-put-lifecycle-policy-execute-async
 
@@ -380,6 +385,77 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase {
         assertTrue(latch.await(30L, TimeUnit.SECONDS));
     }
 
+    public void testRetryPolicy() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+
+        // setup policy to immediately fail on index
+        {
+            Map<String, Phase> phases = new HashMap<>();
+            Map<String, LifecycleAction> warmActions = new HashMap<>();
+            warmActions.put(ShrinkAction.NAME, new ShrinkAction(1));
+            phases.put("warm", new Phase("warm", TimeValue.ZERO, warmActions));
+
+            LifecyclePolicy policy = new LifecyclePolicy("my_policy",
+                phases);
+            PutLifecyclePolicyRequest putRequest =
+                new PutLifecyclePolicyRequest(policy);
+            client.indexLifecycle().putLifecyclePolicy(putRequest, RequestOptions.DEFAULT);
+
+            CreateIndexRequest createIndexRequest = new CreateIndexRequest("my_index",
+                Settings.builder()
+                    .put(IndexMetaData.SETTING_NUMBER_OF_SHARDS, 1)
+                    .put("index.lifecycle.name", "my_policy")
+                    .build());
+            client.indices().create(createIndexRequest, RequestOptions.DEFAULT);
+            assertBusy(() -> assertNotNull(client.indexLifecycle()
+                .explainLifecycle(new ExplainLifecycleRequest().indices("my_index"), RequestOptions.DEFAULT)
+                .getIndexResponses().get("my_index").getFailedStep()));
+        }
+
+        // tag::ilm-retry-lifecycle-policy-request
+        RetryLifecyclePolicyRequest request =
+            new RetryLifecyclePolicyRequest("my_index"); // <1>
+        // end::ilm-retry-lifecycle-policy-request
+
+
+        // tag::ilm-retry-lifecycle-policy-execute
+        AcknowledgedResponse response = client.indexLifecycle()
+            .retryLifecyclePolicy(request, RequestOptions.DEFAULT);
+        // end::ilm-retry-lifecycle-policy-execute
+
+        // tag::ilm-retry-lifecycle-policy-response
+        boolean acknowledged = response.isAcknowledged(); // <1>
+        // end::ilm-retry-lifecycle-policy-response
+
+        assertTrue(acknowledged);
+
+        // tag::ilm-retry-lifecycle-policy-execute-listener
+        ActionListener<AcknowledgedResponse> listener =
+            new ActionListener<AcknowledgedResponse>() {
+                @Override
+                public void onResponse(AcknowledgedResponse response) {
+                    boolean acknowledged = response.isAcknowledged(); // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+        // end::ilm-retry-lifecycle-policy-execute-listener
+
+        // Replace the empty listener by a blocking listener in test
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener<>(listener, latch);
+
+        // tag::ilm-retry-lifecycle-policy-execute-async
+        client.indexLifecycle().retryLifecyclePolicyAsync(request,
+            RequestOptions.DEFAULT, listener); // <1>
+        // end::ilm-retry-lifecycle-policy-execute-async
+
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
+    }
+
     static Map<String, Object> toMap(Response response) throws IOException {
         return XContentHelper.convertToMap(JsonXContent.jsonXContent, EntityUtils.toString(response.getEntity()), false);
     }

docs/java-rest/high-level/ilm/put_lifecycle_policy.asciidoc

@@ -31,7 +31,7 @@ The returned +{response}+ indicates if the put lifecycle policy request was rece
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> Whether or not the put lifecycle policy was acknowledge.
+<1> Whether or not the put lifecycle policy was acknowledged.
 
 include::../execution.asciidoc[]
 

docs/java-rest/high-level/ilm/retry_lifecycle_policy.asciidoc

@@ -0,0 +1,36 @@
+--
+:api: ilm-retry-lifecycle-policy
+:request: RetryLifecyclePolicyRequest
+:response: AcknowledgedResponse
+--
+
+[id="{upid}-{api}"]
+=== Retry Lifecycle Policy API
+
+
+[id="{upid}-{api}-request"]
+==== Request
+
+The Retry Lifecycle Policy API allows you to invoke execution of policies
+that encountered errors in certain indices.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+<1> Retries execution of `my_index`'s policy
+
+[id="{upid}-{api}-response"]
+==== Response
+
+The returned +{response}+ indicates if the retry lifecycle policy request was received.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> Whether or not the lifecycle policy retry was acknowledged.
+
+include::../execution.asciidoc[]
+
+

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

@@ -461,10 +461,12 @@ Management APIs:
 * <<{upid}-ilm-start-ilm>>
 * <<{upid}-ilm-stop-ilm>>
 * <<{upid}-ilm-status>>
+* <<{upid}-ilm-retry-lifecycle-policy>>
 
 
 include::ilm/put_lifecycle_policy.asciidoc[]
 include::ilm/get_lifecycle_policy.asciidoc[]
 include::ilm/start_lifecycle_management.asciidoc[]
 include::ilm/stop_lifecycle_management.asciidoc[]
-include::ilm/lifecycle_management_status.asciidoc[]
+include::ilm/lifecycle_management_status.asciidoc[]
+include::ilm/retry_lifecycle_policy.asciidoc[]