Add more static analyzer annotations (#2675)

* Add unmodifiable annotation * Handle parsing errors in retrievePinnedMessages * Add missing docs for Guild#retrieveActiveThreads * Use Blocking annotation
discord-jda · May 9, 2024 · 994713b · 994713b
1 parent 5560408
commit 994713b
Show file tree

Hide file tree

Showing 48 changed files with 245 additions and 28 deletions.
diff --git a/src/main/java/net/dv8tion/jda/api/JDA.java b/src/main/java/net/dv8tion/jda/api/JDA.java
@@ -16,7 +16,6 @@
 
 package net.dv8tion.jda.api;
 
-import net.dv8tion.jda.annotations.ForRemoval;
 import net.dv8tion.jda.annotations.Incubating;
 import net.dv8tion.jda.api.entities.*;
 import net.dv8tion.jda.api.entities.channel.Channel;
@@ -50,6 +49,7 @@
 import net.dv8tion.jda.internal.utils.EntityString;
 import net.dv8tion.jda.internal.utils.Helpers;
 import okhttp3.OkHttpClient;
+import org.jetbrains.annotations.Unmodifiable;
 
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
@@ -933,6 +933,7 @@ default RestAction<Void> deleteCommandById(long commandId)
      * @return Immutable list of all created AudioManager instances
      */
     @Nonnull
+    @Unmodifiable
     default List<AudioManager> getAudioManagers()
     {
         return getAudioManagerCache().asList();
@@ -966,6 +967,7 @@ default List<AudioManager> getAudioManagers()
      * @return Immutable list of all {@link net.dv8tion.jda.api.entities.User Users} that are visible to JDA.
      */
     @Nonnull
+    @Unmodifiable
     default List<User> getUsers()
     {
         return getUserCache().asList();
@@ -1031,14 +1033,9 @@ default User getUserById(long id)
      *         If the provided tag is null or not in the described format
      *
      * @return The {@link net.dv8tion.jda.api.entities.User} for the discord tag or null if no user has the provided tag
-     *
-     * @deprecated This will become obsolete in the future.
-     *             Discriminators are being phased out and replaced by globally unique usernames.
-     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nullable
-    @Deprecated
-    @ForRemoval
+    @Incubating
     default User getUserByTag(@Nonnull String tag)
     {
         Checks.notNull(tag, "Tag");
@@ -1070,14 +1067,9 @@ default User getUserByTag(@Nonnull String tag)
      *         If the provided arguments are null or not in the described format
      *
      * @return The {@link net.dv8tion.jda.api.entities.User} for the discord tag or null if no user has the provided tag
-     *
-     * @deprecated This will become obsolete in the future.
-     *             Discriminators are being phased out and replaced by globally unique usernames.
-     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nullable
-    @Deprecated
-    @ForRemoval
+    @Incubating
     default User getUserByTag(@Nonnull String username, @Nonnull String discriminator)
     {
         Checks.notNull(username, "Username");
@@ -1112,6 +1104,7 @@ default User getUserByTag(@Nonnull String username, @Nonnull String discriminato
      */
     @Nonnull
     @Incubating
+    @Unmodifiable
     default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
     {
         return getUserCache().getElementsByName(name, ignoreCase);
@@ -1128,6 +1121,7 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
      * @see    Guild#isMember(UserSnowflake)
      */
     @Nonnull
+    @Unmodifiable
     List<Guild> getMutualGuilds(@Nonnull User... users);
 
     /**
@@ -1139,6 +1133,7 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
      * @return Immutable list of all {@link Guild Guild} instances which have all {@link net.dv8tion.jda.api.entities.User Users} in them.
      */
     @Nonnull
+    @Unmodifiable
     List<Guild> getMutualGuilds(@Nonnull Collection<User> users);
 
     /**
@@ -1229,6 +1224,7 @@ default CacheRestAction<User> retrieveUserById(@Nonnull String id)
      * @return Possibly-empty immutable list of all the {@link Guild Guilds} that this account is connected to.
      */
     @Nonnull
+    @Unmodifiable
     default List<Guild> getGuilds()
     {
         return getGuildCache().asList();
@@ -1279,6 +1275,7 @@ default Guild getGuildById(long id)
      * @return Possibly-empty immutable list of all the {@link Guild Guilds} that all have the same name as the provided name.
      */
     @Nonnull
+    @Unmodifiable
     default List<Guild> getGuildsByName(@Nonnull String name, boolean ignoreCase)
     {
         return getGuildCache().getElementsByName(name, ignoreCase);
@@ -1330,6 +1327,7 @@ default List<Guild> getGuildsByName(@Nonnull String name, boolean ignoreCase)
      * @return Immutable List of all visible Roles
      */
     @Nonnull
+    @Unmodifiable
     default List<Role> getRoles()
     {
         return getRoleCache().asList();
@@ -1383,10 +1381,12 @@ default Role getRoleById(long id)
      * @return Immutable List of all Roles matching the parameters provided.
      */
     @Nonnull
+    @Unmodifiable
     default List<Role> getRolesByName(@Nonnull String name, boolean ignoreCase)
     {
         return getRoleCache().getElementsByName(name, ignoreCase);
     }
+
     /**
      * {@link SnowflakeCacheView} of
      * all cached {@link ScheduledEvent ScheduledEvents} visible to this JDA session.
@@ -1412,6 +1412,7 @@ default List<Role> getRolesByName(@Nonnull String name, boolean ignoreCase)
      * @return Possibly-empty immutable list of all known {@link ScheduledEvent ScheduledEvents}.
      */
     @Nonnull
+    @Unmodifiable
     default List<ScheduledEvent> getScheduledEvents()
     {
         return getScheduledEventCache().asList();
@@ -1474,6 +1475,7 @@ default ScheduledEvent getScheduledEventById(long id)
      *         same name as the provided name.
      */
     @Nonnull
+    @Unmodifiable
     default List<ScheduledEvent> getScheduledEventsByName(@Nonnull String name, boolean ignoreCase)
     {
         return getScheduledEventCache().getElementsByName(name, ignoreCase);
@@ -1499,6 +1501,7 @@ default List<ScheduledEvent> getScheduledEventsByName(@Nonnull String name, bool
      * @return Possibly-empty list of all {@link PrivateChannel PrivateChannels}.
      */
     @Nonnull
+    @Unmodifiable
     default List<PrivateChannel> getPrivateChannels()
     {
         return getPrivateChannelCache().asList();
@@ -1634,6 +1637,7 @@ default CacheRestAction<PrivateChannel> openPrivateChannelById(@Nonnull String u
      * @return An immutable list of Custom Emojis (which may or may not be available to usage).
      */
     @Nonnull
+    @Unmodifiable
     default List<RichCustomEmoji> getEmojis()
     {
         return getEmojiCache().asList();
@@ -1696,6 +1700,7 @@ default RichCustomEmoji getEmojiById(long id)
      *         name as the provided name.
      */
     @Nonnull
+    @Unmodifiable
     default List<RichCustomEmoji> getEmojisByName(@Nonnull String name, boolean ignoreCase)
     {
         return getEmojiCache().getElementsByName(name, ignoreCase);
@@ -1734,7 +1739,7 @@ default List<RichCustomEmoji> getEmojisByName(@Nonnull String name, boolean igno
      */
     @Nonnull
     @CheckReturnValue
-    RestAction<List<StickerPack>> retrieveNitroStickerPacks();
+    RestAction<@Unmodifiable List<StickerPack>> retrieveNitroStickerPacks();
 
     /**
      * The EventManager used by this JDA instance.

diff --git a/src/main/java/net/dv8tion/jda/api/audit/AuditLogEntry.java b/src/main/java/net/dv8tion/jda/api/audit/AuditLogEntry.java
@@ -27,6 +27,7 @@
 import net.dv8tion.jda.internal.entities.WebhookImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 import net.dv8tion.jda.internal.utils.EntityString;
+import org.jetbrains.annotations.Unmodifiable;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
@@ -240,6 +241,7 @@ public AuditLogChange getChangeByKey(@Nullable final String key)
      * @return Possibly-empty, never-null immutable list of {@link AuditLogChange AuditLogChanges}
      */
     @Nonnull
+    @Unmodifiable
     public List<AuditLogChange> getChangesForKeys(@Nonnull AuditLogKey... keys)
     {
         Checks.notNull(keys, "Keys");
@@ -329,6 +331,7 @@ public <T> T getOption(@Nonnull AuditLogOption option)
      * @return Unmodifiable list of representative values
      */
     @Nonnull
+    @Unmodifiable
     public List<Object> getOptions(@Nonnull AuditLogOption... options)
     {
         Checks.notNull(options, "Options");

diff --git a/src/main/java/net/dv8tion/jda/api/entities/ApplicationInfo.java b/src/main/java/net/dv8tion/jda/api/entities/ApplicationInfo.java
@@ -20,6 +20,7 @@
 import net.dv8tion.jda.api.Permission;
 import net.dv8tion.jda.api.utils.ImageProxy;
 import net.dv8tion.jda.internal.utils.Checks;
+import org.jetbrains.annotations.Unmodifiable;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
@@ -313,6 +314,7 @@ default String getInviteUrl(long guildId, @Nullable Permission... permissions)
      * @return Immutable list containing the tags of this bot's application
      */
     @Nonnull
+    @Unmodifiable
     List<String> getTags();
 
     /**
@@ -323,6 +325,7 @@ default String getInviteUrl(long guildId, @Nullable Permission... permissions)
      * @return Immutable list containing the OAuth2 redirect URIs of this bot's application
      */
     @Nonnull
+    @Unmodifiable
     List<String> getRedirectUris();
 
     /**
@@ -366,6 +369,7 @@ default String getInviteUrl(long guildId, @Nullable Permission... permissions)
      * @return Immutable list of scopes the default authorization URL is set up with.
      */
     @Nonnull
+    @Unmodifiable
     List<String> getScopes();
 
     /**

diff --git a/src/main/java/net/dv8tion/jda/api/entities/ApplicationTeam.java b/src/main/java/net/dv8tion/jda/api/entities/ApplicationTeam.java
@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.utils.ImageProxy;
 import net.dv8tion.jda.api.utils.MiscUtil;
 import net.dv8tion.jda.internal.utils.Checks;
+import org.jetbrains.annotations.Unmodifiable;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
@@ -107,6 +108,7 @@ default ImageProxy getIcon()
      * @return Immutable list of team members
      */
     @Nonnull
+    @Unmodifiable
     List<TeamMember> getMembers();
 
     /**