Package net.dv8tion.jda.api.sharding

Class DefaultShardManagerBuilder

  • public class DefaultShardManagerBuilder
extends java.lang.Object
    Used to create new instances of JDA's default ShardManager implementation.

    A single DefaultShardManagerBuilder can be reused multiple times. Each call to build() creates a new ShardManager instance using the same information.

    Since:
    3.4.0
    Author:
    Aljoscha Grebe

    • Method Detail

      • create

        @Nonnull
@CheckReturnValue
public static DefaultShardManagerBuilder create​(@Nonnull
                                                java.util.Collection<GatewayIntent> intents)
        Creates a completely empty DefaultShardManagerBuilder with the predefined intents.
        If you use this, you need to set the token using setToken(String) before calling build()

        If you don't enable certain intents, the cache will be disabled. For instance, if the GUILD_MEMBERS intent is disabled, then members will only be cached when a voice state is available. If both GUILD_MEMBERS and GUILD_VOICE_STATES are disabled then no members will be cached.

        The individual CacheFlags will also be disabled if the required intent is not enabled.

        Parameters:
        intents - The gateway intents to use
        Returns:
        The DefaultShardManagerBuilder instance
        Throws:
        java.lang.IllegalArgumentException - If the provided intents are null
        See Also:
        setToken(String)

      • create

        @Nonnull
@CheckReturnValue
public static DefaultShardManagerBuilder create​(@Nullable
                                                java.lang.String token,
                                                @Nonnull
                                                java.util.Collection<GatewayIntent> intents)
        Creates a DefaultShardManagerBuilder with the predefined token.

        If you don't enable certain intents, the cache will be disabled. For instance, if the GUILD_MEMBERS intent is disabled, then members will only be cached when a voice state is available. If both GUILD_MEMBERS and GUILD_VOICE_STATES are disabled then no members will be cached.

        The individual CacheFlags will also be disabled if the required intent is not enabled.

        Parameters:
        token - The bot token to use
        intents - The gateway intents to use
        Returns:
        The DefaultShardManagerBuilder instance
        Throws:
        java.lang.IllegalArgumentException - If the provided intents are null
        See Also:
        setToken(String)

      • setGatewayEncoding

        @Nonnull
public DefaultShardManagerBuilder setGatewayEncoding​(@Nonnull
                                                     GatewayEncoding encoding)
        Choose which GatewayEncoding JDA should use.
        Parameters:
        encoding - The GatewayEncoding (default: JSON)
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If null is provided
        Since:
        4.2.1

      • setRawEventsEnabled

        @Nonnull
public DefaultShardManagerBuilder setRawEventsEnabled​(boolean enable)
        Whether JDA should fire RawGatewayEvent for every discord event.
        Default: false
        Parameters:
        enable - True, if JDA should fire RawGatewayEvent.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.0.0

      • setRelativeRateLimit

        @Nonnull
public DefaultShardManagerBuilder setRelativeRateLimit​(boolean enable)
        Whether the rate-limit should be relative to the current time plus latency.
        By default we use the X-RateLimit-Rest-After header to determine when a rate-limit is no longer imminent. This has the disadvantage that it might wait longer than needed due to the latency which is ignored by the reset-after relative delay.

        When disabled, we will use the X-RateLimit-Reset absolute timestamp instead which accounts for latency but requires a properly NTP synchronized clock to be present. If your system does have this feature you might gain a little quicker rate-limit handling than the default allows.

        Default: true

        Parameters:
        enable - True, if the relative X-RateLimit-Reset-After header should be used.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.1.0

      • setEnabledCacheFlags

        @Nonnull
@Deprecated
@ForRemoval(deadline="5.0.0")
@ReplaceWith("enableCache(flags) and disableCache(flags)")
@DeprecatedSince("4.2.0")
public DefaultShardManagerBuilder setEnabledCacheFlags​(@Nullable
                                                       java.util.EnumSet<CacheFlag> flags)
        Deprecated.
        We add CacheFlags to the enum over time which will be disabled when using this method. This introduces breaking changes due to the way the setter works. You should use enableCache(Collection) and disableCache(Collection) instead, to disable and enable cache flags without side-effects that may break in future versions.
        Flags used to enable parts of the JDA cache to reduce the runtime memory footprint.
        It is highly recommended to use setDisabledCacheFlags(EnumSet) instead for backwards compatibility. We might add more flags in the future which you then effectively disable when updating and not changing your setting here.
        Parameters:
        flags - EnumSet containing the flags for cache services that should be enabled
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setDisabledCacheFlags

        @Nonnull
