Package com.jagrosh.jdautilities.commons.utils

Class FinderUtil

java.lang.Object
com.jagrosh.jdautilities.commons.utils.FinderUtil
public final class FinderUtil extends Object
A series of query based utilities for finding entities, either globally across all accessible Guilds, or locally to a specified Guild.

All methods use a similar priority hierarchy and return an immutable List based on the results.
The hierarchy is as follows:

  • Special Cases: Specifics of these are described per individual method documentation.
    Note that successful results from these are typically a singleton list.
  • Direct ID: Query is a number with 17 or more digits, resembling an Snowflake ID.
  • Exact Match: Query provided is an exact match (case sensitive and complete) to one or more entities.
  • Wrong Case: Query provided is a case-insensitive, but exact, match to the entirety of one or more entities.
  • Starting With: Query provided is an case-insensitive match to the beginning of one or more entities.
  • Contains: Query provided is a case-insensitive match to a part of one or more entities.
All queries return the highest List in this hierarchy that contains one or more entities, and only of these kind of results (IE: the "exact" list will never contain any results from a successful "starting with" match, unless by chance they could technically be the same result).

Shard Manager Usage
Methods that query an instance of JDA always have two implementations:

  • Global: Queries a ShardManager if one is available, or JDA if one is not.
  • Shard: Always queries the provided instance, and never a ShardManager, even if one is available.

Many of these utilities were inspired by and ported to JDA 3.X from Spectra's FinderUtil originally written by jagrosh in 2.X.

