Class JDABuilder
- java.lang.Object
-
- net.dv8tion.jda.api.JDABuilder
-
public class JDABuilder extends Object
Used to create newJDA
instances. This is also useful for making sure all of yourEventListeners
are registered beforeJDA
attempts to log in.A single JDABuilder can be reused multiple times. Each call to
build()
creates a newJDA
instance using the same information. This means that you can have listeners easily registered to multipleJDA
instances.
-
-
Constructor Summary
Constructors Constructor Description JDABuilder()
Creates a completely empty JDABuilder.JDABuilder(String token)
Creates a JDABuilder with the predefined token.JDABuilder(AccountType accountType)
Creates a completely empty JDABuilder.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description JDABuilder
addEventListeners(Object... listeners)
Adds all provided listeners to the list of listeners that will be used to populate theJDA
object.JDA
build()
Builds a newJDA
instance and uses the provided token to start the login process.JDABuilder
removeEventListeners(Object... listeners)
Removes all provided listeners from the list of listeners.JDABuilder
setActivity(Activity activity)
Sets theActivity
for our session.JDABuilder
setAudioSendFactory(IAudioSendFactory factory)
Changes the factory used to createIAudioSendSystem
objects which handle the sending loop for audio packets.JDABuilder
setAutoReconnect(boolean autoReconnect)
Sets whether or not JDA should try to reconnect if a connection-error is encountered.JDABuilder
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.JDABuilder
setCallbackPool(ExecutorService executor)
Sets theExecutorService
that should be used in the JDA callback handler which mostly consists ofRestAction
callbacks.JDABuilder
setCallbackPool(ExecutorService executor, boolean automaticShutdown)
Sets theExecutorService
that should be used in the JDA callback handler which mostly consists ofRestAction
callbacks.JDABuilder
setCompression(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.JDABuilder
setContextEnabled(boolean enable)
Whether JDA should use a synchronized MDC context for all of its controlled threads.JDABuilder
setContextMap(ConcurrentMap<String,String> map)
Sets theMDC
mappings to use in JDA.JDABuilder
setDisabledCacheFlags(EnumSet<CacheFlag> flags)
Flags used to disable parts of the JDA cache to reduce the runtime memory footprint.JDABuilder
setEnabledCacheFlags(EnumSet<CacheFlag> flags)
Flags used to enable selective parts of the JDA cache to reduce the runtime memory footprint.JDABuilder
setEnableShutdownHook(boolean enable)
Enables/Disables the use of a Shutdown hook to clean up JDA.JDABuilder
setEventManager(IEventManager manager)
Changes the internally used EventManager.JDABuilder
setGatewayPool(ScheduledExecutorService pool)
Sets theScheduledExecutorService
used by the main WebSocket connection for workers.JDABuilder
setGatewayPool(ScheduledExecutorService pool, boolean automaticShutdown)
Sets theScheduledExecutorService
used by the main WebSocket connection for workers.JDABuilder
setHttpClient(OkHttpClient client)
Sets theOkHttpClient
that will be used by JDAs requester.JDABuilder
setHttpClientBuilder(OkHttpClient.Builder builder)
Sets theBuilder
that will be used by JDAs requester.JDABuilder
setIdle(boolean idle)
Sets whether or not we should mark our session as afk
This value can be changed at any time in thePresence
from a JDA instance.JDABuilder
setMaxReconnectDelay(int maxReconnectDelay)
Sets the maximum amount of time that JDA will back off to wait when attempting to reconnect the MainWebsocket.JDABuilder
setRateLimitPool(ScheduledExecutorService pool)
Sets theScheduledExecutorService
that should be used in the JDA rate-limit handler.JDABuilder
setRateLimitPool(ScheduledExecutorService pool, boolean automaticShutdown)
Sets theScheduledExecutorService
that should be used in the JDA rate-limit handler.JDABuilder
setRawEventsEnabled(boolean enable)
Whether JDA should fireRawGatewayEvent
for every discord event.JDABuilder
setRequestTimeoutRetry(boolean retryOnTimeout)
Whether the Requester should retry when aSocketTimeoutException
occurs.JDABuilder
setSessionController(SessionController controller)
Sets theSessionController
for this JDABuilder instance.JDABuilder
setStatus(OnlineStatus status)
Sets theOnlineStatus
our connection will display.JDABuilder
setToken(String token)
JDABuilder
setVoiceDispatchInterceptor(VoiceDispatchInterceptor interceptor)
Configures a custom voice dispatch handler which handles audio connections.JDABuilder
setWebsocketFactory(WebSocketFactory factory)
Sets theWebSocketFactory
that will be used by JDA's websocket client.JDABuilder
useSharding(int shardId, int shardTotal)
This will enable sharding mode for JDA.
-
-
-
Constructor Detail
-
JDABuilder
public JDABuilder()
Creates a completely empty JDABuilder.
If you use this, you need to set the token usingsetToken(String)
before callingbuild()
- See Also:
JDABuilder(String)
-
JDABuilder
public JDABuilder(@Nullable String token)
Creates a JDABuilder with the predefined token.- Parameters:
token
- The bot token to use- See Also:
setToken(String)
-
JDABuilder
@Incubating public JDABuilder(@Nonnull AccountType accountType)
Creates a completely empty JDABuilder.
If you use this, you need to set the token usingsetToken(String)
before callingbuild()
- Parameters:
accountType
- TheAccountType
.- Throws:
IllegalArgumentException
- If the given AccountType isnull
- Incubating:
- Due to policy changes for the discord API this method may not be provided in a future version
-
-
Method Detail
-
setRawEventsEnabled
@Nonnull public JDABuilder setRawEventsEnabled(boolean enable)
- Parameters:
enable
- True, if JDA should fireRawGatewayEvent
.- Returns:
- The JDABuilder instance. Useful for chaining.
- Since:
- 4.0.0
-
setEnabledCacheFlags
@Nonnull public JDABuilder setEnabledCacheFlags(@Nullable EnumSet<CacheFlag> flags)
Flags used to enable selective parts of the JDA cache to reduce the runtime memory footprint.
It is highly recommended to usesetDisabledCacheFlags(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 JDABuilder instance. Useful for chaining.
- See Also:
setDisabledCacheFlags(EnumSet)
-
setDisabledCacheFlags
@Nonnull public JDABuilder setDisabledCacheFlags(@Nullable EnumSet<CacheFlag> flags)
Flags used to disable parts of the JDA cache to reduce the runtime memory footprint.
Shortcut forsetEnabledCacheFlags(EnumSet.complementOf(flags))
- Parameters:
flags
- EnumSet containing the flags for cache services that should be disabled- Returns:
- The JDABuilder instance. Useful for chaining.
-
setContextMap
@Nonnull public JDABuilder setContextMap(@Nullable ConcurrentMap<String,String> map)
Sets theMDC
mappings to use in JDA.
If sharding is enabled JDA will automatically add ajda.shard
context with the format[SHARD_ID / TOTAL]
whereSHARD_ID
andTOTAL
are the shard configuration. Additionally it will provide context for the id viajda.shard.id
and the total viajda.shard.total
.If provided with non-null map this automatically enables MDC context using
setContextEnable(true)
!- Parameters:
map
- The modifiable context map to use in JDA, ornull
to reset- Returns:
- The JDABuilder instance. Useful for chaining.
- See Also:
- MDC Javadoc,
setContextEnabled(boolean)
-
setContextEnabled
@Nonnull public JDABuilder setContextEnabled(boolean enable)
Whether JDA should use a synchronized MDC context for all of its controlled threads.
Default:true
- Parameters:
enable
- True, if JDA should provide an MDC context map- Returns:
- The JDABuilder instance. Useful for chaining.
- See Also:
- MDC Javadoc,
setContextMap(java.util.concurrent.ConcurrentMap)
-
setCompression
@Nonnull public JDABuilder 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 toCompression.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 with the gateway connection- Returns:
- The JDABuilder instance. Useful for chaining
- Throws:
IllegalArgumentException
- If provided with null- See Also:
- Official Discord Documentation - Transport Compression
-
setRequestTimeoutRetry
@Nonnull public JDABuilder setRequestTimeoutRetry(boolean retryOnTimeout)
Whether the Requester should retry when aSocketTimeoutException
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 JDABuilder instance. Useful for chaining.
-
setToken
@Nonnull public JDABuilder setToken(@Nullable String token)
Sets the token that will be used by theJDA
instance to log in whenbuild()
is called.For
AccountType.BOT
- Go to your Discord Applications
- Create or select an already existing application
- Verify that it has already been turned into a Bot. If you see the "Create a Bot User" button, click it.
- 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 JDABuilder instance. Useful for chaining.
-
setHttpClientBuilder
@Nonnull public JDABuilder setHttpClientBuilder(@Nullable OkHttpClient.Builder builder)
Sets theBuilder
that will be used by JDAs requester.
This can be used to set things such as connection timeout and proxy.- Parameters:
builder
- The newBuilder
to use- Returns:
- The JDABuilder instance. Useful for chaining.
-
setHttpClient
@Nonnull public JDABuilder setHttpClient(@Nullable OkHttpClient client)
Sets theOkHttpClient
that will be used by JDAs requester.
This can be used to set things such as connection timeout and proxy.- Parameters:
client
- The newOkHttpClient
to use- Returns:
- The JDABuilder instance. Useful for chaining.
-
setWebsocketFactory
@Nonnull public JDABuilder setWebsocketFactory(@Nullable WebSocketFactory factory)
Sets theWebSocketFactory
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 newWebSocketFactory
to use.- Returns:
- The JDABuilder instance. Useful for chaining.
-
setRateLimitPool
@Nonnull public JDABuilder setRateLimitPool(@Nullable ScheduledExecutorService pool)
Sets theScheduledExecutorService
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 automatically disables the automatic shutdown of the rate-limit pool, you can enable it usingsetRateLimitPool(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.- Parameters:
pool
- The thread-pool to use for rate-limit handling- Returns:
- The JDABuilder instance. Useful for chaining.
-
setRateLimitPool
@Nonnull public JDABuilder setRateLimitPool(@Nullable ScheduledExecutorService pool, boolean automaticShutdown)
Sets theScheduledExecutorService
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.- Parameters:
pool
- The thread-pool to use for rate-limit handlingautomaticShutdown
- WhetherJDA.shutdown()
should shutdown this pool- Returns:
- The JDABuilder instance. Useful for chaining.
-
setGatewayPool
@Nonnull public JDABuilder setGatewayPool(@Nullable ScheduledExecutorService pool)
Sets theScheduledExecutorService
used by the main WebSocket connection for workers. These workers spend most of their lifetime sleeping because they only activate for sending messages over the gateway.
Only change this pool if you know what you're doing.
This automatically disables the automatic shutdown of the main-ws pool, you can enable it usingsetGatewayPool(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)
Default:
ScheduledThreadPoolExecutor
with 1 thread- Parameters:
pool
- The thread-pool to use for WebSocket workers- Returns:
- The JDABuilder instance. Useful for chaining.
-
setGatewayPool
@Nonnull public JDABuilder setGatewayPool(@Nullable ScheduledExecutorService pool, boolean automaticShutdown)
Sets theScheduledExecutorService
used by the main WebSocket connection for workers. These workers spend most of their lifetime sleeping because they only activate for sending messages over the gateway.
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)
Default:
ScheduledThreadPoolExecutor
with 1 thread- Parameters:
pool
- The thread-pool to use for WebSocket workersautomaticShutdown
- WhetherJDA.shutdown()
should shutdown this pool- Returns:
- The JDABuilder instance. Useful for chaining.
-
setCallbackPool
@Nonnull public JDABuilder setCallbackPool(@Nullable ExecutorService executor)
Sets theExecutorService
that should be used in the JDA callback handler which mostly consists ofRestAction
callbacks. By default JDA will useForkJoinPool.commonPool()
Only change this pool if you know what you're doing.
This automatically disables the automatic shutdown of the callback pool, you can enable it usingsetCallbackPool(executor, true)
This is used to handle callbacks of
RestAction.queue()
, similarly it is used to finishRestAction.submit()
andRestAction.complete()
tasks which build on queue.Default:
ForkJoinPool.commonPool()
- Parameters:
executor
- The thread-pool to use for callback handling- Returns:
- The JDABuilder instance. Useful for chaining.
-
setCallbackPool
@Nonnull public JDABuilder setCallbackPool(@Nullable ExecutorService executor, boolean automaticShutdown)
Sets theExecutorService
that should be used in the JDA callback handler which mostly consists ofRestAction
callbacks. By default JDA will useForkJoinPool.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 finishRestAction.submit()
andRestAction.complete()
tasks which build on queue.Default:
ForkJoinPool.commonPool()
- Parameters:
executor
- The thread-pool to use for callback handlingautomaticShutdown
- WhetherJDA.shutdown()
should shutdown this executor- Returns:
- The JDABuilder instance. Useful for chaining.
-
setBulkDeleteSplittingEnabled
@Nonnull public JDABuilder 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 theMessageBulkDeleteEvent
Default: true (enabled)
- Parameters:
enabled
- True - The MESSAGE_DELETE_BULK will be split into multiple individual MessageDeleteEvents.- Returns:
- The JDABuilder instance. Useful for chaining.
-
setEnableShutdownHook
@Nonnull public JDABuilder setEnableShutdownHook(boolean enable)
Enables/Disables the use of a Shutdown hook to clean up JDA.
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 JDA if the Java program is closed.- Returns:
- Return the
JDABuilder
instance. Useful for chaining.
-
setAutoReconnect
@Nonnull public JDABuilder 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 JDABuilder instance. Useful for chaining.
-
setEventManager
@Nonnull public JDABuilder setEventManager(@Nullable IEventManager manager)
Changes the internally used EventManager.
There are 2 provided Implementations:InterfacedEventManager
which uses the InterfaceEventListener
(tip: use theListenerAdapter
).
This is the default EventManager.AnnotatedEventManager
which uses the Annotation@SubscribeEvent
to mark the methods that listen for events.
You can also create your own EventManager (SeeIEventManager
).- Parameters:
manager
- The newIEventManager
to use.- Returns:
- The JDABuilder instance. Useful for chaining.
-
setAudioSendFactory
@Nonnull public JDABuilder setAudioSendFactory(@Nullable IAudioSendFactory factory)
Changes the factory used to createIAudioSendSystem
objects which handle the sending loop for audio packets.
By default, JDA usesDefaultSendFactory
.- Parameters:
factory
- The newIAudioSendFactory
to be used when creating newIAudioSendSystem
objects.- Returns:
- The JDABuilder instance. Useful for chaining.
-
setIdle
@Nonnull public JDABuilder setIdle(boolean idle)
Sets whether or not we should mark our session as afk
This value can be changed at any time in thePresence
from a JDA instance.- Parameters:
idle
- boolean value that will be provided with our IDENTIFY package to mark our session as afk or not. (default false)- Returns:
- The JDABuilder instance. Useful for chaining.
- See Also:
Presence#setIdle(boolean)
-
setActivity
@Nonnull public JDABuilder setActivity(@Nullable Activity activity)
Sets theActivity
for our session.
This value can be changed at any time in thePresence
from a JDA instance.Hint: You can create a
Activity
object usingActivity.playing(String)
orActivity.streaming(String, String)
.- Parameters:
activity
- An instance ofActivity
(null allowed)- Returns:
- The JDABuilder instance. Useful for chaining.
- See Also:
Presence.setActivity(Activity)
-
setStatus
@Nonnull public JDABuilder setStatus(@Nullable OnlineStatus status)
Sets theOnlineStatus
our connection will display.
This value can be changed at any time in thePresence
from a JDA instance.Note:This will not take affect for
AccountType.CLIENT
if the status specified in the user_settings is not "online" as it is overriding our identify status.- Parameters:
status
- Not-null OnlineStatus (default online)- Returns:
- The JDABuilder instance. Useful for chaining.
- Throws:
IllegalArgumentException
- if the provided OnlineStatus is null orUNKNOWN
- See Also:
Presence.setStatus(OnlineStatus)
-
addEventListeners
@Nonnull public JDABuilder addEventListeners(@Nonnull Object... listeners)
Adds all provided listeners to the list of listeners that will be used to populate theJDA
object.
This uses theInterfacedEventListener
by default.
To switch to theAnnotatedEventManager
, usesetEventManager(new AnnotatedEventManager())
.Note: When using the
InterfacedEventListener
(default), given listener(s) must be instance ofEventListener
!- Parameters:
listeners
- The listener(s) to add to the list.- Returns:
- The JDABuilder instance. Useful for chaining.
- Throws:
IllegalArgumentException
- If either listeners or one of it's objects isnull
.- See Also:
JDA.addEventListeners(Object...)
-
removeEventListeners
@Nonnull public JDABuilder removeEventListeners(@Nonnull Object... listeners)
Removes all provided listeners from the list of listeners.- Parameters:
listeners
- The listener(s) to remove from the list.- Returns:
- The JDABuilder instance. Useful for chaining.
- Throws:
IllegalArgumentException
- If either listeners or one of it's objects isnull
.- See Also:
JDA.removeEventListeners(Object...)
-
setMaxReconnectDelay
@Nonnull public JDABuilder 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 JDABuilder instance. Useful for chaining.
- Throws:
IllegalArgumentException
- Thrown if the providedmaxReconnectDelay
is less than 32.
-
useSharding
@Nonnull public JDABuilder useSharding(int shardId, int shardTotal)
This will enable sharding mode for JDA.
In sharding mode, guilds are split up and assigned one of multiple shards (clients).
The shardId that receives all stuff related to given bot is calculated as follows: shardId == (guildId >> 22) % shardTotal;
PMs are only sent to shard 0.Please note, that a shard will not know about guilds which are not assigned to it.
It is not possible to use sharding with an account for
AccountType.CLIENT
!- Parameters:
shardId
- The id of this shard (starting at 0).shardTotal
- The number of overall shards.- Returns:
- The JDABuilder instance. Useful for chaining.
- Throws:
AccountTypeException
- If this is used on a JDABuilder forAccountType.CLIENT
IllegalArgumentException
- If the provided shard configuration is invalid (0 <= shardId < shardTotal
withshardTotal > 0
)- See Also:
JDA.getShardInfo()
,ShardManager
-
setSessionController
@Nonnull public JDABuilder setSessionController(@Nullable SessionController controller)
Sets theSessionController
for this JDABuilder instance. This can be used to sync behaviour and state between shards of a bot and should be one and the same instance on all builders for the shards.
WhenuseSharding(int, int)
is enabled, this is set by default.When set, this allows the builder to build shards with respect to the login ratelimit automatically.
- Parameters:
controller
- TheSessionController
to use- Returns:
- The JDABuilder instance. Useful for chaining.
- See Also:
SessionControllerAdapter
-
setVoiceDispatchInterceptor
@Nonnull public JDABuilder 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 JDABuilder instance. Useful for chaining.
- Since:
- 4.0.0
- See Also:
VoiceDispatchInterceptor
-
build
@Nonnull public JDA build() throws LoginException
Builds a newJDA
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,JDA
has not finished loading, thus manyJDA
methods have the chance to return incorrect information. For exampleJDA.getGuilds()
might return an empty list orJDA.getUserById(long)
might return null for arbitrary user IDs.If you wish to be sure that the
JDA
information is correct, please useJDA.awaitReady()
or register anEventListener
to listen for theReadyEvent
.- Returns:
- A
JDA
instance that has started the login process. It is unknown as to whether or not loading has finished when this returns. - Throws:
LoginException
- If the provided token is invalid.IllegalArgumentException
- If the provided token is empty or null.- See Also:
JDA.awaitReady()
-
-