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
build()
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() |
Creates a completely empty JDABuilder.
|
JDABuilder(java.lang.String token) |
Creates a JDABuilder with the predefined token.
|
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 |
build() |
Builds a new
JDA instance and uses the provided token to start the login process. |
JDA |
buildAsync() |
Deprecated.
Use
build() instead |
JDA |
buildBlocking() |
Deprecated.
Use
build() and JDA.awaitReady() instead |
JDA |
buildBlocking(JDA.Status status) |
Deprecated.
Use
build() and JDA.awaitStatus(Status) instead |
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 |
setCallbackPool(java.util.concurrent.ExecutorService executor) |
Sets the
ExecutorService that should be used in
the JDA callback handler which mostly consists of RestAction callbacks. |
JDABuilder |
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. |
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 |
setDisabledCacheFlags(java.util.EnumSet<CacheFlag> flags) |
Flags used to disable parts of the JDA cache to reduce the runtime memory footprint.
|
JDABuilder |
setEnabledCacheFlags(java.util.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 |
setGame(Game game) |
Sets the
Game for our session. |
JDABuilder |
setGatewayPool(java.util.concurrent.ScheduledExecutorService pool) |
Sets the
ScheduledExecutorService used by
the main WebSocket connection for workers. |
JDABuilder |
setGatewayPool(java.util.concurrent.ScheduledExecutorService pool,
boolean automaticShutdown) |
Sets the
ScheduledExecutorService used by
the main WebSocket connection for workers. |
JDABuilder |
setHttpClient(okhttp3.OkHttpClient client) |
Sets the
OkHttpClient that will be used by JDAs requester. |
JDABuilder |
setHttpClientBuilder(okhttp3.OkHttpClient.Builder builder) |
Sets the
Builder 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 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 |
setRateLimitPool(java.util.concurrent.ScheduledExecutorService pool) |
Sets the
ScheduledExecutorService that should be used in
the JDA rate-limit handler. |
JDABuilder |
setRateLimitPool(java.util.concurrent.ScheduledExecutorService pool,
boolean automaticShutdown) |
Sets the
ScheduledExecutorService that should be used in
the JDA rate-limit handler. |
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) |
|
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()
setToken(String)
before calling build()
JDABuilder(String)
public JDABuilder(java.lang.String token)
token
- The bot token to usesetToken(String)
@Incubating public JDABuilder(AccountType accountType)
setToken(String)
before calling build()
accountType
- The AccountType
.java.lang.IllegalArgumentException
- If the given AccountType is null
public JDABuilder setEnabledCacheFlags(java.util.EnumSet<CacheFlag> flags)
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.flags
- EnumSet containing the flags for cache services that should be enabledsetDisabledCacheFlags(EnumSet)
public JDABuilder setDisabledCacheFlags(java.util.EnumSet<CacheFlag> flags)
setEnabledCacheFlags(EnumSet.complementOf(flags))
flags
- EnumSet containing the flags for cache services that should be disabledpublic 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
build()
is called.
AccountType.BOT
token
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 JDAs requester.
builder
- The new Builder
to usepublic JDABuilder setHttpClient(okhttp3.OkHttpClient client)
OkHttpClient
that will be used by JDAs requester.
client
- The new OkHttpClient
to usepublic 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: 5)
setRateLimitPool(ScheduledExecutorService)
.size
- The core pool size for the global JDA executorjava.lang.IllegalArgumentException
- If the specified core pool size is not positivepublic JDABuilder setRateLimitPool(java.util.concurrent.ScheduledExecutorService pool)
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.
setRateLimitPool(executor, true)
pool
- The thread-pool to use for rate-limit handlingpublic JDABuilder setRateLimitPool(java.util.concurrent.ScheduledExecutorService pool, boolean automaticShutdown)
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.pool
- The thread-pool to use for rate-limit handlingautomaticShutdown
- Whether JDA.shutdown()
should shutdown this poolpublic JDABuilder setGatewayPool(java.util.concurrent.ScheduledExecutorService pool)
ScheduledExecutorService
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.
setGatewayPool(pool, true)
pool
- The thread-pool to use for WebSocket workerspublic JDABuilder setGatewayPool(java.util.concurrent.ScheduledExecutorService pool, boolean automaticShutdown)
ScheduledExecutorService
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.
pool
- The thread-pool to use for WebSocket workersautomaticShutdown
- Whether JDA.shutdown()
should shutdown this poolpublic JDABuilder setCallbackPool(java.util.concurrent.ExecutorService executor)
ExecutorService
that should be used in
the JDA callback handler which mostly consists of RestAction
callbacks.
By default JDA will use ForkJoinPool.commonPool()
setCallbackPool(executor, true)
executor
- The thread-pool to use for callback handlingpublic JDABuilder setCallbackPool(java.util.concurrent.ExecutorService executor, boolean automaticShutdown)
ExecutorService
that should be used in
the JDA callback handler which mostly consists of RestAction
callbacks.
By default JDA will use ForkJoinPool.commonPool()
executor
- The thread-pool to use for callback handlingautomaticShutdown
- Whether JDA.shutdown()
should shutdown this executorpublic 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
@Deprecated @DeprecatedSince("3.8.0") @ReplaceWith("build()") public JDA buildAsync() throws javax.security.auth.login.LoginException
build()
insteadJDA
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.@Deprecated @DeprecatedSince("3.8.0") @ReplaceWith("build().awaitStatus(Status)") public JDA buildBlocking(JDA.Status status) throws javax.security.auth.login.LoginException, java.lang.InterruptedException
build()
and JDA.awaitStatus(Status)
insteadJDA
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.@Deprecated @DeprecatedSince("3.8.0") @ReplaceWith("build().awaitReady()") public JDA buildBlocking() throws javax.security.auth.login.LoginException, java.lang.InterruptedException
build()
and JDA.awaitReady()
insteadJDA
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.public JDA build() 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
JDA.awaitReady()
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.