Skip to content

IntegrationBuilder🔗

API State: Unfinished

Todo

This part of the API is only planned.

Do not use anything of this part of the API yet. It will change in the future.

Unfinished

This part of the API is brand-new. It will be changed if there are any bugs, missing features or usability improvements. This part of the API might receive breaking changes within a minor version.

It is not recommended relying on this part of the API, it will most likely change.

Draft

Our own usage and testing has shown that this part of the API is complete and seems bug free. However, other plugins may have other use cases which are not covered by our testing. Therefore, please go ahead and use this API part. Let us know if there are missing features or bugs. This API part will be changed if there are more bugs, missing features or usability improvements. We will try to keep it compatible with previous versions if changes are needed. This part of the API won't receive breaking changes within a minor version.

Please use this part of the API and give us feedback!

Stable

Both our own and third party testing showed that this part of the API is complete. Only bugs and major conceptual problems would lead to more changes. This part of the API will only change over at least one major version and will likely carry deprecation as long as possible.

This part of the API should be safe to use. We try to keep it compatible with previous versions if changes are needed.

Integration API Classes
  • org.betonquest.betonquest.api.integration.IntegrationBuilder

Introduction🔗

The integration API offers a custom integration builder to create custom integration implementations without defining a class. It is recommended to use this API if you want to integrate a bunch of smaller independent features from multiple plugins or sources.

If you want to create a custom implementation, have a look at the Integration interface.

You should have viewed these pages

Use Case

The integration builder is best used if you want to integrate a bunch of smaller independent features from multiple plugins or sources.

Do Not Use

Custom integration implementations are recommended if you want to integrate the entirety of a plugin with BetonQuest. For custom integrations, take a look at the Integration interface first.

Quick Demonstration🔗

The IntegrationBuilder is used to create and register integration features on the spot in a stream-like call.

IntegrationBuilder
final IntegrationPolicy integrationPolicy; //(1)!
integrationPolicy.builder() //(2)!
  .enable(/* ... */) //(3)!
  .postEnable(/* ... */) //(4)!
  .disable(/* ... */) //(5)!
  .integrate(pluginInstance); //(6)!
  1. The integration policy is required to create a new builder.
  2. The builder call creates a new IntegrationBuilder instance.
  3. Define the function called when the integration is enabled.
  4. Define the function called when the integration is post-enabled. (after BetonQuest has been enabled, before the first server tick)
  5. Define the function called when the integration is disabled.
  6. Integrate using a plugin instance. The integration will deactivate if the plugin is deactivated.

Method details🔗

The minimal required methods for a valid integration builder registration are either enable() or postEnable() and the builder must be finalized with integrate().

The following methods are available and may be called once at most per server start in the given order:

  • enable(QuestConsumer<BetonQuestApi>): Called when the integration is enabled, early in the integration process of BetonQuest.
  • postEnable(QuestConsumer<BetonQuestApi>): Called when the integration is post-enabled, after BetonQuest, all integrations and all its features have been fully enabled, but before the first server tick.
  • disable(QuestRunnable): Called when the integration is disabled. An integration can be disabled by disabling BetonQuest or by the plugin integrating it disabling itself. An integration may only be disabled if it is enabled before.

The integrate(Plugin) method is required to register the integration with BetonQuest. The plugin provided must be a valid and loaded plugin instance, usually the instance of the plugin that is providing the integration. The integrating plugin does not need to be identical to any plugin required by the integration(s).

The methods enable() and postEnable() are provided a BetonQuest API instance to allow the integration to register features and services. Please do not inject another API instance into the integration methods from outside.

An Example🔗

Suppose you want to integrate a custom action implementation MyAction using the integration builder, since it's the only feature you want to integrate and there is no need to create a custom integration implementation.

IntegrationBuilder
final IntegrationPolicy integrationPolicy; //(1)!
integrationPolicy.builder() //(2)!
  .enable(api -> api.actions().registry().register("myaction", MyAction.class)) //(3)!
  .integrate(pluginInstance); //(4)!
  1. The integration policy is required to create a new builder.
  2. The builder call creates a new IntegrationBuilder instance.
  3. Register the action implementation with the action registry.
  4. Integrate using a plugin instance.