@Deprecated
@ForRemoval(deadline="5.0.0")
@ReplaceWith("enableCache(flags) and disableCache(flags)")
@DeprecatedSince("4.2.0")
public DefaultShardManagerBuilder setDisabledCacheFlags​(@Nullable
                                                        java.util.EnumSet<CacheFlag> flags)
        Deprecated.
        We add CacheFlags to the enum over time which will be disabled when using this method. This introduces breaking changes due to the way the setter works. You should use enableCache(Collection) and disableCache(Collection) instead, to disable and enable cache flags without side-effects that may break in future versions.
        Flags used to disable parts of the JDA cache to reduce the runtime memory footprint.
        Shortcut for setEnabledCacheFlags(EnumSet.complementOf(flags))
        Parameters:
        flags - EnumSet containing the flags for cache services that should be disabled
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setMemberCachePolicy

        @Nonnull
public DefaultShardManagerBuilder setMemberCachePolicy​(@Nullable
                                                       MemberCachePolicy policy)
        Configure the member caching policy. This will decide whether to cache a member (and its respective user).
        All members are cached by default. If a guild is enabled for chunking, all members will be cached for it.

        You can use this to define a custom caching policy that will greatly improve memory usage.

        It is not recommended to disable GatewayIntent.GUILD_MEMBERS when using MemberCachePolicy.ALL as the members cannot be removed from cache by a leave event without this intent.

        Example

        
 public void configureCache(DefaultShardManagerBuilder builder) {
     // Cache members who are in a voice channel
     MemberCachePolicy policy = MemberCachePolicy.VOICE;
     // Cache members who are in a voice channel
     // AND are also online
     policy = policy.and(MemberCachePolicy.ONLINE);
     // Cache members who are in a voice channel
     // AND are also online
     // OR are the owner of the guild
     policy = policy.or(MemberCachePolicy.OWNER);
     // Cache members who have a role with the name "Moderator"
     policy = (member) -> member.getRoles().stream().map(Role::getName).anyMatch("Moderator"::equals);

     builder.setMemberCachePolicy(policy);
 }
        Parameters:
        policy - The MemberCachePolicy or null to use default MemberCachePolicy.ALL
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.0
        See Also:
        MemberCachePolicy, setEnabledIntents(Collection)

      • setVoiceDispatchInterceptor

        @Nonnull
public DefaultShardManagerBuilder setVoiceDispatchInterceptor​(@Nullable
                                                              VoiceDispatchInterceptor interceptor)
        Configures a custom voice dispatch handler which handles audio connections.
        Parameters:
        interceptor - The new voice dispatch handler, or null to use the default
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.0.0
        See Also:
        VoiceDispatchInterceptor

      • setContextMap

        @Nonnull
public DefaultShardManagerBuilder setContextMap​(@Nullable
                                                java.util.function.IntFunction<? extends java.util.concurrent.ConcurrentMap<java.lang.String,​java.lang.String>> provider)
        Sets the MDC mappings provider to use in JDA.
        If sharding is enabled JDA will automatically add a jda.shard context with the format [SHARD_ID / TOTAL] where SHARD_ID and TOTAL are the shard configuration. Additionally it will provide context for the id via jda.shard.id and the total via jda.shard.total.

        The manager will call this with a shardId and it is recommended to provide a different context map for each shard!
        This automatically switches setContextEnabled(boolean) to true if the provided function is not null!

        Parameters:
        provider - The provider for modifiable context maps to use in JDA, or null to reset
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        See Also:
        MDC Javadoc

      • setCompression

        @Nonnull
public DefaultShardManagerBuilder setCompression​(@Nonnull
                                                 Compression compression)
        Sets the compression algorithm used with the gateway connection, this will decrease the amount of used bandwidth for the running bot instance for the cost of a few extra cycles for decompression. Compression can be entirely disabled by setting this to Compression.NONE.
        Default: Compression.ZLIB

        We recommend to keep this on the default unless you have issues with the decompression
        This mode might become obligatory in a future version, do not rely on this switch to stay.

        Parameters:
        compression - The compression algorithm to use for the gateway connection
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If provided with null
        See Also:
        Official Discord Documentation - Transport Compression

      • removeEventListeners

        @Nonnull