Since:
1.3
Author:
Kaidan Gustave

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Pattern
    CHANNEL_MENTION
     
    static final Pattern
    DISCORD_ID
     
    static final Pattern
    EMOTE_MENTION
     
    static final Pattern
    FULL_USER_REF
     
    static final Pattern
    ROLE_MENTION
     
    static final Pattern
    USER_MENTION
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<net.dv8tion.jda.api.entities.User>
    findBannedUsers(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for a banned User.
    static List<net.dv8tion.jda.api.entities.channel.concrete.Category>
    findCategories(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for Categories.
    static List<net.dv8tion.jda.api.entities.channel.concrete.Category>
    findCategories(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for Categories.
    static List<net.dv8tion.jda.api.entities.emoji.Emoji>
    findEmotes(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for Emotes.
    static List<net.dv8tion.jda.api.entities.emoji.Emoji>
    findEmotes(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for Emojis.
    static List<net.dv8tion.jda.api.entities.Member>
    findMembers(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for Members.
    static List<net.dv8tion.jda.api.entities.Role>
    findRoles(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for Roles.
    static List<net.dv8tion.jda.api.entities.channel.concrete.Category>
    findShardCategories(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for Categories.
    static List<net.dv8tion.jda.api.entities.emoji.Emoji>
    findShardEmotes(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for Emotes.
    static List<net.dv8tion.jda.api.entities.channel.concrete.TextChannel>
    findShardTextChannels(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for TextChannels.
    static List<net.dv8tion.jda.api.entities.User>
    findShardUsers(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for Users.
    static List<net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel>
    findShardVoiceChannels(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for VoiceChannels.
    static List<net.dv8tion.jda.api.entities.channel.concrete.TextChannel>
    findTextChannels(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for TextChannels.
    static List<net.dv8tion.jda.api.entities.channel.concrete.TextChannel>
    findTextChannels(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for TextChannels.
    static List<net.dv8tion.jda.api.entities.User>
    findUsers(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for Users.
    static List<net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel>
    findVoiceChannels(String query, net.dv8tion.jda.api.entities.Guild guild)
    Queries a provided Guild for VoiceChannels.
    static List<net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel>
    findVoiceChannels(String query, net.dv8tion.jda.api.JDA jda)
    Queries a provided instance of JDA for VoiceChannels.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DISCORD_ID

      public static final Pattern DISCORD_ID

    • FULL_USER_REF

      public static final Pattern FULL_USER_REF

    • USER_MENTION

      public static final Pattern USER_MENTION

    • CHANNEL_MENTION

      public static final Pattern CHANNEL_MENTION

    • ROLE_MENTION

      public static final Pattern ROLE_MENTION

    • EMOTE_MENTION

      public static final Pattern EMOTE_MENTION

  • Method Details

    • findUsers

      public static List<net.dv8tion.jda.api.entities.User> findUsers(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for Users.

      If a ShardManager is available this will query across that instead of the JDA instance.

      The following special cases are applied in order of listing before the standard search is done:

      • User Mention: Query provided matches an @user mention (more specifically <@userID>).
      • Full User Reference: Query provided matches a full Username#XXXX reference.
        NOTE: this can return a list with more than one entity.
      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of Users found by the query from the provided JDA instance.

    • findShardUsers

      public static List<net.dv8tion.jda.api.entities.User> findShardUsers(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for Users.

      This only queries the instance of JDA, regardless of whether or not a ShardManager is available.

      The following special cases are applied in order of listing before the standard search is done:

      • User Mention: Query provided matches an @user mention (more specifically <@userID>).
      • Full User Reference: Query provided matches a full Username#XXXX reference.
        NOTE: this can return a list with more than one entity.
      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of Users found by the query from the provided JDA instance.

    • findBannedUsers

      public static List<net.dv8tion.jda.api.entities.User> findBannedUsers(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for a banned User.

      The following special cases are applied in order of listing before the standard search is done:

      • User Mention: Query provided matches an @user mention (more specifically <@userID>).
      • Full User Reference: Query provided matches a full Username#XXXX reference.
        NOTE: this can return a list with more than one entity.

      WARNING

      Unlike the other finder methods, this one has two very unique features that set it apart from the rest:

      • 1) In order to get a list of bans that is usable, this method initial retrieves it by usage of Guild#getBans().complete(). Because of this, as would be the same expected effect from the other utility methods, this will block the thread it is called in. The difference, however, comes in that this method may have slight variations in return speed, especially when put under higher usage over a shorter period of time.
      • 2) This method can return null if and only if an Exception is thrown while initially getting banned Users via Guild#getBanList().
      Parameters:
      query - The String query to search by
      guild - The Guild to search for banned Users from
      Returns:
      A possibly-empty List of Users found by the query from the provided JDA instance, or null if an Exception is thrown while initially getting banned Users.
      See Also:
      • Guild#getBanList()

    • findMembers

      public static List<net.dv8tion.jda.api.entities.Member> findMembers(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for Members.

      The following special cases are applied in order of listing before the standard search is done:

      • User Mention: Query provided matches an @user mention (more specifically <@userID> or <@!userID>).
      • Full User Reference: Query provided matches a full Username#XXXX reference.
        NOTE: this can return a list with more than one entity.

      Unlike FinderUtil.findUsers(String, JDA), this method queries based on two different names: user name and effective name (excluding special cases in which it queries solely based on user name).
      Each standard check looks at the user name, then the member name, and if either one's criteria is met the Member is added to the returned list. This is important to note, because the returned list may contain exact matches for User's name as well as exact matches for a Member's effective name, with nothing guaranteeing the returns will be exclusively containing matches for one or the other.
      Information on effective name can be found in Member#getEffectiveName().

      Parameters:
      query - The String query to search by
      guild - The Guild to search from
      Returns:
      A possibly empty List of Members found by the query from the provided Guild.

    • findTextChannels

      public static List<net.dv8tion.jda.api.entities.channel.concrete.TextChannel> findTextChannels(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for TextChannels.

      If a ShardManager is available this will query across that instead of the JDA instance.

      The following special case is applied before the standard search is done:

      • Channel Mention: Query provided matches a #channel mention (more specifically <#channelID>)
      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of TextChannels found by the query from the provided JDA instance.

    • findShardTextChannels

      public static List<net.dv8tion.jda.api.entities.channel.concrete.TextChannel> findShardTextChannels(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for TextChannels.

      This only queries the instance of JDA, regardless of whether or not a ShardManager is available.

      The following special case is applied before the standard search is done:

      • Channel Mention: Query provided matches a #channel mention (more specifically <#channelID>)
      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of TextChannels found by the query from the provided JDA instance.

    • findTextChannels

      public static List<net.dv8tion.jda.api.entities.channel.concrete.TextChannel> findTextChannels(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for TextChannels.

      The following special case is applied before the standard search is done:

      • Channel Mention: Query provided matches a #channel mention (more specifically <#channelID>)
      Parameters:
      query - The String query to search by
      guild - The Guild to search from
      Returns:
      A possibly-empty List of TextChannels found by the query from the provided Guild.

    • findVoiceChannels

      public static List<net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel> findVoiceChannels(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for VoiceChannels.

      If a ShardManager is available this will query across that instead of the JDA instance.

      The standard search does not follow any special cases.

      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of VoiceChannels found by the query from the provided JDA instance.

    • findShardVoiceChannels

      public static List<net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel> findShardVoiceChannels(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for VoiceChannels.

      This only queries the instance of JDA, regardless of whether or not a ShardManager is available.

      The standard search does not follow any special cases.

      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of VoiceChannels found by the query from the provided JDA instance.

    • findVoiceChannels

      public static List<net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel> findVoiceChannels(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for VoiceChannels.

      The standard search does not follow any special cases.

      Parameters:
      query - The String query to search by
      guild - The Guild to search from
      Returns:
      A possibly-empty List of VoiceChannels found by the query from the provided Guild.

    • findCategories

      public static List<net.dv8tion.jda.api.entities.channel.concrete.Category> findCategories(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for Categories.

      If a ShardManager is available this will query across that instead of the JDA instance.

      The standard search does not follow any special cases.

      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of Categories found by the query from the provided JDA instance.

    • findShardCategories

      public static List<net.dv8tion.jda.api.entities.channel.concrete.Category> findShardCategories(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for Categories.

      This only queries the instance of JDA, regardless of whether or not a ShardManager is available.

      The standard search does not follow any special cases.

      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of Categories found by the query from the provided JDA instance.

    • findCategories

      public static List<net.dv8tion.jda.api.entities.channel.concrete.Category> findCategories(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for Categories.

      The standard search does not follow any special cases.

      Parameters:
      query - The String query to search by
      guild - The Guild to search from
      Returns:
      A possibly-empty List of Categories found by the query from the provided Guild.

    • findRoles

      public static List<net.dv8tion.jda.api.entities.Role> findRoles(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for Roles.

      The following special case is applied before the standard search is done:

      • Role Mention: Query provided matches a @role mention (more specifically <@&roleID>)
      Parameters:
      query - The String query to search by
      guild - The Guild to search from
      Returns:
      A possibly-empty List of Roles found by the query from the provided Guild.

    • findEmotes

      public static List<net.dv8tion.jda.api.entities.emoji.Emoji> findEmotes(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for Emojis.

      If a ShardManager is available this will query across that instead of the JDA instance.

      The following special case is applied before the standard search is done:

      • Emote Mention: Query provided matches a :emote: mention (more specifically <:emoteName:emoteID>).
        Note: This only returns here if the emote is valid. Validity being the ID retrieves a non-null Emote and that the name of the Emote is equal to the name found in the query.
      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of Emotes found by the query from the provided JDA instance.

    • findShardEmotes

      public static List<net.dv8tion.jda.api.entities.emoji.Emoji> findShardEmotes(String query, net.dv8tion.jda.api.JDA jda)
      Queries a provided instance of JDA for Emotes.

      This only queries the instance of JDA, regardless of whether or not a ShardManager is available.

      The following special case is applied before the standard search is done:

      • Emote Mention: Query provided matches a :emote: mention (more specifically <:emoteName:emoteID>).
        Note: This only returns here if the emote is valid. Validity being the ID retrieves a non-null Emote and that the name of the Emote is equal to the name found in the query.
      Parameters:
      query - The String query to search by
      jda - The instance of JDA to search from
      Returns:
      A possibly-empty List of Emotes found by the query from the provided JDA instance.

    • findEmotes

      public static List<net.dv8tion.jda.api.entities.emoji.Emoji> findEmotes(String query, net.dv8tion.jda.api.entities.Guild guild)
      Queries a provided Guild for Emotes.

      The following special case is applied before the standard search is done:

      • Emote Mention: Query provided matches a :emote: mention (more specifically <:emoteName:emoteID>).
        Note: This only returns here if the emote is valid. Validity being the ID retrieves a non-null Emote and that the name of the Emote is equal to the name found in the query.
      Parameters:
      query - The String query to search by
      guild - The Guild to search from
      Returns:
      A possibly-empty List of Emotes found by the query from the provided Guild.