net.dv8tion.jda.api.entities.Mentions Maven / Gradle / Ivy
Show all versions of JDA Show documentation
/*
* 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.api.entities;
import net.dv8tion.jda.api.JDA;
import net.dv8tion.jda.api.entities.channel.concrete.PrivateChannel;
import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel;
import net.dv8tion.jda.api.entities.emoji.CustomEmoji;
import net.dv8tion.jda.api.interactions.commands.SlashCommandReference;
import org.apache.commons.collections4.Bag;
import org.jetbrains.annotations.Unmodifiable;
import javax.annotation.Nonnull;
import java.util.List;
/**
* Interface to access the mentions of various entities.
*/
public interface Mentions
{
/**
* The corresponding JDA instance
*
* @return The jda instance
*/
@Nonnull
JDA getJDA();
/**
* Indicates if everyone is mentioned, by either using {@code @everyone} or {@code @here}.
*
* This is different from checking if {@code @everyone} is in the string, since mentions require additional flags to trigger.
*
* @return True, if everyone is mentioned
*/
boolean mentionsEveryone();
/**
* An immutable list of all mentioned {@link net.dv8tion.jda.api.entities.User Users}.
*
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 everyone mentions.
*
*
This might also contain users which are not present in {@link #getMembers()}.
*
* @return Immutable list of mentioned users
*/
@Nonnull
@Unmodifiable
List getUsers();
/**
* A {@link org.apache.commons.collections4.Bag Bag} of mentioned {@link net.dv8tion.jda.api.entities.User Users}.
*
This can be used to retrieve the amount of times a user was mentioned. This only
* counts direct mentions of the user and not mentions through roles or everyone mentions.
* The count may be {@code 1}, if the user was mentioned through a message reply.
*
* This might also contain users which are not present in {@link #getMembers()}.
*
*
Example
*
{@code
* void sendCount(Message msg)
* {
* List mentions = msg.getMentions().getUsers(); // distinct list, in order of appearance
* Bag count = msg.getMentions().getUsersBag();
* 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();
* }
* }
*
* @return {@link org.apache.commons.collections4.Bag Bag} of mentioned users
*
* @see #getUsers()
*/
@Nonnull
Bag getUsersBag();
/**
* An immutable list of all mentioned {@link net.dv8tion.jda.api.entities.channel.middleman.GuildChannel GuildChannels}.
*
If none were mentioned, this list is empty. Elements are sorted in order of appearance.
*
* This may include GuildChannels from other {@link net.dv8tion.jda.api.entities.Guild Guilds}
*
* @return Immutable list of mentioned GuildChannels
*/
@Nonnull
@Unmodifiable
List getChannels();
/**
* A {@link org.apache.commons.collections4.Bag Bag} of mentioned channels.
*
This can be used to retrieve the amount of times a channel was mentioned.
*
* This may include GuildChannels from other {@link net.dv8tion.jda.api.entities.Guild Guilds}
*
*
Example
*
{@code
* void sendCount(Message msg)
* {
* Bag mentions = msg.getMentions().getChannelsBag();
* StringBuilder content = new StringBuilder();
* for (GuildChannel channel : mentions.uniqueSet())
* {
* content.append("#")
* .append(channel.getName())
* .append(": ")
* .append(mentions.getCount(channel))
* .append("\n");
* }
* msg.getChannel().sendMessage(content.toString()).queue();
* }
* }
*
* @return {@link org.apache.commons.collections4.Bag Bag} of mentioned channels
*
* @see #getChannels()
*/
@Nonnull
Bag getChannelsBag();
/**
* An immutable list of all mentioned {@link net.dv8tion.jda.api.entities.channel.middleman.GuildChannel GuildChannels} of type {@code clazz}.
*
If none were mentioned, this list is empty. Elements are sorted in order of appearance.
*
* This may include GuildChannels from other {@link net.dv8tion.jda.api.entities.Guild Guilds}
*
*
Example
*
{@code
* List getCoolMessageChannels(Message msg)
* {
* List channels = msg.getMentions().getChannels(GuildMessageChannel.class);
* return channels.stream()
* .filter(channel -> channel.getName().contains("cool"))
* .collect(Collectors.toList());
* }
* }
*
* @param clazz
* The {@link GuildChannel} sub-class {@link Class class object} of the type of channel desired
*
* @throws java.lang.IllegalArgumentException
* If {@code clazz} is {@code null}
*
* @return Immutable list of mentioned GuildChannels that are of type {@code clazz}.
*/
@Nonnull
@Unmodifiable
List getChannels(@Nonnull Class clazz);
/**
* A {@link org.apache.commons.collections4.Bag Bag} of mentioned channels of type {@code clazz}.
*
This can be used to retrieve the amount of times a channel was mentioned.
*
* This may include GuildChannels from other {@link net.dv8tion.jda.api.entities.Guild Guilds}
*
*
Example
*
{@code
* void sendCount(Message msg)
* {
* Bag mentions = msg.getMentions().getChannelsBag(GuildMessageChannel.class);
* StringBuilder content = new StringBuilder();
* for (GuildMessageChannel channel : mentions.uniqueSet())
* {
* content.append("#")
* .append(channel.getName())
* .append(": ")
* .append(mentions.getCount(channel))
* .append("\n");
* }
* msg.getChannel().sendMessage(content.toString()).queue();
* }
* }
*
* @param clazz
* The {@link GuildChannel} sub-class {@link Class class object} of the type of channel desired
*
* @throws java.lang.IllegalArgumentException
* If {@code clazz} is {@code null}
*
* @return {@link org.apache.commons.collections4.Bag Bag} of mentioned channels of type {@code clazz}
*
* @see #getChannels(Class)
*/
@Nonnull
Bag getChannelsBag(@Nonnull Class clazz);
/**
* An immutable list of all mentioned {@link net.dv8tion.jda.api.entities.Role Roles}.
*
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 everyone mentions.
*
* This may include Roles from other {@link net.dv8tion.jda.api.entities.Guild Guilds}
*
* @return immutable list of mentioned Roles
*/
@Nonnull
@Unmodifiable
List getRoles();
/**
* A {@link org.apache.commons.collections4.Bag Bag} of mentioned roles.
*
This can be used to retrieve the amount of times a role was mentioned. This only
* counts direct mentions of the role and not mentions through everyone mentions.
*
* This may include Roles from other {@link net.dv8tion.jda.api.entities.Guild Guilds}
*
*
Example
*
{@code
* void sendCount(Message msg)
* {
* List mentions = msg.getMentions().getRoles(); // distinct list, in order of appearance
* Bag count = msg.getMentions().getRolesBag();
* 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();
* }
* }
*
* @return {@link org.apache.commons.collections4.Bag Bag} of mentioned roles
*
* @see #getRoles()
*/
@Nonnull
Bag getRolesBag();
/**
* All {@link net.dv8tion.jda.api.entities.emoji.CustomEmoji CustomEmojis} used.
*
This only includes Custom Emojis, not unicode Emojis. These are not the same
* as the unicode emojis that Discord also supports. Elements are sorted in order of appearance.
*
* Unicode emojis are not included as {@link net.dv8tion.jda.api.entities.emoji.CustomEmoji CustomEmojis}!
*
* @return An immutable list of the Custom Emojis used (example match {@literal <:jda:230988580904763393>})
*/
@Nonnull
@Unmodifiable
List getCustomEmojis();
/**
* A {@link org.apache.commons.collections4.Bag Bag} of custom emojis used.
*
This can be used to retrieve the amount of times an emoji was used.
*
* Example
*
{@code
* void sendCount(Message msg)
* {
* List emojis = msg.getMentions().getCustomEmojis(); // distinct list, in order of appearance
* Bag count = msg.getMentions().getCustomEmojisBag();
* StringBuilder content = new StringBuilder();
* for (CustomEmoji emoji : emojis)
* {
* content.append(emojis.getName())
* .append(": ")
* .append(count.getCount(emoji))
* .append("\n");
* }
* msg.getChannel().sendMessage(content.toString()).queue();
* }
* }
*
* @return {@link org.apache.commons.collections4.Bag Bag} of used custom emojis
*
* @see #getCustomEmojis()
*/
@Nonnull
Bag getCustomEmojisBag();
/**
* An immutable list of all mentioned {@link net.dv8tion.jda.api.entities.Member Members}.
*
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 everyone mentions.
*
* This is always empty in {@link PrivateChannel PrivateChannels}.
*
* @return Immutable list of mentioned Members, or an empty list
*/
@Nonnull
List getMembers();
/**
* A {@link org.apache.commons.collections4.Bag Bag} of mentioned {@link net.dv8tion.jda.api.entities.Member Members}.
*
This can be used to retrieve the amount of times a user was mentioned. This only
* counts direct mentions of the member and not mentions through roles or everyone mentions.
* The count may be {@code 1}, if the user was mentioned through a message reply.
*
* Example
*
{@code
* void sendCount(Message msg)
* {
* List mentions = msg.getMentions().getMembers(); // distinct list, in order of appearance
* Bag count = msg.getMentions().getMembersBag();
* StringBuilder content = new StringBuilder();
* for (Member user : mentions)
* {
* content.append(member.getUser().getAsTag())
* .append(": ")
* .append(count.getCount(member))
* .append("\n");
* }
* msg.getChannel().sendMessage(content.toString()).queue();
* }
* }
*
* @return {@link org.apache.commons.collections4.Bag Bag} of mentioned members
*
* @see #getMembers()
*/
@Nonnull
Bag getMembersBag();
/**
* An immutable list of all mentioned {@link SlashCommandReference slash commands}.
*
If none were mentioned, this list is empty. Elements are sorted in order of appearance.
*
* Be aware these mentions could be mentioning a non-existent command
*
* @return Immutable list of mentioned slash commands, or an empty list
*/
@Nonnull
@Unmodifiable
List getSlashCommands();
/**
* A {@link org.apache.commons.collections4.Bag Bag} of mentioned {@link SlashCommandReference slash commands}.
*
This can be used to retrieve the amount of times a slash commands was mentioned.
*
* Be aware these mentions could be mentioning a non-existent command
*
*
Example
*
{@code
* void sendCount(Message msg)
* {
* List mentions = msg.getMentions().getSlashCommands(); // distinct list, in order of appearance
* Bag count = msg.getMentions().getSlashCommandsBag();
* StringBuilder content = new StringBuilder();
* for (SlashCommandReference commandRef : mentions)
* {
* content.append(commandRef.getAsMention())
* .append(": ")
* .append(count.getCount(commandRef))
* .append("\n");
* }
* msg.getChannel().sendMessage(content.toString()).queue();
* }
* }
*
* @return {@link org.apache.commons.collections4.Bag Bag} of mentioned slash commands
*
* @see #getSlashCommands()
*/
@Nonnull
Bag getSlashCommandsBag();
/**
* 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.
*
If a {@link Member} is available, it will be taken in favor of a {@link User}.
* This only provides either the Member or the User instance, rather than both.
*
* If no MentionType values are given, all types are used.
*
* @param types
* {@link net.dv8tion.jda.api.entities.Message.MentionType MentionTypes} to include
*
* @throws java.lang.IllegalArgumentException
* If provided with {@code null}
*
* @return Immutable list of filtered {@link net.dv8tion.jda.api.entities.IMentionable IMentionable} instances
*/
@Nonnull
@Unmodifiable
List getMentions(@Nonnull Message.MentionType... types);
/**
* Checks if given {@link net.dv8tion.jda.api.entities.IMentionable IMentionable}
* was mentioned in any way (@User, @everyone, @here, @Role).
*
If no filtering {@link net.dv8tion.jda.api.entities.Message.MentionType MentionTypes} are
* specified, all types are used.
*
* {@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}.
*
Online status of Users/Members is NOT 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...)}
*
* @return True, if the given mentionable was mentioned in this message
*/
boolean isMentioned(@Nonnull IMentionable mentionable, @Nonnull Message.MentionType... types);
}