Implement Role#getTags and add CacheFlag#ROLE_TAGS (#1343)

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

@@ -37,6 +37,7 @@
 import net.dv8tion.jda.api.requests.restaction.pagination.AuditLogPaginationAction;
 import net.dv8tion.jda.api.requests.restaction.pagination.PaginationAction;
 import net.dv8tion.jda.api.utils.MiscUtil;
+import net.dv8tion.jda.api.utils.cache.CacheFlag;
 import net.dv8tion.jda.api.utils.cache.MemberCacheView;
 import net.dv8tion.jda.api.utils.cache.SnowflakeCacheView;
 import net.dv8tion.jda.api.utils.cache.SortedSnowflakeCacheView;
@@ -1578,6 +1579,119 @@ default List<Role> getRolesByName(@Nonnull String name, boolean ignoreCase)
         return getRoleCache().getElementsByName(name, ignoreCase);
     }
 
+    /**
+     * Looks up a role which is the integration role for a bot.
+     * <br>These roles are created when the bot requested a list of permission in the authorization URL.
+     *
+     * <p>To check whether a role is a bot role you can use {@code role.getTags().isBot()} and you can use
+     * {@link Role.RoleTags#getBotIdLong()} to check which bot it applies to.
+     *
+     * <p>This requires {@link net.dv8tion.jda.api.utils.cache.CacheFlag#ROLE_TAGS CacheFlag.ROLE_TAGS} to be enabled.
+     * See {@link net.dv8tion.jda.api.JDABuilder#enableCache(CacheFlag, CacheFlag...) JDABuilder.enableCache(...)}.
+     *
+     * @param  userId
+     *         The user id of the bot
+     *
+     * @return The bot role, or null if no role matches
+     */
+    @Nullable
+    default Role getRoleByBot(long userId)
+    {
+        return getRoleCache().applyStream(stream ->
+            stream.filter(role -> role.getTags().getBotIdLong() == userId)
+                  .findFirst()
+                  .orElse(null)
+        );
+    }
+
+    /**
+     * Looks up a role which is the integration role for a bot.
+     * <br>These roles are created when the bot requested a list of permission in the authorization URL.
+     *
+     * <p>To check whether a role is a bot role you can use {@code role.getTags().isBot()} and you can use
+     * {@link Role.RoleTags#getBotIdLong()} to check which bot it applies to.
+     *
+     * <p>This requires {@link net.dv8tion.jda.api.utils.cache.CacheFlag#ROLE_TAGS CacheFlag.ROLE_TAGS} to be enabled.
+     * See {@link net.dv8tion.jda.api.JDABuilder#enableCache(CacheFlag, CacheFlag...) JDABuilder.enableCache(...)}.
+     *
+     * @param  userId
+     *         The user id of the bot
+     *
+     * @throws IllegalArgumentException
+     *         If the userId is null or not a valid snowflake
+     *
+     * @return The bot role, or null if no role matches
+     */
+    @Nullable
+    default Role getRoleByBot(@Nonnull String userId)
+    {
+        return getRoleByBot(MiscUtil.parseSnowflake(userId));
+    }
+
+    /**
+     * Looks up a role which is the integration role for a bot.
+     * <br>These roles are created when the bot requested a list of permission in the authorization URL.
+     *
+     * <p>To check whether a role is a bot role you can use {@code role.getTags().isBot()} and you can use
+     * {@link Role.RoleTags#getBotIdLong()} to check which bot it applies to.
+     *
+     * <p>This requires {@link net.dv8tion.jda.api.utils.cache.CacheFlag#ROLE_TAGS CacheFlag.ROLE_TAGS} to be enabled.
+     * See {@link net.dv8tion.jda.api.JDABuilder#enableCache(CacheFlag, CacheFlag...) JDABuilder.enableCache(...)}.
+     *
+     * @param  user
+     *         The bot user
+     *
+     * @throws IllegalArgumentException
+     *         If null is provided
+     *
+     * @return The bot role, or null if no role matches
+     */
+    @Nullable
+    default Role getRoleByBot(@Nonnull User user)
+    {
+        Checks.notNull(user, "User");
+        return getRoleByBot(user.getIdLong());
+    }
+
+    /**
+     * Looks up the role which is the integration role for the currently connected bot (self-user).
+     * <br>These roles are created when the bot requested a list of permission in the authorization URL.
+     *
+     * <p>To check whether a role is a bot role you can use {@code role.getTags().isBot()} and you can use
+     * {@link Role.RoleTags#getBotIdLong()} to check which bot it applies to.
+     *
+     * <p>This requires {@link net.dv8tion.jda.api.utils.cache.CacheFlag#ROLE_TAGS CacheFlag.ROLE_TAGS} to be enabled.
+     * See {@link net.dv8tion.jda.api.JDABuilder#enableCache(CacheFlag, CacheFlag...) JDABuilder.enableCache(...)}.
+     *
+     * @return The bot role, or null if no role matches
+     */
+    @Nullable
+    default Role getBotRole()
+    {
+        return getRoleByBot(getJDA().getSelfUser());
+    }
+
+    /**
+     * Looks up the role which is the booster role of this guild.
+     * <br>These roles are created when the first user boosts this guild.
+     *
+     * <p>To check whether a role is a booster role you can use {@code role.getTags().isBoost()}.
+     *
+     * <p>This requires {@link net.dv8tion.jda.api.utils.cache.CacheFlag#ROLE_TAGS CacheFlag.ROLE_TAGS} to be enabled.
+     * See {@link net.dv8tion.jda.api.JDABuilder#enableCache(CacheFlag, CacheFlag...) JDABuilder.enableCache(...)}.
+     *
+     * @return The boost role, or null if no role matches
+     */
+    @Nullable
+    default Role getBoostRole()
+    {
+        return getRoleCache().applyStream(stream ->
+            stream.filter(role -> role.getTags().isBoost())
+                  .findFirst()
+                  .orElse(null)
+        );
+    }
+
     /**
      * Sorted {@link net.dv8tion.jda.api.utils.cache.SnowflakeCacheView SnowflakeCacheView} of
      * all cached {@link net.dv8tion.jda.api.entities.Role Roles} of this Guild.

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.managers.RoleManager;
 import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
 import net.dv8tion.jda.api.requests.restaction.RoleAction;
+import net.dv8tion.jda.api.utils.cache.CacheFlag;
 
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
@@ -271,4 +272,89 @@ default RoleAction createCopy()
      */
     @Nonnull
     JDA getJDA();
