HLRC: ML Delete Forecast API

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

@@ -28,6 +28,7 @@
 import org.apache.lucene.util.BytesRef;
 import org.elasticsearch.client.RequestConverters.EndpointBuilder;
 import org.elasticsearch.client.ml.CloseJobRequest;
+import org.elasticsearch.client.ml.DeleteForecastRequest;
 import org.elasticsearch.client.ml.DeleteJobRequest;
 import org.elasticsearch.client.ml.FlushJobRequest;
 import org.elasticsearch.client.ml.ForecastJobRequest;
@@ -180,6 +181,26 @@ static Request updateJob(UpdateJobRequest updateJobRequest) throws IOException {
         return request;
     }
 
+    static Request deleteForecast(DeleteForecastRequest deleteForecastRequest) throws IOException {
+        String endpoint = new EndpointBuilder()
+            .addPathPartAsIs("_xpack")
+            .addPathPartAsIs("ml")
+            .addPathPartAsIs("anomaly_detectors")
+            .addPathPart(deleteForecastRequest.getJobId())
+            .addPathPartAsIs("_forecast")
+            .addPathPart(Strings.collectionToCommaDelimitedString(deleteForecastRequest.getForecastIds()))
+            .build();
+        Request request = new Request(HttpDelete.METHOD_NAME, endpoint);
+        RequestConverters.Params params = new RequestConverters.Params(request);
+        if (deleteForecastRequest.isAllowNoForecasts() != null) {
+            params.putParam("allow_no_forecasts", Boolean.toString(deleteForecastRequest.isAllowNoForecasts()));
+        }
+        if (deleteForecastRequest.timeout() != null) {
+            params.putParam("timeout", deleteForecastRequest.timeout().getStringRep());
+        }
+        return request;
+    }
+
     static Request getBuckets(GetBucketsRequest getBucketsRequest) throws IOException {
         String endpoint = new EndpointBuilder()
                 .addPathPartAsIs("_xpack")

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

@@ -19,6 +19,8 @@
 package org.elasticsearch.client;
 
 import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.support.master.AcknowledgedResponse;
+import org.elasticsearch.client.ml.DeleteForecastRequest;
 import org.elasticsearch.client.ml.ForecastJobRequest;
 import org.elasticsearch.client.ml.ForecastJobResponse;
 import org.elasticsearch.client.ml.PostDataRequest;
@@ -387,6 +389,11 @@ public ForecastJobResponse forecastJob(ForecastJobRequest request, RequestOption
     /**
      * Updates a Machine Learning {@link org.elasticsearch.client.ml.job.config.Job}
      *
+     * <p>
+     *     For additional info
+     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-job.html"></a>
+     * </p>
+     *
      * @param request the {@link UpdateJobRequest} object enclosing the desired updates
      * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return a PutJobResponse object containing the updated job object
@@ -425,6 +432,10 @@ public void forecastJobAsync(ForecastJobRequest request, RequestOptions options,
     /**
      * Updates a Machine Learning {@link org.elasticsearch.client.ml.job.config.Job} asynchronously
      *
+     * <p>
+     *     For additional info
+     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-job.html"></a>
+     * </p>
      * @param request the {@link UpdateJobRequest} object enclosing the desired updates
      * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @param listener Listener to be notified upon request completion
@@ -438,6 +449,48 @@ public void updateJobAsync(UpdateJobRequest request, RequestOptions options, Act
             Collections.emptySet());
     }
 
+    /**
+     * Deletes Machine Learning Job Forecasts
+     *
+     * <p>
+     *     For additional info
+     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-forecast.html"></a>
+     * </p>
+     *
+     * @param request the {@link DeleteForecastRequest} object enclosing the desired jobId, forecastIDs, and other options
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return a AcknowledgedResponse object indicating request success
+     * @throws IOException when there is a serialization issue sending the request or receiving the response
+     */
+    public AcknowledgedResponse deleteForecast(DeleteForecastRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request,
+            MLRequestConverters::deleteForecast,
+            options,
+            AcknowledgedResponse::fromXContent,
+            Collections.emptySet());
+    }
+
+    /**
+     * Deletes Machine Learning Job Forecasts asynchronously
+     *
+     * <p>
+     *     For additional info
+     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-forecast.html"></a>
+     * </p>
+     *
+     * @param request the {@link DeleteForecastRequest} object enclosing the desired jobId, forecastIDs, and other options
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener Listener to be notified upon request completion
+     */
+    public void deleteForecastAsync(DeleteForecastRequest request, RequestOptions options, ActionListener<AcknowledgedResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request,
+            MLRequestConverters::deleteForecast,
+            options,
+            AcknowledgedResponse::fromXContent,
+            listener,
+            Collections.emptySet());
+    }
+
     /**
      * Gets the buckets for a Machine Learning Job.
      * <p>

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

@@ -0,0 +1,183 @@
+/*
+ * 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.ml;
+
+import org.elasticsearch.action.ActionRequest;
+import org.elasticsearch.action.ActionRequestValidationException;
+import org.elasticsearch.client.ml.job.config.Job;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.ToXContentObject;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * POJO for a delete forecast request
+ */
+public class DeleteForecastRequest extends ActionRequest implements ToXContentObject {
+
+    public static final ParseField FORECAST_ID = new ParseField("forecast_id");
+    public static final ParseField ALLOW_NO_FORECASTS = new ParseField("allow_no_forecasts");
+    public static final ParseField TIMEOUT = new ParseField("timeout");
+    public static final String ALL = "_all";
+
+    public static final ConstructingObjectParser<DeleteForecastRequest, Void> PARSER =
+        new ConstructingObjectParser<>("delete_forecast_request", (a) -> new DeleteForecastRequest((String) a[0]));
+
+    static {
+        PARSER.declareString(ConstructingObjectParser.constructorArg(), Job.ID);
+        PARSER.declareStringOrNull(
+            (c, p) -> c.setForecastIds(Strings.commaDelimitedListToStringArray(p)), FORECAST_ID);
+        PARSER.declareBoolean(DeleteForecastRequest::setAllowNoForecasts, ALLOW_NO_FORECASTS);
+        PARSER.declareString(DeleteForecastRequest::timeout, TIMEOUT);
+    }
+
+    /**
+     * Create a new {@link DeleteForecastRequest} that explicitly deletes all forecasts
+     *
+     * @param jobId the jobId of the Job whose forecasts to delete
+     */
+    public static DeleteForecastRequest deleteAllForecasts(String jobId) {
+        DeleteForecastRequest request = new DeleteForecastRequest(jobId);
+        request.setForecastIds(ALL);
+        return request;
+    }
+
+    private final String jobId;
+    private List<String> forecastIds = new ArrayList<>();
+    private Boolean allowNoForecasts;
+    private TimeValue timeout;
+
+    /**
+     * Create a new DeleteForecastRequest for the given Job ID
+     *
+     * @param jobId the jobId of the Job whose forecast(s) to delete
+     */
+    public DeleteForecastRequest(String jobId) {
+        this.jobId = Objects.requireNonNull(jobId, Job.ID.getPreferredName());
+    }
+
+    public String getJobId() {
+        return jobId;
+    }
+
+    public List<String> getForecastIds() {
+        return forecastIds;
+    }
+
+    /**
+     * The forecast IDs to delete. Can be also be {@link DeleteForecastRequest#ALL} to explicitly delete ALL forecasts
+     *
+     * @param forecastIds forecast IDs to delete
+     */
+    public void setForecastIds(String... forecastIds) {
+        setForecastIds(Arrays.asList(forecastIds));
+    }
+
+    void setForecastIds(List<String> forecastIds) {
+        if (forecastIds.stream().anyMatch(Objects::isNull)) {
+            throw new NullPointerException("forecastIds must not contain null values");
+        }
+        this.forecastIds = new ArrayList<>(forecastIds);
+    }
+
+    public Boolean isAllowNoForecasts() {
+        return allowNoForecasts;
+    }
+
+    /**
+     * Sets the `allow_no_forecasts` field.
+     *
+     * @param allowNoForecasts when {@code true} no error is thrown when {@link DeleteForecastRequest#ALL} does not find any forecasts
+     */
+    public void setAllowNoForecasts(boolean allowNoForecasts) {
+        this.allowNoForecasts = allowNoForecasts;
+    }
+
+    /**
+     * Allows to set the timeout
+     * @param timeout timeout as a string (e.g. 1s)
+     */
+    public void timeout(String timeout) {
+        this.timeout = TimeValue.parseTimeValue(timeout, this.timeout, getClass().getSimpleName() + ".timeout");
+    }
+
+    /**
+     * Allows to set the timeout
+     * @param timeout timeout as a {@link TimeValue}
+     */
+    public void timeout(TimeValue timeout) {
+        this.timeout = timeout;
+    }
+
+    public TimeValue timeout() {
+        return timeout;
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        if (this == other) {
+            return true;
+        }
+
+        if (other == null || getClass() != other.getClass()) {
+            return false;
+        }
+
+        DeleteForecastRequest that = (DeleteForecastRequest) other;
+        return Objects.equals(jobId, that.jobId) &&
+            Objects.equals(forecastIds, that.forecastIds) &&
+            Objects.equals(allowNoForecasts, that.allowNoForecasts) &&
+            Objects.equals(timeout, that.timeout);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(jobId, forecastIds, allowNoForecasts, timeout);
+    }
+
+    @Override
+    public ActionRequestValidationException validate() {
+        return null;
+    }
+
+    @Override
+    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
+        builder.startObject();
+        builder.field(Job.ID.getPreferredName(), jobId);
+        if (forecastIds != null) {
+            builder.field(FORECAST_ID.getPreferredName(), Strings.collectionToCommaDelimitedString(forecastIds));
+        }
+        if (allowNoForecasts != null) {
+            builder.field(ALLOW_NO_FORECASTS.getPreferredName(), allowNoForecasts);
+        }
+        if (timeout != null) {
+            builder.field(TIMEOUT.getPreferredName(), timeout.getStringRep());
+        }
+        builder.endObject();
+        return builder;
+    }
+}

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

