Continue building out tooling around paging

Author: Crim

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

@@ -127,6 +127,30 @@ public PageOptions getPageOptions() {
         return pageOptions;
     }
 
+    public String getOrgIdSlug() {
+        return orgIdSlug;
+    }
+
+    public boolean hasOrgIdSlug() {
+        return orgIdSlug != null;
+    }
+
+    public String getPipelineIdSlug() {
+        return pipelineIdSlug;
+    }
+
+    public boolean hasPipelineIdSlug() {
+        return hasOrgIdSlug() && pipelineIdSlug != null;
+    }
+
+    public Long getBuildNumber() {
+        return buildNumber;
+    }
+
+    public boolean hasBuildNumber() {
+        return hasPipelineIdSlug() && buildNumber != null;
+    }
+
     @Override
     public String toString() {
         return "BuildRequestOptions{"

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

@@ -41,6 +41,14 @@ public ListBuildsRequest(final BuildFilters filters) {
 
     @Override
     public String getPath() {
+        // TODO need to urlencode these?
+        if (filters.hasBuildNumber()) {
+            return "/v2/organizations/" + filters.getOrgIdSlug() + "/pipelines/" + filters.getPipelineIdSlug() + "/builds/" + filters.getBuildNumber();
+        } else if (filters.hasPipelineIdSlug()) {
+            return "/v2/organizations/" + filters.getOrgIdSlug() + "/pipelines/" + filters.getPipelineIdSlug() + "/builds";
+        } else if (filters.hasOrgIdSlug()) {
+            return "/v2/organizations/" + filters.getOrgIdSlug() + "/builds";
+        }
         return "/v2/builds";
     }
 

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

@@ -25,7 +25,7 @@
  * Paging options.
  */
 public class PageOptions {
-    private final int page;
+    private final long page;
     private final int perPage;
 
     private static final PageOptions DEFAULT = new PageOptions(1, 30);
@@ -43,7 +43,7 @@ public static PageOptions getDefault() {
      * @param page Which page to request.
      * @param perPage How many entries per page.
      */
-    public PageOptions(int page, int perPage) {
+    public PageOptions(long page, int perPage) {
         if (page < 0) {
             page = 1;
         }
@@ -90,7 +90,7 @@ public static PageOptions fromUrl(final String url) {
         return new PageOptions(page, perPage);
     }
 
-    public int getPage() {
+    public long getPage() {
         return page;
     }
 

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

@@ -23,7 +23,6 @@
 
 import java.io.IOException;
 import java.util.Collections;
-import java.util.Map;
 
 /**
  * Defines an API request.

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

@@ -68,6 +68,14 @@ public List<Build> getBuilds() {
         return builds;
     }
 
+    /**
+     * The total number of builds found.
+     * @return The total number of builds found.
+     */
+    public int countBuilds() {
+        return getBuilds().size();
+    }
+
     /**
      * Get all build Ids.
      * @return All build ids.

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

@@ -17,6 +17,8 @@
 
 package org.sourcelab.buildkite.api.client.response;
 
+import org.sourcelab.buildkite.api.client.request.PageOptions;
+
 /**
  * Represents the 'Link' header for paging results.
  */
@@ -108,6 +110,19 @@ public String getLastUrl() {
         return lastUrl;
     }
 
+    /**
+     * If the Last Page URL is populated, calculate the total number of entries.
+     * @return If the Last Page URL is populated, calculate the total number of entries.
+     * @throws IllegalStateException If the Last Url is not defined.
+     */
+    public long getTotalNumberOfEntries() {
+        if (!hasLastUrl()) {
+            throw new IllegalStateException("Last Url is not defined, cannot determine total number of entries.");
+        }
+        final PageOptions pageOptions = PageOptions.fromUrl(getLastUrl());
+        return ((long) pageOptions.getPage()) * ((long) pageOptions.getPerPage());
+    }
+
     @Override
     public String toString() {
         return "LinkHeader{"

src/main/java/org/sourcelab/buildkite/api/client/response/parser/JacksonFactory.java

@@ -20,7 +20,6 @@
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;
-import com.fasterxml.jackson.databind.PropertyNamingStrategy;
 import com.fasterxml.jackson.databind.type.MapType;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 

src/main/java/org/sourcelab/buildkite/api/client/response/parser/ListBuildsResponseParser.java

@@ -18,15 +18,18 @@
 package org.sourcelab.buildkite.api.client.response.parser;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.sourcelab.buildkite.api.client.http.HttpResult;
 import org.sourcelab.buildkite.api.client.request.ListBuildsRequest;
 import org.sourcelab.buildkite.api.client.response.Build;
-import org.sourcelab.buildkite.api.client.response.PagingLinks;
 import org.sourcelab.buildkite.api.client.response.ListBuildsResponse;
+import org.sourcelab.buildkite.api.client.response.PagingLinks;
 
 import java.util.Arrays;
 
 public class ListBuildsResponseParser implements ResponseParser<ListBuildsResponse> {
+    private static final Logger logger = LoggerFactory.getLogger(ListBuildsResponseParser.class);
     private final ListBuildsRequest originalRequest;
 
     public ListBuildsResponseParser(final ListBuildsRequest originalRequest) {
@@ -35,7 +38,7 @@ public ListBuildsResponseParser(final ListBuildsRequest originalRequest) {
 
     @Override
     public ListBuildsResponse parseResponse(final HttpResult result) throws JsonProcessingException {
-
+        logger.info(result.getContent());
         final PagingLinks pagingLinks;
         if (result.getHttpHeaders().hasHeader("Link")) {
             // Parse out the link header.

src/main/java/org/sourcelab/buildkite/api/client/response/parser/ListEmojisResponseParser.java

@@ -19,10 +19,8 @@
 
 import org.sourcelab.buildkite.api.client.http.HttpResult;
 import org.sourcelab.buildkite.api.client.response.Emoji;
-import org.sourcelab.buildkite.api.client.response.PingResponse;
 
 import java.io.IOException;
-import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import java.util.stream.Collectors;

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

@@ -0,0 +1,70 @@
+/**
+ * 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.util;
+
+import org.sourcelab.buildkite.api.client.BuildkiteClient;
+import org.sourcelab.buildkite.api.client.request.BuildFilters;
+import org.sourcelab.buildkite.api.client.request.ListBuildsRequest;
+import org.sourcelab.buildkite.api.client.request.PageOptions;
+import org.sourcelab.buildkite.api.client.response.Build;
+import org.sourcelab.buildkite.api.client.response.ListBuildsResponse;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Collection of Utilities for common access patterns that consists of multiple
+ * requests to the Buildkite REST Api.
+ */
+public class BuildkiteClientUtils {
+
+    /**
+     * Helper method to retrieve the N **newest** builds given the supplied search criteria.
+     * The results will be ordered from NEWEST to OLDEST.
+     *
+     * @param numberOfBuilds How many builds to retrieve, (artificially) limited to max of 100.
+     * @param filters Search criteria.
+     * @param client The BuildkiteClient to execute the requests against.
+     * @return List of Builds sorted from NEWEST to OLDEST.
+     */
+    public static List<Build> retrieveNewestBuilds(final int numberOfBuilds, final BuildFilters filters, final BuildkiteClient client) {
+        // Create request
+        final ListBuildsRequest request = new ListBuildsRequest(filters);
+        request.updatePageOptions(new PageOptions(1, 1));
+
+        // Retrieve first entry only, to determine how many total entries there are.
+        final ListBuildsResponse lookupResponse = client.executeRequest(request);
+        final long totalNumberOfEntries = lookupResponse.getPagingLinks().getTotalNumberOfEntries();
+
+        /**
+         * Assumption is that we can only pull at max, the last 100 entries as that is the maximum that
+         * the API can return in a single request.
+         * This method could be updated pretty easily to support larger numbers, submit a PR :)
+         */
+        final long pageNumber  = totalNumberOfEntries / numberOfBuilds;
+        request.updatePageOptions(new PageOptions(pageNumber, numberOfBuilds));
+
+        // Execute the request for the correct page of results.
+        final ListBuildsResponse response = client.executeRequest(request);
+
+        // But the results are still sorted in oldest to newest, we want newest to oldest, so reverse the order
+        // before returning.
+        final List<Build> reversed = new ArrayList<>(response.getBuilds());
+        return reversed;
+    }
+}