Package net.dv8tion.jda.api.sharding

Interface ShardManager

All Superinterfaces:

IGuildChannelContainer<Channel>

All Known Implementing Classes:

DefaultShardManager

public interface ShardManager
extends IGuildChannelContainer<Channel>

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 throw UnsupportedOperationExceptions instead.

Since:

3.4

Author:

Aljoscha Grebe

Method Summary

Modifier and Type	Method	Description
default void	addEventListener(Object... listeners)	Adds all provided listeners to the event-listeners that will be used to handle events.
default void	addEventListeners(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 double	getAverageGatewayPing()	The average time in milliseconds between all shards that discord took to respond to our last heartbeat.
default SnowflakeCacheView<Category>	getCategoryCache()	SnowflakeCacheView of all cached Categories visible to this ShardManager instance.
default ChannelCacheView<Channel>	getChannelCache()	Unified cache of all channels associated with this shard or guild.
default RichCustomEmoji	getEmojiById(long id)	Retrieves a custom emoji matching the specified id if one is available in our cache.
default RichCustomEmoji	getEmojiById(String id)	Retrieves a custom emoji matching the specified id if one is available in our cache.
default SnowflakeCacheView<RichCustomEmoji>	getEmojiCache()	Unified SnowflakeCacheView of all cached RichCustomEmojis visible to this ShardManager instance.
default @Unmodifiable List<RichCustomEmoji>	getEmojis()	A collection of all known custom emojis (managed/restricted included).
default @Unmodifiable List<RichCustomEmoji>	getEmojisByName(String name, boolean ignoreCase)	An unmodifiable list of all RichCustomEmojis that have the same name as the one provided.
default SnowflakeCacheView<ForumChannel>	getForumChannelCache()	SnowflakeCacheView of ForumChannel.
default EnumSet<GatewayIntent>	getGatewayIntents()	The GatewayIntents for the JDA sessions of this shard manager.
default Guild	getGuildById(long id)	This returns the Guild which has the same id as the one provided.
default Guild	getGuildById(String id)	This returns the Guild which has the same id as the one provided.
default SnowflakeCacheView<Guild>	getGuildCache()	SnowflakeCacheView of all cached Guilds visible to this ShardManager instance.
default GuildChannel	getGuildChannelById(long id)	Get GuildChannel for the provided ID.
default GuildChannel	getGuildChannelById(ChannelType type, long id)	Get GuildChannel for the provided ID.
default @Unmodifiable List<Guild>	getGuilds()	An unmodifiable List of all Guilds that the logged account is connected to.
default @Unmodifiable List<Guild>	getGuildsByName(String name, boolean ignoreCase)	An unmodifiable list of all Guilds that have the same name as the one provided.
default SnowflakeCacheView<MediaChannel>	getMediaChannelCache()	SnowflakeCacheView of MediaChannel.
default @Unmodifiable List<Guild>	getMutualGuilds(Collection<User> users)	Gets all Guilds that contain all given users as their members.
default @Unmodifiable List<Guild>	getMutualGuilds(User... users)	Gets all Guilds that contain all given users as their members.
default SnowflakeCacheView<NewsChannel>	getNewsChannelCache()	Sorted SnowflakeCacheView of NewsChannel.
default PrivateChannel	getPrivateChannelById(long id)	This returns the PrivateChannel which has the same id as the one provided.
default PrivateChannel	getPrivateChannelById(String id)	This returns the PrivateChannel which has the same id as the one provided.
default SnowflakeCacheView<PrivateChannel>	getPrivateChannelCache()	SnowflakeCacheView of all cached PrivateChannels visible to this ShardManager instance.
default @Unmodifiable List<PrivateChannel>	getPrivateChannels()	An unmodifiable list of all known PrivateChannels.
default Role	getRoleById(long id)	Retrieves the Role associated to the provided id.
default Role	getRoleById(String id)	Retrieves the Role associated to the provided id.
default SnowflakeCacheView<Role>	getRoleCache()	Unified SnowflakeCacheView of all cached Roles visible to this ShardManager instance.
default @Unmodifiable List<Role>	getRoles()	All Roles this ShardManager instance can see.
default @Unmodifiable List<Role>	getRolesByName(String name, boolean ignoreCase)	Retrieves all Roles visible to this ShardManager instance.
default JDA	getShardById(int id)	This returns the JDA instance which has the same id as the one provided.
default JDA	getShardById(String id)	This returns the JDA instance which has the same id as the one provided.
ShardCacheView	getShardCache()	Unified ShardCacheView of all cached JDA bound to this ShardManager instance.
default @Unmodifiable List<JDA>	getShards()	Gets all JDA instances bound to this ShardManager.
int	getShardsQueued()	Returns the amount of shards queued for (re)connecting.
default int	getShardsRunning()	Returns the amount of running shards.
default int	getShardsTotal()	Returns the amount of shards managed by this ShardManager.
default SnowflakeCacheView<StageChannel>	getStageChannelCache()	Sorted SnowflakeCacheView of StageChannel.
default JDA.Status	getStatus(int shardId)	This returns the JDA.Status of the shard which has the same id as the one provided.
default @Unmodifiable Map<JDA,JDA.Status>	getStatuses()	Gets the current Status of all shards.
default SnowflakeCacheView<TextChannel>	getTextChannelCache()	Sorted SnowflakeCacheView of TextChannel.
default SnowflakeCacheView<ThreadChannel>	getThreadChannelCache()	SnowflakeCacheView of ThreadChannel.
default User	getUserById(long id)	This returns the User which has the same id as the one provided.
default User	getUserById(String id)	This returns the User which has the same id as the one provided.
default User	getUserByTag(String tag)	Searches for the first user that has the matching Discord Tag.
default User	getUserByTag(String username, String discriminator)	Searches for the first user that has the matching Discord Tag.
default SnowflakeCacheView<User>	getUserCache()	SnowflakeCacheView of all cached Users visible to this ShardManager instance.
default @Unmodifiable List<User>	getUsers()	An unmodifiable list of all Users that share a Guild with the currently logged in account.
default SnowflakeCacheView<VoiceChannel>	getVoiceChannelCache()	Sorted SnowflakeCacheView of VoiceChannel.
void	login()	Initializes and starts all shards.
default void	removeEventListener(Object... listeners)	Removes all provided listeners from the event-listeners and no longer uses them to handle events.
default void	removeEventListenerProvider(IntFunction<Object> eventListenerProvider)	Remove a listener provider.
default void	removeEventListeners(IntFunction<Collection<Object>> eventListenerProvider)	Remove listeners from shards by their id.
void	restart()	Restarts all shards, shutting old ones down first.
void	restart(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 a User object based on the provided id.
default RestAction<User>	retrieveUserById(String id)	Attempts to retrieve a User object based on the provided id.
default void	setActivity(Activity activity)	Sets the Activity for all shards.
default void	setActivityProvider(IntFunction<? extends Activity> activityProvider)	Sets provider that provider the Activity for all shards.
default void	setIdle(boolean idle)	Sets whether all instances should be marked as afk or not
default void	setIdleProvider(IntFunction<Boolean> idleProvider)	Sets the provider that decides for all shards whether they should be marked as afk or not.
default void	setPresence(OnlineStatus status, Activity activity)	Sets the OnlineStatus and Activity for all shards.
default void	setPresenceProvider(IntFunction<OnlineStatus> statusProvider, IntFunction<? extends Activity> activityProvider)	Sets the provider that provides the OnlineStatus and Activity for all shards.
default void	setStatus(OnlineStatus status)	Sets the OnlineStatus for all shards.
default void	setStatusProvider(IntFunction<OnlineStatus> statusProvider)	Sets the provider that provides the OnlineStatus for all shards.
void	shutdown()	Shuts down all JDA shards, closing all their connections.
void	shutdown(int shardId)	Shuts down the shard with the given id only.
void	start(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

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 of EventListener!

Parameters:

listeners - The listener(s) which will react to events.

Throws:

IllegalArgumentException - If either listeners or one of it's objects is null.

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 is null.

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 of EventListener!

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 are null.

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 is null.

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 like DefaultShardManager.removeEventListenerProvider(IntFunction) for actual code

Parameters:

eventListenerProvider - The provider of listeners that shall be removed.

Throws:

IllegalArgumentException - If the provided listener provider is null.

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 this ShardManager. This includes shards currently queued for a restart.

Returns:

The managed amount of shards.

getGatewayIntents

@Nonnull
default EnumSet<GatewayIntent> getGatewayIntents()

The GatewayIntents for the JDA sessions of this shard manager.

Returns:

EnumSet of active gateway intents

retrieveApplicationInfo

@Nonnull
@CheckReturnValue
default RestAction<ApplicationInfo> retrieveApplicationInfo()

Used to access application details of this bot.
Since this is the same for every shard it picks JDA.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.

RestAction request 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()

SnowflakeCacheView of all cached Categories visible to this ShardManager instance.

Specified by:

getCategoryCache in interface IGuildChannelContainer<Channel>

Returns:

SnowflakeCacheView

getEmojiById

@Nullable
default RichCustomEmoji getEmojiById(long id)

Retrieves a custom emoji matching the specified id if one is available in our cache.

Unicode emojis are not included as RichCustomEmoji!

Parameters:

id - The id of the requested RichCustomEmoji.

Returns:

An RichCustomEmoji represented by this id or null if none is found in our cache.

getEmojiById

@Nullable
default RichCustomEmoji getEmojiById(@Nonnull
 String id)

Retrieves a custom emoji matching the specified id if one is available in our cache.

Unicode emojis are not included as RichCustomEmoji!

Parameters:

id - The id of the requested RichCustomEmoji.

Returns:

An RichCustomEmoji represented by this id or null if none is found in our cache.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getEmojiCache

@Nonnull
default SnowflakeCacheView<RichCustomEmoji> getEmojiCache()

Unified SnowflakeCacheView of all cached RichCustomEmojis visible to this ShardManager instance.

Returns:

Unified SnowflakeCacheView

getEmojis

@Nonnull
default @Unmodifiable List<RichCustomEmoji> getEmojis()

A collection of all known custom emojis (managed/restricted included).

Hint: To check whether you can use a RichCustomEmoji in a specific context you can use RichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.Member) or RichCustomEmoji.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 all RichCustomEmojis that have the same name as the one provided.
If there are no RichCustomEmojis with the provided name, this will return an empty list.

Unicode emojis are not included as RichCustomEmoji!

Parameters:

name - The name of the requested RichCustomEmojis. Without colons.

ignoreCase - Whether to ignore case or not when comparing the provided name to each Emoji.getName().

Returns:

Possibly-empty list of all the RichCustomEmojis that all have the same name as the provided name.

getGuildById

@Nullable
default Guild getGuildById(long id)

This returns the Guild which has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, this will return null.

Parameters:

id - The id of the Guild.

Returns:

Possibly-null Guild with matching id.

getGuildById

@Nullable
default Guild getGuildById(@Nonnull
 String id)

This returns the Guild which has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, this will return null.

Parameters:

id - The id of the Guild.

Returns:

Possibly-null Guild with matching id.

getGuildsByName

@Nonnull
default @Unmodifiable List<Guild> getGuildsByName(@Nonnull
 String name,
 boolean ignoreCase)

An unmodifiable list of all Guilds that have the same name as the one provided.
If there are no Guilds with the provided name, this will return an empty list.

Parameters:

name - The name of the requested Guilds.

ignoreCase - Whether to ignore case or not when comparing the provided name to each Guild.getName().

Returns:

Possibly-empty list of all the Guilds that all have the same name as the provided name.

getGuildCache

@Nonnull
default SnowflakeCacheView<Guild> getGuildCache()

SnowflakeCacheView of all cached Guilds visible to this ShardManager instance.

Returns:

SnowflakeCacheView

getGuilds

@Nonnull
default @Unmodifiable List<Guild> getGuilds()

An unmodifiable List of all Guilds that the logged account is connected to.
If this account is not connected to any Guilds, 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 Guilds that this account is connected to.

getMutualGuilds

@Nonnull
default @Unmodifiable List<Guild> getMutualGuilds(@Nonnull
 Collection<User> users)

Gets all Guilds that contain all given users as their members.

Parameters:

users - The users which all the returned Guilds must contain.

Returns:

Unmodifiable list of all Guild instances which have all Users in them.

getMutualGuilds

@Nonnull
default @Unmodifiable List<Guild> getMutualGuilds(@Nonnull
 User... users)

Gets all Guilds that contain all given users as their members.

Parameters:

users - The users which all the returned Guilds must contain.

Returns:

Unmodifiable list of all Guild instances which have all Users in them.

retrieveUserById

@Nonnull
@CheckReturnValue
default RestAction<User> retrieveUserById(@Nonnull
 String id)

Attempts to retrieve a User object based on the provided id.
This first calls getUserById(long), and if the return is null then a request is made to the Discord servers.

The returned RestAction can encounter the following Discord errors:

• ErrorResponse.UNKNOWN_USER
  Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).

Parameters:

id - The id of the requested User.

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 a User object based on the provided id.
This first calls getUserById(long), and if the return is null then a request is made to the Discord servers.

The returned RestAction can encounter the following Discord errors:

• ErrorResponse.UNKNOWN_USER
  Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).

