Message interface declutter: Message#getMentions()

src/examples/java/MessageListenerExample.java

@@ -170,7 +170,7 @@ else if (msg.startsWith("!kick"))   //Note, I used "startsWith, not equals.
             if (message.isFromType(ChannelType.TEXT))
             {
                 //If no users are provided, we can't kick anyone!
-                if (message.getMentionedUsers().isEmpty())
+                if (message.getMentions().getUsers().isEmpty())
                 {
                     channel.sendMessage("You must mention 1 or more Users to be kicked!").queue();
                 }
@@ -188,7 +188,7 @@ else if (msg.startsWith("!kick"))   //Note, I used "startsWith, not equals.
                     }
 
                     //Loop over all mentioned users, kicking them one at a time. Mwauahahah!
-                    List<User> mentionedUsers = message.getMentionedUsers();
+                    List<User> mentionedUsers = message.getMentions().getUsers();
                     for (User user : mentionedUsers)
                     {
                         Member member = guild.getMember(user);  //We get the member object for each mentioned user to kick them!

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

@@ -245,246 +245,9 @@ default Message getReferencedMessage()
                 : null;
     }
 
-    /**
-     * An immutable list of all mentioned {@link net.dv8tion.jda.api.entities.User Users}.
-     * <br>If no user was mentioned, this list is empty. Elements are sorted in order of appearance. This only
-     * counts direct mentions of the user and not mentions through roles or the everyone tag.
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return immutable list of mentioned users
-     */
-    @Nonnull
-    List<User> getMentionedUsers();
-
-    /**
-     * A {@link org.apache.commons.collections4.Bag Bag} of mentioned users.
-     * <br>This can be used to retrieve the amount of times a user was mentioned in this message. This only
-     * counts direct mentions of the user and not mentions through roles or the everyone tag.
-     *
-     * <h2>Example</h2>
-     * <pre>{@code
-     * public void sendCount(Message msg)
-     * {
-     *     List<User> mentions = msg.getMentionedUsers(); // distinct list, in order of appearance
-     *     Bag<User> count = msg.getMentionedUsersBag();
-     *     StringBuilder content = new StringBuilder();
-     *     for (User user : mentions)
-     *     {
-     *         content.append(user.getAsTag())
-     *                .append(": ")
-     *                .append(count.getCount(user))
-     *                .append("\n");
-     *     }
-     *     msg.getChannel().sendMessage(content.toString()).queue();
-     * }
-     * }</pre>
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return {@link org.apache.commons.collections4.Bag Bag} of mentioned users
-     *
-     * @see    #getMentionedUsers()
-     */
-    @Nonnull
-    Bag<User> getMentionedUsersBag();
-
-    /**
-     * A immutable list of all mentioned {@link net.dv8tion.jda.api.entities.TextChannel TextChannels}.
-     * <br>If none were mentioned, this list is empty. Elements are sorted in order of appearance.
-     *
-     * <p><b>This may include TextChannels from other {@link net.dv8tion.jda.api.entities.Guild Guilds}</b>
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return immutable list of mentioned TextChannels
-     */
-    @Nonnull
-    List<TextChannel> getMentionedChannels();
-
-    /**
-     * A {@link org.apache.commons.collections4.Bag Bag} of mentioned channels.
-     * <br>This can be used to retrieve the amount of times a channel was mentioned in this message.
-     *
-     * <h2>Example</h2>
-     * <pre>{@code
-     * public void sendCount(Message msg)
-     * {
-     *     List<TextChannel> mentions = msg.getMentionedTextChannels(); // distinct list, in order of appearance
-     *     Bag<TextChannel> count = msg.getMentionedTextChannelsBag();
-     *     StringBuilder content = new StringBuilder();
-     *     for (TextChannel channel : mentions)
-     *     {
-     *         content.append("#")
-     *                .append(channel.getName())
-     *                .append(": ")
-     *                .append(count.getCount(channel))
-     *                .append("\n");
-     *     }
-     *     msg.getChannel().sendMessage(content.toString()).queue();
-     * }
-     * }</pre>
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return {@link org.apache.commons.collections4.Bag Bag} of mentioned channels
-     *
-     * @see    #getMentionedChannels()
-     */
-    @Nonnull
-    Bag<TextChannel> getMentionedChannelsBag();
-
-    /**
-     * A immutable list of all mentioned {@link net.dv8tion.jda.api.entities.Role Roles}.
-     * <br>If none were mentioned, this list is empty. Elements are sorted in order of appearance. This only
-     * counts direct mentions of the role and not mentions through the everyone tag.
-     *
-     * <p><b>This may include Roles from other {@link net.dv8tion.jda.api.entities.Guild Guilds}</b>
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return immutable list of mentioned Roles
-     */
+    //TODO | Docs
     @Nonnull