public DefaultShardManagerBuilder removeEventListeners​(@Nonnull
                                                       java.lang.Object... listeners)
        Removes all provided listeners from the list of listeners.
        Parameters:
        listeners - The listener(s) to remove from the list.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        See Also:
        JDA.removeEventListeners(Object...)

      • removeEventListeners

        @Nonnull
public DefaultShardManagerBuilder removeEventListeners​(@Nonnull
                                                       java.util.Collection<java.lang.Object> listeners)
        Removes all provided listeners from the list of listeners.
        Parameters:
        listeners - The listener(s) to remove from the list.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        See Also:
        JDA.removeEventListeners(Object...)

      • addEventListenerProvider

        @Nonnull
public DefaultShardManagerBuilder addEventListenerProvider​(@Nonnull
                                                           java.util.function.IntFunction<java.lang.Object> listenerProvider)
        Adds the provided listener provider to the list of listener providers that will be used to create listeners. On shard creation (including shard restarts) the provider will have the shard id applied and must return a listener, which will be used, along all other listeners, to populate the listeners of the JDA object of that shard.
        This uses the InterfacedEventListener by default.
        To switch to the AnnotatedEventManager, use setEventManager(id -> new AnnotatedEventManager()).

        Note: When using the InterfacedEventListener (default), given listener(s) must be instance of EventListener!

        Parameters:
        listenerProvider - The listener provider to add to the list of listener providers.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • addEventListenerProviders

        @Nonnull
public DefaultShardManagerBuilder addEventListenerProviders​(@Nonnull
                                                            java.util.Collection<java.util.function.IntFunction<java.lang.Object>> listenerProviders)
        Adds the provided listener providers to the list of listener providers that will be used to create listeners. On shard creation (including shard restarts) each provider will have the shard id applied and must return a listener, which will be used, along all other listeners, to populate the listeners of the JDA object of that shard.
        This uses the InterfacedEventListener by default.
        To switch to the AnnotatedEventManager, use setEventManager(id -> new AnnotatedEventManager()).

        Note: When using the InterfacedEventListener (default), given listener(s) must be instance of EventListener!

        Parameters:
        listenerProviders - The listener provider to add to the list of listener providers.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • removeEventListenerProvider

        @Nonnull
public DefaultShardManagerBuilder removeEventListenerProvider​(@Nonnull
                                                              java.util.function.IntFunction<java.lang.Object> listenerProvider)
        Removes the provided listener provider from the list of listener providers.
        Parameters:
        listenerProvider - The listener provider to remove from the list of listener providers.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • removeEventListenerProviders

        @Nonnull
public DefaultShardManagerBuilder removeEventListenerProviders​(@Nonnull
                                                               java.util.Collection<java.util.function.IntFunction<java.lang.Object>> listenerProviders)
        Removes all provided listener providers from the list of listener providers.
        Parameters:
        listenerProviders - The listener provider(s) to remove from the list of listener providers.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setAutoReconnect

        @Nonnull
public DefaultShardManagerBuilder setAutoReconnect​(boolean autoReconnect)
        Sets whether or not JDA should try to reconnect if a connection-error is encountered.
        This will use an incremental reconnect (timeouts are increased each time an attempt fails). Default: true (enabled)
        Parameters:
        autoReconnect - If true - enables autoReconnect
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setBulkDeleteSplittingEnabled

        @Nonnull
public DefaultShardManagerBuilder setBulkDeleteSplittingEnabled​(boolean enabled)
        If enabled, JDA will separate the bulk delete event into individual delete events, but this isn't as efficient as handling a single event would be. It is recommended that BulkDelete Splitting be disabled and that the developer should instead handle the MessageBulkDeleteEvent.

        Default: true (enabled)

        Parameters:
        enabled - True - The MESSAGE_DELETE_BULK will be split into multiple individual MessageDeleteEvents.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setEnableShutdownHook

        @Nonnull
public DefaultShardManagerBuilder setEnableShutdownHook​(boolean enable)
        Enables/Disables the use of a Shutdown hook to clean up the ShardManager and it's JDA instances.
        When the Java program closes shutdown hooks are run. This is used as a last-second cleanup attempt by JDA to properly close connections.

        Default: true (enabled)

        Parameters:
        enable - True (default) - use shutdown hook to clean up the ShardManager and it's JDA instances if the Java program is closed.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setIdleProvider

        @Nonnull