@@ -24,6 +24,7 @@
 import org.apache.http.client.methods.HttpPost;
 import org.apache.http.client.methods.HttpPut;
 import org.elasticsearch.client.ml.CloseJobRequest;
+import org.elasticsearch.client.ml.DeleteForecastRequest;
 import org.elasticsearch.client.ml.DeleteJobRequest;
 import org.elasticsearch.client.ml.FlushJobRequest;
 import org.elasticsearch.client.ml.ForecastJobRequest;
@@ -43,6 +44,7 @@
 import org.elasticsearch.client.ml.job.config.JobUpdate;
 import org.elasticsearch.client.ml.job.config.JobUpdateTests;
 import org.elasticsearch.client.ml.job.util.PageParams;
+import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.unit.TimeValue;
 import org.elasticsearch.common.xcontent.XContentParser;
 import org.elasticsearch.common.xcontent.XContentType;
@@ -203,6 +205,33 @@ public void testUpdateJob() throws Exception {
         }
     }
 
+    public void testDeleteForecast() throws Exception {
+        String jobId = randomAlphaOfLength(10);
+        DeleteForecastRequest deleteForecastRequest = new DeleteForecastRequest(jobId);
+
+        Request request = MLRequestConverters.deleteForecast(deleteForecastRequest);
+        assertEquals(HttpDelete.METHOD_NAME, request.getMethod());
+        assertEquals("/_xpack/ml/anomaly_detectors/" + jobId + "/_forecast", request.getEndpoint());
+        assertFalse(request.getParameters().containsKey("timeout"));
+        assertFalse(request.getParameters().containsKey("allow_no_forecasts"));
+
+        deleteForecastRequest.setForecastIds(randomAlphaOfLength(10), randomAlphaOfLength(10));
+        deleteForecastRequest.timeout("10s");
+        deleteForecastRequest.setAllowNoForecasts(true);
+
+        request = MLRequestConverters.deleteForecast(deleteForecastRequest);
+        assertEquals(
+            "/_xpack/ml/anomaly_detectors/" +
+                jobId +
+                "/_forecast/" +
+                Strings.collectionToCommaDelimitedString(deleteForecastRequest.getForecastIds()),
+            request.getEndpoint());
+        assertEquals("10s",
+            request.getParameters().get(DeleteForecastRequest.TIMEOUT.getPreferredName()));
+        assertEquals(Boolean.toString(true),
+            request.getParameters().get(DeleteForecastRequest.ALLOW_NO_FORECASTS.getPreferredName()));
+    }
+
     public void testGetBuckets() throws IOException {
         String jobId = randomAlphaOfLength(10);
         GetBucketsRequest getBucketsRequest = new GetBucketsRequest(jobId);