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
    Author:
    Aljoscha Grebe
    • Constructor Detail

      • DefaultShardManagerBuilder

        public DefaultShardManagerBuilder()
        Creates a completely empty DefaultShardManagerBuilder.
        You need to set the token using setToken(String) before calling build().
    • Method Detail

      • setEnabledCacheFlags

        public DefaultShardManagerBuilder setEnabledCacheFlags​(java.util.EnumSet<CacheFlag> flags)
        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

        public DefaultShardManagerBuilder setDisabledCacheFlags​(java.util.EnumSet<CacheFlag> flags)
        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.
      • setContextMap

        public DefaultShardManagerBuilder setContextMap​(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
      • setCompressionEnabled

        public DefaultShardManagerBuilder setCompressionEnabled​(boolean enable)
        Enable stream-compression on 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.
        Default: true

        We recommend to keep this enabled 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:
        enable - True, if the gateway connection should use compression
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        See Also:
        Official Discord Documentation - Transport Compression
      • removeEventListeners

        public DefaultShardManagerBuilder removeEventListeners​(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.removeEventListener(Object...)
      • removeEventListeners

        public DefaultShardManagerBuilder removeEventListeners​(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.removeEventListener(Object...)
      • addEventListenerProvider

        public DefaultShardManagerBuilder addEventListenerProvider​(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

        public DefaultShardManagerBuilder addEventListenerProviders​(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

        public DefaultShardManagerBuilder removeEventListenerProvider​(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

        public DefaultShardManagerBuilder removeEventListenerProviders​(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.
      • setAudioEnabled

        public DefaultShardManagerBuilder setAudioEnabled​(boolean enabled)
        Enables/Disables Voice functionality.
        This is useful, if your current system doesn't support Voice and you do not need it.

        Default: true (enabled)

        Parameters:
        enabled - True - enables voice support.
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setAutoReconnect

        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

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

        public DefaultShardManagerBuilder setCorePoolSize​(int size)
        Sets the core pool size for the global JDA ScheduledExecutorService which is used in various locations throughout the JDA instance created by this ShardManager. (Default: 5)
        Note: This has no effect if you set a pool using setRateLimitPool(ScheduledExecutorService) or setRateLimitPoolProvider(ThreadPoolProvider).
        Parameters:
        size - The core pool size for the global JDA executor
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
        Throws:
        java.lang.IllegalArgumentException - If the specified core pool size is not positive
      • setEnableShutdownHook

        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

        public DefaultShardManagerBuilder setIdleProvider​(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)
      • setStatus

        public DefaultShardManagerBuilder setStatus​(OnlineStatus status)
        Sets the OnlineStatus our connection will display.
        This value can be changed at any time in the Presence from a JDA instance.

        Note:This will not take affect for AccountType.CLIENT if the statusProvider specified in the user_settings is not "online" as it is overriding our identify statusProvider.

        Parameters:
        status - 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)
      • setStatusProvider

        public DefaultShardManagerBuilder setStatusProvider​(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.

        Note:This will not take affect for AccountType.CLIENT if the statusProvider specified in the user_settings is not "online" as it is overriding our identify statusProvider.

        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

        public DefaultShardManagerBuilder setThreadFactory​(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

        public DefaultShardManagerBuilder setHttpClientBuilder​(okhttp3.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

        public DefaultShardManagerBuilder setHttpClient​(okhttp3.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

        public DefaultShardManagerBuilder setRateLimitPool​(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)
        Parameters:
        pool - The thread-pool to use for rate-limit handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setRateLimitPool

        public DefaultShardManagerBuilder setRateLimitPool​(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).
        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

        public DefaultShardManagerBuilder setRateLimitPoolProvider​(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.
        Parameters:
        provider - The thread-pool provider to use for rate-limit handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setGatewayPool

        public DefaultShardManagerBuilder setGatewayPool​(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)
        Parameters:
        pool - The thread-pool to use for main WebSocket workers
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setGatewayPool

        public DefaultShardManagerBuilder setGatewayPool​(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).
        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

        public DefaultShardManagerBuilder setGatewayPoolProvider​(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.
        Parameters:
        provider - The thread-pool provider to use for main WebSocket workers
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setCallbackPool

        public DefaultShardManagerBuilder setCallbackPool​(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)
        Parameters:
        executor - The thread-pool to use for callback handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setCallbackPool

        public DefaultShardManagerBuilder setCallbackPool​(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.
        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

        public DefaultShardManagerBuilder setCallbackPoolProvider​(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.
        Parameters:
        provider - The thread-pool provider to use for callback handling
        Returns:
        The DefaultShardManagerBuilder instance. Useful for chaining.
      • setMaxReconnectDelay

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

        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

        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

        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

        public DefaultShardManagerBuilder setShards​(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

        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

        public DefaultShardManagerBuilder setToken​(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

        public DefaultShardManagerBuilder setWebsocketFactory​(com.neovisionaries.ws.client.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.
      • build

        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.