public DefaultShardManagerBuilder setIdleProvider​(@Nullable
                                                  java.util.function.IntFunction<java.lang.Boolean> idleProvider)
        Sets whether or not we should mark our sessions as afk
        This value can be changed at any time using DefaultShardManager#setIdleProvider(boolean).
        Parameters:
        idleProvider - boolean value that will be provided with our IDENTIFY packages to mark our sessions as afk or not. (default false)
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        See Also:
        Presence.setIdle(boolean)

      • setStatusProvider

        @Nonnull
public DefaultShardManagerBuilder setStatusProvider​(@Nullable
                                                    java.util.function.IntFunction<OnlineStatus> statusProvider)
        Sets the OnlineStatus our connection will display.
        This value can be changed at any time in the Presence from a JDA instance.
        Parameters:
        statusProvider - Not-null OnlineStatus (default online)
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - if the provided OnlineStatus is null or UNKNOWN
        See Also:
        Presence.setStatusProvider(OnlineStatus)

      • setThreadFactory

        @Nonnull
public DefaultShardManagerBuilder setThreadFactory​(@Nullable
                                                   java.util.concurrent.ThreadFactory threadFactory)
        Sets the ThreadFactory that will be used by the internal executor of the ShardManager.

        Note: This will not affect Threads created by any JDA instance.

        Parameters:
        threadFactory - The ThreadFactory or null to reset to the default value.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setHttpClientBuilder

        @Nonnull
public DefaultShardManagerBuilder setHttpClientBuilder​(@Nullable
                                                       OkHttpClient.Builder builder)
        Sets the Builder that will be used by JDA's requester. This can be used to set things such as connection timeout and proxy.
        Parameters:
        builder - The new OkHttpClient.Builder to use.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setHttpClient

        @Nonnull
public DefaultShardManagerBuilder setHttpClient​(@Nullable
                                                OkHttpClient client)
        Sets the OkHttpClient that will be used by JDAs requester.
        This can be used to set things such as connection timeout and proxy.
        Parameters:
        client - The new OkHttpClient to use
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setRateLimitPool

        @Nonnull
public DefaultShardManagerBuilder setRateLimitPool​(@Nullable
                                                   java.util.concurrent.ScheduledExecutorService pool)
        Sets the ScheduledExecutorService that should be used in the JDA rate-limit handler. Changing this can drastically change the JDA behavior for RestAction execution and should be handled carefully. Only change this pool if you know what you're doing.
        This will override the rate-limit pool provider set from setRateLimitPoolProvider(ThreadPoolProvider).
        This automatically disables the automatic shutdown of the rate-limit pool, you can enable it using setRateLimiPool(executor, true)

        This is used mostly by the Rate-Limiter to handle backoff delays by using scheduled executions. Besides that it is also used by planned execution for RestAction.queueAfter(long, TimeUnit) and similar methods.

        Default: ScheduledThreadPoolExecutor with 5 threads (per shard).

        Parameters:
        pool - The thread-pool to use for rate-limit handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setRateLimitPool

        @Nonnull
public DefaultShardManagerBuilder setRateLimitPool​(@Nullable
                                                   java.util.concurrent.ScheduledExecutorService pool,
                                                   boolean automaticShutdown)
        Sets the ScheduledExecutorService that should be used in the JDA rate-limit handler. Changing this can drastically change the JDA behavior for RestAction execution and should be handled carefully. Only change this pool if you know what you're doing.
        This will override the rate-limit pool provider set from setRateLimitPoolProvider(ThreadPoolProvider).

        This is used mostly by the Rate-Limiter to handle backoff delays by using scheduled executions. Besides that it is also used by planned execution for RestAction.queueAfter(long, TimeUnit) and similar methods.

        Default: ScheduledThreadPoolExecutor with 5 threads (per shard).

        Parameters:
        pool - The thread-pool to use for rate-limit handling
        automaticShutdown - Whether JDA.shutdown() should automatically shutdown this pool
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setRateLimitPoolProvider

        @Nonnull
