Merge branch 'main' into feature/hub4j#1497

Author: bloslo

.github/workflows/maven-build.yml

@@ -43,7 +43,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java: [ 11 ]
+        java: [ 17 ]
     steps:
       - uses: actions/checkout@v3
       - name: Set up JDK
@@ -53,6 +53,8 @@ jobs:
           distribution: 'adopt'
           cache: 'maven'
       - name: Maven Site
+        env:
+          MAVEN_OPTS: ${{ env.JAVA_11_PLUS_MAVEN_OPTS }}
         run: mvn -B  clean site -D enable-ci --file pom.xml
   test-8:
     name: test (${{ matrix.os }}, Java 8)

pom.xml

@@ -2,7 +2,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>org.kohsuke</groupId>
   <artifactId>github-api</artifactId>
-  <version>1.309-SNAPSHOT</version>
+  <version>1.312-SNAPSHOT</version>
   <name>GitHub API for Java</name>
   <url>https://github-api.kohsuke.org/</url>
   <description>GitHub API for Java</description>
@@ -213,9 +213,9 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-javadoc-plugin</artifactId>
-          <version>3.4.0</version>
+          <version>3.4.1</version>
           <configuration>
-            <source>8</source>
+            <source>11</source>
             <failOnWarnings>true</failOnWarnings>
             <doclint>all</doclint>
           </configuration>
@@ -333,7 +333,7 @@
       <plugin>
         <groupId>com.diffplug.spotless</groupId>
         <artifactId>spotless-maven-plugin</artifactId>
-        <version>2.24.0</version>
+        <version>2.25.0</version>
         <executions>
           <execution>
             <id>spotless-check</id>
@@ -567,7 +567,7 @@
     <dependency>
       <groupId>org.mockito</groupId>
       <artifactId>mockito-core</artifactId>
-      <version>4.6.1</version>
+      <version>4.7.0</version>
       <scope>test</scope>
     </dependency>
     <dependency>

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

@@ -5,6 +5,7 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
+// TODO: Auto-generated Javadoc
 /**
  * An abstract data object builder/updater.
  *
@@ -32,13 +33,12 @@
  * If {@link S} is not the same as {@link R}, {@link #with(String, Object)} will batch together multiple changes and let
  * the user call {@link #done()} when they are ready.
  *
+ * @author Liam Newman
  * @param <R>
  *            Final return type built by this builder returned when {@link #done()}} is called.
  * @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 {
 
@@ -50,26 +50,28 @@ abstract class AbstractBuilder<R, S> extends GitHubInteractiveObject {
     @CheckForNull
     private final R baseInstance;
 
+    /** The requester. */
     @Nonnull
     protected final Requester requester;
 
     // TODO: Not sure how update-in-place behavior should be controlled
     // However, it certainly can be controlled dynamically down to the instance level or inherited for all children of
     // some
+    /** The update in place. */
     // connection.
     protected boolean updateInPlace;
 
     /**
      * Creates a builder.
      *
-     * @param root
-     *            the GitHub instance to connect to.
+     * @param finalReturnType
+     *            the final return type for built by this builder returned when {@link #done()}} is called.
      * @param intermediateReturnType
      *            the intermediate return type of type {@link S} returned by calls to {@link #with(String, Object)}.
      *            Must either be equal to {@code builtReturnType} or this instance must be castable to this class. If
      *            not, the constructor will throw {@link IllegalArgumentException}.
-     * @param finalReturnType
-     *            the final return type for built by this builder returned when {@link #done()}} is called.
+     * @param root
+     *            the GitHub instance to connect to.
      * @param baseInstance
      *            optional instance on which to base this builder.
      */

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

@@ -8,6 +8,7 @@
 
 import javax.annotation.Nonnull;
 