-    List<Role> getMentionedRoles();
-
-    /**
-     * A {@link org.apache.commons.collections4.Bag Bag} of mentioned roles.
-     * <br>This can be used to retrieve the amount of times a role was mentioned in this message. This only
-     * counts direct mentions of the role and not mentions through the everyone tag.
-     * If a role is not {@link net.dv8tion.jda.api.entities.Role#isMentionable() mentionable} it will not be included.
-     *
-     * <h2>Example</h2>
-     * <pre>{@code
-     * public void sendCount(Message msg)
-     * {
-     *     List<Role> mentions = msg.getMentionedRoles(); // distinct list, in order of appearance
-     *     Bag<Role> count = msg.getMentionedRolesBag();
-     *     StringBuilder content = new StringBuilder();
-     *     for (Role role : mentions)
-     *     {
-     *         content.append(role.getName())
-     *                .append(": ")
-     *                .append(count.getCount(role))
-     *                .append("\n");
-     *     }
-     *     msg.getChannel().sendMessage(content.toString()).queue();
-     * }
-     * }</pre>
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return {@link org.apache.commons.collections4.Bag Bag} of mentioned roles
-     *
-     * @see    #getMentionedRoles()
-     */
-    @Nonnull
-    Bag<Role> getMentionedRolesBag();
-
-    /**
-     * Creates an immutable list of {@link net.dv8tion.jda.api.entities.Member Members}
-     * representing the users of {@link #getMentionedUsers()} in the specified
-     * {@link net.dv8tion.jda.api.entities.Guild Guild}.
-     * <br>This is only a convenience method and will skip all users that are not in the specified
-     * Guild.
-     *
-     * @param  guild
-     *         Non-null {@link net.dv8tion.jda.api.entities.Guild Guild}
-     *         that will be used to retrieve Members.
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     * @throws java.lang.IllegalArgumentException
-     *         If the specified Guild is {@code null}
-     *
-     * @return Immutable list of mentioned Members
-     *
-     * @since  3.4.0
-     */
-    @Nonnull
-    List<Member> getMentionedMembers(@Nonnull Guild guild);
-
-    /**
-     * Creates an immutable list of {@link net.dv8tion.jda.api.entities.Member Members}
-     * representing the users of {@link #getMentionedUsers()} in the
-     * {@link net.dv8tion.jda.api.entities.Guild Guild} this Message was sent in.
-     * <br>This is only a convenience method and will skip all users that are not in the specified Guild.
-     * <br>It will provide the {@link #getGuild()} output Guild to {@link #getMentionedMembers(Guild)}.
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     * @throws java.lang.IllegalStateException
-     *         If this message was not sent in a {@link net.dv8tion.jda.api.entities.TextChannel TextChannel}
-     *
-     * @return Immutable list of mentioned Members
-     *
-     * @since  3.4.0
-     */
-    @Nonnull
-    List<Member> getMentionedMembers();
-
-    /**
-     * Combines all instances of {@link net.dv8tion.jda.api.entities.IMentionable IMentionable}
-     * filtered by the specified {@link net.dv8tion.jda.api.entities.Message.MentionType MentionType} values.
-     * <br>This does not include {@link #getMentionedMembers()} to avoid duplicates.
-     *
-     * <p>If no MentionType values are given this will fallback to all types.
-     *
-     * @param  types
-     *         Amount of {@link net.dv8tion.jda.api.entities.Message.MentionType MentionTypes}
-     *         to include in the list of mentions
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     * @throws java.lang.IllegalArgumentException
-     *         If provided with {@code null}
-     *
-     * @return Immutable list of filtered {@link net.dv8tion.jda.api.entities.IMentionable IMentionable} instances
-     *
-     * @since  3.4.0
-     */
-    @Nonnull
-    List<IMentionable> getMentions(@Nonnull MentionType... types);
-
-    /**
-     * Checks if given {@link net.dv8tion.jda.api.entities.IMentionable IMentionable}
-     * was mentioned in this message in any way (@User, @everyone, @here, @Role).
-     * <br>If no filtering {@link net.dv8tion.jda.api.entities.Message.MentionType MentionTypes} are
-     * specified this will fallback to all mention types.
-     *
-     * <p>{@link Message.MentionType#HERE MentionType.HERE} and {@link Message.MentionType#EVERYONE MentionType.EVERYONE}
-     * will only be checked, if the given {@link net.dv8tion.jda.api.entities.IMentionable IMentionable} is of type
-     * {@link net.dv8tion.jda.api.entities.User User} or {@link net.dv8tion.jda.api.entities.Member Member}.
-     * <br>Online status of Users/Members is <b>NOT</b> considered when checking {@link Message.MentionType#HERE MentionType.HERE}.
-     *
-     * @param  mentionable
-     *         The mentionable entity to check on.
-     * @param  types
-     *         The types to include when checking whether this type was mentioned.
-     *         This will be used with {@link #getMentions(Message.MentionType...) getMentions(MentionType...)}
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return True, if the given mentionable was mentioned in this message
-     */
-    boolean isMentioned(@Nonnull IMentionable mentionable, @Nonnull MentionType... types);
-
-    /**
-     * Indicates if this Message mentions everyone using @everyone or @here.
-     *
-     * @throws java.lang.UnsupportedOperationException
-     *         If this is a system message
-     *
-     * @return True, if message is mentioning everyone
-     */
-    boolean mentionsEveryone();
+    MessageMentions getMentions();
 
     /**
      * Returns whether or not this Message has been edited before.