Parameters:

id - The id of the requested User.

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 form Username#Discriminator where 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-Cache it 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 format Username#Discriminator

Returns:

The User for 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 form Username#Discriminator where 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-Cache it 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 user

discriminator - The discriminator of the user

Returns:

The User for 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 @Unmodifiable List<PrivateChannel> getPrivateChannels()

An unmodifiable list of all known PrivateChannels.

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 the Role associated to the provided id.
This iterates over all Guilds and 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 Role for the specified ID

getRoleById

@Nullable
default Role getRoleById(@Nonnull
 String id)

Retrieves the Role associated to the provided id.
This iterates over all Guilds and 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 Role for the specified ID

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getRoleCache

@Nonnull
default SnowflakeCacheView<Role> getRoleCache()

Unified SnowflakeCacheView of all cached Roles visible to this ShardManager instance.

Returns:

Unified SnowflakeCacheView

getRoles

@Nonnull
default @Unmodifiable List<Role> getRoles()

All Roles this ShardManager instance can see.
This will iterate over each Guild retrieved from getGuilds() and collect its Guild.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 @Unmodifiable List<Role> getRolesByName(@Nonnull
 String name,
 boolean ignoreCase)

Retrieves all Roles visible to this ShardManager instance.
This simply filters the Roles returned by getRoles() with the provided name, either using String.equals(Object) or String.equalsIgnoreCase(String) on Role.getName().

