Add readme

Author: Crim

README.md

@@ -1,2 +1,123 @@
-# Buildkite-Api-Client
-Buildkite REST Api Client for Java
+# Buildkite-Api-Client Java REST Api Client
+
+## What is it?
+
+This library provides an easy to use client library for interacting with the [Buildkite Rest API](https://buildkite.com/docs/apis/rest-api) (V2).
+
+## How to use this library
+
+This client library is released on Maven Central.  Add a new dependency to your project's POM file:
+
+```xml
+<dependency>
+    <groupId>org.sourcelab</groupId>
+    <artifactId>buildkite-api-client</artifactId>
+    <version>0.1.0</version>
+</dependency>
+```
+
+
+#### Example Code:
+```java
+/*
+ * Create a new configuration object passing your API token.
+ * Your API Token can be found/created at: https://buildkite.com/user/api-access-tokens
+ */
+final Configuration configuration = Configuration.newBuilder()
+    .withApiToken("your-api-token-here")
+    .build();
+
+/*
+ * Create an instance of BuildkiteClient, passing your configuration.
+ */
+final BuildkiteClient client = new BuildkiteClient(configuration);
+    
+/*
+ * Making requests by calling the public methods available on BuildkiteClient.
+ * 
+ * For example, to retrieve information about your own user:
+ * https://buildkite.com/docs/apis/rest-api/user
+ */
+final CurrentUserResponse myUser = client.getUser();
+
+/*
+ * To retrieve your organizations:
+ * https://buildkite.com/docs/apis/rest-api/organizations#list-organizations
+ */
+final ListOrganizationsResponse organizations = client.listOrganizations();
+
+/*
+ * To search for builds:   
+ */
+final BuildFilters filters = BuildFilters.newBuilder()
+    // Retrieve 1st page, with each page having 25 results
+    .withPageOptions(1, 25)
+    // Filtering for builds with state 'failed'
+    .withStateChooser().failed()
+    // And created within the last day
+    .withCreatedFrom(ZonedDateTime.now().minusDays(1))
+    .build();
+final ListBuildsResponse buildsResult = client.listBuilds(filters);
+
+/*
+ * To retrieve the 3rd page of the above query simply do:   
+ */
+if (buildsResult.hasNextPage()) {
+    final ListBuildsResponse buildsPage2 = client.nextPage(buildsPage1);
+}
+
+/*
+ * See BuildkiteClient for other available operations and end points.
+ */
+```
+
+Public methods available on BuildkiteClient can be [found here](src/main/java/org/sourcelab/buildkite/api/client/BuildkiteClient.java#L111)
+
+# Contributing
+
+Found a bug? Think you've got an awesome feature you want to add? We welcome contributions!
+
+
+## Submitting a Contribution
+
+1. Search for an existing issue. If none exists, create a new issue so that other contributors can keep track of what you are trying to add/fix and offer suggestions (or let you know if there is already an effort in progress).  Be sure to clearly state the problem you are trying to solve and an explanation of why you want to use the strategy you're proposing to solve it.
+1. Fork this repository on GitHub and create a branch for your feature.
+1. Clone your fork and branch to your local machine.
+1. Commit changes to your branch.
+1. Push your work up to GitHub.
+1. Submit a pull request so that we can review your changes.
+
+*Make sure that you rebase your branch off of master before opening a new pull request. We might also ask you to rebase it if master changes after you open your pull request.*
+
+## Acceptance Criteria
+
+We love contributions, but it's important that your pull request adhere to some of the standards we maintain in this repository.
+
+- All tests must be passing!
+- All code changes require tests!
+- All code changes must be consistent with our checkstyle rules.
+- Great inline comments.
+
+# Other Notes
+
+
+## Releasing
+
+Steps for proper release:
+- Update release version: `mvn versions:set -DnewVersion=X.Y.Z`
+- Validate and then commit version: `mvn versions:commit`
+- Update CHANGELOG and README files.
+- Merge to master.
+- Deploy to Maven Central: `mvn clean deploy -P release`
+- Create release on Github project.
+
+
+## Changelog
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+[View Changelog](CHANGELOG.md)
+
+
+

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

@@ -29,6 +29,7 @@ public class RetryMultipleJobsOptions {
     private final String pipelineSlug;
     private final long buildNumber;
     private final Set<String> jobIds;
+    private final boolean throwOnError;
 
     /**
      * Builder instance for {@link RetryMultipleJobsOptions}.
@@ -41,11 +42,12 @@ public static RetryMultipleJobsOptionsBuilder newBuilder() {
     /**
      * Constructor.
      */
-    public RetryMultipleJobsOptions(final String organizationSlug, final String pipelineIdSlug, final long buildNumber, final Collection<String> jobIds) {
+    public RetryMultipleJobsOptions(final String organizationSlug, final String pipelineIdSlug, final long buildNumber, final Collection<String> jobIds, final boolean throwOnError) {
         this.organizationSlug = organizationSlug;
         this.pipelineSlug = pipelineIdSlug;
         this.buildNumber = buildNumber;
         this.jobIds = new HashSet<>(jobIds);
+        this.throwOnError = throwOnError;
     }
 
     public String getOrganizationSlug() {
@@ -64,13 +66,25 @@ public Set<String> getJobIds() {
         return jobIds;
     }
 
+    /**
+     * @return If true, if any single request fails, it will not process the remaining requests and immediately
+     * throw an exception.
+     *
+     * If false, any errors will be captured by the return result, and further requests will continue.
+     *
+     */
+    public boolean isThrowOnError() {
+        return throwOnError;
+    }
+
     @Override
     public String toString() {
         return "RetryMultipleJobsOptions{"
             + "\n\torganizationSlug='" + organizationSlug + '\''
             + "\n\tpipelineSlug='" + pipelineSlug + '\''
             + "\n\tbuildNumber=" + buildNumber
             + "\n\tjobIds=" + jobIds
+            + "\n\tthrowOnError=" + throwOnError
             + "\n}";
     }
 }

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

@@ -28,6 +28,7 @@ public final class RetryMultipleJobsOptionsBuilder {
     private String pipelineSlug = null;
     private Long buildNumber = null;
     private Set<String> jobIds = new HashSet<>();
+    private boolean throwOnError = true;
 
     public RetryMultipleJobsOptionsBuilder() {
     }
@@ -57,6 +58,11 @@ public RetryMultipleJobsOptionsBuilder withJobIds(final Collection<String> jobId
         return this;
     }
 
+    public RetryMultipleJobsOptionsBuilder withThrowExceptionOnError(final boolean throwExceptionOnError) {
+        this.throwOnError = throwExceptionOnError;
+        return this;
+    }
+
     /**
      * Create new {@link RetryMultipleJobsOptions} instance.
      * @return Create new {@link RetryMultipleJobsOptions} instance.
@@ -75,6 +81,6 @@ public RetryMultipleJobsOptions build() {
         if (jobIds.isEmpty()) {
             throw new BuilderValidationException("At least one JobId must be provided.");
         }
-        return new RetryMultipleJobsOptions(organizationSlug, pipelineSlug, buildNumber, jobIds);
+        return new RetryMultipleJobsOptions(organizationSlug, pipelineSlug, buildNumber, jobIds, throwOnError);
     }
 }

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

@@ -17,33 +17,63 @@
 
 package org.sourcelab.buildkite.api.client.response;
 
+import org.sourcelab.buildkite.api.client.BuildkiteClient;
+import org.sourcelab.buildkite.api.client.exception.BuildkiteException;
+import org.sourcelab.buildkite.api.client.request.RetryMultipleJobsOptions;
+import org.sourcelab.buildkite.api.client.util.BuildkiteClientUtils;
+
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
 /**
  * Results set from retrying multiple jobs.
+ * {@link BuildkiteClientUtils#retryMultipleJobs(RetryMultipleJobsOptions, BuildkiteClient)}
  */
 public class MultipleRetriedJobsResults {
+    /**
+     * Maps Original Job Id => The new retried job instance.
+     */
     private final Map<String,Job> originalJobIdsMappedToUpdatedJobs;
 
+    /**
+     * Maps Original Job Id => The new retried job instance.
+     */
+    private final Map<String, BuildkiteException> originalJobIdsMappedToErrors;
+
     /**
      * Constructor.
+     *
      * @param originalJobIdsMappedToUpdatedJobs Original Job Id mapped to the updated Job.
+     * @param originalJobIdsMappedToErrors Original Job Id mapped to any error that occurred during the request.
      */
-    public MultipleRetriedJobsResults(final Map<String, Job> originalJobIdsMappedToUpdatedJobs) {
+    public MultipleRetriedJobsResults(final Map<String, Job> originalJobIdsMappedToUpdatedJobs, final Map<String, BuildkiteException> originalJobIdsMappedToErrors) {
         this.originalJobIdsMappedToUpdatedJobs = Collections.unmodifiableMap(new HashMap<>(originalJobIdsMappedToUpdatedJobs));
+        this.originalJobIdsMappedToErrors = Collections.unmodifiableMap(new HashMap<>(originalJobIdsMappedToErrors));
     }
 
     /**
      * Ids of the jobs that were retried.
      * @return Ids of the jobs that were retried.
      */
     public Set<String> getOriginalJobIds() {
-        return originalJobIdsMappedToUpdatedJobs.keySet();
+        // Merge keys from both sets.
+        final Set<String> jobIds = new HashSet<>(originalJobIdsMappedToUpdatedJobs.keySet());
+        jobIds.addAll(originalJobIdsMappedToErrors.keySet());
+        return jobIds;
+    }
+
+    /**
+     * Check of a Retried job instance exists for the original job id.
+     * @param originalJobId Id of the job that was retried.
+     * @return true if an instance exists, false if not.
+     */
+    public boolean hasRetriedJob(final String originalJobId) {
+        return originalJobIdsMappedToUpdatedJobs.containsKey(originalJobId);
     }
 
     /**
@@ -52,8 +82,8 @@ public Set<String> getOriginalJobIds() {
      * @return The new Job instance.
      */
     public Job getRetriedJobByOriginalJobId(final String originalJobId) {
-        if (!originalJobIdsMappedToUpdatedJobs.containsKey(originalJobId)) {
-            throw new IllegalArgumentException("Job Id " + originalJobId + " was not retried and has no result");
+        if (!hasRetriedJob(originalJobId)) {
+            throw new IllegalArgumentException("Job Id " + originalJobId + " was not retried and has no result.");
         }
         return originalJobIdsMappedToUpdatedJobs.get(originalJobId);
     }
@@ -67,17 +97,55 @@ public Map<String, Job> getOriginalJobIdsMappedToUpdatedJobs() {
     }
 
     /**
-     * Original Job Id mapped to the new retried job instance.
-     * @return Original Job Id mapped to the new retried job instance.
+     * All of the new retried job instances.
+     * @return All of the new retried job instances.
      */
     public List<Job> getRetriedJobs() {
         return new ArrayList<>(originalJobIdsMappedToUpdatedJobs.values());
     }
 
+    /**
+     * Check of a given Job id had an error.
+     * @param originalJobId Id of the job that was retried.
+     * @return true if an error occurred/exists, false if not.
+     */
+    public boolean didJobHaveError(final String originalJobId) {
+        return originalJobIdsMappedToErrors.containsKey(originalJobId);
+    }
+
+    /**
+     * Get the error associated with the original job id.
+     * @param originalJobId Id of the job that was retried.
+     * @return The error that occurred.
+     */
+    public BuildkiteException getErrorByOriginalJobId(final String originalJobId) {
+        if (!didJobHaveError(originalJobId)) {
+            throw new IllegalArgumentException("Job Id " + originalJobId + " did not have an error.");
+        }
+        return originalJobIdsMappedToErrors.get(originalJobId);
+    }
+
+    /**
+     * Original Job Id mapped to the error associated with it.
+     * @return Original Job Id mapped to the error associated with it.
+     */
+    public Map<String, BuildkiteException> getOriginalJobIdsMappedToErrors() {
+        return originalJobIdsMappedToErrors;
+    }
+
+    /**
+     * All the errors.
+     * @return All the errors.
+     */
+    public List<BuildkiteException> getErrors() {
+        return new ArrayList<>(originalJobIdsMappedToErrors.values());
+    }
+
     @Override
     public String toString() {
         return "MultipleRetriedJobsResults{"
             + "\n\toriginalJobIdsMappedToUpdatedJobs=" + originalJobIdsMappedToUpdatedJobs
+            + "\n\toriginalJobIdsMappedToErrors=" + originalJobIdsMappedToErrors
             + "\n}";
     }
 }

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

@@ -127,16 +127,25 @@ public static MultipleRetriedJobsResults retryMultipleJobs(
         final BuildkiteClient client
     ) {
         final Map<String, Job> updatedJobs = new HashMap<>();
+        final Map<String, BuildkiteException> errors = new HashMap<>();
+
         options.getJobIds().forEach((jobId) -> {
-            final Job retriedJob = client.retryJob(RetryJobOptions.newBuilder()
-                .withJobId(jobId)
-                .withBuildNumber(options.getBuildNumber())
-                .withPipelineSlug(options.getPipelineSlug())
-                .withOrganizationSlug(options.getOrganizationSlug())
-                .build()
-            );
-            updatedJobs.put(jobId, retriedJob);
+            try {
+                final Job retriedJob = client.retryJob(RetryJobOptions.newBuilder()
+                    .withJobId(jobId)
+                    .withBuildNumber(options.getBuildNumber())
+                    .withPipelineSlug(options.getPipelineSlug())
+                    .withOrganizationSlug(options.getOrganizationSlug())
+                    .build()
+                );
+                updatedJobs.put(jobId, retriedJob);
+            } catch (final BuildkiteException error) {
+                if (options.isThrowOnError()) {
+                    throw error;
+                }
+                errors.put(jobId, error);
+            }
         });
-        return new MultipleRetriedJobsResults(updatedJobs);
+        return new MultipleRetriedJobsResults(updatedJobs, errors);
     }
 }