public DefaultShardManagerBuilder setRateLimitPoolProvider​(@Nullable
                                                           ThreadPoolProvider<? extends java.util.concurrent.ScheduledExecutorService> provider)
        Sets the ScheduledExecutorService provider that should be used in the JDA rate-limit handler. Changing this can drastically change the JDA behavior for RestAction execution and should be handled carefully. Only change this pool if you know what you're doing.

        This is used mostly by the Rate-Limiter to handle backoff delays by using scheduled executions. Besides that it is also used by planned execution for RestAction.queueAfter(long, TimeUnit) and similar methods.

        Default: ScheduledThreadPoolExecutor with 5 threads (per shard).

        Parameters:
        provider - The thread-pool provider to use for rate-limit handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setGatewayPool

        @Nonnull
public DefaultShardManagerBuilder setGatewayPool​(@Nullable
                                                 java.util.concurrent.ScheduledExecutorService pool)
        Sets the ScheduledExecutorService that should be used for the JDA main WebSocket workers.
        Only change this pool if you know what you're doing.
        This will override the worker pool provider set from setGatewayPoolProvider(ThreadPoolProvider).
        This automatically disables the automatic shutdown of the main-ws pools, you can enable it using setGatewayPoolProvider(pool, true)

        This is used to send various forms of session updates such as:

        • Voice States - (Dis-)Connecting from channels
        • Presence - Changing current activity or online status
        • Guild Setup - Requesting Members of newly joined guilds
        • Heartbeats - Regular updates to keep the connection alive (usually once a minute)
        When nothing has to be sent the pool will only be used every 500 milliseconds to check the queue for new payloads. Once a new payload is sent we switch to "rapid mode" which means more tasks will be submitted until no more payloads have to be sent.

        Default: ScheduledThreadPoolExecutor with 1 thread (per shard)

        Parameters:
        pool - The thread-pool to use for main WebSocket workers
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setGatewayPool

        @Nonnull
public DefaultShardManagerBuilder setGatewayPool​(@Nullable
                                                 java.util.concurrent.ScheduledExecutorService pool,
                                                 boolean automaticShutdown)
        Sets the ScheduledExecutorService that should be used for the JDA main WebSocket workers.
        Only change this pool if you know what you're doing.
        This will override the worker pool provider set from setGatewayPoolProvider(ThreadPoolProvider).

        This is used to send various forms of session updates such as:

        • Voice States - (Dis-)Connecting from channels
        • Presence - Changing current activity or online status
        • Guild Setup - Requesting Members of newly joined guilds
        • Heartbeats - Regular updates to keep the connection alive (usually once a minute)
        When nothing has to be sent the pool will only be used every 500 milliseconds to check the queue for new payloads. Once a new payload is sent we switch to "rapid mode" which means more tasks will be submitted until no more payloads have to be sent.

        Default: ScheduledThreadPoolExecutor with 1 thread (per shard)

        Parameters:
        pool - The thread-pool to use for main WebSocket workers
        automaticShutdown - Whether JDA.shutdown() should automatically shutdown this pool
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setGatewayPoolProvider

        @Nonnull
public DefaultShardManagerBuilder setGatewayPoolProvider​(@Nullable
                                                         ThreadPoolProvider<? extends java.util.concurrent.ScheduledExecutorService> provider)
        Sets the ScheduledExecutorService that should be used for the JDA main WebSocket workers.
        Only change this pool if you know what you're doing.

        This is used to send various forms of session updates such as:

        • Voice States - (Dis-)Connecting from channels
        • Presence - Changing current activity or online status
        • Guild Setup - Requesting Members of newly joined guilds
        • Heartbeats - Regular updates to keep the connection alive (usually once a minute)
        When nothing has to be sent the pool will only be used every 500 milliseconds to check the queue for new payloads. Once a new payload is sent we switch to "rapid mode" which means more tasks will be submitted until no more payloads have to be sent.

        Default: ScheduledThreadPoolExecutor with 1 thread (per shard)

        Parameters:
        provider - The thread-pool provider to use for main WebSocket workers
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setCallbackPool

        @Nonnull
public DefaultShardManagerBuilder setCallbackPool​(@Nullable
                                                  java.util.concurrent.ExecutorService executor)
        Sets the ExecutorService that should be used in the JDA callback handler which mostly consists of RestAction callbacks. By default JDA will use ForkJoinPool.commonPool()
        Only change this pool if you know what you're doing.
        This automatically disables the automatic shutdown of the callback pools, you can enable it using setCallbackPool(executor, true)

        This is used to handle callbacks of RestAction.queue(), similarly it is used to finish RestAction.submit() and RestAction.complete() tasks which build on queue.

        Default: ForkJoinPool.commonPool()

        Parameters:
        executor - The thread-pool to use for callback handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setCallbackPool

        @Nonnull
