Callbacks

Working with Callbacks in TheNewEconomy

TheNewEconomy (TNE) provides a robust callback system that allows developers to hook into specific points of the plugin's lifecycle. This is in place of using events because this allows TNE callbacks to be the same regardless of platform, whether it's Spigot, Paper, Folia, or Sponge. Callbacks enable you to extend functionality, integrate with external systems, or monitor critical events.

---

Overview

What is a Callback?

A Callback represents a specific event or action that can trigger custom logic. Each callback is associated with a name identifier and a set of consumers (functions) that handle the event.

---

Registering a Callback Consumer

To add a consumer to handle its events, you only need a few lines of code:

callbackManager.addConsumer(TNECallbacks.ACCOUNT_TYPES.id(), (callback -> {
  // Custom logic here
}));

---

Default Callbacks in TNE

Account Callbacks

Callback Name	Description
ACCOUNT_TYPES	Triggered when account types are loaded.
ACCOUNT_LOAD	Triggered when an account is loaded.
ACCOUNT_SAVE	Triggered when an account is saved.
ACCOUNT_CREATE	Triggered when a new account is created.
ACCOUNT_DELETE	Triggered when an account is deleted.

Transaction Callbacks

Callback Name	Description
TRANSACTION_PRE	Triggered before a transaction is executed.
TRANSACTION_POST	Triggered after a transaction is processed.

Currency Callbacks

Callback Name	Description
CURRENCY_DROP	Triggered when a currency is removed.
CURRENCY_LOAD	Triggered when currencies are loaded.
DENOMINATION_LOAD	Triggered when denominations are loaded.

---

Example: PreTransactionCallback

The PreTransactionCallback is invoked before a transaction is executed, allowing you to cancel the transaction if needed.

import net.tnemc.core.transaction.Transaction;
import net.tnemc.core.api.callback.transaction.PreTransactionCallback;

callbackManager.addConsumer(TNECallbacks.TRANSACTION_PRE.id(), (callback -> {
  PreTransactionCallback preCallback = (PreTransactionCallback) callback;

  Transaction transaction = preCallback.getTransaction();
  if (transaction.getAmount().compareTo(new BigDecimal("1000.00")) > 0) {
    return true; // Cancels the transaction
  }
  return false;
}));

---

Example: PostTransactionCallback

The PostTransactionCallback is invoked after a transaction has been processed. This is ideal for logging or analytics.

import net.tnemc.core.transaction.TransactionResult;
import net.tnemc.core.api.callback.transaction.PostTransactionCallback;

callbackManager.addConsumer(TNECallbacks.TRANSACTION_POST.id(), (callback -> {
  PostTransactionCallback postCallback = (PostTransactionCallback) callback;

  TransactionResult result = postCallback.result();
  // Log the transaction result
  return false; // Cannot cancel at this stage
}));

---

Creating Custom Callbacks

Step 1: Implement the Callback Interface

Define a custom callback by implementing the Callback interface:

import net.tnemc.plugincore.core.api.callback.Callback;

public class CustomCallback implements Callback {

  private final String data;

  public CustomCallback(String data) {
    this.data = data;
  }

  @Override
  public String name() {
    return "custom_callback";
  }

  public String getData() {
    return data;
  }
}

Step 2: Register the Custom Callback

Use the PluginCore to register your custom callback:

PluginCore.callbacks().addCallback("custom_callback", new CallbackEntry(CustomCallback.class));

Step 3: Add a Consumer

Add a consumer to handle the custom callback:

callbackManager.addConsumer("custom_callback", (callback -> {
  CustomCallback custom = (CustomCallback) callback;
  // Process the callback data
  return false;
}));

---

Key Components of the Callback System

CallbackManager

Manages all callbacks, including registration and execution.

CallbackEntry

Represents a single callback and its associated consumers.

TNECallbacks

An enumeration of all default callback names.

---

Notes

1. Callback Registration: Callbacks must be registered before adding consumers.

2. Cancellability: Only certain callbacks, like TRANSACTION_PRE, can be canceled.

3. Extensibility: Custom callbacks allow seamless integration with external systems.

---

By leveraging TNE's callback system, you can build powerful extensions and enhance the plugin’s functionality.