Parameters:

name - The name for the Roles

ignoreCase - Whether to use String.equalsIgnoreCase(String)

Returns:

Immutable List of all Roles matching the parameters provided.

getPrivateChannelById

@Nullable
default PrivateChannel getPrivateChannelById(long id)

This returns the PrivateChannel which has the same id as the one provided.
If there is no known PrivateChannel with an id that matches the provided one, then this will return null.

Parameters:

id - The id of the PrivateChannel.

Returns:

Possibly-null PrivateChannel with matching id.

getPrivateChannelById

@Nullable
default PrivateChannel getPrivateChannelById(@Nonnull
 String id)

This returns the PrivateChannel which has the same id as the one provided.
If there is no known PrivateChannel with an id that matches the provided one, this will return null.

Parameters:

id - The id of the PrivateChannel.

Returns:

Possibly-null PrivateChannel with matching id.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getPrivateChannelCache

@Nonnull
default SnowflakeCacheView<PrivateChannel> getPrivateChannelCache()

SnowflakeCacheView of all cached PrivateChannels visible to this ShardManager instance.

Returns:

SnowflakeCacheView

getGuildChannelById

@Nullable
default GuildChannel getGuildChannelById(long id)

Description copied from interface: IGuildChannelContainer

Get GuildChannel for the provided ID.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.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:

