first pass getting paging thru results working

Author: Crim

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

@@ -20,6 +20,7 @@
 import org.sourcelab.buildkite.api.client.exception.BuildkiteException;
 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.NotFoundException;
 import org.sourcelab.buildkite.api.client.http.Client;
 import org.sourcelab.buildkite.api.client.http.HttpResult;
@@ -31,6 +32,8 @@
 import org.sourcelab.buildkite.api.client.request.GetUserRequest;
 import org.sourcelab.buildkite.api.client.request.ListBuildsRequest;
 import org.sourcelab.buildkite.api.client.request.ListEmojisRequest;
+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.Request;
 import org.sourcelab.buildkite.api.client.response.AccessTokenResponse;
@@ -39,11 +42,14 @@
 import org.sourcelab.buildkite.api.client.response.ErrorResponse;
 import org.sourcelab.buildkite.api.client.response.ListBuildsResponse;
 import org.sourcelab.buildkite.api.client.response.MetaResponse;
+import org.sourcelab.buildkite.api.client.response.PageableResponse;
+import org.sourcelab.buildkite.api.client.response.PagingLinks;
 import org.sourcelab.buildkite.api.client.response.PingResponse;
 import org.sourcelab.buildkite.api.client.response.parser.ErrorResponseParser;
 
 import java.io.IOException;
 import java.util.List;
+import java.util.Objects;
 
 /**
  * API Client for Buildkite's REST Api.
@@ -121,23 +127,180 @@ public MetaResponse getMeta() throws BuildkiteException {
      * List all of the Emojis defined in the given Organization.
      * @param orgIdSlug Organization Id slug to retrieve list of emojis for.
      * @return List of Emojis.
+     * @throws BuildkiteException if API returns an error response.
      */
     public List<Emoji> listEmojis(final String orgIdSlug) {
         return executeRequest(new ListEmojisRequest(orgIdSlug));
     }
 
+    /**
+     * Retrieve all Builds accessible to the current user/API access token, across all Organizations.
+     * Results will be paged.
+     *
+     * @return All Builds accessible to the current user/API access token, across all Organizations. Results
+     *         will be paged if the number of results exceeds 30.
+     * @throws BuildkiteException if API returns an error response.
+     */
     public ListBuildsResponse listBuilds() {
         return listBuilds(BuildFilters.newBuilder().build());
     }
 
+    /**
+     * Retrieve all builds which match the supplied search criteria.
+     *
+     * @return All builds which match the supplied search criteria. Results will be paged if the number of results
+     *         exceeds 30 (or the page limit specified in the search criteria).
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
     public ListBuildsResponse listBuilds(final BuildFiltersBuilder filtersBuilder) {
         return listBuilds(filtersBuilder.build());
     }
 
+    /**
+     * Retrieve all builds which match the supplied search criteria.
+     *
+     * @return All builds which match the supplied search criteria. Results will be paged if the number of results
+     *         exceeds 30 (or the page limit specified in the search criteria).
+     *
+     * @throws BuildkiteException if API returns an error response.
+     */
     public ListBuildsResponse listBuilds(final BuildFilters filters) {
         return executeRequest(new ListBuildsRequest(filters));
     }
 