+// TODO: Auto-generated Javadoc
 /**
  * Pluggable strategy to determine what to do when the API abuse limit is hit.
  *

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

@@ -2,15 +2,27 @@
 
 import java.util.Locale;
 
+// TODO: Auto-generated Javadoc
 /**
  * This was added during preview API period but it has changed since then.
  *
  * @author Kohsuke Kawaguchi
  */
 @Deprecated
 public enum EnforcementLevel {
-    OFF, NON_ADMINS, EVERYONE;
 
+    /** The off. */
+    OFF,
+    /** The non admins. */
+    NON_ADMINS,
+    /** The everyone. */
+    EVERYONE;
+
+    /**
+     * To string.
+     *
+     * @return the string
+     */
     public String toString() {
         return name().toLowerCase(Locale.ENGLISH);
     }

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

@@ -12,6 +12,7 @@
 
 import static org.kohsuke.github.internal.Previews.MACHINE_MAN;
 
+// TODO: Auto-generated Javadoc
 /**
  * A Github App.
  *
@@ -22,6 +23,7 @@ public class GHApp extends GHObject {
 
     private GHUser owner;
     private String name;
+    private String slug;
     private String description;
     private String externalUrl;
     private Map<String, String> permissions;
@@ -60,6 +62,15 @@ public String getName() {
         return name;
     }
 
+    /**
+     * Gets the slug name of the GitHub app.
+     *
+     * @return the slug name of the GitHub app
+     */
+    public String getSlug() {
+        return slug;
+    }
+
     /**
      * Sets name.
      *
@@ -158,6 +169,11 @@ public void setInstallationsCount(long installationsCount) {
         throw new RuntimeException("Do not use this method.");
     }
 
+    /**
+     * Gets the html url.
+     *
+     * @return the html url
+     */
     public URL getHtmlUrl() {
         return GitHubClient.parseURL(htmlUrl);
     }

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

@@ -7,24 +7,45 @@
 
 import static org.kohsuke.github.internal.Previews.MACHINE_MAN;
 
+// TODO: Auto-generated Javadoc
 /**
- * Creates a access token for a GitHub App Installation
+ * Creates a access token for a GitHub App Installation.
  *
  * @author Paulo Miguel Almeida
  * @see GHAppInstallation#createToken(Map) GHAppInstallation#createToken(Map)
  * @see GHAppInstallation#createToken() GHAppInstallation#createToken()
  */
 public class GHAppCreateTokenBuilder extends GitHubInteractiveObject {
+
+    /** The builder. */
     protected final Requester builder;
     private final String apiUrlTail;
 
+    /**
+     * Instantiates a new GH app create token builder.
+     *
+     * @param root
+     *            the root
+     * @param apiUrlTail
+     *            the api url tail
+     */
     @BetaApi
     GHAppCreateTokenBuilder(GitHub root, String apiUrlTail) {
         super(root);
         this.apiUrlTail = apiUrlTail;
         this.builder = root.createRequest();
     }
 
+    /**
+     * Instantiates a new GH app create token builder.
+     *
+     * @param root
+     *            the root
+     * @param apiUrlTail
+     *            the api url tail
+     * @param permissions
+     *            the permissions
+     */
     @BetaApi
     GHAppCreateTokenBuilder(GitHub root, String apiUrlTail, Map<String, GHPermissionType> permissions) {
         this(root, apiUrlTail);

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

@@ -16,6 +16,7 @@
 import static org.kohsuke.github.internal.Previews.GAMBIT;
 import static org.kohsuke.github.internal.Previews.MACHINE_MAN;
 
+// TODO: Auto-generated Javadoc
 /**
  * A Github App Installation.
  *
@@ -50,6 +51,11 @@ public class GHAppInstallation extends GHObject {
     private GHRepositorySelection repositorySelection;
     private String htmlUrl;
 
+    /**
+     * Gets the html url.
+     *
+     * @return the html url
+     */
     public URL getHtmlUrl() {
         return GitHubClient.parseURL(htmlUrl);
     }
@@ -122,7 +128,15 @@ public String getRepositoriesUrl() {
      * List repositories that this app installation can access.
      *
      * @return the paged iterable
+     * @deprecated This method cannot work on a {@link GHAppInstallation} retrieved from
+     *             {@link GHApp#listInstallations()} (for example), except when resorting to unsupported hacks involving
+     *             {@link GHAppInstallation#setRoot(GitHub)} to switch from an application client to an installation
+     *             client. This method will be removed. You should instead use an installation client (with an
+     *             installation token, not a JWT), retrieve a {@link GHAuthenticatedAppInstallation} from
+     *             {@link GitHub#getInstallation()}, then call
+     *             {@link GHAuthenticatedAppInstallation#listRepositories()}.
      */
+    @Deprecated
     @Preview(MACHINE_MAN)
     public PagedSearchIterable<GHRepository> listRepositories() {
         GitHubRequest request;

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

@@ -6,6 +6,7 @@
 import java.io.IOException;
 import java.util.*;
 
+// TODO: Auto-generated Javadoc
 /**
  * A Github App Installation Token.
  *
@@ -14,6 +15,8 @@
  */
 public class GHAppInstallationToken extends GitHubInteractiveObject {
     private String token;
+
+    /** The expires at. */
     protected String expires_at;
     private Map<String, String> permissions;
     private List<GHRepository> repositories;

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

@@ -4,18 +4,34 @@
 
 import javax.annotation.Nonnull;
 
+// TODO: Auto-generated Javadoc
 /**
  * Iterable for GHAppInstallation listing.
  */
 class GHAppInstallationsIterable extends PagedIterable<GHAppInstallation> {
+
+    /** The Constant APP_INSTALLATIONS_URL. */
     public static final String APP_INSTALLATIONS_URL = "/user/installations";
     private final transient GitHub root;
     private GHAppInstallationsPage result;
 
+    /**
+     * Instantiates a new GH app installations iterable.
+     *
+     * @param root
+     *            the root
+     */
     public GHAppInstallationsIterable(GitHub root) {
         this.root = root;
     }
 
+    /**
+     * Iterator.
+     *
+     * @param pageSize
+     *            the page size
+     * @return the paged iterator
+     */
     @Nonnull
     @Override
     public PagedIterator<GHAppInstallation> _iterator(int pageSize) {
@@ -25,6 +41,13 @@ public PagedIterator<GHAppInstallation> _iterator(int pageSize) {
                 null);
     }
 
+    /**
+     * Adapt.
+     *
+     * @param base
+     *            the base
+     * @return the iterator
+     */
     protected Iterator<GHAppInstallation[]> adapt(final Iterator<GHAppInstallationsPage> base) {
         return new Iterator<GHAppInstallation[]>() {
             public boolean hasNext() {

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

@@ -1,16 +1,27 @@
 package org.kohsuke.github;
 
+// TODO: Auto-generated Javadoc
 /**
  * Represents the one page of GHAppInstallations.
  */
 class GHAppInstallationsPage {
     private int total_count;
     private GHAppInstallation[] installations;
 
+    /**
+     * Gets the total count.
+     *
+     * @return the total count
+     */
     public int getTotalCount() {
         return total_count;
     }
 
+    /**
+     * Gets the installations.
+     *
+     * @return the installations
+     */
     GHAppInstallation[] getInstallations() {
         return installations;
     }