public DefaultShardManagerBuilder setCallbackPool​(@Nullable
                                                  java.util.concurrent.ExecutorService executor,
                                                  boolean automaticShutdown)
        Sets the ExecutorService that should be used in the JDA callback handler which mostly consists of RestAction callbacks. By default JDA will use ForkJoinPool.commonPool()
        Only change this pool if you know what you're doing.

        This is used to handle callbacks of RestAction.queue(), similarly it is used to finish RestAction.submit() and RestAction.complete() tasks which build on queue.

        Default: ForkJoinPool.commonPool()

        Parameters:
        executor - The thread-pool to use for callback handling
        automaticShutdown - Whether JDA.shutdown() should automatically shutdown this pool
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setCallbackPoolProvider

        @Nonnull
public DefaultShardManagerBuilder setCallbackPoolProvider​(@Nullable
                                                          ThreadPoolProvider<? extends java.util.concurrent.ExecutorService> provider)
        Sets the ExecutorService that should be used in the JDA callback handler which mostly consists of RestAction callbacks. By default JDA will use ForkJoinPool.commonPool()
        Only change this pool if you know what you're doing.

        This is used to handle callbacks of RestAction.queue(), similarly it is used to finish RestAction.submit() and RestAction.complete() tasks which build on queue.

        Default: ForkJoinPool.commonPool()

        Parameters:
        provider - The thread-pool provider to use for callback handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setEventPool

        @Nonnull
public DefaultShardManagerBuilder setEventPool​(@Nullable
                                               java.util.concurrent.ExecutorService executor)
        Sets the ExecutorService that should be used by the event proxy to schedule events. This will be done on the calling thread by default.

        The executor will not be shutdown automatically when the shard is shutdown. To shut it down automatically use setEventPool(ExecutorService, boolean).

        Parameters:
        executor - The executor for the event proxy, or null to use calling thread
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.0

      • setEventPool

        @Nonnull
public DefaultShardManagerBuilder setEventPool​(@Nullable
                                               java.util.concurrent.ExecutorService executor,
                                               boolean automaticShutdown)
        Sets the ExecutorService that should be used by the event proxy to schedule events. This will be done on the calling thread by default.
        Parameters:
        executor - The executor for the event proxy, or null to use calling thread
        automaticShutdown - True, if the executor should be shutdown when JDA shuts down
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.0

      • setEventPoolProvider

        @Nonnull
public DefaultShardManagerBuilder setEventPoolProvider​(@Nullable
                                                       ThreadPoolProvider<? extends java.util.concurrent.ExecutorService> provider)
        Sets the ExecutorService that should be used in the JDA callback handler which mostly consists of RestAction callbacks. By default JDA will use ForkJoinPool.commonPool()
        Only change this pool if you know what you're doing.

        This is used to handle callbacks of RestAction.queue(), similarly it is used to finish RestAction.submit() and RestAction.complete() tasks which build on queue.

        Default: ForkJoinPool.commonPool()

        Parameters:
        provider - The thread-pool provider to use for callback handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.0

      • setAudioPool

        @Nonnull
public DefaultShardManagerBuilder setAudioPool​(@Nullable
                                               java.util.concurrent.ScheduledExecutorService pool)
        Sets the ScheduledExecutorService used by the audio WebSocket connection. Used for sending keepalives and closing the connection.
        Only change this pool if you know what you're doing.

        Default: ScheduledThreadPoolExecutor with 1 thread

        Parameters:
        pool - The thread-pool to use for the audio WebSocket
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.1

      • setAudioPool

        @Nonnull
public DefaultShardManagerBuilder setAudioPool​(@Nullable
                                               java.util.concurrent.ScheduledExecutorService pool,
                                               boolean automaticShutdown)
        Sets the ScheduledExecutorService used by the audio WebSocket connection. Used for sending keepalives and closing the connection.
        Only change this pool if you know what you're doing.

        Default: ScheduledThreadPoolExecutor with 1 thread

        Parameters:
        pool - The thread-pool to use for the audio WebSocket
        automaticShutdown - True, if the executor should be shutdown when JDA shuts down
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.1

      • setAudioPoolProvider

        @Nonnull
