com.jagrosh.jdautilities.commons.utils

Class FinderUtil

java.lang.Object

com.jagrosh.jdautilities.commons.utils.FinderUtil

public final class FinderUtil
extends java.lang.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 and Description
static java.util.regex.Pattern	CHANNEL_MENTION
static java.util.regex.Pattern	DISCORD_ID
static java.util.regex.Pattern	EMOTE_MENTION
static java.util.regex.Pattern	FULL_USER_REF
static java.util.regex.Pattern	ROLE_MENTION
static java.util.regex.Pattern	USER_MENTION

Method Summary

Modifier and Type	Method and Description
static java.util.List<net.dv8tion.jda.core.entities.User>	findBannedUsers(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for a banned User.
static java.util.List<net.dv8tion.jda.core.entities.Category>	findCategories(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for Categories.
static java.util.List<net.dv8tion.jda.core.entities.Category>	findCategories(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for Categories.
static java.util.List<net.dv8tion.jda.core.entities.Emote>	findEmotes(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for Emotes.
static java.util.List<net.dv8tion.jda.core.entities.Emote>	findEmotes(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for Emotes.
static java.util.List<net.dv8tion.jda.core.entities.Member>	findMembers(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for Members.
static java.util.List<net.dv8tion.jda.core.entities.Role>	findRoles(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for Roles.
static java.util.List<net.dv8tion.jda.core.entities.Category>	findShardCategories(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for Categories.
static java.util.List<net.dv8tion.jda.core.entities.Emote>	findShardEmotes(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for Emotes.
static java.util.List<net.dv8tion.jda.core.entities.TextChannel>	findShardTextChannels(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for TextChannels.
static java.util.List<net.dv8tion.jda.core.entities.User>	findShardUsers(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for Users.
static java.util.List<net.dv8tion.jda.core.entities.VoiceChannel>	findShardVoiceChannels(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for VoiceChannels.
static java.util.List<net.dv8tion.jda.core.entities.TextChannel>	findTextChannels(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for TextChannels.
static java.util.List<net.dv8tion.jda.core.entities.TextChannel>	findTextChannels(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for TextChannels.
static java.util.List<net.dv8tion.jda.core.entities.User>	findUsers(java.lang.String query, net.dv8tion.jda.core.JDA jda) Queries a provided instance of JDA for Users.
static java.util.List<net.dv8tion.jda.core.entities.VoiceChannel>	findVoiceChannels(java.lang.String query, net.dv8tion.jda.core.entities.Guild guild) Queries a provided Guild for VoiceChannels.
static java.util.List<net.dv8tion.jda.core.entities.VoiceChannel>	findVoiceChannels(java.lang.String query, net.dv8tion.jda.core.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 Detail

DISCORD_ID

public static final java.util.regex.Pattern DISCORD_ID

FULL_USER_REF

public static final java.util.regex.Pattern FULL_USER_REF

USER_MENTION

public static final java.util.regex.Pattern USER_MENTION

CHANNEL_MENTION

public static final java.util.regex.Pattern CHANNEL_MENTION

ROLE_MENTION

public static final java.util.regex.Pattern ROLE_MENTION

EMOTE_MENTION

public static final java.util.regex.Pattern EMOTE_MENTION

Method Detail

findUsers

public static java.util.List<net.dv8tion.jda.core.entities.User> findUsers(java.lang.String query,
                                                                           net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.User> findShardUsers(java.lang.String query,
                                                                                net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.User> findBannedUsers(java.lang.String query,
                                                                                 net.dv8tion.jda.core.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#getBans().

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#getBans()

findMembers

public static java.util.List<net.dv8tion.jda.core.entities.Member> findMembers(java.lang.String query,
                                                                               net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.TextChannel> findTextChannels(java.lang.String query,
                                                                                         net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.TextChannel> findShardTextChannels(java.lang.String query,
                                                                                              net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.TextChannel> findTextChannels(java.lang.String query,
                                                                                         net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.VoiceChannel> findVoiceChannels(java.lang.String query,
                                                                                           net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.VoiceChannel> findShardVoiceChannels(java.lang.String query,
                                                                                                net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.VoiceChannel> findVoiceChannels(java.lang.String query,
                                                                                           net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.Category> findCategories(java.lang.String query,
                                                                                    net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.Category> findShardCategories(java.lang.String query,
                                                                                         net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.Category> findCategories(java.lang.String query,
                                                                                    net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.Role> findRoles(java.lang.String query,
                                                                           net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.Emote> findEmotes(java.lang.String query,
                                                                             net.dv8tion.jda.core.JDA jda)

Queries a provided instance of JDA for Emotes.

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 java.util.List<net.dv8tion.jda.core.entities.Emote> findShardEmotes(java.lang.String query,
                                                                                  net.dv8tion.jda.core.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 java.util.List<net.dv8tion.jda.core.entities.Emote> findEmotes(java.lang.String query,
                                                                             net.dv8tion.jda.core.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.