v3.0.0-alpha.4 | Localization extensions, service priorities

Overview

Improved the extensibility of the Localization API, service types of interfaced services are added automatically, and added service priority.

Fixes

• Suspending service factories are now prohibited correctly
• Fixed single-implementation interfaces services not being constrained correctly
• Fixed BStatusChangeEvent not having the correct old status

Changes

• Renamed FirstReadyEvent to FirstGuildReadyEvent
• Improved extension of the Localization API, more details here
• Service types of interfaced services are now added automatically
  • If you still have a @ServiceType used for it, you will be warned
• Application commands will not be updated if there is an error on the initial update (i.e., on startup)
• Improved exception when an option annotation was possibly forgotten
• Bundles with a -default postfix (between the base name and the locale tag) are read by default
  • The "default" bundle is overridden by existing bundles
• Reworked interaction filters
  • Uses interfaced services and coroutines
  • All filters are now ran before their targets gets executed

Additions

• Added extensions to MessageCreateData and MessageEditData
• Added suppressContentWarning to temporarily suppress message content intent warnings
  • This is useful if you read the content of message context commands, but without having the MESSAGE_CONTENT intent
• Added namedDefaultScope to easily create a CoroutineScope with incrementally named threads
• Added readResource, withResource and readResourceAsString to read resources relative to the caller class
• Added getValue operator on ServiceContainer (enables you to use the by operator to get a service)
• Added service priority
  • Either on @BService or with @ServicePriority
• Added Class overloads for functions which accepted KClass
• Added logs of annotated commands being excluded by @Test / @CommandId
• Check autocomplete parameters missing from slash commands
• Added an error when invalid component IDs are used

Removals

• Removed Gson

Full Changelog: v3.0.0-alpha.3...v3.0.0-alpha.4

v3.0.0-alpha.3 | Docs, dynamic help examples and EventWaiter

Overview

Added back EventWaiter, fixed inconsistent handling of default locked/test commands

Fixes

• Fixed inconsistent handling of default locked/test commands

Changes

• Separated AppOption into SlashOption and ContextOption

Additions

• Added back EventWaiter, with coroutines support
• Added dynamic help examples, which lets you generate an help example based on the execution context (by using the event)
• Exposed CooldownService to the API
• Added InjectedJDAEvent, which gets fired when a JDA instance is received and injected as a service
• Reworked most docs related to commands/components/modals

Full Changelog: v3.0.0-alpha.2...v3.0.0-alpha.3

v3.0.0-alpha.2 | Fixes and utilities

Overview

Fixes for autocomplete cache, component groups NPE, and added utilities.

Fixes

• Fixed autocomplete cache not taking forceCache into account
• Fix components groups throwing when retrieving a timeout with no handler

Changes

• Built-in help command and ready listener uses internal service names to avoid conflicts
• Added the Class being checked to ConditionalServiceChecker#checkServiceAvailability
• Enrich exceptions when localizing strings

Additions

• Added LocalizationContext#getEffectiveLocale
• Added to infix function for Localization.Entry
• Exposed some internal utilities, added Guild/JDA utilities about retrieving Member/User, and for:
  • Collections
  • ErrorResponses
  • Reflection/ClassGraph
• Added awaitOrNull on components, awaitAny for component groups
• Added DefaultMessage#getPermission to localize permissions
  • The default localization is simply the one set in JDA, as always, you can override and localize those with your own DefaultMessages.json

Full Changelog: v3.0.0-alpha.1...v3.0.0-alpha.2

v3.0.0-alpha.1 | Dynamic commands, async loading and new services

While V3 has most major features reworked and improved, this came to a cost; in particular, some parts of the API are now built toward Kotlin users.
It is not sure how the API may be adapted to fit Java users more.

While some features which require configuration using a DSL appeal more to Kotlin users, they should still be usable by Java users.

Fortunately, annotation-driven features that already existed can still be used with no problem, both in Java and Kotlin.

You can also refer to the examples and bot template folder on the repository in order to have an idea on how V3 is supposed to be used.

Kotlin support

All commands and handlers support coroutines (except service factories) and default parameters.

Each feature has its own CoroutineScope, configurable in BCoroutineScopesConfigBuilder