getGuildChannelById in interface IGuildChannelContainer<Channel>

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: IGuildChannelContainer

Get GuildChannel for the provided ID.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().
This is meant for systems that use a dynamic ChannelType and 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:

getGuildChannelById in interface IGuildChannelContainer<Channel>

Parameters:

type - The ChannelType

id - The ID of the channel

Returns:

The GuildChannel or null

getTextChannelCache

@Nonnull
default SnowflakeCacheView<TextChannel> getTextChannelCache()

Description copied from interface: IGuildChannelContainer

Sorted SnowflakeCacheView of TextChannel.
In Guild cache, channels are sorted according to their position and id.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getTextChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SortedSnowflakeCacheView

getVoiceChannelCache

@Nonnull
default SnowflakeCacheView<VoiceChannel> getVoiceChannelCache()

Description copied from interface: IGuildChannelContainer

Sorted SnowflakeCacheView of VoiceChannel.
In Guild cache, channels are sorted according to their position and id.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getVoiceChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SortedSnowflakeCacheView

getStageChannelCache

@Nonnull
default SnowflakeCacheView<StageChannel> getStageChannelCache()

Description copied from interface: IGuildChannelContainer

Sorted SnowflakeCacheView of StageChannel.
In Guild cache, channels are sorted according to their position and id.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getStageChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SortedSnowflakeCacheView

