HLRC: request/response homogeneity and JavaDoc improvements (#33133)

Author: benwtrent

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobRequest.java

@@ -35,6 +35,9 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Request to close Machine Learning Jobs
+ */
 public class CloseJobRequest extends ActionRequest implements ToXContentObject {
 
     public static final ParseField JOB_ID = new ParseField("job_id");
@@ -98,49 +101,44 @@ public List<String> getJobIds() {
         return jobIds;
     }
 
-    /**
-     * How long to wait for the close request to complete before timing out.
-     *
-     * Default: 30 minutes
-     */
     public TimeValue getTimeout() {
         return timeout;
     }
 
     /**
-     * {@link CloseJobRequest#getTimeout()}
+     * How long to wait for the close request to complete before timing out.
+     *
+     * @param timeout Default value: 30 minutes
      */
     public void setTimeout(TimeValue timeout) {
         this.timeout = timeout;
     }
 
-    /**
-     * Should the closing be forced.
-     *
-     * Use to close a failed job, or to forcefully close a job which has not responded to its initial close request.
-     */
     public Boolean isForce() {
         return force;
     }
 
     /**
-     * {@link CloseJobRequest#isForce()}
+     * Should the closing be forced.
+     *
+     * Use to close a failed job, or to forcefully close a job which has not responded to its initial close request.
+     *
+     * @param force When {@code true} forcefully close the job. Defaults to {@code false}
      */
     public void setForce(boolean force) {
         this.force = force;
     }
 
-    /**
-     * Whether to ignore if a wildcard expression matches no jobs.
-     *
-     * This includes `_all` string or when no jobs have been specified
-     */
     public Boolean isAllowNoJobs() {
         return this.allowNoJobs;
     }
 
     /**
-     * {@link CloseJobRequest#isAllowNoJobs()}
+     * Whether to ignore if a wildcard expression matches no jobs.
+     *
+     * This includes `_all` string or when no jobs have been specified
+     *
+     * @param allowNoJobs When {@code true} ignore if wildcard or `_all` matches no jobs. Defaults to {@code true}
      */
     public void setAllowNoJobs(boolean allowNoJobs) {
         this.allowNoJobs = allowNoJobs;

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobResponse.java

@@ -20,30 +20,30 @@
 
 import org.elasticsearch.action.ActionResponse;
 import org.elasticsearch.common.ParseField;
-import org.elasticsearch.common.xcontent.ObjectParser;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
 import org.elasticsearch.common.xcontent.ToXContentObject;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentParser;
 
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Response indicating if the Job(s) closed or not
+ */
 public class CloseJobResponse extends ActionResponse implements ToXContentObject {
 
     private static final ParseField CLOSED = new ParseField("closed");
 
-    public static final ObjectParser<CloseJobResponse, Void> PARSER =
-        new ObjectParser<>("close_job_response", true, CloseJobResponse::new);
+    public static final ConstructingObjectParser<CloseJobResponse, Void> PARSER =
+        new ConstructingObjectParser<>("close_job_response", true, (a) -> new CloseJobResponse((Boolean)a[0]));
 
     static {
-        PARSER.declareBoolean(CloseJobResponse::setClosed, CLOSED);
+        PARSER.declareBoolean(ConstructingObjectParser.constructorArg(), CLOSED);
     }
 
     private boolean closed;
 
-    CloseJobResponse() {
-    }
-
     public CloseJobResponse(boolean closed) {
         this.closed = closed;
     }
@@ -52,14 +52,14 @@ public static CloseJobResponse fromXContent(XContentParser parser) throws IOExce
         return PARSER.parse(parser, null);
     }
 
+    /**
+     * Has the job closed or not
+     * @return boolean value indicating the job closed status
+     */
     public boolean isClosed() {
         return closed;
     }
 
-    public void setClosed(boolean closed) {
-        this.closed = closed;
-    }
-
     @Override
     public boolean equals(Object other) {
         if (this == other) {

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobRequest.java

@@ -23,6 +23,9 @@
 
 import java.util.Objects;
 
+/**
+ * Request to delete a Machine Learning Job via its ID
+ */
 public class DeleteJobRequest extends ActionRequest {
 
     private String jobId;
@@ -36,6 +39,10 @@ public String getJobId() {
         return jobId;
     }
 
+    /**
+     * The jobId which to delete
+     * @param jobId unique jobId to delete, must not be null
+     */
     public void setJobId(String jobId) {
         this.jobId = Objects.requireNonNull(jobId, "[job_id] must not be null");
     }
@@ -44,6 +51,12 @@ public boolean isForce() {
         return force;
     }
 
+    /**
+     * Used to forcefully delete an opened job.
+     * This method is quicker than closing and deleting the job.
+     *
+     * @param force When {@code true} forcefully delete an opened job. Defaults to {@code false}
+     */
     public void setForce(boolean force) {
         this.force = force;
     }

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobResponse.java

@@ -24,6 +24,9 @@
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Response acknowledging the Machine Learning Job request
+ */
 public class DeleteJobResponse extends AcknowledgedResponse {
 
    public DeleteJobResponse(boolean acknowledged) {

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/GetJobRequest.java

@@ -87,20 +87,15 @@ public List<String> getJobIds() {
         return jobIds;
     }
 
-
     /**
-     * See {@link GetJobRequest#isAllowNoJobs()}
-     * @param allowNoJobs
+     * Whether to ignore if a wildcard expression matches no jobs.
+     *
+     * @param allowNoJobs If this is {@code false}, then an error is returned when a wildcard (or `_all`) does not match any jobs
      */
     public void setAllowNoJobs(boolean allowNoJobs) {
         this.allowNoJobs = allowNoJobs;
     }
 
-    /**
-     * Whether to ignore if a wildcard expression matches no jobs.
-     *
-     * If this is `false`, then an error is returned when a wildcard (or `_all`) does not match any jobs
-     */
     public Boolean isAllowNoJobs() {
         return allowNoJobs;
     }

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobRequest.java

@@ -33,6 +33,9 @@
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Request to open a Machine Learning Job
+ */
 public class OpenJobRequest extends ActionRequest implements ToXContentObject {
 
     public static final ParseField TIMEOUT = new ParseField("timeout");
@@ -51,6 +54,11 @@ public static OpenJobRequest fromXContent(XContentParser parser) throws IOExcept
     private String jobId;
     private TimeValue timeout;
 
+    /**
+     * Create a new request with the desired jobId
+     *
+     * @param jobId unique jobId, must not be null
+     */
     public OpenJobRequest(String jobId) {
         this.jobId = Objects.requireNonNull(jobId, "[job_id] must not be null");
     }
@@ -59,6 +67,11 @@ public String getJobId() {
         return jobId;
     }
 
+    /**
+     * The jobId to open
+     *
+     * @param jobId unique jobId, must not be null
+     */
     public void setJobId(String jobId) {
         this.jobId = Objects.requireNonNull(jobId, "[job_id] must not be null");
     }
@@ -67,6 +80,11 @@ public TimeValue getTimeout() {
         return timeout;
     }
 
+    /**
+     * How long to wait for job to open before timing out the request
+     *
+     * @param timeout default value of 30 minutes
+     */
     public void setTimeout(TimeValue timeout) {
         this.timeout = timeout;
     }

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobResponse.java

@@ -20,45 +20,47 @@
 
 import org.elasticsearch.action.ActionResponse;
 import org.elasticsearch.common.ParseField;
-import org.elasticsearch.common.xcontent.ObjectParser;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
 import org.elasticsearch.common.xcontent.ToXContentObject;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentParser;
 
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Response indicating if the Machine Learning Job is now opened or not
+ */
 public class OpenJobResponse extends ActionResponse implements ToXContentObject {
 
     private static final ParseField OPENED = new ParseField("opened");
 
-    public static final ObjectParser<OpenJobResponse, Void> PARSER = new ObjectParser<>("open_job_response", true, OpenJobResponse::new);
+    public static final ConstructingObjectParser<OpenJobResponse, Void> PARSER =
+        new ConstructingObjectParser<>("open_job_response", true, (a) -> new OpenJobResponse((Boolean)a[0]));
 
     static {
-        PARSER.declareBoolean(OpenJobResponse::setOpened, OPENED);
+        PARSER.declareBoolean(ConstructingObjectParser.constructorArg(), OPENED);
     }
 
     private boolean opened;
 
-    OpenJobResponse() {
-    }
-
-    public OpenJobResponse(boolean opened) {
+    OpenJobResponse(boolean opened) {
         this.opened = opened;
     }
 
     public static OpenJobResponse fromXContent(XContentParser parser) throws IOException {
         return PARSER.parse(parser, null);
     }
 
+    /**
+     * Has the job opened or not
+     *
+     * @return boolean value indicating the job opened status
+     */
     public boolean isOpened() {
         return opened;
     }
 
-    public void setOpened(boolean opened) {
-        this.opened = opened;
-    }
-
     @Override
     public boolean equals(Object other) {
         if (this == other) {

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobRequest.java

@@ -28,10 +28,18 @@
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Request to create a new Machine Learning Job given a {@link Job} configuration
+ */
 public class PutJobRequest extends ActionRequest implements ToXContentObject {
 
     private final Job job;
 
+    /**
+     * Construct a new PutJobRequest
+     *
+     * @param job a {@link Job} configuration to create
+     */
     public PutJobRequest(Job job) {
         this.job = job;
     }

x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobResponse.java

@@ -27,6 +27,9 @@
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Response containing the newly created {@link Job}
+ */
 public class PutJobResponse implements ToXContentObject {
 
     private Job job;
@@ -35,7 +38,7 @@ public static PutJobResponse fromXContent(XContentParser parser) throws IOExcept
         return new PutJobResponse(Job.PARSER.parse(parser, null).build());
     }
 
-    public PutJobResponse(Job job) {
+    PutJobResponse(Job job) {
         this.job = job;
     }