Interface ShardManager
-
- All Superinterfaces:
IGuildChannelContainer
- All Known Implementing Classes:
DefaultShardManager
public interface ShardManager extends IGuildChannelContainer
This class acts as a manager for multiple shards. It contains several methods to make your life with sharding easier.
Custom implementations may not support all methods and throwUnsupportedOperationExceptionsinstead.- Since:
- 3.4
- Author:
- Aljoscha Grebe
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default voidaddEventListener(Object... listeners)Adds all provided listeners to the event-listeners that will be used to handle events.default voidaddEventListeners(IntFunction<Object> eventListenerProvider)Adds listeners provided by the listener provider to each shard to the event-listeners that will be used to handle events.default doublegetAverageGatewayPing()The average time in milliseconds between all shards that discord took to respond to our last heartbeat.default SnowflakeCacheView<Category>getCategoryCache()SnowflakeCacheViewof all cachedCategoriesvisible to this ShardManager instance.default <T extends Channel>
TgetChannelById(Class<T> type, long id)Get a channel of the specified type by id.default EmotegetEmoteById(long id)Retrieves an emote matching the specifiedidif one is available in our cache.default EmotegetEmoteById(String id)Retrieves an emote matching the specifiedidif one is available in our cache.default SnowflakeCacheView<Emote>getEmoteCache()UnifiedSnowflakeCacheViewof all cachedEmotesvisible to this ShardManager instance.default List<Emote>getEmotes()A collection of all known emotes (managed/restricted included).default List<Emote>getEmotesByName(String name, boolean ignoreCase)An unmodifiable list of allEmotesthat have the same name as the one provided.default EnumSet<GatewayIntent>getGatewayIntents()TheGatewayIntentsfor the JDA sessions of this shard manager.default GuildgetGuildById(long id)This returns theGuildwhich has the same id as the one provided.default GuildgetGuildById(String id)This returns theGuildwhich has the same id as the one provided.default SnowflakeCacheView<Guild>getGuildCache()SnowflakeCacheViewof all cachedGuildsvisible to this ShardManager instance.default GuildChannelgetGuildChannelById(long id)GetGuildChannelfor the provided ID.default GuildChannelgetGuildChannelById(ChannelType type, long id)GetGuildChannelfor the provided ID.default List<Guild>getGuilds()An unmodifiable List of allGuildsthat the logged account is connected to.default List<Guild>getGuildsByName(String name, boolean ignoreCase)An unmodifiable list of allGuildsthat have the same name as the one provided.default List<Guild>getMutualGuilds(Collection<User> users)Gets allGuildsthat contain all given users as their members.default List<Guild>getMutualGuilds(User... users)Gets allGuildsthat contain all given users as their members.default SnowflakeCacheView<NewsChannel>getNewsChannelCache()SortedSnowflakeCacheViewofNewsChannel.default PrivateChannelgetPrivateChannelById(long id)This returns thePrivateChannelwhich has the same id as the one provided.default PrivateChannelgetPrivateChannelById(String id)This returns thePrivateChannelwhich has the same id as the one provided.default SnowflakeCacheView<PrivateChannel>getPrivateChannelCache()SnowflakeCacheViewof all cachedPrivateChannelsvisible to this ShardManager instance.default List<PrivateChannel>getPrivateChannels()An unmodifiable list of all knownPrivateChannels.default RolegetRoleById(long id)Retrieves theRoleassociated to the provided id.default RolegetRoleById(String id)Retrieves theRoleassociated to the provided id.default SnowflakeCacheView<Role>getRoleCache()UnifiedSnowflakeCacheViewof all cachedRolesvisible to this ShardManager instance.default List<Role>getRoles()AllRolesthis ShardManager instance can see.default List<Role>getRolesByName(String name, boolean ignoreCase)Retrieves allRolesvisible to this ShardManager instance.default JDAgetShardById(int id)This returns theJDAinstance which has the same id as the one provided.default JDAgetShardById(String id)This returns theJDAinstance which has the same id as the one provided.ShardCacheViewgetShardCache()UnifiedShardCacheViewof all cachedJDAbound to this ShardManager instance.default List<JDA>getShards()Gets allJDAinstances bound to this ShardManager.intgetShardsQueued()Returns the amount of shards queued for (re)connecting.default intgetShardsRunning()Returns the amount of running shards.default intgetShardsTotal()Returns the amount of shards managed by thisShardManager.default SnowflakeCacheView<StageChannel>getStageChannelCache()SortedSnowflakeCacheViewofStageChannel.default JDA.StatusgetStatus(int shardId)This returns theJDA.Statusof the shard which has the same id as the one provided.default Map<JDA,JDA.Status>getStatuses()Gets the currentStatusof all shards.default SnowflakeCacheView<TextChannel>getTextChannelCache()SortedSnowflakeCacheViewofTextChannel.default SnowflakeCacheView<ThreadChannel>getThreadChannelCache()default UsergetUserById(long id)This returns theUserwhich has the same id as the one provided.default UsergetUserById(String id)This returns theUserwhich has the same id as the one provided.default UsergetUserByTag(String tag)Searches for the first user that has the matching Discord Tag.default UsergetUserByTag(String username, String discriminator)Searches for the first user that has the matching Discord Tag.default SnowflakeCacheView<User>getUserCache()SnowflakeCacheViewof all cachedUsersvisible to this ShardManager instance.default List<User>getUsers()default SnowflakeCacheView<VoiceChannel>getVoiceChannelCache()SortedSnowflakeCacheViewofVoiceChannel.voidlogin()Initializes and starts all shards.default voidremoveEventListener(Object... listeners)Removes all provided listeners from the event-listeners and no longer uses them to handle events.default voidremoveEventListenerProvider(IntFunction<Object> eventListenerProvider)Remove a listener provider.default voidremoveEventListeners(IntFunction<Collection<Object>> eventListenerProvider)Remove listeners from shards by their id.voidrestart()Restarts all shards, shutting old ones down first.voidrestart(int id)Restarts the shards with the given id only.default RestAction<ApplicationInfo>retrieveApplicationInfo()Used to access application details of this bot.default RestAction<User>retrieveUserById(long id)Attempts to retrieve aUserobject based on the provided id.default RestAction<User>retrieveUserById(String id)Attempts to retrieve aUserobject based on the provided id.default voidsetActivity(Activity activity)Sets theActivityfor all shards.default voidsetActivityProvider(IntFunction<? extends Activity> activityProvider)Sets provider that provider theActivityfor all shards.default voidsetIdle(boolean idle)Sets whether all instances should be marked as afk or notdefault voidsetIdleProvider(IntFunction<Boolean> idleProvider)Sets the provider that decides for all shards whether they should be marked as afk or not.default voidsetPresence(OnlineStatus status, Activity activity)Sets theOnlineStatusandActivityfor all shards.default voidsetPresenceProvider(IntFunction<OnlineStatus> statusProvider, IntFunction<? extends Activity> activityProvider)Sets the provider that provides theOnlineStatusandActivityfor all shards.default voidsetStatus(OnlineStatus status)Sets theOnlineStatusfor all shards.default voidsetStatusProvider(IntFunction<OnlineStatus> statusProvider)Sets the provider that provides theOnlineStatusfor all shards.voidshutdown()Shuts down all JDA shards, closing all their connections.voidshutdown(int shardId)Shuts down the shard with the given id only.voidstart(int shardId)Adds a new shard with the given id to this ShardManager and starts it.-
Methods inherited from interface net.dv8tion.jda.api.entities.channel.IGuildChannelContainer
getCategories, getCategoriesByName, getCategoryById, getCategoryById, getChannelById, getGuildChannelById, getGuildChannelById, getNewsChannelById, getNewsChannelById, getNewsChannels, getNewsChannelsByName, getStageChannelById, getStageChannelById, getStageChannels, getStageChannelsByName, getTextChannelById, getTextChannelById, getTextChannels, getTextChannelsByName, getThreadChannelById, getThreadChannelById, getThreadChannels, getThreadChannelsByName, getVoiceChannelById, getVoiceChannelById, getVoiceChannels, getVoiceChannelsByName
-
-
-
-
Method Detail
-
addEventListener
default void addEventListener(@Nonnull Object... listeners)
Adds all provided listeners to the event-listeners that will be used to handle events.Note: when using the
InterfacedEventListener(default), the given listener must be an instance ofEventListener!- Parameters:
listeners- The listener(s) which will react to events.- Throws:
IllegalArgumentException- If either listeners or one of it's objects isnull.
-
removeEventListener
default void removeEventListener(@Nonnull Object... listeners)
Removes all provided listeners from the event-listeners and no longer uses them to handle events.- Parameters:
listeners- The listener(s) to be removed.- Throws:
IllegalArgumentException- If either listeners or one of it's objects isnull.
-
addEventListeners
default void addEventListeners(@Nonnull IntFunction<Object> eventListenerProvider)
Adds listeners provided by the listener provider to each shard to the event-listeners that will be used to handle events. The listener provider gets a shard id applied and is expected to return a listener.Note: when using the
InterfacedEventListener(default), the given listener must be an instance ofEventListener!- Parameters:
eventListenerProvider- The provider of listener(s) which will react to events.- Throws:
IllegalArgumentException- If the provided listener provider or any of the listeners or provides arenull.
-
removeEventListeners
default void removeEventListeners(@Nonnull IntFunction<Collection<Object>> eventListenerProvider)
Remove listeners from shards by their id. The provider takes shard ids, and returns a collection of listeners that shall be removed from the respective shards.- Parameters:
eventListenerProvider- Gets shard ids applied and is expected to return a collection of listeners that shall be removed from the respective shards- Throws:
IllegalArgumentException- If the provided event listeners provider isnull.
-
removeEventListenerProvider
default void removeEventListenerProvider(@Nonnull IntFunction<Object> eventListenerProvider)
Remove a listener provider. This will stop further created / restarted shards from getting a listener added by that provider. Default is a no-op for backwards compatibility, see implementations likeDefaultShardManager.removeEventListenerProvider(IntFunction)for actual code- Parameters:
eventListenerProvider- The provider of listeners that shall be removed.- Throws:
IllegalArgumentException- If the provided listener provider isnull.
-
getShardsQueued
int getShardsQueued()
Returns the amount of shards queued for (re)connecting.- Returns:
- The amount of shards queued for (re)connecting.
-
getShardsRunning
default int getShardsRunning()
Returns the amount of running shards.- Returns:
- The amount of running shards.
-
getShardsTotal
default int getShardsTotal()
Returns the amount of shards managed by thisShardManager. This includes shards currently queued for a restart.- Returns:
- The managed amount of shards.
-
getGatewayIntents
@Nonnull default EnumSet<GatewayIntent> getGatewayIntents()
TheGatewayIntentsfor the JDA sessions of this shard manager.- Returns:
EnumSetof active gateway intents
-
retrieveApplicationInfo
@Nonnull default RestAction<ApplicationInfo> retrieveApplicationInfo()
Used to access application details of this bot.
Since this is the same for every shard it picksJDA.retrieveApplicationInfo()from any shard.- Returns:
- The Application registry for this bot.
- Throws:
IllegalStateException- If there is no running shard
-
getAverageGatewayPing
default double getAverageGatewayPing()
The average time in milliseconds between all shards that discord took to respond to our last heartbeat. This roughly represents the WebSocket ping of this session. If there are no shards running, this will return-1.RestActionrequest times do not correlate to this value!- Returns:
- The average time in milliseconds between heartbeat and the heartbeat ack response
-
getCategoryCache
@Nonnull default SnowflakeCacheView<Category> getCategoryCache()
SnowflakeCacheViewof all cachedCategoriesvisible to this ShardManager instance.- Specified by:
getCategoryCachein interfaceIGuildChannelContainer- Returns:
SnowflakeCacheView
-
getEmoteById
@Nullable default Emote getEmoteById(long id)
Retrieves an emote matching the specifiedidif one is available in our cache.Unicode emojis are not included as
Emote!
-
getEmoteById
@Nullable default Emote getEmoteById(@Nonnull String id)
Retrieves an emote matching the specifiedidif one is available in our cache.Unicode emojis are not included as
Emote!- Parameters:
id- The id of the requestedEmote.- Returns:
- An
Emoterepresented by this id or null if none is found in our cache. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getEmoteCache
@Nonnull default SnowflakeCacheView<Emote> getEmoteCache()
UnifiedSnowflakeCacheViewof all cachedEmotesvisible to this ShardManager instance.- Returns:
- Unified
SnowflakeCacheView
-
getEmotes
@Nonnull default List<Emote> getEmotes()
A collection of all known emotes (managed/restricted included).Hint: To check whether you can use an
Emotein a specific context you can useEmote.canInteract(net.dv8tion.jda.api.entities.Member)orEmote.canInteract(net.dv8tion.jda.api.entities.User, net.dv8tion.jda.api.entities.MessageChannel)Unicode emojis are not included as
Emote!This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use
getEmoteCache()and use its more efficient versions of handling these values.- Returns:
- An immutable list of Emotes (which may or may not be available to usage).
-
getEmotesByName
@Nonnull default List<Emote> getEmotesByName(@Nonnull String name, boolean ignoreCase)
An unmodifiable list of allEmotesthat have the same name as the one provided.
If there are noEmoteswith the provided name, this will return an empty list.Unicode emojis are not included as
Emote!- Parameters:
name- The name of the requestedEmotes. Without colons.ignoreCase- Whether to ignore case or not when comparing the provided name to eachEmote.getName().- Returns:
- Possibly-empty list of all the
Emotesthat all have the same name as the provided name.
-
getGuildById
@Nullable default Guild getGuildById(long id)
This returns theGuildwhich has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, this will returnnull.
-
getGuildById
@Nullable default Guild getGuildById(@Nonnull String id)
This returns theGuildwhich has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, this will returnnull.
-
getGuildsByName
@Nonnull default List<Guild> getGuildsByName(@Nonnull String name, boolean ignoreCase)
An unmodifiable list of allGuildsthat have the same name as the one provided.
If there are noGuildswith the provided name, this will return an empty list.- Parameters:
name- The name of the requestedGuilds.ignoreCase- Whether to ignore case or not when comparing the provided name to eachGuild.getName().- Returns:
- Possibly-empty list of all the
Guildsthat all have the same name as the provided name.
-
getGuildCache
@Nonnull default SnowflakeCacheView<Guild> getGuildCache()
SnowflakeCacheViewof all cachedGuildsvisible to this ShardManager instance.- Returns:
SnowflakeCacheView
-
getGuilds
@Nonnull default List<Guild> getGuilds()
An unmodifiable List of allGuildsthat the logged account is connected to.
If this account is not connected to anyGuilds, this will return an empty list.This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use
getGuildCache()and use its more efficient versions of handling these values.- Returns:
- Possibly-empty list of all the
Guildsthat this account is connected to.
-
getMutualGuilds
@Nonnull default List<Guild> getMutualGuilds(@Nonnull Collection<User> users)
Gets allGuildsthat contain all given users as their members.
-
getMutualGuilds
@Nonnull default List<Guild> getMutualGuilds(@Nonnull User... users)
Gets allGuildsthat contain all given users as their members.
-
retrieveUserById
@Nonnull @CheckReturnValue default RestAction<User> retrieveUserById(@Nonnull String id)
Attempts to retrieve aUserobject based on the provided id.
This first callsgetUserById(long), and if the return isnullthen a request is made to the Discord servers.The returned
RestActioncan encounter the following Discord errors:ErrorResponse.UNKNOWN_USER
Occurs when the provided id does not refer to aUserknown by Discord. Typically occurs when developers provide an incomplete id (cut short).
- Parameters:
id- The id of the requestedUser.- Returns:
RestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
IllegalArgumentException- If the provided id String is not a valid snowflake.IllegalStateException- If there isn't any active shards.
-
retrieveUserById
@Nonnull @CheckReturnValue default RestAction<User> retrieveUserById(long id)
Attempts to retrieve aUserobject based on the provided id.
This first callsgetUserById(long), and if the return isnullthen a request is made to the Discord servers.The returned
RestActioncan encounter the following Discord errors:ErrorResponse.UNKNOWN_USER
Occurs when the provided id does not refer to aUserknown by Discord. Typically occurs when developers provide an incomplete id (cut short).
- Parameters:
id- The id of the requestedUser.- Returns:
RestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
IllegalStateException- If there isn't any active shards.
-
getUserByTag
@Nullable default User getUserByTag(@Nonnull String tag)
Searches for the first user that has the matching Discord Tag.
Format has to be in the formUsername#Discriminatorwhere the username must be between 2 and 32 characters (inclusive) matching the exact casing and the discriminator must be exactly 4 digits.This will only check cached users!
This only checks users that are known to the currently logged in account (shards). If a user exists with the tag that is not available in the
User-Cacheit will not be detected.
Currently Discord does not offer a way to retrieve a user by their discord tag.- Parameters:
tag- The Discord Tag in the formatUsername#Discriminator- Returns:
- The
Userfor the discord tag or null if no user has the provided tag - Throws:
IllegalArgumentException- If the provided tag is null or not in the described format
-
getUserByTag
@Nullable default User getUserByTag(@Nonnull String username, @Nonnull String discriminator)
Searches for the first user that has the matching Discord Tag.
Format has to be in the formUsername#Discriminatorwhere the username must be between 2 and 32 characters (inclusive) matching the exact casing and the discriminator must be exactly 4 digits.This will only check cached users!
This only checks users that are known to the currently logged in account (shards). If a user exists with the tag that is not available in the
User-Cacheit will not be detected.
Currently Discord does not offer a way to retrieve a user by their discord tag.- Parameters:
username- The name of the userdiscriminator- The discriminator of the user- Returns:
- The
Userfor the discord tag or null if no user has the provided tag - Throws:
IllegalArgumentException- If the provided arguments are null or not in the described format
-
getPrivateChannels
@Nonnull default List<PrivateChannel> getPrivateChannels()
An unmodifiable list of all knownPrivateChannels.This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use
getPrivateChannelCache()and use its more efficient versions of handling these values.- Returns:
- Possibly-empty list of all
PrivateChannels.
-
getRoleById
@Nullable default Role getRoleById(long id)
Retrieves theRoleassociated to the provided id.
This iterates over allGuildsand check whether a Role from that Guild is assigned to the specified ID and will return the first that can be found.- Parameters:
id- The id of the searched Role- Returns:
- Possibly-null
Rolefor the specified ID
-
getRoleById
@Nullable default Role getRoleById(@Nonnull String id)
Retrieves theRoleassociated to the provided id.
This iterates over allGuildsand check whether a Role from that Guild is assigned to the specified ID and will return the first that can be found.- Parameters:
id- The id of the searched Role- Returns:
- Possibly-null
Rolefor the specified ID - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getRoleCache
@Nonnull default SnowflakeCacheView<Role> getRoleCache()
UnifiedSnowflakeCacheViewof all cachedRolesvisible to this ShardManager instance.- Returns:
- Unified
SnowflakeCacheView
-
getRoles
@Nonnull default List<Role> getRoles()
AllRolesthis ShardManager instance can see.
This will iterate over eachGuildretrieved fromgetGuilds()and collect itsGuild.getRoles().This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use
getRoleCache()and use its more efficient versions of handling these values.- Returns:
- Immutable List of all visible Roles
-
getRolesByName
@Nonnull default List<Role> getRolesByName(@Nonnull String name, boolean ignoreCase)
Retrieves allRolesvisible to this ShardManager instance.
This simply filters the Roles returned bygetRoles()with the provided name, either usingString.equals(Object)orString.equalsIgnoreCase(String)onRole.getName().- Parameters:
name- The name for the RolesignoreCase- Whether to useString.equalsIgnoreCase(String)- Returns:
- Immutable List of all Roles matching the parameters provided.
-
getChannelById
@Nullable default <T extends Channel> T getChannelById(@Nonnull Class<T> type, long id)
Description copied from interface:IGuildChannelContainerGet a channel of the specified type by id.This will automatically check for all channel types and cast to the specified class. If a channel with the specified id does not exist, or exists but is not an instance of the provided class, this returns null.
- Specified by:
getChannelByIdin interfaceIGuildChannelContainer- Type Parameters:
T- The type argument for the class- Parameters:
type-Classof a channel typeid- The snowflake id of the channel- Returns:
- The casted channel, if it exists and is assignable to the provided class, or null
-
getPrivateChannelById
@Nullable default PrivateChannel getPrivateChannelById(long id)
This returns thePrivateChannelwhich has the same id as the one provided.
If there is no knownPrivateChannelwith an id that matches the provided one, then this will returnnull.- Parameters:
id- The id of thePrivateChannel.- Returns:
- Possibly-null
PrivateChannelwith matching id.
-
getPrivateChannelById
@Nullable default PrivateChannel getPrivateChannelById(@Nonnull String id)
This returns thePrivateChannelwhich has the same id as the one provided.
If there is no knownPrivateChannelwith an id that matches the provided one, this will returnnull.- Parameters:
id- The id of thePrivateChannel.- Returns:
- Possibly-null
PrivateChannelwith matching id. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getPrivateChannelCache
@Nonnull default SnowflakeCacheView<PrivateChannel> getPrivateChannelCache()
SnowflakeCacheViewof all cachedPrivateChannelsvisible to this ShardManager instance.- Returns:
SnowflakeCacheView
-
getGuildChannelById
@Nullable default GuildChannel getGuildChannelById(long id)
Description copied from interface:IGuildChannelContainerGetGuildChannelfor the provided ID.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().To get more specific channel types you can use one of the following:
- Specified by:
getGuildChannelByIdin interfaceIGuildChannelContainer- Parameters:
id- The ID of the channel- Returns:
- The GuildChannel or null
-
getGuildChannelById
@Nullable default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
Description copied from interface:IGuildChannelContainerGetGuildChannelfor the provided ID.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().
This is meant for systems that use a dynamicChannelTypeand can profit from a simple function to get the channel instance.To get more specific channel types you can use one of the following:
- Specified by:
getGuildChannelByIdin interfaceIGuildChannelContainer- Parameters:
type- TheChannelTypeid- The ID of the channel- Returns:
- The GuildChannel or null
-
getTextChannelCache
@Nonnull default SnowflakeCacheView<TextChannel> getTextChannelCache()
Description copied from interface:IGuildChannelContainerSortedSnowflakeCacheViewofTextChannel.
InGuildcache, channels are sorted according to their position and id.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().- Specified by:
getTextChannelCachein interfaceIGuildChannelContainer- Returns:
SortedSnowflakeCacheView
-
getVoiceChannelCache
@Nonnull default SnowflakeCacheView<VoiceChannel> getVoiceChannelCache()
Description copied from interface:IGuildChannelContainerSortedSnowflakeCacheViewofVoiceChannel.
InGuildcache, channels are sorted according to their position and id.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().- Specified by:
getVoiceChannelCachein interfaceIGuildChannelContainer- Returns:
SortedSnowflakeCacheView
-
getStageChannelCache
@Nonnull default SnowflakeCacheView<StageChannel> getStageChannelCache()
Description copied from interface:IGuildChannelContainerSortedSnowflakeCacheViewofStageChannel.
InGuildcache, channels are sorted according to their position and id.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().- Specified by:
getStageChannelCachein interfaceIGuildChannelContainer- Returns:
SortedSnowflakeCacheView
-
getThreadChannelCache
@Nonnull default SnowflakeCacheView<ThreadChannel> getThreadChannelCache()
Description copied from interface:IGuildChannelContainerSnowflakeCacheViewofThreadChannel.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().- Specified by:
getThreadChannelCachein interfaceIGuildChannelContainer- Returns:
SnowflakeCacheView
-
getNewsChannelCache
@Nonnull default SnowflakeCacheView<NewsChannel> getNewsChannelCache()
Description copied from interface:IGuildChannelContainerSortedSnowflakeCacheViewofNewsChannel.
InGuildcache, channels are sorted according to their position and id.This getter exists on any instance of
IGuildChannelContainerand only checks the caches with the relevant scoping. ForGuild,JDA, orShardManager, this returns the relevant channel with respect to the cache within each of those objects. For a guild, this would mean it only returns channels within the same guild.
If this is called onJDAorShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building yourJDAinstance, you can useJDA.awaitReady().- Specified by:
getNewsChannelCachein interfaceIGuildChannelContainer- Returns:
SortedSnowflakeCacheView
-
getShardById
@Nullable default JDA getShardById(int id)
This returns theJDAinstance which has the same id as the one provided.
If there is no shard with an id that matches the provided one, this will returnnull.- Parameters:
id- The id of the shard.- Returns:
- The
JDAinstance with the given shardId ornullif no shard has the given id
-
getShardById
@Nullable default JDA getShardById(@Nonnull String id)
This returns theJDAinstance which has the same id as the one provided.
If there is no shard with an id that matches the provided one, this will returnnull.- Parameters:
id- The id of the shard.- Returns:
- The
JDAinstance with the given shardId ornullif no shard has the given id
-
getShardCache
@Nonnull ShardCacheView getShardCache()
UnifiedShardCacheViewof all cachedJDAbound to this ShardManager instance.- Returns:
- Unified
ShardCacheView
-
getShards
@Nonnull default List<JDA> getShards()
Gets allJDAinstances bound to this ShardManager.This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use
getShardCache()and use its more efficient versions of handling these values.- Returns:
- An immutable list of all managed
JDAinstances.
-
getStatus
@Nullable default JDA.Status getStatus(int shardId)
This returns theJDA.Statusof the shard which has the same id as the one provided.
If there is no shard with an id that matches the provided one, this will returnnull.- Parameters:
shardId- The id of the shard.- Returns:
- The
JDA.Statusof the shard with the given shardId ornullif no shard has the given id
-
getStatuses
@Nonnull default Map<JDA,JDA.Status> getStatuses()
Gets the currentStatusof all shards.- Returns:
- All current shard statuses.
-
getUserById
@Nullable default User getUserById(long id)
This returns theUserwhich has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this will returnnull.
-
getUserById
@Nullable default User getUserById(@Nonnull String id)
This returns theUserwhich has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this will returnnull.
-
getUserCache
@Nonnull default SnowflakeCacheView<User> getUserCache()
SnowflakeCacheViewof all cachedUsersvisible to this ShardManager instance.- Returns:
SnowflakeCacheView
-
getUsers
@Nonnull default List<User> getUsers()
An unmodifiable list of allUsersthat share aGuildwith the currently logged in account.
This list will never contain duplicates and represents allUsersthat JDA can currently see.If the developer is sharding, then only users from guilds connected to the specifically logged in shard will be returned in the List.
This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use
getUserCache()and use its more efficient versions of handling these values.- Returns:
- List of all
Usersthat are visible to JDA.
-
restart
void restart()
Restarts all shards, shutting old ones down first.As all shards need to connect to discord again this will take equally long as the startup of a new ShardManager (using the 5000ms + backoff as delay between starting new JDA instances).
- Throws:
RejectedExecutionException- Ifshutdown()has already been invoked
-
restart
void restart(int id)
Restarts the shards with the given id only.
If there is no shard with the given Id, this method acts likestart(int).- Parameters:
id- The id of the target shard- Throws:
IllegalArgumentException- If shardId is negative or higher than maxShardIdRejectedExecutionException- Ifshutdown()has already been invoked
-
setActivity
default void setActivity(@Nullable Activity activity)
Sets theActivityfor all shards.
An Activity can be retrieved viaActivity.playing(String). For streams you provide a valid streaming url as second parameter.This will also change the activity for shards that are created in the future.
- Parameters:
activity- AActivityinstance or null to reset- See Also:
Activity.playing(String),Activity.streaming(String, String)
-
setActivityProvider
default void setActivityProvider(@Nullable IntFunction<? extends Activity> activityProvider)
Sets provider that provider theActivityfor all shards.
A Activity can be retrieved viaActivity.playing(String). For streams you provide a valid streaming url as second parameter.This will also change the provider for shards that are created in the future.
- Parameters:
activityProvider- Provider for anActivityinstance or null to reset- See Also:
Activity.playing(String),Activity.streaming(String, String)
-
setIdle
default void setIdle(boolean idle)
Sets whether all instances should be marked as afk or notThis is relevant to client accounts to monitor whether new messages should trigger mobile push-notifications.
This will also change the value for shards that are created in the future.
- Parameters:
idle- boolean
-
setIdleProvider
default void setIdleProvider(@Nonnull IntFunction<Boolean> idleProvider)
Sets the provider that decides for all shards whether they should be marked as afk or not.This will also change the provider for shards that are created in the future.
- Parameters:
idleProvider- Provider for a boolean
-
setPresence
default void setPresence(@Nullable OnlineStatus status, @Nullable Activity activity)
Sets theOnlineStatusandActivityfor all shards.This will also change the status for shards that are created in the future.
- Parameters:
status- TheOnlineStatusto be used (OFFLINE/null -> INVISIBLE)activity- AActivityinstance or null to reset- Throws:
IllegalArgumentException- If the provided OnlineStatus isUNKNOWN- See Also:
Activity.playing(String),Activity.streaming(String, String)
-
setPresenceProvider
default void setPresenceProvider(@Nullable IntFunction<OnlineStatus> statusProvider, @Nullable IntFunction<? extends Activity> activityProvider)
Sets the provider that provides theOnlineStatusandActivityfor all shards.This will also change the status for shards that are created in the future.
- Parameters:
statusProvider- TheOnlineStatusto be used (OFFLINE/null -> INVISIBLE)activityProvider- AActivityinstance or null to reset- Throws:
IllegalArgumentException- If the provided OnlineStatus isUNKNOWN- See Also:
Activity.playing(String),Activity.streaming(String, String)
-
setStatus
default void setStatus(@Nullable OnlineStatus status)
Sets theOnlineStatusfor all shards.This will also change the status for shards that are created in the future.
- Parameters:
status- TheOnlineStatusto be used (OFFLINE/null -> INVISIBLE)- Throws:
IllegalArgumentException- If the provided OnlineStatus isUNKNOWN
-
setStatusProvider
default void setStatusProvider(@Nullable IntFunction<OnlineStatus> statusProvider)
Sets the provider that provides theOnlineStatusfor all shards.This will also change the provider for shards that are created in the future.
- Parameters:
statusProvider- TheOnlineStatusto be used (OFFLINE/null -> INVISIBLE)- Throws:
IllegalArgumentException- If the provided OnlineStatus isUNKNOWN
-
shutdown
void shutdown()
Shuts down all JDA shards, closing all their connections. After this method has been called the ShardManager instance can not be used anymore.
This will shutdown the internal queue worker for (re-)starts of shards. This meansrestart(int),restart(), andstart(int)will throwRejectedExecutionException.This will interrupt the default JDA event thread, due to the gateway connection being interrupted.
-
shutdown
void shutdown(int shardId)
Shuts down the shard with the given id only.
If there is no shard with the given id, this will do nothing.- Parameters:
shardId- The id of the shard that should be stopped
-
start
void start(int shardId)
Adds a new shard with the given id to this ShardManager and starts it.- Parameters:
shardId- The id of the shard that should be started- Throws:
RejectedExecutionException- Ifshutdown()has already been invoked
-
login
void login() throws LoginExceptionInitializes and starts all shards. This should only be called once.- Throws:
LoginException- If the provided token is invalid.
-
-