From 1b234880ddcead3838dbae22413c5b57fb4142ca Mon Sep 17 00:00:00 2001 From: Benjamin Trent Date: Fri, 24 Aug 2018 09:56:25 -0500 Subject: [PATCH] HLRC: request/response homogeneity and JavaDoc improvements --- .../protocol/xpack/ml/CloseJobRequest.java | 34 +++++++++---------- .../protocol/xpack/ml/CloseJobResponse.java | 22 ++++++------ .../protocol/xpack/ml/DeleteJobRequest.java | 13 +++++++ .../protocol/xpack/ml/DeleteJobResponse.java | 3 ++ .../protocol/xpack/ml/GetJobRequest.java | 11 ++---- .../protocol/xpack/ml/OpenJobRequest.java | 18 ++++++++++ .../protocol/xpack/ml/OpenJobResponse.java | 24 +++++++------ .../protocol/xpack/ml/PutJobRequest.java | 8 +++++ .../protocol/xpack/ml/PutJobResponse.java | 5 ++- 9 files changed, 89 insertions(+), 49 deletions(-) diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobRequest.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobRequest.java index 3d54bfb9488a9..38f924163061a 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobRequest.java +++ b/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 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; diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobResponse.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobResponse.java index 9e1f38ef6bab7..1b8ff3ca7d4d4 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobResponse.java +++ b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/CloseJobResponse.java @@ -20,7 +20,7 @@ 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; @@ -28,22 +28,22 @@ 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 PARSER = - new ObjectParser<>("close_job_response", true, CloseJobResponse::new); + public static final ConstructingObjectParser 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) { diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobRequest.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobRequest.java index 1b7450de0929c..9f265fd20a8c9 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobRequest.java +++ b/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; } diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobResponse.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobResponse.java index 0b4faa38f545f..795eb784aaff5 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/DeleteJobResponse.java +++ b/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) { diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/GetJobRequest.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/GetJobRequest.java index b0377c86fdc78..c3c14726505cf 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/GetJobRequest.java +++ b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/GetJobRequest.java @@ -87,20 +87,15 @@ public List 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; } diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobRequest.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobRequest.java index a18a18bb55a14..658c7d38503e3 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobRequest.java +++ b/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; } diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobResponse.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobResponse.java index d8850ddbbe3a8..3a1e477980439 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobResponse.java +++ b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/OpenJobResponse.java @@ -20,7 +20,7 @@ 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; @@ -28,22 +28,23 @@ 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 PARSER = new ObjectParser<>("open_job_response", true, OpenJobResponse::new); + public static final ConstructingObjectParser 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; } @@ -51,14 +52,15 @@ public static OpenJobResponse fromXContent(XContentParser parser) throws IOExcep 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) { diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobRequest.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobRequest.java index 2cdf1993fccd3..bc3fd778c1bd8 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobRequest.java +++ b/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; } diff --git a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobResponse.java b/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobResponse.java index 1bd9e87f6544c..3fa1b30dd3ebe 100644 --- a/x-pack/protocol/src/main/java/org/elasticsearch/protocol/xpack/ml/PutJobResponse.java +++ b/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; }