convert Build.State and Job.State fields into Enums

Author: Crim

CHANGELOG.md

@@ -2,6 +2,9 @@
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## 0.2.0 (02/21/2023)
+- Breaking Change. Job::getState() and Build::getState() now return ENUM values.
+
 ## 0.1.2 (02/21/2023)
 - Add support for annotations end point.
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>org.sourcelab</groupId>
     <artifactId>buildkite-api-client</artifactId>
-    <version>0.1.2</version>
+    <version>0.2.0</version>
     <packaging>jar</packaging>
 
     <!-- Require Maven 3.3.9 -->

src/main/java/org/sourcelab/buildkite/api/client/response/Build.java

@@ -29,7 +29,7 @@ public class Build {
     private final String url;
     private final String webUrl;
     private final long number;
-    private final String state;
+    private final BuildState state;
     private final boolean blocked;
     private final String message;
     private final String commit;
@@ -81,7 +81,7 @@ public Build(
         this.url = url;
         this.webUrl = webUrl;
         this.number = number;
-        this.state = state;
+        this.state = BuildState.createFromString(state);
         this.blocked = blocked;
         this.message = message;
         this.commit = commit;
@@ -119,7 +119,7 @@ public long getNumber() {
         return number;
     }
 
-    public String getState() {
+    public BuildState getState() {
         return state;
     }
 

src/main/java/org/sourcelab/buildkite/api/client/response/BuildState.java

@@ -0,0 +1,75 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ * <p>
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ * <p>
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.sourcelab.buildkite.api.client.response;
+
+public enum BuildState {
+    CREATING,
+    SCHEDULED,
+    RUNNING,
+    PASSED,
+    CANCELING,
+    CANCELED,
+    FAILING,
+    FAILED,
+    BLOCKED,
+    SKIPPED,
+    NOT_RUN,
+    BROKEN,
+    // Fall through value
+    UNKNOWN;
+
+    /**
+     * Create enum from String value as returned from the API.
+     * @param value the string representation.
+     * @return Enum value, or UNKNOWN if passed an unhandled value.
+     */
+    public static BuildState createFromString(final String value) {
+        if (value == null) {
+            return UNKNOWN;
+        }
+
+        switch (value.trim().toLowerCase()) {
+            case "creating":
+                return CREATING;
+            case "scheduled":
+                return SCHEDULED;
+            case "running":
+                return RUNNING;
+            case "passed":
+                return PASSED;
+            case "canceling":
+                return CANCELING;
+            case "canceled":
+                return CANCELED;
+            case "failing":
+                return FAILING;
+            case "failed":
+                return FAILED;
+            case "blocked":
+                return BLOCKED;
+            case "skipped":
+                return SKIPPED;
+            case "not_run":
+                return NOT_RUN;
+            case "broken":
+                return BROKEN;
+            default:
+                return UNKNOWN;
+        }
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/response/Job.java

@@ -28,7 +28,7 @@ public class Job {
     private final String type;
     private final String name;
     private final String stepKey;
-    private final String state;
+    private final JobState state;
     private final String webUrl;
     private final String logUrl;
     private final String rawLogUrl;
@@ -94,7 +94,7 @@ public Job(
         this.type = type;
         this.name = name;
         this.stepKey = stepKey;
-        this.state = state;
+        this.state = JobState.createFromString(state);
         this.webUrl = webUrl;
         this.logUrl = logUrl;
         this.rawLogUrl = rawLogUrl;
@@ -136,7 +136,7 @@ public String getStepKey() {
         return stepKey;
     }
 
-    public String getState() {
+    public JobState getState() {
         return state;
     }
 

src/main/java/org/sourcelab/buildkite/api/client/response/JobState.java

@@ -0,0 +1,111 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ * <p>
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ * <p>
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.sourcelab.buildkite.api.client.response;
+
+public enum JobState {
+    SKIPPED,
+    ACCEPTED,
+    ASSIGNED,
+    SCHEDULED,
+    WAITING,
+    PENDING,
+    WAITING_FAILED,
+    BLOCKED_FAILED,
+    UNBLOCKED_FAILED,
+    TIMED_OUT,
+    BROKEN,
+    FAILED,
+    LIMITING,
+    LIMITED,
+    BLOCKED,
+    CANCELED,
+    TIMING_OUT,
+    RUNNING,
+    UNBLOCKED,
+    CANCELING,
+    PASSED,
+    FINISHED,
+
+    // Fall through value.
+    UNKNOWN;
+
+    /**
+     * Create enum from String value as returned from the API.
+     * @param value the string representation.
+     * @return Enum value, or UNKNOWN if passed an unhandled value.
+     */
+    public static JobState createFromString(final String value) {
+        if (value == null) {
+            return UNKNOWN;
+        }
+        switch (value.trim().toLowerCase()) {
+            case "skipped":
+                return SKIPPED;
+            case "accepted":
+                return ACCEPTED;
+            case "assigned":
+                return ASSIGNED;
+            case "scheduled":
+                return SCHEDULED;
+            case "waiting":
+                return WAITING;
+            case "pending":
+                return PENDING;
+
+            case "waiting_failed":
+                return WAITING_FAILED;
+            case "blocked_failed":
+                return BLOCKED_FAILED;
+            case "unblocked_failed":
+                return UNBLOCKED_FAILED;
+            case "timed_out":
+                return TIMED_OUT;
+            case "broken":
+                return BROKEN;
+            case "failed":
+                return FAILED;
+
+            case "limiting":
+                return LIMITING;
+            case "limited":
+                return LIMITED;
+            case "blocked":
+                return BLOCKED;
+            case "canceled":
+                return CANCELED;
+            case "timing_out":
+                return TIMING_OUT;
+
+            case "running":
+                return RUNNING;
+            case "unblocked":
+                return UNBLOCKED;
+            case "canceling":
+                return CANCELING;
+
+            case "passed":
+                return PASSED;
+            case "finished":
+                return FINISHED;
+
+            default:
+                return UNKNOWN;
+        }
+    }
+
+}

src/main/java/org/sourcelab/buildkite/api/client/util/BuildStateUtils.java

@@ -0,0 +1,67 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ * <p>
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ * <p>
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package org.sourcelab.buildkite.api.client.util;
+
+import org.sourcelab.buildkite.api.client.response.BuildState;
+
+/**
+ * Helpful utilities around Build State field and the BuildState enum.
+ */
+public class BuildStateUtils {
+    /**
+     * Check if the provided BuildState value is able to be cancelled.
+     *
+     * @param state The state to check.
+     * @return true if the state is cancellable, false if not.
+     */
+    public static boolean isStateCancellable(final BuildState state) {
+        if (state == null) {
+            return false;
+        }
+        switch (state) {
+            case CREATING:
+            case SCHEDULED:
+            case FAILING:
+            case RUNNING:
+            case BLOCKED:
+                return true;
+        }
+        return false;
+    }
+
+    /**
+     * Check if the provided BuildState value is considered "finished".
+     *
+     * @param state The state to check.
+     * @return true if the state is considered "finished", false if not.
+     */
+    public static boolean isStateConsideredFinished(final BuildState state) {
+        if (state == null) {
+            return true;
+        }
+
+        switch (state) {
+            case FAILED:
+            case PASSED:
+            case SKIPPED:
+            case NOT_RUN:
+            case BROKEN:
+                return true;
+        }
+        return false;
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/util/JobStateUtil.java

@@ -0,0 +1,44 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ * <p>
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ * <p>
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.sourcelab.buildkite.api.client.util;
+
+import org.sourcelab.buildkite.api.client.response.JobState;
+
+/**
+ * Helpful utilities around Job State field and the JobState enum.
+ */
+public class JobStateUtil {
+
+    /**
+     * Check if the provided JobState retryable.
+     * @param state The JobState to check.
+     * @return true if the job state is retryable, false if not.
+     */
+    public static boolean isRetryableState(final JobState state) {
+        if (state == null) {
+            return false;
+        }
+        switch (state) {
+            case CANCELED:
+            case FAILED:
+                return true;
+            default:
+                return false;
+        }
+    }
+}