+
+    /**
+     * The tags of this role.
+     * <br>This is useful to determine the purpose of a managed role.
+     *
+     * <p>This requires {@link net.dv8tion.jda.api.utils.cache.CacheFlag#ROLE_TAGS CacheFlag.ROLE_TAGS}
+     * to be enabled.
+     * See {@link net.dv8tion.jda.api.JDABuilder#enableCache(CacheFlag, CacheFlag...) JDABuilder.enableCache(...)}.
+     *
+     * @return {@link RoleTags}
+     */
+    @Nonnull
+    RoleTags getTags();
+
+    /**
+     * Tags associated with this role.
+     */
+    interface RoleTags
+    {
+        /**
+         * Whether this role is associated with a bot.
+         *
+         * @return True, if this role is for a bot
+         */
+        boolean isBot();
+
+        /**
+         * The id for the bot associated with this role.
+         *
+         * @return The bot id, or 0 if this role is not for a bot
+         *
+         * @see    #isBot()
+         */
+        long getBotIdLong();
+
+        /**
+         * The id for the bot associated with this role.
+         *
+         * @return The bot id, or null if this role is not for a bot
+         *
+         * @see    #isBot()
+         */
+        @Nullable
+        default String getBotId()
+        {
+            return isBot() ? Long.toUnsignedString(getBotIdLong()) : null;
+        }
+
+        /**
+         * Whether this role is the boost role of this guild.
+         *
+         * @return True, if this role is the boost role
+         */
+        boolean isBoost();
+
+        /**
+         * Whether this role is managed by an integration.
+         * <br>This is usually true for roles such as those created for twitch subscribers.
+         *
+         * @return True, if this role is managed by an integration
+         */
+        boolean isIntegration();
+
+        /**
+         * The id for the integration associated with this role.
+         *
+         * @return The integration id, or 0 if this role is not for an integration
+         *
+         * @see    #isIntegration()
+         */
+        long getIntegrationIdLong();
+
+        /**
+         * The id for the integration associated with this role.
+         *
+         * @return The integration id, or null if this role is not for an integration
+         *
+         * @see    #isIntegration()
+         */
+        @Nullable
+        default String getIntegrationId()
+        {
+            return isIntegration() ? Long.toUnsignedString(getIntegrationIdLong()) : null;
+        }
+    }
 }

src/main/java/net/dv8tion/jda/api/utils/cache/CacheFlag.java

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.GuildChannel;
 import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Role;
 import net.dv8tion.jda.api.requests.GatewayIntent;
 
 import javax.annotation.Nullable;