New dependency injection

In V2, you had to register your resolvers, instances, instance suppliers... using ExtensionsBuilder, which enabled you to use constructor and field injection.

In V3, you no longer need to manually manage your instances manually, a basic DI framework can manage all your services, commands, handlers, resolvers... as long as you annotated them with their appropriate annotations.
You then simply put a parameter in your constructor/method to receive the requested service type.

@BService, @Command and @Resolver are the annotations you will need the most.

Services and factories

@BService can be used to declare classes as services, or, when used on a method, serves as a factory for the return type.
As always, if they are on your search path, then they will be instantiated when building the framework, and available to other classes.

These services can all have a name, in case you want multiple services of the same type, but want to differentiate them.

Conditional services

@ConditionalService can be used when you want your service/command/resolver... to be created under certain conditions.
The annotation will only let the service be created if all the specified check interfaces passes.

Interfaced services

You can find the @InterfacedService annotations on some interfaces of the framework, such as SettingsProvider or IHelpCommand.
This annotation indicates that this interface can be implemented, but needs to be registered as a service of the implemented interface.
This is useful for when the framework needs an instance of the interface, without knowing what the implementation is.
For example, if you want to override the help command, you will need to make an implementation for IHelpCommand.

An example can be found here.

Dynamic suppliers

Dynamic suppliers are interfaced services (that you can make multiple instances of), which lets you provide services of any type.
The framework will give you the class of what it wants to instantiate, and you can then tell if your supplier supports the class, or not, or if it is supported but cannot create an instance of it.

An example can be found here.

New command declarations

Commands can now be declared using a DSL, these works best if you use Kotlin.

Declaration DSL

To use the DSL, you can check out @AppDeclaration and @TextDeclaration.

The DSL can help you provide each parameter explicitly, without the need for annotations, and also enables more features, such as option aggregates.

The DSL also enables you to declare commands with code, configure your names, descriptions, choices... everything by code, so you are not limited to static values with annotations.

You can find an example here, see SlashBanDetailedFront#onDeclare.

New option aggregates

Option aggregates are a way to combine multiple options into one object, the function that combines all the options can be anything, including a constructor.

Option aggregates

Normal aggregates can accept any option type (Discord option, custom option or generated option).

You can still insert options without declaring an aggregate; these options will implicitly have an aggregate created for you.

Note: Option aggregates are only available with DSL declaration (and components and modal handlers by using @Aggregate).

You can find an example here, see aggregate in SlashBanDetailedFront#onDeclare.

Vararg options

Vararg options are a special type of option aggregate, they are essentially an aggregate which generates N options, and the aggregator just accepts a List and returns it as-is, i.e. your parameter accepts a List, not a real vararg.

You can use these with optionVararg.

Note: Aggregators can accept List parameters, but all the options must be under the same declared parameter name, so they can be all put in the list.

You can find an example here.

Inline class options

Kotlin's inline classes can also be used as options, you can use inlineClassOption to declare one in the DSL, they also automatically work for annotated commands.

inlineClassOptionVararg can also be used for inline classes that accept a varargs.

You can find an example here, with SlashSentence.SentenceParts.

Autocomplete changes

Autocomplete annotations and event have been renamed using Autocomplete instead of Autocompletion.

Other than that, @CompositeKey has been replaced by compositeKeys on @CacheAutocomplete.
This lets you configure what Discord options (you can also put the parameter name) must be in the caching key, even if the option is not being used by the autocomplete handler itself.

The slash command DSL also let you configure autocomplete by using SlashCommandOptionBuilder#autocomplete (or SlashCommandOptionBuilder#autocompleteReference for handlers defined by annotation).

You can find an example here, on SlashSentence#onSentencePartAutocomplete.

Async loading

The library now loads asynchronously, you previously had to wait for your entire bot to be loaded, but now you must start the framework before building JDA, which lets you get your stuff started up before the bot goes fully online.

Building JDA before the framework will result in an error, I strongly recommend that you create a "JDA service" class, which must be started at the ServiceStart.READY phase.

You can also refer to the example JDA service.

New database utils

A Database interface has been added, this is mostly useful for Kotlin users and only serves as a very basic abstraction for transactions.

