Add additional end points

Author: Crim

src/main/java/org/sourcelab/buildkite/api/client/BuildkiteClient.java

@@ -21,13 +21,21 @@
 import org.sourcelab.buildkite.api.client.exception.InvalidAccessTokenException;
 import org.sourcelab.buildkite.api.client.exception.InvalidAllowedIpAddressException;
 import org.sourcelab.buildkite.api.client.exception.InvalidPagingRequestException;
+import org.sourcelab.buildkite.api.client.exception.InvalidRequestException;
 import org.sourcelab.buildkite.api.client.exception.NotFoundException;
 import org.sourcelab.buildkite.api.client.http.Client;
 import org.sourcelab.buildkite.api.client.http.HttpResult;
 import org.sourcelab.buildkite.api.client.request.BuildFilters;
 import org.sourcelab.buildkite.api.client.request.BuildFiltersBuilder;
+import org.sourcelab.buildkite.api.client.request.CancelBuildRequest;
+import org.sourcelab.buildkite.api.client.request.CreateBuildOptions;
+import org.sourcelab.buildkite.api.client.request.CreateBuildOptionsBuilder;
+import org.sourcelab.buildkite.api.client.request.CreateBuildRequest;
 import org.sourcelab.buildkite.api.client.request.DeleteAccessTokenRequest;
 import org.sourcelab.buildkite.api.client.request.GetAccessTokenRequest;
+import org.sourcelab.buildkite.api.client.request.GetBuildFilters;
+import org.sourcelab.buildkite.api.client.request.GetBuildFiltersBuilder;
+import org.sourcelab.buildkite.api.client.request.GetBuildRequest;
 import org.sourcelab.buildkite.api.client.request.GetMetaRequest;
 import org.sourcelab.buildkite.api.client.request.GetOrganizationRequest;
 import org.sourcelab.buildkite.api.client.request.GetPipelineRequest;
@@ -41,12 +49,15 @@
 import org.sourcelab.buildkite.api.client.request.PageOptions;
 import org.sourcelab.buildkite.api.client.request.PageableRequest;
 import org.sourcelab.buildkite.api.client.request.PingRequest;
-import org.sourcelab.buildkite.api.client.request.PipelineFiltersBuilder;
 import org.sourcelab.buildkite.api.client.request.PipelineFilters;
+import org.sourcelab.buildkite.api.client.request.PipelineFiltersBuilder;
+import org.sourcelab.buildkite.api.client.request.RebuildBuildRequest;
 import org.sourcelab.buildkite.api.client.request.Request;
 import org.sourcelab.buildkite.api.client.response.AccessTokenResponse;
+import org.sourcelab.buildkite.api.client.response.Build;
 import org.sourcelab.buildkite.api.client.response.CurrentUserResponse;
 import org.sourcelab.buildkite.api.client.response.Emoji;
+import org.sourcelab.buildkite.api.client.response.Error;
 import org.sourcelab.buildkite.api.client.response.ErrorResponse;
 import org.sourcelab.buildkite.api.client.response.ListBuildsResponse;
 import org.sourcelab.buildkite.api.client.response.ListOrganizationsResponse;
@@ -60,9 +71,11 @@
 import org.sourcelab.buildkite.api.client.response.parser.ErrorResponseParser;
 
 import java.io.IOException;
