diff --git a/src/main/java/org/kohsuke/github/GitHub.java b/src/main/java/org/kohsuke/github/GitHub.java index 2e6bd91a4..cfc3a8fd4 100644 --- a/src/main/java/org/kohsuke/github/GitHub.java +++ b/src/main/java/org/kohsuke/github/GitHub.java @@ -829,7 +829,8 @@ public class GitHub { * if the credentials supplied are invalid or if you're trying to access it as a GitHub App via the JWT * authentication */ - GHMetaExamples.GHMetaExample getMetaExample(Class clazz) throws IOException { + GHMetaExamples.GHMetaExample getMetaExample(Class clazz) + throws IOException { return retrieve().to("/meta", clazz); } diff --git a/src/main/java/org/kohsuke/github/example/dataobject/GHMetaExamples.java b/src/main/java/org/kohsuke/github/example/dataobject/GHMetaExamples.java index faf6d6382..7d36950e6 100644 --- a/src/main/java/org/kohsuke/github/example/dataobject/GHMetaExamples.java +++ b/src/main/java/org/kohsuke/github/example/dataobject/GHMetaExamples.java @@ -13,13 +13,14 @@ import java.util.List; /** * {@link org.kohsuke.github.GHMeta} wraps the list of GitHub's IP addresses. *

- * This class is used to show examples of different ways to create simple read-only data objects. - * For data objects that can be modified, perform actions, or get other objects we'll need other examples. + * This class is used to show examples of different ways to create simple read-only data objects. For data objects that + * can be modified, perform actions, or get other objects we'll need other examples. *

* IMPORTANT: There is no one right way to do this, but there are better and worse. *

    - *
  • Better: {@link GHMetaGettersUnmodifiable} is a good balance of clarity and brevity
    • - *
  • Worse: {@link GHMetaPublic} exposes setters that are not needed, making it unclear that fields are actually read-only
    • + *
  • Better: {@link GHMetaGettersUnmodifiable} is a good balance of clarity and brevity
    • + *
  • Worse: {@link GHMetaPublic} exposes setters that are not needed, making it unclear that fields are actually + * read-only
    • * * @author Liam Newman * @@ -55,15 +56,15 @@ public final class GHMetaExamples { *

    * Pro: *

      - *
    • Easy to create
      • - *
    • Not much code
      • - *
    • Mininal annotations
      • + *
    • Easy to create
      • + *
    • Not much code
      • + *
    • Mininal annotations
      • *
    * Con: *
      - *
    • Exposes public setters for fields that should not be changed
      • - *
    • Lists modifiable when they should not be changed
      • - *
    • Jackson generally doesn't call the setters, it just sets the fields directly
      • + *
    • Exposes public setters for fields that should not be changed
      • + *
    • Lists modifiable when they should not be changed
      • + *
    • Jackson generally doesn't call the setters, it just sets the fields directly
      • *
    * * @author Paulo Miguel Almeida @@ -140,20 +141,20 @@ public final class GHMetaExamples { } /** - * This version uses public getters and shows that package or private setters both can be used by jackson. - * You can check this by running in debug and setting break points in the setters. + * This version uses public getters and shows that package or private setters both can be used by jackson. You can + * check this by running in debug and setting break points in the setters. * *

    * Pro: *

      - *
    • Easy to create
      • - *
    • Not much code
      • - *
    • Some annotations
      • + *
    • Easy to create
      • + *
    • Not much code
      • + *
    • Some annotations
      • *
    * Con: *
      - *
    • Exposes some package setters for fields that should not be changed, better than public
      • - *
    • Lists modifiable when they should not be changed
      • + *
    • Exposes some package setters for fields that should not be changed, better than public
      • + *
    • Lists modifiable when they should not be changed
      • *
    * * @author Liam Newman @@ -170,13 +171,11 @@ public final class GHMetaExamples { private List pages; /** - * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore - * getters and setters. + * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore getters and setters. */ @JsonProperty private List importer; - @JsonProperty("verifiable_password_authentication") public boolean isVerifiablePasswordAuthentication() { return verifiablePasswordAuthentication; @@ -192,10 +191,11 @@ public final class GHMetaExamples { } /** - * Setters can be private (or package local) and will still be called by Jackson. - * The {@link JsonProperty} can got on the getter or setter and still work. + * Setters can be private (or package local) and will still be called by Jackson. The {@link JsonProperty} can + * got on the getter or setter and still work. * - * @param hooks list of hooks + * @param hooks + * list of hooks */ private void setHooks(List hooks) { this.hooks = hooks; @@ -206,10 +206,11 @@ public final class GHMetaExamples { } /** - * Since we mostly use Jackson for deserialization, {@link JsonSetter} is also okay, but - * {@link JsonProperty} is preferred. + * Since we mostly use Jackson for deserialization, {@link JsonSetter} is also okay, but {@link JsonProperty} is + * preferred. * - * @param git list of git addresses + * @param git + * list of git addresses */ @JsonSetter void setGit(List git) { @@ -223,7 +224,8 @@ public final class GHMetaExamples { /** * The {@link JsonProperty} can got on the getter or setter and still work. * - * @param web list of web addresses + * @param web + * list of web addresses */ void setWeb(List web) { this.web = web; @@ -248,8 +250,7 @@ public final class GHMetaExamples { } /** - * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore - * getters and setters. + * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore getters and setters. * * @return list of importer addresses */ @@ -258,10 +259,10 @@ public final class GHMetaExamples { } /** - * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore - * getters and setters. + * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore getters and setters. * - * @param importer list of importer addresses + * @param importer + * list of importer addresses */ void setImporter(List importer) { this.importer = importer; @@ -276,15 +277,16 @@ public final class GHMetaExamples { *

    * Pro: *

      - *
    • Very Easy to create
      • - *
    • Minimal code
      • - *
    • Mininal annotations
      • - *
    • Fields effectively final and lists unmodifiable
      • + *
    • Very Easy to create
      • + *
    • Minimal code
      • + *
    • Mininal annotations
      • + *
    • Fields effectively final and lists unmodifiable
      • *
    * Con: *
      - *
    • Effectively final is not quite really final
      • - *
    • If one of the lists were missing (an option member, for example), it will throw NPE but we could mitigate by checking for null or assigning a default.
      • + *
    • Effectively final is not quite really final
      • + *
    • If one of the lists were missing (an option member, for example), it will throw NPE but we could mitigate by + * checking for null or assigning a default.
      • *
    * * @author Liam Newman @@ -338,15 +340,15 @@ public final class GHMetaExamples { *

    * Pro: *

      - *
    • Moderate amount of code
      • - *
    • More annotations
      • - *
    • Fields final and lists unmodifiable
      • + *
    • Moderate amount of code
      • + *
    • More annotations
      • + *
    • Fields final and lists unmodifiable
      • *
    * Con: *
      - *
    • Extra allocations - default array lists will be replaced by Jackson (yes, even though they are final)
      • - *
    • Added constructor is annoying
      • - *
    • If this object could be refreshed or populated, then the final is misleading (and possibly buggy)
      • + *
    • Extra allocations - default array lists will be replaced by Jackson (yes, even though they are final)
      • + *
    • Added constructor is annoying
      • + *
    • If this object could be refreshed or populated, then the final is misleading (and possibly buggy)
      • *
    * * @author Liam Newman @@ -363,8 +365,8 @@ public final class GHMetaExamples { private final List importer = new ArrayList<>(); @JsonCreator - private GHMetaGettersFinal(@JsonProperty("verifiable_password_authentication") - boolean verifiablePasswordAuthentication) { + private GHMetaGettersFinal( + @JsonProperty("verifiable_password_authentication") boolean verifiablePasswordAuthentication) { // boolean fields when final seem to be really final, so we have to switch to constructor this.verifiablePasswordAuthentication = verifiablePasswordAuthentication; } @@ -403,14 +405,15 @@ public final class GHMetaExamples { *

    * Pro: *

      - *
    • Fields final and lists unmodifiable
      • - *
    • Construction behavior can be controlled - if values depended on each other or needed to be set in a specific order, this could do that.
      • + *
    • Fields final and lists unmodifiable
      • + *
    • Construction behavior can be controlled - if values depended on each other or needed to be set in a specific + * order, this could do that.
      • *
    * Con: *
      - *
    • There is no way you'd know about this without some research
      • - *
    • Specific annotations needed
      • - *
    • Brittle and verbose - not friendly to optional fields or large number of fields
      • + *
    • There is no way you'd know about this without some research
      • + *
    • Specific annotations needed
      • + *
    • Brittle and verbose - not friendly to optional fields or large number of fields
      • *
    * * @author Liam Newman @@ -428,12 +431,10 @@ public final class GHMetaExamples { @JsonCreator private GHMetaGettersFinalCreator(@Nonnull @JsonProperty("hooks") List hooks, - @Nonnull @JsonProperty("git") List git, - @Nonnull @JsonProperty("web") Listweb, - @Nonnull @JsonProperty("api")List api, - @Nonnull @JsonProperty("pages") Listpages, - @Nonnull @JsonProperty("importer")List importer, - @JsonProperty("verifiable_password_authentication") boolean verifiablePasswordAuthentication) { + @Nonnull @JsonProperty("git") List git, @Nonnull @JsonProperty("web") List web, + @Nonnull @JsonProperty("api") List api, @Nonnull @JsonProperty("pages") List pages, + @Nonnull @JsonProperty("importer") List importer, + @JsonProperty("verifiable_password_authentication") boolean verifiablePasswordAuthentication) { this.verifiablePasswordAuthentication = verifiablePasswordAuthentication; this.hooks = Collections.unmodifiableList(hooks); this.git = Collections.unmodifiableList(git); @@ -443,7 +444,6 @@ public final class GHMetaExamples { this.importer = Collections.unmodifiableList(importer); } - public boolean isVerifiablePasswordAuthentication() { return verifiablePasswordAuthentication; } diff --git a/src/test/java/org/kohsuke/github/GitHubTest.java b/src/test/java/org/kohsuke/github/GitHubTest.java index fa3cc42c6..ec73d8a90 100644 --- a/src/test/java/org/kohsuke/github/GitHubTest.java +++ b/src/test/java/org/kohsuke/github/GitHubTest.java @@ -87,13 +87,9 @@ public class GitHubTest extends AbstractGitHubWireMockTest { assertEquals(19, meta.getWeb().size()); // Also test examples here - Class[] examples = new Class[] { - GHMetaExamples.GHMetaPublic.class, - GHMetaExamples.GHMetaPackage.class, - GHMetaExamples.GHMetaGettersUnmodifiable.class, - GHMetaExamples.GHMetaGettersFinal.class, - GHMetaExamples.GHMetaGettersFinalCreator.class, - }; + Class[] examples = new Class[] { GHMetaExamples.GHMetaPublic.class, GHMetaExamples.GHMetaPackage.class, + GHMetaExamples.GHMetaGettersUnmodifiable.class, GHMetaExamples.GHMetaGettersFinal.class, + GHMetaExamples.GHMetaGettersFinalCreator.class, }; for (Class metaClass : examples) { GHMetaExamples.GHMetaExample metaExample = gitHub.getMetaExample(metaClass);