getThreadChannelCache

@Nonnull
default SnowflakeCacheView<ThreadChannel> getThreadChannelCache()

Description copied from interface: IGuildChannelContainer

SnowflakeCacheView of ThreadChannel.

These threads can also represent posts in ForumChannels.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getThreadChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SnowflakeCacheView

getNewsChannelCache

@Nonnull
default SnowflakeCacheView<NewsChannel> getNewsChannelCache()

Description copied from interface: IGuildChannelContainer

Sorted SnowflakeCacheView of NewsChannel.
In Guild cache, channels are sorted according to their position and id.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getNewsChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SortedSnowflakeCacheView

getForumChannelCache

@Nonnull
default SnowflakeCacheView<ForumChannel> getForumChannelCache()

Description copied from interface: IGuildChannelContainer

SnowflakeCacheView of ForumChannel.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getForumChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SnowflakeCacheView

getMediaChannelCache

@Nonnull
default SnowflakeCacheView<MediaChannel> getMediaChannelCache()

Description copied from interface: IGuildChannelContainer

SnowflakeCacheView of MediaChannel.

This getter exists on any instance of IGuildChannelContainer and only checks the caches with the relevant scoping. For Guild, JDA, or ShardManager, 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 on JDA or ShardManager, this may return null immediately after building, because the cache isn't initialized yet. To make sure the cache is initialized after building your JDA instance, you can use JDA.awaitReady().

Specified by:

getMediaChannelCache in interface IGuildChannelContainer<Channel>

Returns:

SnowflakeCacheView

getChannelCache

@Nonnull
default ChannelCacheView<Channel> getChannelCache()

Description copied from interface: IGuildChannelContainer

Unified cache of all channels associated with this shard or guild.

This ChannelCacheView stores all channels in individually typed maps based on ChannelType. You can use ChannelCacheView.getElementById(ChannelType, long) or ChannelCacheView.ofType(Class) to filter out more specific types.

Specified by:

getChannelCache in interface IGuildChannelContainer<Channel>

Returns:

ChannelCacheView

getShardById

@Nullable
default JDA getShardById(int id)

This returns the JDA instance which has the same id as the one provided.
If there is no shard with an id that matches the provided one, this will return null.

Parameters:

id - The id of the shard.

Returns:

