Obtaining API

API State: Draft

Unfinished

This part of the API is brand-new. It will be changed if there are any bugs, missing features or usability improvements.

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.

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 should be safe to use. We try to keep it compatible with previous versions if changes are needed.

To obtain the API or a part of the API there are currently two ways, the new way and the legacy way.

Obtaining the API

New method

The new way is the recommended way to get the redesigned parts of the API.
It is not yet available for all parts of the API, but will be in the future.

The new API is designed to be modular and extensible. To obtain a module of the API you use the org.bukkit.plugin.ServicesManager. The ServicesManager is Bukkit API that allows plugins to provide services to other plugins:

Get a module

BetonQuestLoggerFactory loggerFactory = getServer().getServicesManager().load(BetonQuestLoggerFactory.class);

This can only be called after the onEnable method of BetonQuest has been called. This is usually the case when your plugin's onEnable method is called by Bukkit, assuming you defined a dependency on BetonQuest.

BetonQuest always registers its default implementation with the Lowest ServicePriority. If you want to override a module you can register your own implementation with a higher priority. You also need to register your implementation before the onEnable method of BetonQuset is called, so usually in the onLoad method of your plugin:

Register a module

getServer().getServicesManager().register(BetonQuestLoggerFactory.class, new MyLoggerFactory(), this, ServicePriority.Normal);

Legacy API

Old method

The legacy API is how you could interact with BetonQuest in the past before the API was redesigned. For most systems that we haven't been able to improve, it is still the only option.
While it will still be available for the foreseeable future, you should not use it when writing new code working with API that has already been redesigned.

The old API uses the BetonQuest class as the entry point. Most methods are static and can be accessed directly. For those methods that need to be called on a BetonQuest instance you can obtain it by calling the static BetonQuest.getInstance() method.

All the old API is documented on the Legacy API page.

The ServicesManager Hint

The following hint can be found on many API pages:

ServicesManager API Classes

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

It lists all interfaces that are related to the API described on that page. Every one of them can be obtained by using the ServicesManager as described below.

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 BetonQuestLogger that was created by a BetonQuestLoggerFactory into a class implementing some feature.

public class MyAddon extends JavaPlugin {
    private BetonQuestLoggerFactory loggerFactory;

    @Override
    public void onEnable() {
        loggerFactory = Bukkit.getServicesManager().load(BetonQuestLoggerFactory.class);
        new MyFeature(loggerFactory.create(MyFeature.class));
    }
}

public class MyFeature {
    private final BetonQuestLogger log;

    public MyFeature(final BetonQuestLogger log) {
        this.log = log;
    }
}