Merge pull request #1307 from bitwiseman/task/urlcleanup

Code cleanup

pom.xml

@@ -342,6 +342,12 @@
         </executions>
         <configuration>
           <java>
+            <includes>
+              <include>src/main/java/**/*.java</include>
+              <include>src/main/java11/**/*.java</include>
+              <include>src/test/java/**/*.java</include>
+            </includes>
+
             <eclipse>
               <file>${basedir}/src/build/eclipse/formatter.xml</file>
             </eclipse>

src/main/java/org/kohsuke/github/AbstractBuilder.java

@@ -37,6 +37,8 @@
  * @param <S>
  *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@link S}
  *            the same as {@link R}, this builder will commit changes after each call to {@link #with(String, Object)}.
+ *
+ * @author Liam Newman
  */
 abstract class AbstractBuilder<R, S> extends GitHubInteractiveObject {
 

src/main/java/org/kohsuke/github/AbuseLimitHandler.java

@@ -16,6 +16,7 @@
  *      GitHubBuilder#withAbuseLimitHandler(GitHubAbuseLimitHandler)
  * @see <a href="https://developer.github.com/v3/#abuse-rate-limits">documentation</a>
  * @see RateLimitHandler
+ * @deprecated Switch to {@link GitHubAbuseLimitHandler}.
  */
 @Deprecated
 public abstract class AbuseLimitHandler extends GitHubAbuseLimitHandler {

src/main/java/org/kohsuke/github/GHRateLimit.java

@@ -24,7 +24,7 @@
 /**
  * Rate limit.
  *
- * @author Kohsuke Kawaguchi
+ * @author Liam Newman
  */
 @SuppressFBWarnings(value = "URF_UNREAD_PUBLIC_OR_PROTECTED_FIELD", justification = "JSON API")
 public class GHRateLimit {
@@ -380,6 +380,7 @@ static void reset() {
      * A rate limit record.
      *
      * @since 1.100
+     * @author Liam Newman
      */
     public static class Record {
         /**

src/main/java/org/kohsuke/github/GitHubAbuseLimitHandler.java

@@ -13,6 +13,8 @@
  * @author Kohsuke Kawaguchi
  * @see GitHubBuilder#withAbuseLimitHandler(AbuseLimitHandler) GitHubBuilder#withRateLimitHandler(AbuseLimitHandler)
  * @see GitHubRateLimitHandler
+ *
+ * @author Liam Newman
  */
 public abstract class GitHubAbuseLimitHandler extends GitHubConnectorResponseErrorHandler {
 

src/main/java/org/kohsuke/github/GitHubClient.java

@@ -8,7 +8,7 @@
 import org.kohsuke.github.connector.GitHubConnector;
 import org.kohsuke.github.connector.GitHubConnectorRequest;
 import org.kohsuke.github.connector.GitHubConnectorResponse;
-import org.kohsuke.github.function.BodyHandler;
+import org.kohsuke.github.function.FunctionThrows;
 
 import java.io.*;
 import java.net.*;
@@ -33,9 +33,14 @@
 /**
  * A GitHub API Client
  * <p>
- * A GitHubClient can be used to send requests and retrieve their responses. GitHubClient is thread-safe and can be used
- * to send multiple requests. GitHubClient also track some GitHub API information such as {@link GHRateLimit}.
+ * A GitHubClient can be used to send requests and retrieve their responses. Uses {@link GitHubConnector} as a pluggable
+ * component to communicate using differing HTTP client libraries.
+ * <p>
+ * GitHubClient is thread-safe and can be used to send multiple requests simultaneously. GitHubClient also tracks some
+ * GitHub API information such as {@link GHRateLimit}.
  * </p>
+ *
+ * @author Liam Newman
  */
 class GitHubClient {
 
@@ -764,4 +769,14 @@ static class RetryRequestException extends IOException {
             this.connectorRequest = connectorRequest;
         }
     }
+
+    /**
+     * Represents a supplier of results that can throw.
+     *
+     * @param <T>
+     *            the type of results supplied by this supplier
+     */
+    @FunctionalInterface
+    interface BodyHandler<T> extends FunctionThrows<GitHubConnectorResponse, T, IOException> {
+    }
 }

src/main/java/org/kohsuke/github/GitHubConnectorResponseErrorHandler.java

@@ -12,8 +12,7 @@
 import static java.net.HttpURLConnection.HTTP_NOT_FOUND;
 
 /**
- * Pluggable strategy to determine what to detect and choose what to do when various errors occur during an http
- * request.
+ * Pluggable strategy to detect and choose what to do when errors occur during an http request.
  *
  * @author Liam Newman
  */

src/main/java/org/kohsuke/github/GitHubInteractiveObject.java

@@ -13,6 +13,8 @@
  * Ensures that all data references to GitHub connection are transient.
  *
  * Classes that do not need to interact with GitHub after they are instantiated do not need to inherit from this class.
+ *
+ * @author Liam Newman
  */
 abstract class GitHubInteractiveObject {
     @JacksonInject

src/main/java/org/kohsuke/github/GitHubPageContentsIterable.java

@@ -14,6 +14,8 @@
  *
  * @param <T>
  *            the type of items on each page
+ *
+ * @author Liam Newman
  */
 class GitHubPageContentsIterable<T> extends PagedIterable<T> {
 

src/main/java/org/kohsuke/github/GitHubPageIterator.java

@@ -19,6 +19,8 @@
  *
  * @param <T>
  *            type of each page (not the items in the page).
+ *
+ * @author Liam Newman
  */
 class GitHubPageIterator<T> implements Iterator<T> {
 

src/main/java/org/kohsuke/github/GitHubRateLimitChecker.java

@@ -26,6 +26,8 @@
  * allows for a wide range of {@link RateLimitChecker} implementations, including complex throttling strategies and
  * polling.
  * </p>
+ *
+ * @author Liam Newman
  */
 class GitHubRateLimitChecker {
 

src/main/java/org/kohsuke/github/GitHubRateLimitHandler.java

@@ -14,6 +14,8 @@
  * @author Kohsuke Kawaguchi
  * @see GitHubBuilder#withRateLimitHandler(RateLimitHandler) GitHubBuilder#withRateLimitHandler(RateLimitHandler)
  * @see GitHubAbuseLimitHandler
+ *
+ * @author Liam Newman
  */
 public abstract class GitHubRateLimitHandler extends GitHubConnectorResponseErrorHandler {
 

src/main/java/org/kohsuke/github/GitHubRequest.java

@@ -27,12 +27,14 @@
 
 /**
  * Class {@link GitHubRequest} represents an immutable instance used by the client to determine what information to
- * retrieve from a GitHub server. Use the {@link Builder} construct a {@link GitHubRequest}.
+ * retrieve from a GitHub server. Use the {@link Builder} to construct a {@link GitHubRequest}.
  * <p>
  * NOTE: {@link GitHubRequest} should include the data type to be returned. Any use cases where the same request should
  * be used to return different types of data could be handled in some other way. However, the return type is currently
  * not specified until late in the building process, so this is still untyped.
  * </p>
+ *
+ * @author Liam Newman
  */
 public class GitHubRequest implements GitHubConnectorRequest {
 

src/main/java/org/kohsuke/github/GitHubResponse.java

@@ -22,11 +22,13 @@
 /**
  * A GitHubResponse
  * <p>
- * A {@link GitHubResponse} generated by from sending a {@link GitHubRequest} to a {@link GitHubClient}.
+ * A {@link GitHubResponse} generated by sending a {@link GitHubRequest} to a {@link GitHubClient}.
  * </p>
  *
  * @param <T>
  *            the type of the data parsed from the body of a {@link GitHubConnectorResponse}.
+ *
+ * @author Liam Newman
  */
 class GitHubResponse<T> {
 

src/main/java/org/kohsuke/github/RateLimitChecker.java

@@ -16,6 +16,8 @@
  * {@link RateLimitChecker} is called before each request to check the rate limit and wait if the checker criteria are
  * met.
  * </p>
+ *
+ * @author Liam Newman
  */
 public abstract class RateLimitChecker {
 

src/main/java/org/kohsuke/github/RateLimitHandler.java

@@ -15,6 +15,7 @@
  * @see GitHubBuilder#withRateLimitHandler(GitHubRateLimitHandler)
  *      GitHubBuilder#withRateLimitHandler(GitHubRateLimitHandler)
  * @see AbuseLimitHandler
+ * @deprecated Switch to {@link GitHubRateLimitHandler} or even better provide {@link RateLimitChecker}s.
  */
 @Deprecated
 public abstract class RateLimitHandler extends GitHubRateLimitHandler {

src/main/java/org/kohsuke/github/Requester.java

@@ -26,7 +26,6 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import org.apache.commons.io.IOUtils;
 import org.kohsuke.github.connector.GitHubConnectorResponse;
-import org.kohsuke.github.function.BodyHandler;
 import org.kohsuke.github.function.InputStreamFunction;
 
 import java.io.ByteArrayInputStream;
@@ -123,9 +122,9 @@ public <T> T fetchStream(@Nonnull InputStreamFunction<T> handler) throws IOExcep
      *
      * Copies an input stream to an in-memory input stream. The performance on this is not great but
      * {@link GitHubConnectorResponse#bodyStream()} is closed at the end of every call to
-     * {@link GitHubClient#sendRequest(GitHubRequest, BodyHandler)}, so any reads to the original input stream must be
-     * completed before then. There are a number of deprecated methods that return {@link InputStream}. This method
-     * keeps all of them using the same code path.
+     * {@link GitHubClient#sendRequest(GitHubRequest, GitHubClient.BodyHandler)}, so any reads to the original input
+     * stream must be completed before then. There are a number of deprecated methods that return {@link InputStream}.
+     * This method keeps all of them using the same code path.
      *
      * @param inputStream
      *            the input stream to be copied

src/main/java/org/kohsuke/github/authorization/AnonymousAuthorizationProvider.java

@@ -0,0 +1,15 @@
+package org.kohsuke.github.authorization;
+
+import java.io.IOException;
+
+/**
+ * A {@link AuthorizationProvider} that returns an empty authorization.
+ * <p>
+ * This will result in the "Authorization" header not being added to a request.
+ */
+public class AnonymousAuthorizationProvider implements AuthorizationProvider {
+    @Override
+    public String getEncodedAuthorization() throws IOException {
+        return null;
+    }
+}

src/main/java/org/kohsuke/github/authorization/AuthorizationProvider.java

@@ -3,12 +3,17 @@
 import java.io.IOException;
 
 /**
- * Provides a functional interface that returns a valid encodedAuthorization. This strategy allows for a provider that
- * dynamically changes the credentials. Each request will request the credentials from the provider.
+ * Provides a functional interface that returns a valid encodedAuthorization.
+ *
+ * This interface support the creation of providers based on immutable credentials or dynamic credentials which change
+ * of time. Each {@link org.kohsuke.github.connector.GitHubConnectorRequest} will call
+ * {@link #getEncodedAuthorization()} on the provider.
+ *
+ * @author Liam Newman
  */
 public interface AuthorizationProvider {
     /**
-     * An static instance for an ANONYMOUS authorization provider
+     * A static instance for an ANONYMOUS authorization provider
      */
     AuthorizationProvider ANONYMOUS = new AnonymousAuthorizationProvider();
 
@@ -27,17 +32,8 @@ public interface AuthorizationProvider {
      *
      * @return encoded authorization string, can be null
      * @throws IOException
-     *             on any error that prevents the provider from getting a valid authorization
+     *             on any error that prevents the provider from returning a valid authorization
      */
     String getEncodedAuthorization() throws IOException;
 
-    /**
-     * A {@link AuthorizationProvider} that ensures that no credentials are returned
-     */
-    class AnonymousAuthorizationProvider implements AuthorizationProvider {
-        @Override
-        public String getEncodedAuthorization() throws IOException {
-            return null;
-        }
-    }
 }

src/main/java/org/kohsuke/github/authorization/ImmutableAuthorizationProvider.java

@@ -7,7 +7,7 @@
 import javax.annotation.CheckForNull;
 
 /**
- * A {@link AuthorizationProvider} that always returns the same credentials
+ * An {@link AuthorizationProvider} that always returns the same credentials.
  */
 public class ImmutableAuthorizationProvider implements AuthorizationProvider {
 
@@ -99,6 +99,8 @@ public String getEncodedAuthorization() {
     /**
      * An internal class representing all user-related credentials, which are credentials that have a login or should
      * query the user endpoint for the login matching this credential.
+     *
+     * @see org.kohsuke.github.authorization.UserAuthorizationProvider UserAuthorizationProvider
      */
     private static class UserProvider extends ImmutableAuthorizationProvider implements UserAuthorizationProvider {
 

src/main/java/org/kohsuke/github/authorization/OrgAppInstallationAuthorizationProvider.java

@@ -13,7 +13,7 @@
 import javax.annotation.Nonnull;
 
 /**
- * Provides an AuthorizationProvider that performs automatic token refresh.
+ * An AuthorizationProvider that performs automatic token refresh for an organization's AppInstallation.
  */
 public class OrgAppInstallationAuthorizationProvider extends GitHub.DependentAuthorizationProvider {
 

src/main/java/org/kohsuke/github/connector/GitHubConnector.java

@@ -7,18 +7,19 @@
 import java.io.IOException;
 
 /**
- * Pluggability for customizing HTTP request behaviors or using altogether different library.
+ * Interface for customizing HTTP request behaviors or using any HTTP client library for interacting with GitHub.
  *
  * @author Liam Newman
  */
 @FunctionalInterface
 public interface GitHubConnector {
 
     /**
+     * Sends a request and retrieves a raw response for processing.
      *
      * Implementers of {@link GitHubConnector#send(GitHubConnectorRequest)} process the information from a
-     * {@link GitHubConnectorRequest} to open an HTTP connection and retrieve a response. They then return a class that
-     * extends {@link GitHubConnectorResponse} for their response data.
+     * {@link GitHubConnectorRequest} to open an HTTP connection and retrieve a raw response. They then return a class
+     * that extends {@link GitHubConnectorResponse} corresponding their response data.
      *
      * Clients should not implement their own {@link GitHubConnectorRequest}. The {@link GitHubConnectorRequest}
      * provided by the caller of {@link GitHubConnector#send(GitHubConnectorRequest)} should be passed to the
@@ -29,16 +30,18 @@ public interface GitHubConnector {
      * @return a GitHubConnectorResponse for the request
      * @throws IOException
      *             if there is an I/O error
+     *
+     * @author Liam Newman
      */
     GitHubConnectorResponse send(GitHubConnectorRequest connectorRequest) throws IOException;
 
     /**
      * Default implementation used when connector is not set by user.
      *
-     * This calls {@link DefaultGitHubConnector#create} to get the default connector instance. The output of that method
-     * may differ depending on Java version and system properties.
+     * This calls {@link DefaultGitHubConnector#create()} to get the default connector instance. The output of that
+     * method may differ depending on Java version and system properties.
      *
-     * @see DefaultGitHubConnector#create
+     * @see DefaultGitHubConnector#create() DefaultGitHubConnector#create()
      */
     GitHubConnector DEFAULT = DefaultGitHubConnector.create();
 

src/main/java/org/kohsuke/github/connector/GitHubConnectorRequest.java

@@ -9,15 +9,17 @@
 import javax.annotation.Nonnull;
 
 /**
- * A request passed to {@link GitHubConnector#send(GitHubConnectorRequest)} to get a {@link GitHubConnectorResponse}.\
+ * A request passed to {@link GitHubConnector#send(GitHubConnectorRequest)} to get a {@link GitHubConnectorResponse}.
  *
  * Implementers of {@link GitHubConnector#send(GitHubConnectorRequest)} process the information from a
  * {@link GitHubConnectorRequest} to open an HTTP connection and retrieve a response. They then return a class that
- * extends {@link GitHubConnectorResponse} for their response data.
+ * extends {@link GitHubConnectorResponse} corresponding their response data.
  *
  * Clients should not implement their own {@link GitHubConnectorRequest}. The {@link GitHubConnectorRequest} provided by
  * the caller of {@link GitHubConnector#send(GitHubConnectorRequest)} should be passed to the constructor of
  * {@link GitHubConnectorResponse}.
+ *
+ * @author Liam Newman
  */
 public interface GitHubConnectorRequest {