public DefaultShardManagerBuilder setAudioPoolProvider​(@Nullable
                                                       ThreadPoolProvider<? extends java.util.concurrent.ScheduledExecutorService> provider)
        Sets the ScheduledExecutorService used by the audio WebSocket connection. Used for sending keepalives and closing the connection.
        Only change this pool if you know what you're doing.

        Default: ScheduledThreadPoolExecutor with 1 thread

        Parameters:
        provider - The thread-pool provider to use for the audio WebSocket
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.2.1

      • setMaxReconnectDelay

        @Nonnull
public DefaultShardManagerBuilder setMaxReconnectDelay​(int maxReconnectDelay)
        Sets the maximum amount of time that JDA will back off to wait when attempting to reconnect the MainWebsocket.
        Provided value must be 32 or greater.

        Default: 900

        Parameters:
        maxReconnectDelay - The maximum amount of time that JDA will wait between reconnect attempts in seconds.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the provided maxReconnectDelay is less than 32.

      • setRequestTimeoutRetry

        @Nonnull
public DefaultShardManagerBuilder setRequestTimeoutRetry​(boolean retryOnTimeout)
        Whether the Requester should retry when a SocketTimeoutException occurs.
        Default: true

        This value can be changed at any time with JDA.setRequestTimeoutRetry(boolean)!

        Parameters:
        retryOnTimeout - True, if the Request should retry once on a socket timeout
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setShards

        @Nonnull
public DefaultShardManagerBuilder setShards​(int... shardIds)
        Sets the list of shards the DefaultShardManager should contain.

        This does not have any effect if the total shard count is set to -1 (get recommended shards from discord).

        Parameters:
        shardIds - The list of shard ids
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setShards

        @Nonnull
public DefaultShardManagerBuilder setShards​(int minShardId,
                                            int maxShardId)
        Sets the range of shards the DefaultShardManager should contain. This is useful if you want to split your shards between multiple JVMs or servers.

        This does not have any effect if the total shard count is set to -1 (get recommended shards from discord).

        Parameters:
        minShardId - The lowest shard id the DefaultShardManager should contain
        maxShardId - The highest shard id the DefaultShardManager should contain
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If either minShardId is negative, maxShardId is lower than shardsTotal or minShardId is lower than or equal to maxShardId

      • setShards

        @Nonnull
public DefaultShardManagerBuilder setShards​(@Nonnull
                                            java.util.Collection<java.lang.Integer> shardIds)
        Sets the range of shards the DefaultShardManager should contain. This is useful if you want to split your shards between multiple JVMs or servers.

        This does not have any effect if the total shard count is set to -1 (get recommended shards from discord).

        Parameters:
        shardIds - The list of shard ids
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If either minShardId is negative, maxShardId is lower than shardsTotal or minShardId is lower than or equal to maxShardId

      • setShardsTotal

        @Nonnull
public DefaultShardManagerBuilder setShardsTotal​(int shardsTotal)
        This will set the total amount of shards the DefaultShardManager should use.

        If this is set to -1 JDA will automatically retrieve the recommended amount of shards from discord (default behavior).

        Parameters:
        shardsTotal - The number of overall shards or -1 if JDA should use the recommended amount from discord.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        See Also:
        setShards(int, int)

      • setToken

        @Nonnull
public DefaultShardManagerBuilder setToken​(@Nonnull
                                           java.lang.String token)
        Sets the token that will be used by the ShardManager instance to log in when build() is called.

        To get a bot token:

        1. Go to your Discord Applications
        2. Create or select an already existing application
        3. Verify that it has already been turned into a Bot. If you see the "Create a Bot User" button, click it.
        4. Click the click to reveal link beside the Token label to show your Bot's token
        Parameters:
        token - The token of the account that you would like to login with.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If the token is either null or empty

      • setWebsocketFactory

        @Nonnull
public DefaultShardManagerBuilder setWebsocketFactory​(@Nullable
                                                      WebSocketFactory factory)
        Sets the WebSocketFactory that will be used by JDA's websocket client. This can be used to set things such as connection timeout and proxy.
        Parameters:
        factory - The new WebSocketFactory to use.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.

      • setGuildSubscriptionsEnabled

        @Nonnull