You might find helpful how the framework logs the queries going through it, with the timings, if you enable the TRACE logging level.

New components

The Components utility class is now a service, which means you can get it either in your constructor, or in your handler.

As in V2, your components can be set as being usable only once, being able to be used by certain users/with permissions/with roles...

The main difference is that you need to set the handler and the timeout handler inside the component DSL, which means that setting a handler and a timeout handler is optional.

As these handlers are optional, you can still handle them using coroutines, by using await on your component/group.

Note: I recommend setting timeout when creating your component, with or without a handler, instead of using withTimeout. Be sure to catch TimeoutCancellationException.

An example can be found here.

New modals

Just like components, modals are now created using a DSL, while their handlers are still annotated.

The DSL is very similar to the component's DSL, with your usual bindTo and setTimeout functions, you can also await on your modals.

You can find an example here.

New event handler

@BEventListener can now be specified to be run asynchronously (within the parallelism limits of BCoroutineScopesConfig#eventDispatcherScope),
they can also have a priority assigned to them, as well as a timeout, used for suspending handlers.

An example can be found here.

Suspend resolvers & resolver factories

ParameterResolver are now type safe and also support coroutines.

Suspending resolvers

Parameter resolvers in Java can override the usual resolve method, while Kotlin users can override the resolveSuspend function. This is particularly useful when you need to execute a RestAction, so you can await without blocking the thread.

Resolver factories

Resolver factories were also added to enable you to give a parameter resolver based on the parameter of the function.

This is how [App/Text]LocalizationContext are injected, they use factories of ICustomResolver,
and when you put a parameter, they read that parameter for @LocalizationBundle and then construct a resolver which gets you the correct localization bundle.

New in-interaction localization

As briefly explained above, localization has been moved from the framework events, into injectable instances, [App/Text]LocalizationContext.

Naturally, AppLocalizationContext can only be used with...

v2.10.2 - Fix component autocommit and int options

Overview

Fixes global command errors being swallowed and some database operations not being committed when autocommit is off by default (when using Hibernate for example)

Fixes

• Use autocommitted connections in DefaultComponentManager by @freya022 in #70
• Fix IntegerResolver returning a long, when it should return an int in component handlers

Changes

• Throw if a guild-only event is used on a global command
• Improve logs and errors

Additions

• Add BContext#scheduleGlobalApplicationCommandsUpdate to update global commands

Full Changelog: v2.10.1...v2.10.2

v2.10.1 - Fix global command exceptions, warn on missing intents

Overview

Fixes "missing intents" when using EventWaiter, and swallowed exceptions when global commands are misconfigured.

Fixes

• Fix exceptions being swallowed when creating global commands

Changes

• Warn when an EventWaiter and @JDAEventListener uses an event which requires unavailable intents

Additions

• Added EventUtils#suppressMissingIntents to suppress intent warnings for a specific event

Full Changelog: v2.10.0...v2.10.1

v2.10.0 - Fix class discovery, support inner classes

Overview

Fixes issues with class discovery with frameworks like Spring and Tomcat.

Changes

• Rework introspection by @freya022 in #62
• Clarify component listeners do not need to extend a class
• Updated to JDA 5 beta 8

Additions

• Support inner classes

Full Changelog: v2.9.1...v2.10.0

v2.9.1 - Inferred command/option descriptions

New features

• Infer command and option descriptions from root localization bundles by @freya022 in #61

Changes

• Updated to JDA 5 beta 6
• Updated org.json:json being used by com.github.MinnDevelopment:emoji-java

Full Changelog: v2.9.0...v2.9.1

v2.9.0 - JDA 5 beta 5, DiscordLocale for command localization

Changes

• Use DiscordLocale in ApplicationCommandsBuilder#addLocalizations
• Update dependencies

Full Changelog: v2.8.7...v2.9.0

v2.8.7 - Add version metadata

What's Changed

• Fixed more javadocs
• Add unit tests to CI by @freya022 in #59
• Rework versioning scheme and add metadata by @freya022 in #60

Added

• A BCInfo class to get the current BC version and built JDA version

Full Changelog: v2.8.6...v2.8.7