# 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:

```java
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.

```java
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.

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

callbackManager.addConsumer(TNECallbacks.TRANSACTION_POST.toString(), (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:

```java
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:

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

#### Step 3: Add a Consumer

Add a consumer to handle the custom callback:

```java
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.