@Deprecated
@ForRemoval(deadline="5.0.0")
@ReplaceWith("setDisabledIntents(...).setMemberCachePolicy(...)")
@DeprecatedSince("4.2.0")
public DefaultShardManagerBuilder setGuildSubscriptionsEnabled​(boolean enabled)
        Deprecated.
        This is now superceded by setDisabledIntents(Collection) and setMemberCachePolicy(MemberCachePolicy). To get identical behavior you can do setMemberCachePolicy(VOICE).setDisabledIntents(GatewayIntent.GUILD_PRESENCES, GatewayIntent.GUILD_MESSAGE_TYPING, GatewayIntent.GUILD_MEMBERS)
        Enable typing and presence update events.
        These events cover the majority of traffic happening on the gateway and thus cause a lot of bandwidth usage. Disabling these events means the cache for users might become outdated since user properties are only updated by presence updates.
        Default: true

        Notice

        This disables the majority of member cache and related events. If anything in your project relies on member state you should keep this enabled.
        Parameters:
        enabled - True, if guild subscriptions should be enabled
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.1.0

      • enableIntents

        @Nonnull
public DefaultShardManagerBuilder enableIntents​(@Nonnull
                                                java.util.Collection<GatewayIntent> intents)
        Enable the specified GatewayIntents.
        This will not disable any currently set intents.
        Parameters:
        intents - The intents to enable
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If provided with null
        See Also:
        disableIntents(Collection)

      • setLargeThreshold

        @Nonnull
public DefaultShardManagerBuilder setLargeThreshold​(int threshold)
        Decides the total number of members at which a guild should start to use lazy loading.
        This is limited to a number between 50 and 250 (inclusive). If the chunking filter is set to ChunkingFilter.ALL this should be set to 250 (default) to minimize the amount of guilds that need to request members.
        Parameters:
        threshold - The threshold in [50, 250]
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Since:
        4.0.0

      • setMaxBufferSize

        @Nonnull
public DefaultShardManagerBuilder setMaxBufferSize​(int bufferSize)
        The maximum size, in bytes, of the buffer used for decompressing discord payloads.
        If the maximum buffer size is exceeded a new buffer will be allocated instead.
        Setting this to Integer.MAX_VALUE would imply the buffer will never be resized unless memory starvation is imminent.
        Setting this to 0 would imply the buffer would need to be allocated again for every payload (not recommended).

        Default: 2048

        Parameters:
        bufferSize - The maximum size the buffer should allow to retain
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If the provided buffer size is negative

      • build

        @Nonnull
public ShardManager build()
                   throws javax.security.auth.login.LoginException,
                          java.lang.IllegalArgumentException
        Builds a new ShardManager instance and uses the provided token to start the login process.
        The login process runs in a different thread, so while this will return immediately, ShardManager has not finished loading, thus many ShardManager methods have the chance to return incorrect information.
        The main use of this method is to start the JDA connect process and do other things in parallel while startup is being performed like database connection or local resource loading.

        Note that this method is async and as such will not block until all shards are started.

        Returns:
        A ShardManager instance that has started the login process. It is unknown as to whether or not loading has finished when this returns.
        Throws:
        javax.security.auth.login.LoginException - If the provided token is invalid.
        java.lang.IllegalArgumentException - If the provided token is empty or null. Or the provided intents/cache configuration is not possible.
        ErrorResponseException - If some other HTTP error occurred.

      • build

        @Nonnull
public ShardManager build​(boolean login)
                   throws javax.security.auth.login.LoginException,
                          java.lang.IllegalArgumentException
        Builds a new ShardManager instance. If the login parameter is true, then it will start the login process.
        The login process runs in a different thread, so while this will return immediately, ShardManager has not finished loading, thus many ShardManager methods have the chance to return incorrect information.
        The main use of this method is to start the JDA connect process and do other things in parallel while startup is being performed like database connection or local resource loading.

        Note that this method is async and as such will not block until all shards are started.

        Parameters:
        login - Whether the login process will be started. If this is false, then you will need to manually call ShardManager.login() to start it.
        Returns:
        A ShardManager instance. If login is set to true, then the instance will have started the login process. It is unknown as to whether or not loading has finished when this returns.
        Throws:
        javax.security.auth.login.LoginException - If the provided token is invalid and login is true
        java.lang.IllegalArgumentException - If the provided token is empty or null. Or the provided intents/cache configuration is not possible.