BKCommonLib/PluginBase

« Go back

Introduction

For more information, see also:

• Localization
• Permission Defaults
• Metrics

PluginBase is a basic JavaPlugin base class that eases the use of Localization, Permissions, error handling, logging and more. The base implementation takes care of a lot of things going on in the background, including a BKCommonLib compatibility check.

Features

All common plugin routines are taken care of. They will all be listed below. To use PluginBase in your plugin, simply instantiate it as follows:

public class MyPlugin extends PluginBase {
    @Override
    public void enable() {
        // Enable logic
    }

    @Override
    public void disable() {
        // Disable logic
    }

    @Override
    public boolean command(CommandSender sender, String command, String[] args) {
        return false;
    }

    @Override
    public int getMinimumLibVersion() {
        return Common.VERSION;
    }
}

BKCommonLib routines

getMinimumLibVersion() has to be overrided when using this base class. This method tells BKCommonLib the minimum version this plugin supports, so a proper message can be sent to the end-user if BKCommonLib is outdated. This avoids needless dependency-related issues.

Localization

The localization() method is called before enabling and can be used to load Locale information to read/write from/to the Localization.yml. You can load single localization lines or an entire enumeration of them using the loadLocale and loadLocales methods. Examples:

Loading localization lines one by one

@Override
public void localization() {
    loadLocale("noperm", ChatColor.RED + "You do not have permission!");
    loadLocale("nobuild", ChatColor.RED + "You can not build here!");
}

Loading localization lines from a class containing constants, or an enum

@Override
public void localization() {
    loadLocales(MyLocale.class);
}

public class MyLocale extends LocalizationEnum {
    public static final MyLocale NOPERM = new MyLocale("noperm", ChatColor.RED + "You do not have permission!");
    public static final MyLocale NOBUILD = new MyLocale("nobuild", ChatColor.RED + "You can not build in world %0%!");

    private Localization(String name, String defValue) {
        super(name, defValue);
    }

    @Override
    public String get(String... arguments) {
        return MyPlugin.getInstance().getLocale(this.getName(), arguments);
    }
}

The benefit of using a Locale class like the above is that you do not have to use getLocale(name), allowing you to get localization messages a lot easier. For example:

MyLocale.NOPERM.message(player);
MyLocale.NOBUILD.message(player, player.getWorld().getName());

Permission defaults

It works exactly the same way localization works, but instead you override permissions() and use the loadPermission and loadPermissions methods. The equivalent enumeration class to use is called PermissionEnum. This enumeration automatically provides methods for permission checks, such as handle and has.

Commands

BKCommonLib automatically gives you the name version command to display the currently running plugin and BKCommonLib version. It also takes care of permission issues, by using and handling the NoPermissionException. If this is thrown for the console, a message is displayed that the command is not possible for use in the console.

Dependencies

The updateDependency method is called whenever a new plugin enables, and after your plugin has enabled it calls it once for all currently enabled plugins. It allows you to keep track of dependencies, or to change some internal settings to provide support.

Metrics

You can automatically use Metrics by adding the following in the plugin.yml:

metrics: true

By default this is disabled. To use Metrics, call the provided hasMetrics and getMetrics methods. There is no need to start the Metrics instance when enabling, PluginBase does that for you. For more information about Metrics, see this page.

Other

• handle allows you to handle errors occurring in your plugin, which takes care of proper formatting and plugin disabling for critical errors
• log and logAction uses the plugin's logger to write messages, it's a simple shortcut
• register methods allow you to register Bukkit or packet listeners, and to register commands/commandhandlers
• getDataFile obtains a File object pointing to a file relative to the plugin 'workspace' directory
• Properly disables other plugins depending on you before your plugin disables to avoid conflicts
• Handles enable, disable and command method errors automatically