public class JDABuilder
extends java.lang.Object
JDA
instances. This is also useful for making sure all of
your EventListeners
are registered
before JDA
attempts to log in.
A single JDABuilder can be reused multiple times. Each call to
buildAsync()
or
buildBlocking()
creates a new JDA
instance using the same information.
This means that you can have listeners easily registered to multiple JDA
instances.
Constructor | Description |
---|---|
JDABuilder(AccountType accountType) |
Creates a completely empty JDABuilder.
|
Modifier and Type | Method | Description |
---|---|---|
JDABuilder |
addEventListener(java.lang.Object... listeners) |
Adds all provided listeners to the list of listeners that will be used to populate the
JDA object. |
JDA |
buildAsync() |
Builds a new
JDA instance and uses the provided token to start the login process. |
JDA |
buildBlocking() |
Builds a new
JDA instance and uses the provided token to start the login process. |
JDA |
buildBlocking(JDA.Status status) |
Builds a new
JDA instance and uses the provided token to start the login process. |
JDABuilder |
removeEventListener(java.lang.Object... listeners) |
Removes all provided listeners from the list of listeners.
|
JDABuilder |
setAudioEnabled(boolean enabled) |
Enables/Disables Voice functionality.
|
JDABuilder |
setAudioSendFactory(IAudioSendFactory factory) |
Changes the factory used to create
IAudioSendSystem
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 |
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.
|
JDABuilder |
setContextEnabled(boolean enable) |
Whether JDA should use a synchronized MDC context for all of its controlled threads.
|
JDABuilder |
setContextMap(java.util.concurrent.ConcurrentMap<java.lang.String,java.lang.String> map) |
Sets the
MDC mappings to use in JDA. |
JDABuilder |
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 builder. |
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 |
setGame(Game game) |
Sets the
Game for our session. |
JDABuilder |
setHttpClientBuilder(okhttp3.OkHttpClient.Builder builder) |
Sets the
Builder that will be used by JDA's 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 the Presence 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 |
setRequestTimeoutRetry(boolean retryOnTimeout) |
Whether the Requester should retry when
a
SocketTimeoutException occurs. |
JDABuilder |
setSessionController(SessionController controller) |
Sets the
SessionController
for this JDABuilder instance. |
JDABuilder |
setStatus(OnlineStatus status) |
Sets the
OnlineStatus our connection will display. |
JDABuilder |
setToken(java.lang.String token) |
Sets the token that will be used by the
JDA instance to log in when
buildAsync()
or buildBlocking()
is called. |
JDABuilder |
setWebsocketFactory(com.neovisionaries.ws.client.WebSocketFactory factory) |
Sets the
WebSocketFactory that will be used by JDA's websocket client. |
JDABuilder |
useSharding(int shardId,
int shardTotal) |
This will enable sharding mode for JDA.
|
public JDABuilder(AccountType accountType)
setToken(String)
before calling buildAsync()
or buildBlocking()
accountType
- The AccountType
.java.lang.IllegalArgumentException
- If the given AccountType is null
public JDABuilder setContextMap(java.util.concurrent.ConcurrentMap<java.lang.String,java.lang.String> map)
MDC
mappings to use in JDA.
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
.
If provided with non-null map this automatically enables MDC context using setContextEnable(true)
!
map
- The modifiable context map to use in JDA, or null
to resetsetContextEnabled(boolean)
public JDABuilder setContextEnabled(boolean enable)
true
enable
- True, if JDA should provide an MDC context mapsetContextMap(java.util.concurrent.ConcurrentMap)
public JDABuilder setCompressionEnabled(boolean enable)
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.
enable
- True, if the gateway connection should use compressionpublic JDABuilder setRequestTimeoutRetry(boolean retryOnTimeout)
SocketTimeoutException
occurs.
true
This value can be changed at any time with JDA.setRequestTimeoutRetry(boolean)
!
retryOnTimeout
- True, if the Request should retry once on a socket timeoutpublic JDABuilder setToken(java.lang.String token)
JDA
instance to log in when
buildAsync()
or buildBlocking()
is called.
AccountType.BOT
token
AccountType.CLIENT
Ctrl-Shift-i
which will bring up the developer tools.Application
tabStorage
, select Local Storage
, and then discordapp.com
token
row and copy the value that is in quotes.token
- The token of the account that you would like to login with.public JDABuilder setHttpClientBuilder(okhttp3.OkHttpClient.Builder builder)
Builder
that will be used by JDA's requester.
This can be used to set things such as connection timeout and proxy.builder
- The new Builder
to use.public JDABuilder setWebsocketFactory(com.neovisionaries.ws.client.WebSocketFactory factory)
WebSocketFactory
that will be used by JDA's websocket client.
This can be used to set things such as connection timeout and proxy.factory
- The new WebSocketFactory
to use.public JDABuilder setCorePoolSize(int size)
ScheduledExecutorService
which is used
in various locations throughout the JDA instance created by this builder. (Default: 2)size
- The core pool size for the global JDA executorjava.lang.IllegalArgumentException
- If the specified core pool size is not positivepublic JDABuilder setAudioEnabled(boolean enabled)
Default: true (enabled)
enabled
- True - enables voice support.public JDABuilder setBulkDeleteSplittingEnabled(boolean enabled)
MessageBulkDeleteEvent
Default: true (enabled)
enabled
- True - The MESSAGE_DELETE_BULK will be split into multiple individual MessageDeleteEvents.public JDABuilder setEnableShutdownHook(boolean enable)
Default: true (enabled)
enable
- True (default) - use shutdown hook to clean up JDA if the Java program is closed.JDABuilder
instance. Useful for chaining.public JDABuilder setAutoReconnect(boolean autoReconnect)
autoReconnect
- If true - enables autoReconnectpublic JDABuilder setEventManager(IEventManager manager)
InterfacedEventManager
which uses the Interface
EventListener
(tip: use the ListenerAdapter
).
AnnotatedEventManager
which uses the Annotation
@SubscribeEvent
to mark the methods that listen for events.IEventManager
).manager
- The new IEventManager
to use.public JDABuilder setAudioSendFactory(IAudioSendFactory factory)
IAudioSendSystem
objects which handle the sending loop for audio packets.
DefaultSendFactory
.factory
- The new IAudioSendFactory
to be used
when creating new IAudioSendSystem
objects.public JDABuilder setIdle(boolean idle)
Presence
from a JDA instance.idle
- boolean value that will be provided with our IDENTIFY package to mark our session as afk or not. (default false)Presence#setIdle(boolean)
public JDABuilder setGame(Game game)
Game
for our session.
Presence
from a JDA instance.
Hint: You can create a Game
object using
Game.playing(String)
or Game.streaming(String, String)
.
game
- An instance of Game
(null allowed)Presence.setGame(Game)
public JDABuilder setStatus(OnlineStatus status)
OnlineStatus
our connection will display.
Presence
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.
status
- Not-null OnlineStatus (default online)java.lang.IllegalArgumentException
- if the provided OnlineStatus is null or UNKNOWN
Presence.setStatus(OnlineStatus)
public JDABuilder addEventListener(java.lang.Object... listeners)
JDA
object.
InterfacedEventListener
by default.
AnnotatedEventManager
,
use setEventManager(new AnnotatedEventManager())
.
Note: When using the InterfacedEventListener
(default),
given listener(s) must be instance of EventListener
!
listeners
- The listener(s) to add to the list.java.lang.IllegalArgumentException
- If either listeners or one of it's objects is null
.JDA.addEventListener(Object...)
public JDABuilder removeEventListener(java.lang.Object... listeners)
listeners
- The listener(s) to remove from the list.java.lang.IllegalArgumentException
- If either listeners or one of it's objects is null
.JDA.removeEventListener(Object...)
public JDABuilder setMaxReconnectDelay(int maxReconnectDelay)
maxReconnectDelay
- The maximum amount of time that JDA will wait between reconnect attempts in seconds.java.lang.IllegalArgumentException
- Thrown if the provided maxReconnectDelay
is less than 32.public JDABuilder useSharding(int shardId, int shardTotal)
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
!
shardId
- The id of this shard (starting at 0).shardTotal
- The number of overall shards.AccountTypeException
- If this is used on a JDABuilder for AccountType.CLIENT
java.lang.IllegalArgumentException
- If the provided shard configuration is invalid
(0 <= shardId < shardTotal
with shardTotal > 0
)JDA.getShardInfo()
,
ShardManager
public JDABuilder setSessionController(SessionController controller)
SessionController
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.
useSharding(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.
controller
- The SessionController
to useSessionControllerAdapter
public JDA buildAsync() throws javax.security.auth.login.LoginException
JDA
instance and uses the provided token to start the login process.
JDA
has not
finished loading, thus many JDA
methods have the chance to return incorrect information.
If you wish to be sure that the JDA
information is correct, please use
buildBlocking()
or register an
EventListener
to listen for the
ReadyEvent
.
JDA
instance that has started the login process. It is unknown as
to whether or not loading has finished when this returns.javax.security.auth.login.LoginException
- If the provided token is invalid.java.lang.IllegalArgumentException
- If the provided token is empty or null.public JDA buildBlocking(JDA.Status status) throws javax.security.auth.login.LoginException, java.lang.InterruptedException
JDA
instance and uses the provided token to start the login process.
status
- The Status
to wait for, once JDA has reached the specified
stage of the startup cycle this method will return.JDA
Object that is guaranteed to be logged in and finished loading.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 status is not part of the login cycle.java.lang.InterruptedException
- If an interrupt request is received while waiting for JDA
to finish logging in.
This would most likely be caused by a JVM shutdown request.public JDA buildBlocking() throws javax.security.auth.login.LoginException, java.lang.InterruptedException
JDA
instance and uses the provided token to start the login process.
ReadyEvent
.JDA
Object that is guaranteed to be logged in and finished loading.javax.security.auth.login.LoginException
- If the provided token is invalid.java.lang.IllegalArgumentException
- If the provided token is empty or null.java.lang.InterruptedException
- If an interrupt request is received while waiting for JDA
to finish logging in.
This would most likely be caused by a JVM shutdown request.