From c934fb087ac95fd134654fe0e5066ad33e2d6829 Mon Sep 17 00:00:00 2001 From: Colin Goodheart-Smithe Date: Tue, 13 Nov 2018 20:40:53 +0000 Subject: [PATCH] Adds HLRC docs for put lifecycle policy (#35457) * Adds HLRC docs for put lifecycle policy * Adds link to docs in client javadocs * Fixes checkstyle * Make the documentation use the right ack response --- .../client/IndexLifecycleClient.java | 4 +- .../documentation/ILMDocumentationIT.java | 126 ++++++++++++++++++ .../ilm/put_lifecycle_policy.asciidoc | 38 ++++++ .../high-level/supported-apis.asciidoc | 12 ++ 4 files changed, 178 insertions(+), 2 deletions(-) create mode 100644 client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java create mode 100644 docs/java-rest/high-level/ilm/put_lifecycle_policy.asciidoc diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java index f4852816b30..d88dfa3c92b 100644 --- a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java @@ -76,8 +76,8 @@ public class IndexLifecycleClient { } /** - * Create or modify a lifecycle definition - * See + * Create or modify a lifecycle definition See * the docs for more. * @param request the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java new file mode 100644 index 00000000000..69bfbc11f76 --- /dev/null +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java @@ -0,0 +1,126 @@ +/* + * Licensed to Elasticsearch under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.elasticsearch.client.documentation; + +import org.apache.http.util.EntityUtils; +import org.elasticsearch.action.ActionListener; +import org.elasticsearch.action.LatchedActionListener; +import org.elasticsearch.client.ESRestHighLevelClientTestCase; +import org.elasticsearch.client.RequestOptions; +import org.elasticsearch.client.Response; +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.LifecycleAction; +import org.elasticsearch.client.indexlifecycle.LifecyclePolicy; +import org.elasticsearch.client.indexlifecycle.Phase; +import org.elasticsearch.client.indexlifecycle.PutLifecyclePolicyRequest; +import org.elasticsearch.client.indexlifecycle.RolloverAction; +import org.elasticsearch.common.unit.ByteSizeUnit; +import org.elasticsearch.common.unit.ByteSizeValue; +import org.elasticsearch.common.unit.TimeValue; +import org.elasticsearch.common.xcontent.XContentHelper; +import org.elasticsearch.common.xcontent.json.JsonXContent; + +import java.io.IOException; +import java.util.Collections; +import java.util.HashMap; +import java.util.Map; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; + +public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { + + public void testPutLifecyclePolicy() throws Exception { + RestHighLevelClient client = highLevelClient(); + + // tag::ilm-put-lifecycle-policy-request + Map phases = new HashMap<>(); + Map hotActions = new HashMap<>(); + hotActions.put(RolloverAction.NAME, new RolloverAction( + new ByteSizeValue(50, ByteSizeUnit.GB), null, null)); + phases.put("hot", new Phase("hot", TimeValue.ZERO, hotActions)); // <1> + + Map deleteActions = + Collections.singletonMap(DeleteAction.NAME, new DeleteAction()); + phases.put("delete", new Phase("delete", + new TimeValue(90, TimeUnit.DAYS), deleteActions)); // <2> + + LifecyclePolicy policy = new LifecyclePolicy("my_policy", + phases); // <3> + PutLifecyclePolicyRequest request = + new PutLifecyclePolicyRequest(policy); + // end::ilm-put-lifecycle-policy-request + + // tag::ilm-put-lifecycle-policy-execute + AcknowledgedResponse response = client.indexLifecycle(). + putLifecyclePolicy(request, RequestOptions.DEFAULT); + // end::ilm-put-lifecycle-policy-execute + + // tag::ilm-put-lifecycle-policy-response + boolean acknowledged = response.isAcknowledged(); // <1> + // end::ilm-put-lifecycle-policy-response + + assertTrue(acknowledged); + + // Delete the policy so it can be added again + { + DeleteLifecyclePolicyRequest deleteRequest = + new DeleteLifecyclePolicyRequest("my_policy"); + AcknowledgedResponse deleteResponse = client.indexLifecycle() + .deleteLifecyclePolicy(deleteRequest, + RequestOptions.DEFAULT); + assertTrue(deleteResponse.isAcknowledged()); + } + + // tag::ilm-put-lifecycle-policy-execute-listener + ActionListener listener = + new ActionListener() { + @Override + public void onResponse(AcknowledgedResponse response) { + boolean acknowledged = response.isAcknowledged(); // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } + }; + // end::ilm-put-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-put-lifecycle-policy-execute-async + client.indexLifecycle().putLifecyclePolicyAsync(request, + RequestOptions.DEFAULT, listener); // <1> + // end::ilm-put-lifecycle-policy-execute-async + + assertTrue(latch.await(30L, TimeUnit.SECONDS)); + + } + + static Map toMap(Response response) throws IOException { + return XContentHelper.convertToMap(JsonXContent.jsonXContent, EntityUtils.toString(response.getEntity()), false); + } + +} diff --git a/docs/java-rest/high-level/ilm/put_lifecycle_policy.asciidoc b/docs/java-rest/high-level/ilm/put_lifecycle_policy.asciidoc new file mode 100644 index 00000000000..23671e23f75 --- /dev/null +++ b/docs/java-rest/high-level/ilm/put_lifecycle_policy.asciidoc @@ -0,0 +1,38 @@ +-- +:api: ilm-put-lifecycle-policy +:request: PutLifecyclePolicyRequest +:response: AcknowledgedResponse +-- + +[id="{upid}-{api}"] +=== Put Lifecycle Policy API + + +[id="{upid}-{api}-request"] +==== Request + +The Put Lifecycle Policy API allows you to add an Index Lifecycle Management +Policy to the cluster. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-request] +-------------------------------------------------- +<1> Adds a hot phase with a rollover action +<2> Adds a delete phase that will delete in the index 90 days after rollover +<3> Creates the policy with the defined phases and the name `my_policy` + +[id="{upid}-{api}-response"] +==== Response + +The returned +{response}+ indicates if the put lifecycle policy request was received. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-response] +-------------------------------------------------- +<1> Whether or not the put lifecycle policy was acknowledge. + +include::../execution.asciidoc[] + + diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index 9f3674e224b..0d7f77c1f79 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -420,3 +420,15 @@ The Java High Level REST Client supports the following CCR APIs: include::ccr/put_follow.asciidoc[] include::ccr/pause_follow.asciidoc[] + +== Index Lifecycle Management APIs + +:upid: {mainid}-ilm +:doc-tests-file: {doc-tests}/ILMDocumentationIT.java + +The Java High Level REST Client supports the following Index Lifecycle +Management APIs: + +* <<{upid}-ilm-put-lifecycle-policy>> + +include::ilm/put_lifecycle_policy.asciidoc[]