Skip to content

Obtaining API

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.

To obtain the API make yourself familiar with the org.bukkit.plugin.ServicesManager.

Bukkit's ServicesManager🔗

The ServicesManager is a part of the Bukkit API that allows plugins to provide services to other plugins. To avoid a static singleton pattern, the ServicesManager is designed to be used as a dependency injection container. BetonQuest is using the ServicesManager to provide its API.

Obtaining the BetonQuestApiService🔗

The BetonQuestApiService is the single source of truth for BetonQuest that allows other plugins to obtain the API.

Get the API Service
final ServicesManager servicesManager = getServer().getServicesManager(); // or Bukkit.getServicesManager()
final BetonQuestApiService apiService = servicesManager.load(BetonQuestApiService.class);
This can only be called after the onEnable method of BetonQuest. This is usually the case when your plugin's onEnable method is called by Bukkit, assuming you defined a dependency on BetonQuest. The BetonQuestApiService registers its default implementation with the Highest ServicePriority, since it is not meant to be overridden.

The unrecommended way in case of an emergency

If for some reason you need to obtain the API service in fewer steps, you can use a static method in BetonQuestApiService, which essentially does the same thing as the code above, but under the hood:

Static method to obtain the API
final BetonQuestApiService apiService = BetonQuestApiService.get();

Obtaining the BetonQuestApi🔗

The BetonQuestApiService provides a method to obtain the actual API instance:

Obtain the API instance
final Plugin yourPluginInstance;
final BetonQuestApiService apiService;
final BetonQuestApi betonQuestApi = apiService.api(yourPluginInstance);

The API Hints🔗

The following hint can be found on many API pages (usually as collapsed):

Logging API Classes

  • org.betonquest.betonquest.api.logger.BetonQuestLogger
  • org.betonquest.betonquest.api.logger.BetonQuestLoggerFactory

It lists all interfaces that are used from the API on that page.

Working with the API🔗

We recommend that you inject instances you obtained from the ServicesManager into your classes when they need them. You might want to learn about "Dependency Injection" as a programming technique, but as a quick start here's a simple example:

This plugin injects an instance of BetonQuestApi and BetonQuestLogger that was created by the BetonQuestApiService into a class implementing some feature.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class MyAddon extends JavaPlugin {

    @Override
    public void onEnable() {
        final ServicesManager servicesManager = getServer().getServicesManager();
        final BetonQuestApiService betonQuestApiService 
            = servicesManager.load(BetonQuestApiService.class);
        final BetonQuestApi betonQuestApi = betonQuestApiService.api(this);
        final BetonQuestLogger betonQuestLogger = betonQuestApi.loggerFactory().create(MyFeature.class);
        new MyFeature(betonQuestLogger, betonQuestApi);
    }
}

public class MyFeature {
    private final BetonQuestLogger betonQuestLogger;
    private final BetonQuestApi betonQuestApi;

    public MyFeature(final BetonQuestLogger betonQuestLogger,
                     final BetonQuestApi betonQuestApi) {
        this.betonQuestLogger = betonQuestLogger;
        this.betonQuestApi = betonQuestApi;
    }
}