@@ -58,6 +59,10 @@ public enum CacheFlag
      * Enables cache for {@link GuildChannel#getMemberPermissionOverrides()}
      */
     MEMBER_OVERRIDES(null),
+    /**
+     * Enables cache for {@link Role#getTags()}
+     */
+    ROLE_TAGS(null),
     ;
     private final GatewayIntent requiredIntent;
 

src/main/java/net/dv8tion/jda/internal/entities/EntityBuilder.java

@@ -1040,7 +1040,8 @@ public Role createRole(GuildImpl guild, DataObject roleJson, long guildId)
             .setManaged(roleJson.getBoolean("managed"))
             .setHoisted(roleJson.getBoolean("hoist"))
             .setColor(color == 0 ? Role.DEFAULT_COLOR_RAW : color)
-            .setMentionable(roleJson.getBoolean("mentionable"));
+            .setMentionable(roleJson.getBoolean("mentionable"))
+            .setTags(roleJson.optObject("tags").orElseGet(DataObject::empty));
         if (playbackCache)
             getJDA().getEventCache().playbackCache(EventCache.Type.ROLE, id);
         return role;

src/main/java/net/dv8tion/jda/internal/entities/RoleImpl.java

@@ -27,6 +27,8 @@
 import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
 import net.dv8tion.jda.api.requests.restaction.RoleAction;
 import net.dv8tion.jda.api.utils.MiscUtil;
+import net.dv8tion.jda.api.utils.cache.CacheFlag;
+import net.dv8tion.jda.api.utils.data.DataObject;
 import net.dv8tion.jda.internal.JDAImpl;
 import net.dv8tion.jda.internal.managers.RoleManagerImpl;
 import net.dv8tion.jda.internal.requests.Route;
@@ -40,6 +42,7 @@
 import java.time.OffsetDateTime;
 import java.util.Collection;
 import java.util.EnumSet;
+import java.util.Objects;
 import java.util.concurrent.locks.ReentrantLock;
 
 public class RoleImpl implements Role
@@ -51,6 +54,7 @@ public class RoleImpl implements Role
     private final ReentrantLock mngLock = new ReentrantLock();
     private volatile RoleManager manager;
 
+    private RoleTagsImpl tags;
     private String name;
     private boolean managed;
     private boolean hoisted;
@@ -64,6 +68,7 @@ public RoleImpl(long id, Guild guild)
         this.id = id;
         this.api =(JDAImpl) guild.getJDA();
         this.guild = guild;
+        this.tags = api.isCacheFlagSet(CacheFlag.ROLE_TAGS) ? new RoleTagsImpl() : null;
     }
 
     @Override
@@ -278,6 +283,13 @@ public JDA getJDA()
         return api;
     }
 
+    @Nonnull
+    @Override
+    public RoleTags getTags()
+    {
+        return tags == null ? RoleTagsImpl.EMPTY : tags;
+    }
+
     @Nonnull
     @Override
     public String getAsMention()
@@ -383,4 +395,89 @@ public RoleImpl setRawPosition(int rawPosition)
         this.rawPosition = rawPosition;
         return this;
     }
+
+    public RoleImpl setTags(DataObject tags)
+    {
+        if (this.tags == null)
+            return this;
+        this.tags = new RoleTagsImpl(tags);
+        return this;
+    }
+
+    public static class RoleTagsImpl implements RoleTags
+    {
+        public static final RoleTags EMPTY = new RoleTagsImpl();
+        private final long botId;
+        private final long integrationId;
+        private final boolean premiumSubscriber;
+
+        public RoleTagsImpl()
+        {
+            this.botId = 0L;
+            this.integrationId = 0L;
+            this.premiumSubscriber = false;
+        }
+
+        public RoleTagsImpl(DataObject tags)
+        {
+            this.botId = tags.hasKey("bot_id") ? tags.getUnsignedLong("bot_id") : 0L;
+            this.integrationId = tags.hasKey("integration_id") ? tags.getUnsignedLong("integration_id") : 0L;
+            this.premiumSubscriber = tags.hasKey("premium_subscriber");
+        }
+
+        @Override
+        public boolean isBot()
+        {
+            return botId != 0;
+        }
+
+        @Override
+        public long getBotIdLong()
+        {
+            return botId;
+        }
+
+        @Override
+        public boolean isBoost()
+        {
+            return premiumSubscriber;
+        }
+
+        @Override
+        public boolean isIntegration()
+        {
+            return integrationId != 0;
+        }
+
+        @Override
+        public long getIntegrationIdLong()
+        {
+            return integrationId;
+        }
+
+        @Override
+        public int hashCode()
+        {
+            return Objects.hash(botId, integrationId, premiumSubscriber);
+        }
+
+        @Override
+        public boolean equals(Object obj)
+        {
+            if (obj == this)
+                return true;
+            if (!(obj instanceof RoleTagsImpl))
+                return false;
+            RoleTagsImpl other = (RoleTagsImpl) obj;
+            return botId == other.botId
+                && integrationId == other.integrationId
+                && premiumSubscriber == other.premiumSubscriber;
+        }
+
+        @Override
+        public String toString()
+        {
+            return "RoleTags(bot=" + getBotId() + ",integration=" + getIntegrationId() + ",boost=" + isBoost() + ")";
+        }
+    }
 }