Package net.dv8tion.jda.api.sharding

Interface ShardManager

All Known Implementing Classes:
DefaultShardManager
public interface ShardManager
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 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 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

    • getCategories

      @Nonnull default List<Category> getCategories()
      Gets all Categories visible to the currently logged in account.

      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 getCategoryCache() and use its more efficient versions of handling these values.

      Returns:
      An immutable list of all visible Categories.

    • getCategoriesByName

      @Nonnull default List<Category> getCategoriesByName(@Nonnull String name, boolean ignoreCase)
      Gets a list of all Categories that have the same name as the one provided.
      If there are no matching categories, this will return an empty list.
      Parameters:
      name - The name to check
      ignoreCase - Whether to ignore case on name checking
      Returns:
      Immutable list of all categories matching the provided name
      Throws:
      IllegalArgumentException - If the provided name is null

    • getCategoryById

      @Nullable default Category getCategoryById(long id)
      Gets the Category that matches the provided id.
      If there is no matching Category, this will return null.
      Parameters:
      id - The snowflake ID of the wanted Category
      Returns:
      Possibly-null Category for the provided ID.

    • getCategoryById

      @Nullable default Category getCategoryById(@Nonnull String id)
      Gets the Category that matches the provided id.
      If there is no matching Category, this will return null.
      Parameters:
      id - The snowflake ID of the wanted Category
      Returns:
      Possibly-null Category for the provided ID.
      Throws:
      IllegalArgumentException - If the provided ID is not a valid long

    • getCategoryCache

      @Nonnull default SnowflakeCacheView<Category> getCategoryCache()
      SnowflakeCacheView of all cached Categories visible to this ShardManager instance.
      Returns:
      SnowflakeCacheView

    • getEmoteById

      @Nullable default Emote getEmoteById(long id)
      Retrieves an emote matching the specified id if one is available in our cache.

      Unicode emojis are not included as Emote!

      Parameters:
      id - The id of the requested Emote.
      Returns:
      An Emote represented by this id or null if none is found in our cache.

    • getEmoteById

      @Nullable default Emote getEmoteById(@Nonnull String id)
      Retrieves an emote matching the specified id if one is available in our cache.

      Unicode emojis are not included as Emote!

      Parameters:
      id - The id of the requested Emote.
      Returns:
      An Emote 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)

    • getEmoteCache

      @Nonnull default SnowflakeCacheView<Emote> getEmoteCache()
      Unified SnowflakeCacheView of all cached Emotes visible 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 Emote in a specific context you can use Emote.canInteract(net.dv8tion.jda.api.entities.Member) or Emote.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 all Emotes that have the same name as the one provided.
      If there are no Emotes with the provided name, this will return an empty list.

      Unicode emojis are not included as Emote!

      Parameters:
      name - The name of the requested Emotes. Without colons.
      ignoreCase - Whether to ignore case or not when comparing the provided name to each Emote.getName().
      Returns:
      Possibly-empty list of all the Emotes 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 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 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 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 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

    • 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

    • getPrivateChannels

      @Nonnull default 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 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 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.

    • getGuildChannelById

      @Nullable default GuildChannel getGuildChannelById(@Nonnull String id)
      Get GuildChannel for the provided ID.
      This checks if any of the channel types in this guild have the provided ID and returns the first match.
      To get more specific channel types you can use one of the following:
      Parameters:
      id - The ID of the channel
      Returns:
      The GuildChannel or null
      Throws:
      IllegalArgumentException - If the provided ID is null
      NumberFormatException - If the provided ID is not a snowflake

    • getGuildChannelById

      @Nullable default GuildChannel getGuildChannelById(long id)
      Get GuildChannel for the provided ID.
      This checks if any of the channel types in this guild have the provided ID and returns the first match.
      To get more specific channel types you can use one of the following:
      Parameters:
      id - The ID of the channel
      Returns:
      The GuildChannel or null

    • getGuildChannelById

      @Nullable default GuildChannel getGuildChannelById(@Nonnull ChannelType type, @Nonnull String id)
      Get GuildChannel for the provided ID.
      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:
      Parameters:
      type - The ChannelType
      id - The ID of the channel
      Returns:
      The GuildChannel or null
      Throws:
      IllegalArgumentException - If the provided ID is null
      NumberFormatException - If the provided ID is not a snowflake
      IllegalArgumentException - If the provided ChannelType is null

    • getGuildChannelById

      @Nullable default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
      Get GuildChannel for the provided ID.
      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:
      Parameters:
      type - The ChannelType
      id - The ID of the channel
      Returns:
      The GuildChannel or null
      Throws:
      IllegalArgumentException - If the provided ChannelType is null

    • 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 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 Map<JDA,JDA.Status> getStatuses()
      Gets the current Status of all shards.
      Returns:
      All current shard statuses.

    • getTextChannelById

      @Nullable default TextChannel getTextChannelById(long id)
      This returns the TextChannel which has the same id as the one provided.
      If there is no known TextChannel with an id that matches the provided one, this will return null.

      Note: just because a TextChannel is present does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is you will not see the channel that this returns. This is because the discord client hides any TextChannel that you don't have the Permission.VIEW_CHANNEL permission in.

      Parameters:
      id - The id of the TextChannel.
      Returns:
      Possibly-null TextChannel with matching id.

    • getTextChannelById

      @Nullable default TextChannel getTextChannelById(@Nonnull String id)
      This returns the TextChannel which has the same id as the one provided.
      If there is no known TextChannel with an id that matches the provided one, this will return null.

      Note: just because a TextChannel is present does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is you will not see the channel that this returns. This is because the discord client hides any TextChannel that you don't have the Permission.VIEW_CHANNEL permission in.

      Parameters:
      id - The id of the TextChannel.
      Returns:
      Possibly-null TextChannel with matching id.

    • getTextChannelCache

      @Nonnull default SnowflakeCacheView<TextChannel> getTextChannelCache()
      SnowflakeCacheView of all cached TextChannels visible to this ShardManager instance.
      Returns:
      SnowflakeCacheView

    • getTextChannels

      @Nonnull default List<TextChannel> getTextChannels()
      An unmodifiable List of all TextChannels of all connected Guilds.

      Note: just because a TextChannel is present in this list does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is possible that you will see fewer channels than this returns. This is because the discord client hides any TextChannel that you don't have the Permission.VIEW_CHANNEL permission in.

      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 getTextChannelCache() and use its more efficient versions of handling these values.

      Returns:
      Possibly-empty list of all known TextChannels.

    • getStoreChannelById

      @Nullable default StoreChannel getStoreChannelById(long id)
      This returns the StoreChannel which has the same id as the one provided.
      If there is no known StoreChannel with an id that matches the provided one, this will return null.
      Parameters:
      id - The id of the StoreChannel.
      Returns:
      Possibly-null StoreChannel with matching id.

    • getStoreChannelById

      @Nullable default StoreChannel getStoreChannelById(@Nonnull String id)
      This returns the StoreChannel which has the same id as the one provided.
      If there is no known StoreChannel with an id that matches the provided one, this will return null.
      Parameters:
      id - The id of the StoreChannel.
      Returns:
      Possibly-null StoreChannel with matching id.

    • getStoreChannelCache

      @Nonnull default SnowflakeCacheView<StoreChannel> getStoreChannelCache()
      SnowflakeCacheView of all cached StoreChannels visible to this ShardManager instance.
      Returns:
      SnowflakeCacheView

    • getStoreChannels

      @Nonnull default List<StoreChannel> getStoreChannels()
      An unmodifiable List of all StoreChannels of all connected Guilds.

      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 getStoreChannelCache() and use its more efficient versions of handling these values.

      Returns:
      Possibly-empty list of all known StoreChannels.

    • 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 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.

    • getVoiceChannelById

      @Nullable default VoiceChannel getVoiceChannelById(long id)
      This returns the VoiceChannel which has the same id as the one provided.
      If there is no known VoiceChannel with an id that matches the provided one, this will return null.
      Parameters:
      id - The id of the VoiceChannel.
      Returns:
      Possibly-null VoiceChannel with matching id.

    • getVoiceChannelById

      @Nullable default VoiceChannel getVoiceChannelById(@Nonnull String id)
      This returns the VoiceChannel which has the same id as the one provided.
      If there is no known VoiceChannel with an id that matches the provided one, this will return null.
      Parameters:
      id - The id of the VoiceChannel.
      Returns:
      Possibly-null VoiceChannel with matching id.

    • getVoiceChannelCache

      @Nonnull default SnowflakeCacheView<VoiceChannel> getVoiceChannelCache()
      SnowflakeCacheView of all cached VoiceChannels visible to this ShardManager instance.
      Returns:
      SnowflakeCacheView

    • getVoiceChannels

      @Nonnull default List<VoiceChannel> getVoiceChannels()
      An unmodifiable list of all VoiceChannels of all connected Guilds.

      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 getVoiceChannelCache() and use its more efficient versions of handling these values.

      Returns:
      Possible-empty list of all known VoiceChannels.

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

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

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

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

    • 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() throws LoginException
      Initializes and starts all shards. This should only be called once.
      Throws:
      LoginException - If the provided token is invalid.