+import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.stream.Collectors;
 
 /**
  * API Client for Buildkite's REST Api.
@@ -296,6 +309,101 @@ public ListBuildsResponse listBuilds(final BuildFilters filters) {
         return executeRequest(new ListBuildsRequest(filters));
     }
 
+    /**
+     * Retrieve a specific build based on the filter criteria.
+     *
+     * @param filters Filter criteria.
+     * @return The build which matches the criteria if found.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Optional<Build> getBuild(final GetBuildFiltersBuilder filters) {
+        return getBuild(filters.build());
+    }
+
+    /**
+     * Retrieve a specific build based on the filter criteria.
+     *
+     * @param organizationSlugId Organization associated with the build.
+     * @param pipelineSlugId Pipeline associated with the build.
+     * @param buildNumber The build number.
+     * @return The build which matches the criteria if found.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Optional<Build> getBuild(final String organizationSlugId, final String pipelineSlugId, final long buildNumber) {
+        return getBuild(GetBuildFilters.newBuilder()
+            .withOrgIdSlug(organizationSlugId)
+            .withPipelineIdSlug(pipelineSlugId)
+            .withBuildNumber(buildNumber)
+        );
+    }
+
+    /**
+     * Retrieve a specific build based on the filter criteria.
+     *
+     * @param filters Filter criteria.
+     * @return The build which matches the criteria if found.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Optional<Build> getBuild(final GetBuildFilters filters) {
+        final Build build = executeRequest(new GetBuildRequest(filters));
+        return Optional.ofNullable(build);
+    }
+
+    /**
+     * Cancels the build if its state is either scheduled or running.
+     *
+     * @param organizationSlugId Organization associated with the build.
+     * @param pipelineSlugId Pipeline associated with the build.
+     * @param buildNumber The build number.
+     * @return Updated Build instance.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Build cancelBuild(final String organizationSlugId, final String pipelineSlugId, final long buildNumber) {
+        return executeRequest(new CancelBuildRequest(organizationSlugId, pipelineSlugId, buildNumber));
+    }
+
+    /**
+     * Creates a new build to be executed.
+     *
+     * @param createBuildOptions Defines the build to be created.
+     * @return Created Build instance.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Build createBuild(final CreateBuildOptionsBuilder createBuildOptions) {
+        return createBuild(createBuildOptions.build());
+    }
+
+    /**
+     * Creates a new build to be executed.
+     *
+     * @param createBuildOptions Defines the build to be created.
+     * @return Created Build instance.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Build createBuild(final CreateBuildOptions createBuildOptions) {
+        return executeRequest(new CreateBuildRequest(createBuildOptions));
+    }
+
+    /**
+     * Retries a build.
+     *
+     * @param organizationSlugId Organization associated with the build.
+     * @param pipelineSlugId Pipeline associated with the build.
+     * @param buildNumber The build number.
+     * @return Updated Build instance.
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Build rebuildBuild(final String organizationSlugId, final String pipelineSlugId, final long buildNumber) {
+        return executeRequest(new RebuildBuildRequest(organizationSlugId, pipelineSlugId, buildNumber));
+    }
+
     /**
      * Retrieve the next page of results from the previously retrieved request.
      *
@@ -444,7 +552,7 @@ public <T> T executeRequest(final Request<T> request) throws BuildkiteException
         final HttpResult result = httpClient.executeRequest(request);
 
         // Handle Errors based on HttpCode.
-        if (result.getStatus() != 200 && result.getStatus() != 204) {
+        if (result.getStatus() != 200 && result.getStatus() != 201 && result.getStatus() != 204) {
             handleError(result);
         }
 
@@ -460,9 +568,11 @@ public <T> T executeRequest(final Request<T> request) throws BuildkiteException
     private void handleError(final HttpResult errorResult) throws BuildkiteException {
         // Attempt to parse error response.
         String errorMessage = null;
+        List<Error> errors = Collections.emptyList();
         try {
             final ErrorResponse errorResponse = new ErrorResponseParser().parseResponse(errorResult);
             errorMessage = errorResponse.getMessage();
+            errors = errorResponse.getErrors();
         } catch (final IOException e) {
             errorMessage = errorResult.getContent();
         }
@@ -478,18 +588,24 @@ private void handleError(final HttpResult errorResult) throws BuildkiteException
             case 403:
                 throw new InvalidAllowedIpAddressException(
                     errorMessage == null
-                        ?
-                            "API requested from an IP address not specifically allowed by your AccessToken. "
-                            + "Check the 'Allowed IP Addresses' field on your Access Token"
-                        : errorMessage
+                    ?
+                        "API requested from an IP address not specifically allowed by your AccessToken. "
+                        + "Check the 'Allowed IP Addresses' field on your Access Token"
+                    : errorMessage
                 );
             case 404:
                 throw new NotFoundException(
                     errorMessage == null
-                            ?
-                            "The URL or Resource Request could not be found"
-                            : errorMessage
+                        ?
+                        "The URL or Resource Request could not be found"
+                        : errorMessage
                 );
+            case 422:
+                String validationErrorMessage = (( errorMessage != null) ? errorMessage : "The submitted request was invalid. ");
+                validationErrorMessage += "\n" + errors.stream()
+                    .map((error) -> error.getField() + ": " + error.getCode())
+                    .collect(Collectors.joining("\n"));
+                throw new InvalidRequestException(validationErrorMessage, errors);
             default:
                 throw new BuildkiteException(
                     errorMessage == null ? "Unknown/Unhandled Error HttpCode: " + errorResult.getStatus() : errorMessage

src/main/java/org/sourcelab/buildkite/api/client/ConfigurationBuilder.java

@@ -17,6 +17,7 @@
 
 package org.sourcelab.buildkite.api.client;
 
+import org.sourcelab.buildkite.api.client.exception.BuilderValidationException;
 import org.sourcelab.buildkite.api.client.http.ClientFactory;
 import org.sourcelab.buildkite.api.client.http.DefaultClientFactory;
 
@@ -56,17 +57,17 @@ public ConfigurationBuilder withClientFactory(final ClientFactory clientFactory)
 
     /**
      * Validates that the supplied values are correct.
-     * @throws IllegalStateException if improper values defined.
+     * @throws BuilderValidationException if not valid or complete.
      */
     private void validate() {
         if (apiToken == null || apiToken.trim().isEmpty()) {
-            throw new IllegalStateException("The 'ApiToken' property must be configured.");
+            throw new BuilderValidationException("The 'ApiToken' property must be configured.");
         }
         if (clientFactory == null) {
-            throw new IllegalStateException("The 'ClientFactory' property must be configured.");
+            throw new BuilderValidationException("The 'ClientFactory' property must be configured.");
         }
         if (apiUrl == null || apiUrl.trim().isEmpty()) {
-            throw new IllegalStateException("The 'ApiUrl' property must be configured.");
+            throw new BuilderValidationException("The 'ApiUrl' property must be configured.");
         }
     }
 

