Interface ShardManager
- All Superinterfaces:
IGuildChannelContainer<Channel>
- All Known Implementing Classes:
DefaultShardManager
Custom implementations may not support all methods and throw
UnsupportedOperationExceptions instead.- Since:
- 3.4
- Author:
- Aljoscha Grebe
-
Method Summary
Modifier and TypeMethodDescriptiondefault 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 doubleThe average time in milliseconds between all shards that discord took to respond to our last heartbeat.default SnowflakeCacheView<Category>SnowflakeCacheViewof all cachedCategoriesvisible to this ShardManager instance.default ChannelCacheView<Channel>Unified cache of all channels associated with this shard or guild.default RichCustomEmojigetEmojiById(long id) Retrieves a custom emoji matching the specifiedidif one is available in our cache.default RichCustomEmojigetEmojiById(String id) Retrieves a custom emoji matching the specifiedidif one is available in our cache.default SnowflakeCacheView<RichCustomEmoji>UnifiedSnowflakeCacheViewof all cachedRichCustomEmojisvisible to this ShardManager instance.default @Unmodifiable List<RichCustomEmoji>A collection of all known custom emojis (managed/restricted included).default @Unmodifiable List<RichCustomEmoji>getEmojisByName(String name, boolean ignoreCase) An unmodifiable list of allRichCustomEmojisthat have the same name as the one provided.default SnowflakeCacheView<ForumChannel>default EnumSet<GatewayIntent>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>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.An unmodifiable List of allGuildsthat the logged account is connected to.getGuildsByName(String name, boolean ignoreCase) An unmodifiable list of allGuildsthat have the same name as the one provided.default SnowflakeCacheView<MediaChannel>getMutualGuilds(Collection<User> users) Gets allGuildsthat contain all given users as their members.getMutualGuilds(User... users) Gets allGuildsthat contain all given users as their members.default SnowflakeCacheView<NewsChannel>SortedSnowflakeCacheViewofNewsChannel.default PrivateChannelgetPrivateChannelById(long id) This returns thePrivateChannelwhich has the same id as the one provided.default PrivateChannelThis returns thePrivateChannelwhich has the same id as the one provided.default SnowflakeCacheView<PrivateChannel>SnowflakeCacheViewof all cachedPrivateChannelsvisible to this ShardManager instance.default @Unmodifiable List<PrivateChannel>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>UnifiedSnowflakeCacheViewof all cachedRolesvisible to this ShardManager instance.getRoles()AllRolesthis ShardManager instance can see.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.UnifiedShardCacheViewof all cachedJDAbound to this ShardManager instance.Gets allJDAinstances bound to this ShardManager.intReturns the amount of shards queued for (re)connecting.default intReturns the amount of running shards.default intReturns the amount of shards managed by thisShardManager.default SnowflakeCacheView<StageChannel>SortedSnowflakeCacheViewofStageChannel.default JDA.StatusgetStatus(int shardId) This returns theJDA.Statusof the shard which has the same id as the one provided.default @Unmodifiable Map<JDA,JDA.Status> Gets the currentStatusof all shards.default SnowflakeCacheView<TextChannel>SortedSnowflakeCacheViewofTextChannel.default SnowflakeCacheView<ThreadChannel>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>SnowflakeCacheViewof all cachedUsersvisible to this ShardManager instance.getUsers()default SnowflakeCacheView<VoiceChannel>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>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>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.attribute.IGuildChannelContainer
getCategories, getCategoriesByName, getCategoryById, getCategoryById, getChannelById, getChannelById, getForumChannelById, getForumChannelById, getForumChannels, getForumChannelsByName, getGuildChannelById, getGuildChannelById, getMediaChannelById, getMediaChannelById, getMediaChannels, getMediaChannelsByName, getNewsChannelById, getNewsChannelById, getNewsChannels, getNewsChannelsByName, getStageChannelById, getStageChannelById, getStageChannels, getStageChannelsByName, getTextChannelById, getTextChannelById, getTextChannels, getTextChannelsByName, getThreadChannelById, getThreadChannelById, getThreadChannels, getThreadChannelsByName, getVoiceChannelById, getVoiceChannelById, getVoiceChannels, getVoiceChannelsByName
-
Method Details
-
addEventListener
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
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
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
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
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 like
DefaultShardManager.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
TheGatewayIntentsfor the JDA sessions of this shard manager.- Returns:
EnumSetof active gateway intents
-
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
SnowflakeCacheViewof all cachedCategoriesvisible to this ShardManager instance.- Specified by:
getCategoryCachein interfaceIGuildChannelContainer<Channel>- Returns:
SnowflakeCacheView
-
getEmojiById
Retrieves a custom emoji matching the specifiedidif one is available in our cache.Unicode emojis are not included as
RichCustomEmoji!- Parameters:
id- The id of the requestedRichCustomEmoji.- Returns:
- An
RichCustomEmojirepresented by this id or null if none is found in our cache.
-
getEmojiById
Retrieves a custom emoji matching the specifiedidif one is available in our cache.Unicode emojis are not included as
RichCustomEmoji!- Parameters:
id- The id of the requestedRichCustomEmoji.- Returns:
- An
RichCustomEmojirepresented by this id or null if none is found in our cache. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getEmojiCache
UnifiedSnowflakeCacheViewof all cachedRichCustomEmojisvisible to this ShardManager instance.- Returns:
- Unified
SnowflakeCacheView
-
getEmojis
A collection of all known custom emojis (managed/restricted included).Hint: To check whether you can use a
RichCustomEmojiin a specific context you can useRichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.Member)orRichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.User, MessageChannel)Unicode emojis are not included as
RichCustomEmoji!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
getEmojiCache()and use its more efficient versions of handling these values.- Returns:
- An immutable list of custom emojis (which may or may not be available to usage).
-
getEmojisByName
@Nonnull default @Unmodifiable List<RichCustomEmoji> getEmojisByName(@Nonnull String name, boolean ignoreCase) An unmodifiable list of allRichCustomEmojisthat have the same name as the one provided.
If there are noRichCustomEmojiswith the provided name, this will return an empty list.Unicode emojis are not included as
RichCustomEmoji!- Parameters:
name- The name of the requestedRichCustomEmojis. Without colons.ignoreCase- Whether to ignore case or not when comparing the provided name to eachEmoji.getName().- Returns:
- Possibly-empty list of all the
RichCustomEmojisthat all have the same name as the provided name.
-
getGuildById
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
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 @Unmodifiable 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
SnowflakeCacheViewof all cachedGuildsvisible to this ShardManager instance.- Returns:
SnowflakeCacheView
-
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
Gets allGuildsthat contain all given users as their members. -
getMutualGuilds
Gets allGuildsthat contain all given users as their members. -
retrieveUserById
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
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
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
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
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
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
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
UnifiedSnowflakeCacheViewof all cachedRolesvisible to this ShardManager instance.- Returns:
- Unified
SnowflakeCacheView
-
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
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.
-
getPrivateChannelById
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
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
SnowflakeCacheViewof all cachedPrivateChannelsvisible to this ShardManager instance.- Returns:
SnowflakeCacheView
-
getGuildChannelById
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:
IGuildChannelContainer.getChannelById(Class, long)IGuildChannelContainer.getTextChannelById(long)IGuildChannelContainer.getNewsChannelById(long)IGuildChannelContainer.getStageChannelById(long)IGuildChannelContainer.getVoiceChannelById(long)IGuildChannelContainer.getCategoryById(long)IGuildChannelContainer.getForumChannelById(long)
- Specified by:
getGuildChannelByIdin interfaceIGuildChannelContainer<Channel>- Parameters:
id- The ID of the channel- Returns:
- The GuildChannel or null
-
getGuildChannelById
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:
IGuildChannelContainer.getChannelById(Class, long)IGuildChannelContainer.getTextChannelById(long)IGuildChannelContainer.getNewsChannelById(long)IGuildChannelContainer.getStageChannelById(long)IGuildChannelContainer.getVoiceChannelById(long)IGuildChannelContainer.getCategoryById(long)IGuildChannelContainer.getForumChannelById(long)
- Specified by:
getGuildChannelByIdin interfaceIGuildChannelContainer<Channel>- Parameters:
type- TheChannelTypeid- The ID of the channel- Returns:
- The GuildChannel or null
-
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<Channel>- Returns:
SortedSnowflakeCacheView
-
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<Channel>- Returns:
SortedSnowflakeCacheView
-
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<Channel>- Returns:
SortedSnowflakeCacheView
-
getThreadChannelCache
Description copied from interface:IGuildChannelContainerSnowflakeCacheViewofThreadChannel.These threads can also represent posts in
ForumChannels.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<Channel>- Returns:
SnowflakeCacheView
-
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<Channel>- Returns:
SortedSnowflakeCacheView
-
getForumChannelCache
Description copied from interface:IGuildChannelContainerSnowflakeCacheViewofForumChannel.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:
getForumChannelCachein interfaceIGuildChannelContainer<Channel>- Returns:
SnowflakeCacheView
-
getMediaChannelCache
Description copied from interface:IGuildChannelContainerSnowflakeCacheViewofMediaChannel.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:
getMediaChannelCachein interfaceIGuildChannelContainer<Channel>- Returns:
SnowflakeCacheView
-
getChannelCache
Description copied from interface:IGuildChannelContainerUnified cache of all channels associated with this shard or guild.This
ChannelCacheViewstores all channels in individually typed maps based onChannelType. You can useChannelCacheView.getElementById(ChannelType, long)orChannelCacheView.ofType(Class)to filter out more specific types.- Specified by:
getChannelCachein interfaceIGuildChannelContainer<Channel>- Returns:
ChannelCacheView
-
getShardById
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
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
UnifiedShardCacheViewof all cachedJDAbound to this ShardManager instance.- Returns:
- Unified
ShardCacheView
-
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
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
Gets the currentStatusof all shards.- Returns:
- All current shard statuses.
-
getUserById
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
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
SnowflakeCacheViewof all cachedUsersvisible to this ShardManager instance.- Returns:
SnowflakeCacheView
-
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
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:
-
setActivityProvider
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:
-
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
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
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:
-
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:
-
setStatus
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
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()Initializes and starts all shards. This should only be called once.- Throws:
InvalidTokenException- If the provided token is invalid.
-