The JDA instance with the given shardId or null if no shard has the given id

getShardById

@Nullable
default JDA getShardById(@Nonnull
 String id)

This returns the JDA instance which has the same id as the one provided.
If there is no shard with an id that matches the provided one, this will return null.

Parameters:

id - The id of the shard.

Returns:

The JDA instance with the given shardId or null if no shard has the given id

getShardCache

@Nonnull
ShardCacheView getShardCache()

Unified ShardCacheView of all cached JDA bound to this ShardManager instance.

Returns:

Unified ShardCacheView

getShards

@Nonnull
default @Unmodifiable List<JDA> getShards()

Gets all JDA instances 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 JDA instances.

getStatus

@Nullable
default JDA.Status getStatus(int shardId)

This returns the JDA.Status of 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 return null.

Parameters:

shardId - The id of the shard.

Returns:

The JDA.Status of the shard with the given shardId or null if no shard has the given id

getStatuses

@Nonnull
default @Unmodifiable Map<JDA,JDA.Status> getStatuses()

Gets the current Status of all shards.

Returns:

All current shard statuses.

getUserById

@Nullable
default User getUserById(long id)

This returns the User which has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this will return null.

Parameters:

id - The id of the requested User.

Returns:

Possibly-null User with matching id.

getUserById

@Nullable
default User getUserById(@Nonnull
 String id)

This returns the User which has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this will return null.

Parameters:

id - The id of the requested User.

Returns:

Possibly-null User with matching id.

getUserCache

@Nonnull
default SnowflakeCacheView<User> getUserCache()

SnowflakeCacheView of all cached Users visible to this ShardManager instance.

Returns:

SnowflakeCacheView

getUsers

@Nonnull
default @Unmodifiable List<User> getUsers()

An unmodifiable list of all Users that share a Guild with the currently logged in account.
This list will never contain duplicates and represents all Users that 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 Users that 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 - If shutdown() 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 like start(int).

Parameters:

id - The id of the target shard

Throws:

IllegalArgumentException - If shardId is negative or higher than maxShardId

RejectedExecutionException - If shutdown() has already been invoked

setActivity

default void setActivity(@Nullable
 Activity activity)

Sets the Activity for all shards.
An Activity can be retrieved via Activity.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 - A Activity instance 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 the Activity for all shards.
A Activity can be retrieved via Activity.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 an Activity instance 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 not

This 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 the OnlineStatus and Activity for all shards.

This will also change the status for shards that are created in the future.

Parameters:

status - The OnlineStatus to be used (OFFLINE/null -> INVISIBLE)

activity - A Activity instance or null to reset

Throws:

IllegalArgumentException - If the provided OnlineStatus is UNKNOWN

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 the OnlineStatus and Activity for all shards.

This will also change the status for shards that are created in the future.

Parameters:

statusProvider - The OnlineStatus to be used (OFFLINE/null -> INVISIBLE)

activityProvider - A Activity instance or null to reset

Throws:

IllegalArgumentException - If the provided OnlineStatus is UNKNOWN

See Also:

• Activity.playing(String)
• Activity.streaming(String, String)

setStatus

default void setStatus(@Nullable
 OnlineStatus status)

Sets the OnlineStatus for all shards.

This will also change the status for shards that are created in the future.

Parameters:

status - The OnlineStatus to be used (OFFLINE/null -> INVISIBLE)

Throws:

IllegalArgumentException - If the provided OnlineStatus is UNKNOWN

setStatusProvider

default void setStatusProvider(@Nullable
 IntFunction<OnlineStatus> statusProvider)

Sets the provider that provides the OnlineStatus for all shards.

This will also change the provider for shards that are created in the future.

Parameters:

statusProvider - The OnlineStatus to be used (OFFLINE/null -> INVISIBLE)

Throws:

IllegalArgumentException - If the provided OnlineStatus is UNKNOWN

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 means restart(int), restart(), and start(int) will throw RejectedExecutionException.

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 - If shutdown() 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.