Migration Guide 3.X to 4.X¶
This version includes a number of breaking changes.
Extensions That Support 4.X¶
Here is a list of known extensions that support 4.X. The ones that are not checked do not support it yet. You should check that everything used in your project supports 4.X before starting migration.
- jda-nas (since 1.1.0)
- JDA-Utilities (since 3.0.1)
- Lavalink Client (since 4.0)
- JDAction (see #6)
Package layout changes¶
Since we removed the client-only features from JDA the package didn't make much sense anymore.
Instead we have merged
api. The new package prefix for the API functionality is now
If you used internal classes they will not be available under this prefix but instead use
net.dv8tion.jda.core.entities.impl has been moved to
net.dv8tion.jda.internal.entities since the internal packages only contain implementations anyway.
In the case that
PermissionUtil.checkPermissions was used in your code, this should be changed to
Almost everything from
net.dv8tion.jda.client has been removed as its not supported by the API and can lead to account termination which we don't want to happen. Additionally, most of the features advertised by the interfaces in
client were not even implemented or documented properly.
JDABot has been moved into
The flag to disable the audio system with
setAudioEnabled(false) has been removed. This flag only enabled an exception for
Guild.getAudioManager() which is unnecessary.
net.dv8tion.jda.webhook package has been moved to a dedicated library at https://github.com/MinnDevelopment/discord-webhooks
buildAsync have been removed as they were already deprecated. To replace
buildBlocking you should use
awaitReady() on the
JDA instance returned by
The overloads for
sendFile that accepted a
Message as their last parameter have been removed in favor of
MessageAction.addFile. For example
sendFile(file, message) becomes
getCloudflareRays have been removed without replacements. These are not officially supported by the Discord API and subject to change.
Some classes have been renamed to better represent their meaning.
A few methods were renamed for better consistency and clarity.
Some methods have changed their signature in a breaking way. This is supposed to improve either internal code or make the interface more versatile.
JDABuilder and DefaultShardManagerBuilder¶
As of 4.2.0 the JDABuilder constructor has been deprecated in favor of 3 factory methods:
Further details are explained in a dedicated wiki page here: Gateway Intents and Member Cache Policy
Everything that once returned
List<Permission> has been changed to return
EnumSet<Permission> instead for a better representation.
You can no longer use blocking operations to download attachments of a message. Instead we replaced the old
downloadToFile() and similar methods. These use
CompletableFuture to provide continuations such as
whenComplete. Examples are provided in the documentation for the respective methods.
AudioSendHandler.provide20MsAudio() now returns
ByteBuffer instead of
byte. An easy transition is to use
ByteBuffer.wrap(byte). This was done to allow re-using the same buffer for multiple packets instead of allocating a fitting array every time.
PermissionOverride.getManager() now returns a
PermissionOverrideAction instead to remove code duplication. You can now also use
GuildChannel.upsertPermissionOverride which will either return
getManager() on an existing override or use
putPermissionOverride() if there is no existing override.
ListenerAdapter.onGenericEvent now accepts
GenericEvent which is a new interface that allows a more versatile hierarchy for the events it can handle.
UpdateEvent is now a subinterface for
The methods provided by the old
GuildController class have been moved into the
Guild interface. The
GuildController has been removed completely. Additionally,
Member received a few new shortcuts like
removeRolesFromMember have been removed and should be replaced with
Since we added
@Nullable annotations we had to compromise on conditional nullability. This means the methods like
Message.getTextChannel now throw instead of returning
null if the message was not sent in a
TextChannel. You can use
Message.isFromType to test for the channel type.
To support other compression algorithms like
zstd that Discord may offer in the future we changed
setCompression. In this change we also replaced the
boolean with a new enum for each algorithm. The new way to disable compression is
RestAction types have been changed to be interfaces to improve maintainability. Additionally,
submitAfter now returns
DelayedCompletableFuture to allow usage of continuations.