Add compliance tests for common patterns (discord-jda#2746)

* Add compliance test for rest action annotations
* Add compliance test for future annotations
* Add compliance test for nullability annotations

Author: MinnDevelopment

build.gradle.kts

@@ -163,6 +163,7 @@ dependencies {
     testImplementation(libs.assertj)
     testImplementation(libs.commons.lang3)
     testImplementation(libs.logback.classic)
+    testImplementation(libs.archunit)
 }
 
 

settings.gradle.kts

@@ -24,6 +24,7 @@ dependencyResolutionManagement {
             library("reflections",           "org.reflections",          "reflections"         ).version("0.10.2")
             library("slf4j",                 "org.slf4j",                "slf4j-api"           ).version("2.0.13")
             library("tink",                  "com.google.crypto.tink",   "tink"                ).version("1.14.1")
+            library("archunit",              "com.tngtech.archunit",     "archunit"            ).version("1.3.0")
         }
     }
 }

src/main/java/net/dv8tion/jda/annotations/UnknownNullability.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dv8tion.jda.annotations;
+
+import java.lang.annotation.*;
+
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.METHOD})
+public @interface UnknownNullability
+{
+}

src/main/java/net/dv8tion/jda/api/JDA.java

@@ -186,11 +186,13 @@ public int getShardTotal()
          *
          * @return A String representing the information used to build this shard.
          */
+        @Nonnull
         public String getShardString()
         {
             return "[" + shardId + " / " + shardTotal + "]";
         }
 