+    /**
+     * Retrieve the next page of results from the previously retrieved request.
+     *
+     * @param <T> The parsed return object representing the result.
+     * @param response Previously retrieved result/response to retrieve the next page of results for.
+     * @return The next page of results.
+     * @throws InvalidPagingRequestException if no next page exists to retrieve.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public <T> T nextPage(final PageableResponse<T> response) {
+        // Validate
+        Objects.requireNonNull(response);
+        final PagingLinks pagingLinks = Objects.requireNonNull(response.getPagingLinks());
+        if (!pagingLinks.hasNextUrl()) {
+            throw new InvalidPagingRequestException(
+                "Requested 'Next' page on response " + response.getClass().getSimpleName() + ", but no Next page is available."
+            );
+        }
+
+        // Update request with appropriate page options.
+        final PageOptions pageOptions;
+        try {
+            pageOptions = PageOptions.fromUrl(pagingLinks.getNextUrl());
+        } catch (final IllegalArgumentException ex) {
+            throw new InvalidPagingRequestException("Unable to parse URL for paging information", ex);
+        }
+        final PageableRequest<T> request = response.getOriginalRequest();
+        request.updatePageOptions(pageOptions);
+
+        // Execute and return.
+        return executeRequest(request);
+    }
+
+    /**
+     * Retrieve the previous page of results from the previously retrieved request.
+     *
+     * @param <T> The parsed return object representing the result.
+     * @param response Previously retrieved result/response to retrieve the previous page of results for.
+     * @return The previous page of results.
+     * @throws InvalidPagingRequestException if no previous page exists to retrieve.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public <T> T previousPage(final PageableResponse<T> response) {
+        // Validate
+        Objects.requireNonNull(response);
+        final PagingLinks pagingLinks = Objects.requireNonNull(response.getPagingLinks());
+        if (!pagingLinks.hasPrevUrl()) {
+            throw new InvalidPagingRequestException(
+                "Requested 'Previous' page on response " + response.getClass().getSimpleName() + ", but no Previous page is available."
+            );
+        }
+
+        // Update request with appropriate page options.
+        final PageOptions pageOptions;
+        try {
+            pageOptions = PageOptions.fromUrl(pagingLinks.getNextUrl());
+        } catch (final IllegalArgumentException ex) {
+            throw new InvalidPagingRequestException("Unable to parse URL for paging information", ex);
+        }
+        final PageableRequest<T> request = response.getOriginalRequest();
+        request.updatePageOptions(pageOptions);
+
+        // Execute and return.
+        return executeRequest(request);
+    }
+
+    /**
+     * Retrieve the first page of results from the previously retrieved request.
+     *
+     * @param <T> The parsed return object representing the result.
+     * @param response Previously retrieved result/response to retrieve the first page of results for.
+     * @return The first page of results.
+     * @throws InvalidPagingRequestException if no previous page exists to retrieve.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public <T> T firstPage(final PageableResponse<T> response) {
+        // Validate
+        Objects.requireNonNull(response);
+        final PagingLinks pagingLinks = Objects.requireNonNull(response.getPagingLinks());
+        if (!pagingLinks.hasFirstUrl()) {
+            throw new InvalidPagingRequestException(
+                "Requested 'First' page on response " + response.getClass().getSimpleName() + ", but no First page is available."
+            );
+        }
+
+        // Update request with appropriate page options.
+        final PageOptions pageOptions;
+        try {
+            pageOptions = PageOptions.fromUrl(pagingLinks.getNextUrl());
+        } catch (final IllegalArgumentException ex) {
+            throw new InvalidPagingRequestException("Unable to parse URL for paging information", ex);
+        }
+        final PageableRequest<T> request = response.getOriginalRequest();
+        request.updatePageOptions(pageOptions);
+
+        // Execute and return.
+        return executeRequest(request);
+    }
+
+    /**
+     * Retrieve the last page of results from the previously retrieved request.
+     *
+     * @param <T> The parsed return object representing the result.
+     * @param response Previously retrieved result/response to retrieve the last page of results for.
+     * @return The last page of results.
+     * @throws InvalidPagingRequestException if no previous page exists to retrieve.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public <T> T lastPage(final PageableResponse<T> response) {
+        // Validate
+        Objects.requireNonNull(response);
+        final PagingLinks pagingLinks = Objects.requireNonNull(response.getPagingLinks());
+        if (!pagingLinks.hasLastUrl()) {
+            throw new InvalidPagingRequestException(
+                "Requested 'Last' page on response " + response.getClass().getSimpleName() + ", but no Last page is available."
+            );
+        }
+
+        // Update request with appropriate page options.
+        final PageOptions pageOptions;
+        try {
+            pageOptions = PageOptions.fromUrl(pagingLinks.getNextUrl());
+        } catch (final IllegalArgumentException ex) {
+            throw new InvalidPagingRequestException("Unable to parse URL for paging information", ex);
+        }
+        final PageableRequest<T> request = response.getOriginalRequest();
+        request.updatePageOptions(pageOptions);
+
+        // Execute and return.
+        return executeRequest(request);
+    }
+
     /**
      * Execute the given request, returning the parsed response, or throwing the appropriate
      * exception if an error was returned from the API.
@@ -168,7 +331,7 @@ public <T> T executeRequest(final Request<T> request) throws BuildkiteException
      * @throws BuildkiteException relating to specific underlying API error.
      */
     private void handleError(final HttpResult errorResult) throws BuildkiteException {
-        // Attempt to parse error respone.
+        // Attempt to parse error response.
         String errorMessage = null;
         try {
             final ErrorResponse errorResponse = new ErrorResponseParser().parseResponse(errorResult);

src/main/java/org/sourcelab/buildkite/api/client/exception/InvalidPagingRequestException.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 requested to access a page that is not linked.
+ */
+public class InvalidPagingRequestException extends BuildkiteException {
+     /**
+     * Constructor.
+     * @param message Error message.
+      */
+    public InvalidPagingRequestException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Constructor.
+     * @param message Error message.
+     * @param cause Underlying error cause.
+     */
+    public InvalidPagingRequestException(final String message, final IllegalArgumentException cause) {
+        super(message, cause);
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/request/BuildFilters.java

@@ -81,7 +81,7 @@ public BuildFilters(
         this.includeRetriedJobs = includeRetriedJobs;
         this.metaData = Collections.unmodifiableMap(new HashMap<>(metaData));
         this.states = Collections.unmodifiableSet(new HashSet<>(states));
-        this.pageOptions = pageOptions;
+        this.pageOptions = pageOptions == null ? PageOptions.getDefault() : pageOptions;
         this.orgIdSlug = orgIdSlug;
         this.pipelineIdSlug = pipelineSlugId;
         this.buildNumber = buildNumber;

src/main/java/org/sourcelab/buildkite/api/client/request/ListBuildsRequest.java

@@ -17,7 +17,6 @@
 
 package org.sourcelab.buildkite.api.client.request;
 
-import org.sourcelab.buildkite.api.client.BuildkiteClient;
 import org.sourcelab.buildkite.api.client.response.ListBuildsResponse;
 import org.sourcelab.buildkite.api.client.response.parser.ListBuildsResponseParser;
 import org.sourcelab.buildkite.api.client.response.parser.ResponseParser;
@@ -26,14 +25,21 @@
 import java.util.Map;
 import java.util.Objects;
 
-public class ListBuildsRequest extends GetRequest<ListBuildsResponse> {
+public class ListBuildsRequest extends GetRequest<ListBuildsResponse> implements PageableRequest<ListBuildsResponse> {
     private final BuildFilters filters;
+    private PageOptions pageOptions;
 
+    /**
+     * Constructor.
+     * @param filters Search Criteria.
+     */
     public ListBuildsRequest(final BuildFilters filters) {
         Objects.requireNonNull(filters);
         this.filters = filters;
+        this.pageOptions = filters.getPageOptions() == null ? PageOptions.getDefault() : filters.getPageOptions();
     }
 
+    @Override
     public String getPath() {
         return "/v2/builds";
     }
@@ -43,10 +49,8 @@ public RequestParameters getRequestParameters() {
         final RequestParametersBuilder builder = RequestParameters.newBuilder();
 
         // Paging options
-        if (filters.getPageOptions() != null) {
-            builder.withParameter("per_page", filters.getPageOptions().getPerPage());
-            builder.withParameter("page", filters.getPageOptions().getPage());
-        }
+        builder.withParameter("per_page", pageOptions.getPerPage());
+        builder.withParameter("page", pageOptions.getPage());
 
         // If we have branches
         if (!filters.getBranches().isEmpty()) {
@@ -94,6 +98,11 @@ public RequestParameters getRequestParameters() {
 
     @Override
     public ResponseParser<ListBuildsResponse> getResponseParser() {
-        return new ListBuildsResponseParser();
+        return new ListBuildsResponseParser(this);
+    }
+
+    @Override
+    public void updatePageOptions(final PageOptions pageOptions) {
+        this.pageOptions = Objects.requireNonNull(pageOptions);
     }
 }

src/main/java/org/sourcelab/buildkite/api/client/request/PageOptions.java

@@ -17,6 +17,10 @@
 
 package org.sourcelab.buildkite.api.client.request;
 
+import java.util.Objects;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
 /**
  * Paging options.
  */
@@ -53,6 +57,39 @@ public PageOptions(int page, int perPage) {
         this.perPage = perPage;
     }
 
+    /**
+     * Parses the given url and creates a PageOptions instance from the parameters.
+     *
+     * @param url The url to parse for per_page and page parameters.
+     * @return PageOptions instance populated from the supplied url.
+     * @throws IllegalArgumentException if passed an invalid url.
+     */
+    public static PageOptions fromUrl(final String url) {
+        Objects.requireNonNull(url);
+
+        final Pattern perPagePattern = Pattern.compile(".*[?&]per_page=([0-9]+).*");
+        final Pattern pagePattern = Pattern.compile(".*[?&]page=([0-9]+).*");
+
+        Integer perPage = null;
+        Integer page = null;
+
+        final Matcher perPageMatcher = perPagePattern.matcher(url);
+        if (perPageMatcher.matches() && perPageMatcher.groupCount() == 1) {
+            perPage = Integer.parseInt(perPageMatcher.group(1));
+        }
+
+        final Matcher pageMatcher = pagePattern.matcher(url);
+        if (pageMatcher.matches() && pageMatcher.groupCount() == 1) {
+            page = Integer.parseInt(pageMatcher.group(1));
+        }
+
+        if (perPage == null || page == null) {
+            throw new IllegalArgumentException("Unable to parse url " + url);
+        }
+
+        return new PageOptions(page, perPage);
+    }
+
     public int getPage() {
         return page;
     }
@@ -64,8 +101,8 @@ public int getPerPage() {
     @Override
     public String toString() {
         return "PageOptions{"
-                + "page=" + page
-                + ", perPage=" + perPage
-                + '}';
+            + "page=" + page
+            + ", perPage=" + perPage
+            + '}';
     }
 }