src/main/java/org/sourcelab/buildkite/api/client/exception/BuilderValidationException.java

@@ -0,0 +1,40 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * 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:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * 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.exception;
+
+/**
+ * Thrown if a builder fails validation or is not complete.
+ */
+public class BuilderValidationException extends BuildkiteException {
+    /**
+     * Constructor.
+     * @param message Error message.
+     */
+    public BuilderValidationException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Constructor.
+     * @param message Error message.
+     * @param cause Underlying exception.
+     */
+    public BuilderValidationException(final String message, final Throwable cause) {
+        super(message, cause);
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/exception/InvalidRequestException.java

@@ -0,0 +1,67 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * 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:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * 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.exception;
+
+import org.sourcelab.buildkite.api.client.response.Error;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Thrown if request submitted to API comes back as invalid.
+ */
+public class InvalidRequestException extends BuildkiteException {
+    private final List<Error> errors;
+
+     /**
+     * Constructor.
+     * @param message Error message.
+      */
+    public InvalidRequestException(final String message) {
+        this(message, Collections.emptyList());
+    }
+
+    /**
+     * Constructor.
+     * @param message Error message.
+     * @param cause Underlying error cause.
+     */
+    public InvalidRequestException(final String message, final Exception cause) {
+        super(message, cause);
+        errors = Collections.emptyList();
+    }
+
+    /**
+     * Constructor.
+     * @param message Error message.
+     * @param errors Underlying errors, if any.
+     */
+    public InvalidRequestException(final String message, final List<Error> errors) {
+        super(message);
+        this.errors = Collections.unmodifiableList(new ArrayList<>(errors));
+    }
+
+    /**
+     * Get errors associated with the request.
+     * @return Errors associated with the request.
+     */
+    public List<Error> getErrors() {
+        return errors;
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/exception/RequestParsingException.java

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * 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:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * 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.exception;
+
+/**
+ * Thrown if the library is unable to serialize a request body.
+ * This likely results from a bug in the Buildkite Api Client library, with it not understanding
+ * how to properly parse a given response.
+ */
+public class RequestParsingException extends BuildkiteException {
+    /**
+     * Constructor.
+     * @param message Error message.
+     */
+    public RequestParsingException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Constructor.
+     * @param message Error message.
+     * @param cause Underlying exception.
+     */
+    public RequestParsingException(final String message, final Throwable cause) {
+        super(message, cause);
+    }
+}