+        @Nonnull
         @Override
         public String toString()
         {
@@ -282,6 +284,7 @@ public boolean equals(Object o)
      * @see    #getGatewayPing()
      */
     @Nonnull
+    @CheckReturnValue
     default RestAction<Long> getRestPing()
     {
         AtomicLong time = new AtomicLong();

src/main/java/net/dv8tion/jda/api/OnlineStatus.java

@@ -15,6 +15,8 @@
  */
 package net.dv8tion.jda.api;
 
+import javax.annotation.Nonnull;
+
 /**
  * Represents the online presence of a {@link net.dv8tion.jda.api.entities.Member Member}.
  */
@@ -63,6 +65,7 @@ public enum OnlineStatus
      *
      * @see    <a href="https://discord.com/developers/docs/topics/gateway#presence-update">PRESENCE_UPDATE</a>
      */
+    @Nonnull
     public String getKey()
     {
         return key;
@@ -77,7 +80,8 @@ public String getKey()
      *
      * @return The matching {@link net.dv8tion.jda.api.OnlineStatus OnlineStatus}. If there is no match, returns {@link net.dv8tion.jda.api.OnlineStatus#UNKNOWN UNKNOWN}.
      */
-    public static OnlineStatus fromKey(String key)
+    @Nonnull
+    public static OnlineStatus fromKey(@Nonnull String key)
     {
         for (OnlineStatus onlineStatus : values())
         {

src/main/java/net/dv8tion/jda/api/audit/ActionType.java

@@ -22,6 +22,8 @@
 import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel;
 import net.dv8tion.jda.api.entities.emoji.RichCustomEmoji;
 
+import javax.annotation.Nonnull;
+
 /**
  * ActionTypes for {@link net.dv8tion.jda.api.audit.AuditLogEntry AuditLogEntry} instances
  * <br>Found via {@link net.dv8tion.jda.api.audit.AuditLogEntry#getType() AuditLogEntry.getType()}
@@ -684,11 +686,13 @@ public int getKey()
      *
      * @return {@link net.dv8tion.jda.api.audit.TargetType TargetType}
      */
+    @Nonnull
     public TargetType getTargetType()
     {
         return target;
     }
 
+    @Nonnull
     public static ActionType from(int key)
     {
         for (ActionType type : values())

src/main/java/net/dv8tion/jda/api/audit/AuditLogKey.java

@@ -33,6 +33,8 @@
 import net.dv8tion.jda.api.entities.sticker.GuildSticker;
 import net.dv8tion.jda.internal.utils.EntityString;
 
+import javax.annotation.Nonnull;
+
 /**
  * Enum of possible/expected keys that can be provided
  * to {@link AuditLogEntry#getChangeByKey(AuditLogKey) AuditLogEntry.getChangeByKey(AuditLogEntry.AuditLogKey}.
@@ -686,11 +688,13 @@ public enum AuditLogKey
         this.key = key;
     }
 
+    @Nonnull
     public String getKey()
     {
         return key;
     }
 
+    @Nonnull
     @Override
     public String toString()
     {

src/main/java/net/dv8tion/jda/api/audit/AuditLogOption.java

@@ -18,6 +18,8 @@
 
 import net.dv8tion.jda.internal.utils.EntityString;
 
+import javax.annotation.Nonnull;
+
 /**
  * Enum constants for possible options
  * <br>Providing detailed description of possible occasions and expected types.
@@ -139,6 +141,7 @@ public enum AuditLogOption
      *
      * @return Key for this option
      */
+    @Nonnull
     public String getKey()
     {
         return key;

src/main/java/net/dv8tion/jda/api/entities/ClientType.java

@@ -47,6 +47,7 @@ public enum ClientType
      *
      * @return The raw key
      */
+    @Nonnull
     public String getKey()
     {
         return key;

src/main/java/net/dv8tion/jda/api/entities/Entitlement.java

@@ -79,6 +79,7 @@ default String getApplicationId()
      *
      * @return The id of the user that purchased the {@link Entitlement Entitlement}
      */
+    @Nonnull
     default String getUserId()
     {
         return Long.toUnsignedString(getUserIdLong());

src/main/java/net/dv8tion/jda/api/entities/Guild.java

@@ -2322,6 +2322,7 @@ default RestAction<RichCustomEmoji> retrieveEmoji(@Nonnull CustomEmoji emoji)
      * @return The Manager of this Guild
      */
     @Nonnull
+    @CheckReturnValue
     GuildManager getManager();
 
     /**
@@ -2827,6 +2828,7 @@ default Task<List<Member>> findMembersWithRoles(@Nonnull Role... roles)
      * @see    #unloadMember(long)
      */
     @Nonnull
+    @CheckReturnValue
     default CacheRestAction<Member> retrieveMember(@Nonnull UserSnowflake user)
     {
         Checks.notNull(user, "User");
@@ -2862,6 +2864,7 @@ default CacheRestAction<Member> retrieveMember(@Nonnull UserSnowflake user)
      * @see    #retrieveMemberById(long)
      */
     @Nonnull
+    @CheckReturnValue
     default CacheRestAction<Member> retrieveOwner()
     {
         return retrieveMemberById(getOwnerIdLong());
@@ -2898,6 +2901,7 @@ default CacheRestAction<Member> retrieveOwner()
      * @see    #unloadMember(long)
      */
     @Nonnull
+    @CheckReturnValue
     default CacheRestAction<Member> retrieveMemberById(@Nonnull String id)
     {
         return retrieveMemberById(MiscUtil.parseSnowflake(id));
@@ -2929,6 +2933,7 @@ default CacheRestAction<Member> retrieveMemberById(@Nonnull String id)
      * @see    #unloadMember(long)
      */
     @Nonnull
+    @CheckReturnValue
     CacheRestAction<Member> retrieveMemberById(long id);
 
     /**
@@ -3950,6 +3955,7 @@ default AuditableRestAction<Void> timeoutFor(@Nonnull UserSnowflake user, @Nonnu
      * @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
      */
     @Nonnull
+    @CheckReturnValue
     AuditableRestAction<Void> removeTimeout(@Nonnull UserSnowflake user);
 
     /**

src/main/java/net/dv8tion/jda/api/entities/GuildWelcomeScreen.java

@@ -26,6 +26,7 @@
 import net.dv8tion.jda.internal.entities.GuildWelcomeScreenImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import java.util.List;
@@ -66,6 +67,7 @@ public interface GuildWelcomeScreen
      * @see Guild#modifyWelcomeScreen()
      */
     @Nonnull
+    @CheckReturnValue
     GuildWelcomeScreenManager getManager();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/Invite.java

@@ -65,6 +65,7 @@ public interface Invite
      *         <br>The Invite object
      */
     @Nonnull
+    @CheckReturnValue
     static RestAction<Invite> resolve(@Nonnull final JDA api, @Nonnull final String code)
     {
         return resolve(api, code, false);
@@ -91,6 +92,7 @@ static RestAction<Invite> resolve(@Nonnull final JDA api, @Nonnull final String
      *         <br>The Invite object
      */
     @Nonnull
+    @CheckReturnValue
     static RestAction<Invite> resolve(@Nonnull final JDA api, @Nonnull final String code, final boolean withCounts)
     {
         return InviteImpl.resolve(api, code, withCounts);

src/main/java/net/dv8tion/jda/api/entities/Message.java

@@ -2382,8 +2382,9 @@ default MessageCreateAction forwardTo(@Nonnull MessageChannel channel)
      *
      * @return A specific {@link ThreadChannelAction} that may be used to configure the new ThreadChannel before its creation.
      */
+    @Nonnull
     @CheckReturnValue
-    ThreadChannelAction createThreadChannel(String name);
+    ThreadChannelAction createThreadChannel(@Nonnull String name);
 
     /**
      * Mention constants, useful for use with {@link java.util.regex.Pattern Patterns}

src/main/java/net/dv8tion/jda/api/entities/MessageReference.java

@@ -29,6 +29,7 @@
 import net.dv8tion.jda.internal.requests.RestActionImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
@@ -102,6 +103,7 @@ public MessageReference(int type, long messageId, long channelId, long guildId,
      * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@link net.dv8tion.jda.api.entities.Message}
      */
     @Nonnull
+    @CheckReturnValue
     public RestAction<Message> resolve()
     {
         return resolve(true);
@@ -146,6 +148,7 @@ public RestAction<Message> resolve()
      * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@link net.dv8tion.jda.api.entities.Message}
      */
     @Nonnull
+    @CheckReturnValue
     public RestAction<Message> resolve(boolean update)
     {
         checkPermission(Permission.VIEW_CHANNEL);

src/main/java/net/dv8tion/jda/api/entities/PermissionOverride.java

@@ -182,6 +182,7 @@ public interface PermissionOverride extends ISnowflake
      * @return The PermissionOverrideAction of this override.
      */
     @Nonnull
+    @CheckReturnValue
     PermissionOverrideAction getManager();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/RichPresence.java

@@ -84,6 +84,7 @@ public interface RichPresence extends Activity
      * @see    ActivityFlag
      * @see    ActivityFlag#getFlags(int)
      */
+    @Nonnull
     EnumSet<ActivityFlag> getFlagSet();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/Role.java

@@ -238,6 +238,7 @@ default RoleAction createCopy()
      * @return The RoleManager of this Role
      */
     @Nonnull
+    @CheckReturnValue
     RoleManager getManager();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/ScheduledEvent.java

@@ -305,6 +305,7 @@ default JDA getJDA()
      * @return The ScheduledEventManager of this event
      */
     @Nonnull
+    @CheckReturnValue
     ScheduledEventManager getManager();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/SelfUser.java

@@ -18,6 +18,7 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.managers.AccountManager;
 
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 
 /**
@@ -84,5 +85,6 @@ default String getApplicationId()
      * @return An AccountManager instance for the current account
      */
     @Nonnull
+    @CheckReturnValue
     AccountManager getManager();
 }

src/main/java/net/dv8tion/jda/api/entities/Webhook.java

@@ -297,6 +297,7 @@ public interface Webhook extends ISnowflake, WebhookClient<Message>
      * @return The {@link WebhookManager WebhookManager} for this Webhook
      */
     @Nonnull
+    @CheckReturnValue
     WebhookManager getManager();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/automod/AutoModRule.java

@@ -26,6 +26,7 @@
 import net.dv8tion.jda.api.managers.AutoModRuleManager;
 import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
 
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 import java.util.EnumSet;
 import java.util.List;
@@ -225,6 +226,7 @@ default String getCreatorId()
      * @return The manager instance
      */
     @Nonnull
+    @CheckReturnValue
     default AutoModRuleManager getManager()
     {
         return getGuild().modifyAutoModRuleById(getId());
@@ -239,6 +241,7 @@ default AutoModRuleManager getManager()
      * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@link Void}
      */
     @Nonnull
+    @CheckReturnValue
     default AuditableRestAction<Void> delete()
     {
         return getGuild().deleteAutoModRuleById(getId());

src/main/java/net/dv8tion/jda/api/entities/channel/attribute/ICategorizableChannel.java

@@ -20,6 +20,7 @@
 import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel;
 import net.dv8tion.jda.api.managers.channel.attribute.ICategorizableChannelManager;
 
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
@@ -35,6 +36,7 @@ public interface ICategorizableChannel extends GuildChannel, IPermissionContaine
 {
     @Override
     @Nonnull
+    @CheckReturnValue
     ICategorizableChannelManager<?, ?> getManager();
 
     /**

src/main/java/net/dv8tion/jda/api/entities/channel/attribute/IPermissionContainer.java

@@ -40,6 +40,7 @@ public interface IPermissionContainer extends GuildChannel
 {
     @Override
     @Nonnull
+    @CheckReturnValue
     IPermissionContainerManager<?, ?> getManager();
 
     /**