Replace jda-ktx with our own module

[freya022]

Removes jda-ktx and introduces a new BotCommands-jda-ktx module, this is done for a few reasons:

1. A significant part of it is unused, because the framework already provides the functionality in a similar way, such as creating commands, components and modals
2. It depends on JDA, meaning we can't upgrade to a new major JDA version without also updating jda-ktx, and in some cases it forces us to use Jitpack for it, we don't want that
3. Along with the previous point, adding utilities is faster if we maintain it ourselves

This will no longer include jda-ktx transitively, you are recommended to migrate, but if you choose to add it back, be aware that functions relying on CoroutineEventManager, such as JDA#await/listen will no longer work.

Please look at the README for more details.

Differences with jda-ktx

Changes to the CoroutineEventManager

The core module includes its own event manager, you can configure its default timeout at BEventManagerConfig#defaultTimeout, and the CoroutineScope in BCoroutineScopesConfig#eventManagerScope.

As a result, extensions from jda-ktx relying on its CoroutineEventManager no longer work, but you can fix this by importing the extension from this module.

You can still register CoroutineEventListeners (the one from BotCommands-core, not jda-ktx!) if required.

Changed functionalities

If you decide to switch, some functions have replacements:

• awaitMessage must now be used on an EventWaiter instance
• awaitButton is now Button#await (the framework's Button class)
• jda-ktx's Paginator is replaced by the core Paginators

Incompatible functionalities

If you keep using jda-ktx, some functions will not work or behave unexpectedly:

• scope on JDA/ShardManager
• Any function related to build JDA or shard managers, it is recommended you use the helper functions in JDAService.

Missing functionalities

Additionally, jda-ktx has additional extensions that were not ported:

• String#toEmoji()
• String#toCustomEmoji()
  • It is recommended to use application emojis
• String#toUnicodeEmoji()
  • It is recommended to use jda-emojis's UnicodeEmojis class (included by default)
• getDefaultScope
  • Replaced with namedDefaultScope
• All extensions already handled by the framework, such as creating/listening to commands, components and modals
• The WebhookAppender
• named, String#invoke and some into extensions from messages/utils.kt
• OkHttp's Call extensions awaitWith and await
  • I would recommend using ktor with the OkHttp client engine
• SLF4J logger delegation (private val logger by SLF4J)
  • I recommend using kotlin-logging instead (private val logger = KotlinLogging.logger { })
  • The Logging class may also be of interest
• ref extensions on entities
  • I don't recommend using them because while they keep entities up to date between reconnects, they don't prevent you from sending requests to deleted entities

Please open an issue if you feel like one of these extensions are worth porting, an alternative is to port them locally.

Migrating

You can apply an OpenRewrite recipe to change all relevant imports, note that this could still require you to do some changes after it.

Before migrating, your codebase must compile, so you must not update any versions yet.

Make sure you have committed your current changes, or make a back up of your project.

Registering the recipe

Note

This will log warnings for Kotlin sources, but the recipes still work fine.

(Kotlin) Gradle

plugins {
    // ...
    id("org.openrewrite.rewrite") version "7.11.0"
}

repositories {
    // ...
    maven("https://jitpack.io")
}

dependencies {
    // Existing dependencies
    // ...

    rewrite("io.github.freya022:BotCommands-jda-ktx:{{latest commit hash}}")
    rewrite("org.openrewrite.recipe:rewrite-java-dependencies:1.37.0")
}

rewrite {
    // Use 'dev.freya02.MigrateToBcJdaKtx' if you want to migrate from jda-ktx (recommended)
    // Use 'dev.freya02.MigrateFromBcCoreToBcJdaKtx' if you want to keep using jda-ktx
    activeRecipe("dev.freya02.MigrateToBcJdaKtx")
}

Checking changes (dry run)

Run the rewriteDryRun task, this can be done by pressing CTRL twice on IntelliJ then running gradle rewriteDryRun.
This will generate a diff file at build/reports/rewrite/rewrite.patch, you can check the possible changes there.

Applying changes

Run the rewriteRun task.

Maven

1. Add the following repository:

<repository>
    <id>jitpack</id>
    <url>https://jitpack.io</url>
</repository>

2. Add the following plugin:

<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>6.13.0</version>
  <configuration>
    <activeRecipes>
      <!-- Use 'dev.freya02.MigrateToBcJdaKtx' if you want to migrate from jda-ktx (recommended) -->
      <!-- Use 'dev.freya02.MigrateFromBcCoreToBcJdaKtx' if you want to keep using jda-ktx -->
      <recipe>dev.freya02.MigrateToBcJdaKtx</recipe>
    </activeRecipes>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.openrewrite.recipe</groupId>
      <artifactId>rewrite-java-dependencies</artifactId>
      <version>1.37.0</version>
    </dependency>
    <dependency>
      <groupId>io.github.freya022</groupId>
      <artifactId>BotCommands-jda-ktx</artifactId>
      <version>{{latest commit hash}}</version>
    </dependency>
  </dependencies>
</plugin>

Checking changes (dry run)

Run the rewrite:dryRun goal, this can be done by pressing CTRL twice on IntelliJ then running mvn rewrite:dryRun.
This will generate a diff file at target/site/rewrite/rewrite.patch, you can check the possible changes there.

Applying changes

Run the rewrite:run goal.

You can then update BotCommands-core and add BotCommands-jda-ktx.

It is recommended to optimize imports (Code | Optimize imports in IntelliJ) after migrating.

Notes

Breaking changes

• Removed ICoroutineEventManagerSupplier
  • If you want to configure the default timeout, set BEventManagerConfig#defaultTimeout
  • If you want to configure the coroutine scope, set BCoroutineScopesConfig#eventManagerScope
• Removed the jda-ktx api dependency
  • You can add it back if you want, but I'd recommend migrating to BotCommands-jda-ktx

New Features

• Added CoroutineEventListener
• Ported part of jda-ktx to BotCommands-jda-ktx
• Added more extensions, see the readme

Changes

• Moved JDA extensions from the core modules to BotCommands-jda-ktx
  • Deprecated accessors were made to help migrate
• Extensions for RestAction, RestResult and related, which have vararg parameters, now require at least 1 argument