Skip to content

Using callbacks

Callbacks are a modern replacement for Bukkit's events. They are multi-platform and can be intercept and modified by using handlers or listeners.

  • Handlers provide access to the callback's object so that it can be handled, hence the name.
  • Listeners give access to the object's parameters, which are mirrored from the callback's constructor and passed to the listener when a callback is handled. Listeners cannot modify the object at all, they just listen to the result.

Source: callbacks at GitHub

In short, if you want to modify the event you'll want to use a handler. On the other hand, if you're only listening to the event, you'll use a listener (which comes with performance benefits!).

Registering a handler

Let's register a handler for the BancoTransactionProcessCallback. We'll add 1$ to each transaction, just as a demonstration:

var instance = BancoTransactionProcessCallback.INSTANCE;
var identifier = "plugin:handler-name"; // The NAMESPACED identifier for our handler. We recommend using your plugin's name and a descriptive handler namre

instance.registerHandler(identifier, callback -> {
    var addedAmount = BigDecimal.valueOf(1);
    BigDecimal transactionAmount = callback.transaction().amount();

    callback.transaction().amount(transactionAmount.add(addedAmount));
});

Registering a listener

Now let's do the same with a listener, except we'll print the transaction instead of modifying the event. We'll also use a proper IdentifierKey instead of a namespaced string, just to show a different approach:

var instance = BancoTransactionProcessCallback.INSTANCE; // The instance of the callback
var key = IdentifierKey.of("plugin-name", "listener-name");

instance.registerListener(key, (transaction, cancelled) -> {
    if (!cancelled) {
        System.out.println(transaction.toString());
    }
});

Warning

Don't forget that listeners cannot modify the event in any way. You'll want to use handlers for that.