SwoftyDataHandler

https://github.com/swofty-developments/swoftydatahandler
Admin
A reactive, type-safe data management library for Java applications that provides per-entity data...
Tokens:14,910
Snippets:75
Trust Score:9.5
Update:8 months ago
Show doc for...
Tokens:
Raw
### SwoftyDataHandler Quick Start in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Demonstrates the basic setup and usage of SwoftyDataHandler. It covers initializing a storage backend, creating the DataAPI, defining a player field, and performing basic data operations.

```java
// 1. Pick a storage backend
DataStorage storage = new InMemoryDataStorage();          // testing / ephemeral
DataStorage storage = new FileDataStorage(path, new JsonFormat()); // single-server
DataStorage storage = new RedisDataStorage("localhost", 6379);     // multi-server

// 2. Create the API
DataAPI api = new DataAPIImpl(storage);

// 3. Define fields
PlayerField<Integer> COINS = PlayerField.create("economy", "coins", Codecs.INT, 0);

// 4. Use it
UUID player = UUID.randomUUID();
api.set(player, COINS, 500);
api.update(player, COINS, c -> c + 100);
int coins = api.get(player, COINS); // 600
```

--------------------------------

### Instantiate Data Formats in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Provides examples of creating instances for JSON and Binary data formats. These formats implement the DataFormat interface and are used with storage backends.

```java
new JsonFormat()   // human-readable, good for debugging
new BinaryFormat() // compact, good for production
```

--------------------------------

### DataAPI Lifecycle Management (Initialization and Shutdown)

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Properly manage the lifecycle of the DataAPI and its associated storage backends. This Java example demonstrates initialization, event subscription, and graceful shutdown procedures.

```java
import net.swofty.data.DataAPI;
import net.swofty.data.DataAPIImpl;
import net.swofty.data.DataStorage;
import net.swofty.data.storage.RedisDataStorage;
import net.swofty.data.event.LinkChangeListener;
import net.swofty.data.event.LinkType;
import java.util.UUID;

public class GameDataManager {
    private final DataStorage storage;
    private final DataAPI api;

    public GameDataManager(String redisHost, int redisPort) {
        this.storage = new RedisDataStorage(redisHost, redisPort);
        this.api = new DataAPIImpl(storage);

        // Register event listeners
        api.subscribe(COINS, this::onCoinsChanged);
        api.subscribe(ISLAND, new LinkChangeListener<UUID>() {
            public void onLinked(UUID p, LinkType<UUID> t, UUID k) { /* ... */ }
            public void onUnlinked(UUID p, LinkType<UUID> t, UUID k) { /* ... */ }
        });
    }

    public DataAPI getApi() {
        return api;
    }

    public void shutdown() {
        // Shutdown API (stops timers, closes Pub/Sub)
        if (api instanceof DataAPIImpl impl) {
            impl.shutdown();
        }

        // Close storage connection
        if (storage instanceof RedisDataStorage redis) {
            redis.close();
        }
    }

    private void onCoinsChanged(UUID player, Integer oldVal, Integer newVal) {
        // Handle coin changes
    }
}

// Usage
// GameDataManager manager = new GameDataManager("localhost", 6379);
// DataAPI api = manager.getApi();
// ... use api ...
// manager.shutdown();  // Call on server shutdown
```

--------------------------------

### Data Serialization Formats (JSON and Binary)

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Utilize different data serialization formats for flexibility and efficiency. This Java example shows how to instantiate and use both JSON and Binary formats with DataAPI and various storage backends.

```java
import net.swofty.data.DataFormat;
import net.swofty.data.format.JsonFormat;
import net.swofty.data.format.BinaryFormat;
import net.swofty.data.storage.FileDataStorage;
import net.swofty.data.storage.RedisDataStorage;
import net.swofty.data.DataAPI;
import net.swofty.data.DataAPIImpl;
import net.swofty.data.DataStorage;

// Assuming 'path' is a valid file path string

// JSON format - human-readable, good for debugging
DataFormat jsonFormat = new JsonFormat();
DataStorage jsonFileStorage = new FileDataStorage(path, jsonFormat, ".json");
DataAPI jsonApi = new DataAPIImpl(jsonFileStorage, jsonFormat);

// Binary format - compact, efficient, good for production
DataFormat binaryFormat = new BinaryFormat();
DataStorage binaryFileStorage = new FileDataStorage(path, binaryFormat, ".dat");
DataAPI binaryApi = new DataAPIImpl(binaryFileStorage, binaryFormat);

// Both formats work with any storage backend
DataAPI redisJsonApi = new DataAPIImpl(new RedisDataStorage("localhost", 6379), new JsonFormat());
```

--------------------------------

### Bulk Data Operations with SwoftyDataHandler

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Perform bulk queries, counts, and updates on player data based on specified conditions. This Java example demonstrates finding, counting, and modifying data across all players efficiently.

```java
import java.util.function.Predicate;
import java.util.UUID;

// Assuming 'api' is an instance of DataAPI and COINS, LEVEL are defined fields

// Find players matching a condition
List<UUID> richPlayers = api.query(COINS, coins -> coins > 10000);
System.out.println("Found " + richPlayers.size() + " players with >10000 coins");

// Count matching players (more efficient than query().size())
int whaleCount = api.count(COINS, coins -> coins > 1000000);
System.out.println("Millionaires: " + whaleCount);

// Query linked data
List<UUID> activeIslands = api.queryLinked(ISLAND_LEVEL, level -> level > 5);
System.out.println("Active islands (level > 5): " + activeIslands.size());

// Bulk update all players
int playersUpdated = api.updateAll(COINS, coins -> coins + 100);  // Daily bonus
System.out.println("Gave 100 coins to " + playersUpdated + " players");

// Conditional bulk update
int fixedPlayers = api.updateWhere(
        COINS,
        coins -> coins < 0,           // Filter: negative balance
        coins -> 0                     // Update: reset to 0
);
System.out.println("Fixed " + fixedPlayers + " negative balances");

// Complex conditional update
api.updateWhere(
        LEVEL,
        level -> level >= 50,          // High-level players
        level -> Math.min(level + 5, 100)  // Bonus levels, capped at 100
);
```

--------------------------------

### Codecs: Data Serialization and Deserialization (Java)

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Illustrates the use of Codecs for serializing and deserializing data types in SwoftyDataHandler. It covers built-in primitive codecs, compound codecs for collections (List, Set, Map), nullable codecs, and provides examples of their usage with PlayerField and the API.

```java
import net.swofty.codec.Codec;
import net.swofty.codec.Codecs;
import net.swofty.PlayerField;
import java.time.Instant;
import java.util.*;

// Primitive codecs
PlayerField<Integer> INT_FIELD = PlayerField.create("ns", "int", Codecs.INT, 0);
PlayerField<Long> LONG_FIELD = PlayerField.create("ns", "long", Codecs.LONG, 0L);
PlayerField<Float> FLOAT_FIELD = PlayerField.create("ns", "float", Codecs.FLOAT, 0.0f);
PlayerField<Double> DOUBLE_FIELD = PlayerField.create("ns", "double", Codecs.DOUBLE, 0.0);
PlayerField<Boolean> BOOL_FIELD = PlayerField.create("ns", "bool", Codecs.BOOL, false);
PlayerField<String> STRING_FIELD = PlayerField.create("ns", "string", Codecs.STRING, "");
PlayerField<UUID> UUID_FIELD = PlayerField.create("ns", "uuid", Codecs.UUID, null);
PlayerField<Instant> INSTANT_FIELD = PlayerField.create("ns", "time", Codecs.INSTANT, Instant.EPOCH);

// Collection codecs
PlayerField<List<String>> FRIENDS = PlayerField.create(
        "social", "friends", Codecs.list(Codecs.STRING), new ArrayList<>());

PlayerField<Set<UUID>> BLOCKED = PlayerField.create(
        "social", "blocked", Codecs.set(Codecs.UUID), new HashSet<>());

PlayerField<Map<String, Integer>> SKILL_LEVELS = PlayerField.create(
        "rpg", "skills", Codecs.map(Codecs.STRING, Codecs.INT), new HashMap<>());

// Nullable codec for optional values
PlayerField<UUID> PARTY_ID = PlayerField.create(
        "party", "id", Codecs.nullable(Codecs.UUID), null);

// Usage
api.set(player, FRIENDS, List.of("Alice", "Bob", "Charlie"));
api.update(player, SKILL_LEVELS, skills -> {
    skills.put("mining", skills.getOrDefault("mining", 0) + 1);
    return skills;
});

```

--------------------------------

### Implementing Linked Fields (Shared Data) in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Demonstrates how to use Linked Fields in SwoftyDataHandler to manage data shared across multiple players. This involves defining player fields for link keys, link types, and the shared fields themselves, along with examples of linking players and accessing shared data.

```java
// 1. Define the player field that holds the link key
PlayerField<UUID> ISLAND_ID = PlayerField.create(
        "skyblock", "island_id", Codecs.nullable(Codecs.UUID), null);

// 2. Define the link type
LinkType<UUID> ISLAND = LinkType.create("island", Codecs.UUID, ISLAND_ID);

// 3. Define linked fields
// The first argument is the namespace (for storage key organization), not the link type.
// e.g. "island" + "level" -> storage key "island:level"
LinkedField<UUID, Integer> ISLAND_LEVEL = LinkedField.create(
        "island", "level", Codecs.INT, 1, ISLAND);
LinkedField<UUID, Long> ISLAND_BANK = LinkedField.create(
        "island", "bank", Codecs.LONG, 0L, ISLAND);

// 4. Link players and use shared data
UUID islandId = UUID.randomUUID();
api.link(player1, ISLAND, islandId);
api.link(player2, ISLAND, islandId);

api.set(player1, ISLAND_BANK, 1000L);
long bank = api.get(player2, ISLAND_BANK); // 1000 -- same data

// Direct access by link key -- useful when you have the key but not a player UUID,
// e.g. updating island data from a scheduled task or admin command
api.setDirect(islandId, ISLAND_LEVEL, 5);
```

--------------------------------

### SwoftyDataHandler Built-in Codecs in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Lists the built-in codecs provided by SwoftyDataHandler for common Java types, including primitive wrappers, String, UUID, and Instant. It also shows examples of creating compound codecs for collections and nullable types.

```java
Codecs.INT
Codecs.LONG
Codecs.FLOAT
Codecs.DOUBLE
Codecs.BOOL
Codecs.STRING
Codecs.UUID
Codecs.INSTANT

Codecs.list(Codecs.STRING)                   // List<String>
Codecs.set(Codecs.UUID)                      // Set<UUID>
Codecs.map(Codecs.STRING, Codecs.INT)        // Map<String, Integer>
Codecs.nullable(Codecs.UUID)                 // UUID (nullable)
```

--------------------------------

### Define and Use PlayerField for Per-Entity Data

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Illustrates how to define type-safe, per-player data fields using PlayerField. It covers simple field creation with codecs and default values, as well as using a builder pattern for more complex fields with validation. The example shows how to set, update, and retrieve field values, and how validation exceptions are handled.

```java
import net.swofty.PlayerField;
import net.swofty.codec.Codecs;
import net.swofty.validation.Validators;
import net.swofty.api.DataAPI;
import net.swofty.validation.ValidationException;
import java.util.UUID;

// Assuming 'api' is an initialized DataAPI instance
// DataAPI api = ...;

// Simple field creation
PlayerField<Integer> COINS = PlayerField.create("economy", "coins", Codecs.INT, 0);
PlayerField<String> NAME = PlayerField.create("profile", "name", Codecs.STRING, "");
PlayerField<Long> LAST_LOGIN = PlayerField.create("profile", "last_login", Codecs.LONG, 0L);

// Field with validation using builder pattern
PlayerField<Integer> LEVEL = PlayerField.<Integer>builder("rpg", "level")
        .codec(Codecs.INT)
        .defaultValue(1)
        .validator(Validators.range(1, 100))
        .build();

// Usage
UUID player = UUID.randomUUID();
api.set(player, COINS, 500);                    // Set value
api.update(player, COINS, c -> c + 100);        // Atomic update
int coins = api.get(player, COINS);             // Returns 600
int level = api.get(player, LEVEL);             // Returns default (1) if not set

// Validation throws ValidationException on invalid values
try {
    api.set(player, LEVEL, 150);                // Throws: Value must be between 1 and 100
} catch (ValidationException e) {
    System.err.println(e.getMessage());
}
```

--------------------------------

### Initialize DataAPI with Storage Backends

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Demonstrates how to initialize the DataAPI with different storage backends: in-memory for testing, file-based for single-server persistence, and Redis for multi-server deployments. It also shows how to configure Redis with a connection pool and custom key prefix. Remember to shut down the API and close the storage when done.

```java
import net.swofty.DataAPI;
import net.swofty.api.DataAPIImpl;
import net.swofty.storage.*;
import net.swofty.data.format.*;
import java.nio.file.Path;
import redis.clients.jedis.JedisPool;

// In-memory storage (testing/ephemeral)
DataStorage memoryStorage = new InMemoryDataStorage();
DataAPI api = new DataAPIImpl(memoryStorage);

// File-based storage (single-server persistence)
Path dataPath = Path.of("data/players");
DataStorage fileStorage = new FileDataStorage(dataPath, new JsonFormat(), ".json");
DataAPI api = new DataAPIImpl(fileStorage, new JsonFormat());

// Redis storage (multi-server with distributed events)
DataStorage redisStorage = new RedisDataStorage("localhost", 6379);
DataAPI api = new DataAPIImpl(redisStorage);

// Redis with connection pool and custom key prefix
JedisPool pool = new JedisPool("redis-host", 6379);
DataStorage redisStorage = new RedisDataStorage(pool, "myapp:data");
DataAPI api = new DataAPIImpl(redisStorage);

// Always shutdown when done
api.shutdown();
if (redisStorage instanceof RedisDataStorage rs) {
    rs.close();
}
```

--------------------------------

### Configuring File and Redis Storage in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Shows how to configure different storage backends for SwoftyDataHandler. This includes specifying custom formats and extensions for file storage, and setting up Redis with a connection pool or custom key prefix.

```java
// File storage with custom format and extension
new FileDataStorage(basePath, new JsonFormat(), ".json")
new FileDataStorage(basePath, new BinaryFormat(), ".dat")

// Redis with connection pool
JedisPool pool = new JedisPool("localhost", 6379);
new RedisDataStorage(pool)
new RedisDataStorage(pool, "myapp:data") // custom key prefix
```

--------------------------------

### Query Player Data in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Shows how to query players based on specific conditions for a given data type, count matching players, and query linked data.

```java
List<UUID> rich = api.query(COINS, coins -> coins > 10000);

int count = api.count(COINS, coins -> coins > 10000);

List<UUID> activeIslands = api.queryLinked(ISLAND_LEVEL, level -> level > 5);
```

--------------------------------

### Retrieve Leaderboard Entries in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Demonstrates fetching leaderboard entries by natural ordering, custom comparators, and pagination. It also shows how to retrieve linked leaderboard data.

```java
List<LeaderboardEntry<Integer>> top = api.getTop(COINS, 10);
for (LeaderboardEntry<Integer> entry : top) {
    System.out.println("#" + entry.rank() + " " + entry.playerId() + ": " + entry.value());
}

api.getTop(COINS, 10, Comparator.naturalOrder()); // ascending

Page<LeaderboardEntry<Integer>> page = api.getTopPaged(COINS, 1, 50);
page.content();       // entries for this page
page.page();          // current page number
page.totalPages();    // total pages
page.totalElements(); // total entries

api.getTopLinked(ISLAND_LEVEL, 10);
```

--------------------------------

### Leaderboard Queries and Pagination in Java

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Efficiently query and rank data across all players using bulk operations for leaderboards. Supports retrieving top entries, custom sorting with comparators, paginated results, and leaderboards for linked data.

```java
import net.swofty.LeaderboardEntry;
import net.swofty.Page;
import java.util.Comparator;

// Get top 10 players by coins (descending by default)
List<LeaderboardEntry<Integer>> topCoins = api.getTop(COINS, 10);
for (LeaderboardEntry<Integer> entry : topCoins) {
    System.out.printf("#%d %s: %d coins%n",
            entry.rank(), entry.playerId(), entry.value());
}

// Custom comparator (ascending order)
List<LeaderboardEntry<Integer>> lowestCoins = api.getTop(COINS, 10, Comparator.naturalOrder());

// Paginated leaderboards (1-indexed pages)
Page<LeaderboardEntry<Integer>> page1 = api.getTopPaged(COINS, 1, 50);
System.out.println("Page " + page1.page() + " of " + page1.totalPages());
System.out.println("Total players: " + page1.totalElements());
for (LeaderboardEntry<Integer> entry : page1.content()) {
    System.out.printf("#%d: %d coins%n", entry.rank(), entry.value());
}

// Next page
Page<LeaderboardEntry<Integer>> page2 = api.getTopPaged(COINS, 2, 50);

// Linked data leaderboards (e.g., top islands by level)
List<LeaderboardEntry<Integer>> topIslands = api.getTopLinked(ISLAND_LEVEL, 10);
```

--------------------------------

### Perform Bulk Data Updates in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Illustrates how to update data for all players or only for players matching a specific condition. This is useful for applying global bonuses or fixing data inconsistencies.

```java
int updated = api.updateAll(COINS, c -> c + 100); // daily bonus

int reset = api.updateWhere(COINS, c -> c < 0, c -> 0); // fix negative balances
```

--------------------------------

### Defining Player Fields in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Illustrates how to define player-specific data fields using SwoftyDataHandler. It covers simple field creation with default values and more complex fields with validation rules.

```java
PlayerField<Integer> COINS = PlayerField.create("economy", "coins", Codecs.INT, 0);
PlayerField<String> NAME  = PlayerField.create("profile", "name", Codecs.STRING, "");

// With validation
PlayerField<Integer> LEVEL = PlayerField.<Integer>builder("rpg", "level")
        .codec(Codecs.INT)
        .defaultValue(1)
        .validator(Validators.range(1, 100))
        .build();

api.set(player, COINS, 500);
api.update(player, COINS, c -> c + 100);
int coins = api.get(player, COINS);
```

--------------------------------

### Composable Validators for Player Fields in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Illustrates the creation of composable validators for player fields using a fluent API. It demonstrates setting codecs, default values, and chaining validators for complex validation rules.

```java
PlayerField<Integer> SCORE = PlayerField.<Integer>builder("game", "score")
        .codec(Codecs.INT)
        .defaultValue(0)
        .validator(Validators.nonNegative())
        .build();

PlayerField<String> NAME = PlayerField.<String>builder("profile", "name")
        .codec(Codecs.STRING)
        .defaultValue("")
        .validator(Validators.maxLength(32))
        .build();

// Chain validators with .and()
Validator<Integer> strict = Validators.nonNegative().and(Validators.range(0, 10000));
```

--------------------------------

### Data Formats

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Information on the available data serialization formats: JsonFormat and BinaryFormat.

```APIDOC
## Data Formats

### Description
The SwoftyDataHandler supports two primary data serialization formats: `JsonFormat` for human-readable output suitable for debugging, and `BinaryFormat` for compact, efficient data storage suitable for production environments. Both formats implement the `DataFormat` interface and can be used with any compatible storage backend.

### Usage
```java
// Using JsonFormat
DataFormat jsonFormat = new JsonFormat();

// Using BinaryFormat
DataFormat binaryFormat = new BinaryFormat();

// Example with a storage backend (assuming DataAPIImpl constructor takes DataFormat)
// DataAPI api = new DataAPIImpl(storage, jsonFormat);
```
```

--------------------------------

### Event Listeners for Data Changes in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Explains how to subscribe to data changes using event listeners, requiring a storage backend that supports listeners (e.g., Redis or InMemory). It covers listening to player field changes, linked field changes, link/unlink events, and expiration events.

```java
// Player field changes
api.subscribe(COINS, (player, oldValue, newValue) -> {
    System.out.println(player + ": " + oldValue + " -> " + newValue);
});

// Linked field changes (includes all affected players)
api.subscribe(ISLAND_LEVEL, (islandId, oldLevel, newLevel, affectedPlayers) -> {
    System.out.println("Island " + islandId + " leveled up, affecting " + affectedPlayers.size() + " players");
});

// Link/unlink events
api.subscribe(ISLAND, new LinkChangeListener<UUID>() {
    public void onLinked(UUID player, LinkType<UUID> type, UUID key) {
        System.out.println(player + " joined island " + key);
    }
    public void onUnlinked(UUID player, LinkType<UUID> type, UUID previousKey) {
        System.out.println(player + " left island " + previousKey);
    }
});

// Expiration events
api.subscribeExpiration(ACTIVE_BOOST, (player, field, expiredValue) -> {
    System.out.println(player + "'s boost expired: " + expiredValue);
});
```

--------------------------------

### Queries API

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Perform queries to find players matching specific conditions, count matching players, and query linked data.

```APIDOC
## Queries API

### Description
This API provides methods to query player data based on certain conditions. You can find players whose metric values satisfy a given predicate, count the number of such players, and query linked data based on conditions.

### Method
GET / POST

### Endpoint
`/queries/{metric}`
`/queries/linked/{metric}`

### Parameters
#### Path Parameters
- **metric** (string) - Required - The metric to query (e.g., COINS, ISLAND_LEVEL).

#### Query Parameters
- **predicate** (string) - Required - A predicate function to filter players (e.g., `coins -> coins > 10000`).

### Request Example
```java
// Find players with more than 10000 coins
List<UUID> richPlayers = api.query(COINS, coins -> coins > 10000);

// Count players with negative balances
int negativeBalanceCount = api.count(COINS, coins -> coins < 0);

// Find players with island level greater than 5
List<UUID> activeIslands = api.queryLinked(ISLAND_LEVEL, level -> level > 5);
```

### Response
#### Success Response (200)
- **playerIds** (List<UUID>) - A list of player UUIDs matching the query criteria.
- **count** (integer) - The total count of players matching the query criteria (for count queries).

#### Response Example
```json
{
  "playerIds": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ]
}
```
```

--------------------------------

### Atomic Transactions for Multi-Field Operations in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Demonstrates how to perform atomic multi-field operations using transactions, ensuring data consistency with rollback capabilities on abort. It covers operations with and without return values, and direct transactions on linked data.

```java
// With return value
int newBalance = api.transaction(player, tx -> {
    int coins = tx.get(COINS);
    int price = 500;
    if (coins < price) {
        tx.abort(); // rolls back all changes
    }
    tx.set(COINS, coins - price);
    tx.update(ITEMS, items -> items + 1);
    return coins - price;
});

// Without return value
api.transaction(player, tx -> {
    tx.update(COINS, c -> c + 100);
    tx.set(NAME, "NewName");
});

// Direct transaction on linked data
api.transactionDirect(islandId, ISLAND, tx -> {
    tx.update(ISLAND_BANK, bank -> bank - 1000L);
    return null;
});
```

--------------------------------

### Schema Migration with VersionedCodec in Java

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Handles schema changes with automatic migration chains, allowing data format evolution without data loss. It defines data structures for different versions and migration paths between them.

```java
import net.swofty.codec.versioning.VersionedCodec;

// Define versioned data classes
record V1Stats(int kills) {}
record V2Stats(int kills, int deaths) {}
record PlayerStats(int kills, int deaths, String rank) {}

// Create versioned codec with migration chain
VersionedCodec<PlayerStats> STATS_CODEC = VersionedCodec.builder(
        3,  // Current version
        reader -> new PlayerStats(
                reader.readInt(),
                reader.readInt(),
                reader.readString()
        ),
        (writer, stats) -> {
            writer.writeInt(stats.kills());
            writer.writeInt(stats.deaths());
            writer.writeString(stats.rank());
        }
)
    // Define how to read legacy versions
    .legacyReader(1, reader -> new PlayerStats(reader.readInt(), 0, "unranked"))
    .legacyReader(2, reader -> new PlayerStats(reader.readInt(), reader.readInt(), "unranked"))

    // Define migration paths (applied automatically when reading old data)
    .migrate(1, 2, v1 -> new PlayerStats(v1.kills(), 0, "unranked"))
    .migrate(2, 3, v2 -> new PlayerStats(v2.kills(), v2.deaths(), "unranked"))
    .build();

// Use in field definition
PlayerField<PlayerStats> PLAYER_STATS = PlayerField.create(
        "game", "stats", STATS_CODEC, new PlayerStats(0, 0, "unranked"));

// Reading v1 data automatically chains: v1 -> v2 -> v3
// Old data is seamlessly migrated on read
```

--------------------------------

### Bulk Operations - Leaderboards API

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Query and rank data across all players with efficient bulk operations. Supports retrieving top entries, paginated leaderboards, and leaderboards for linked data.

```APIDOC
## Bulk Operations - Leaderboards API

### Description
Query and rank data across all players with efficient bulk operations. Supports retrieving top entries, paginated leaderboards, and leaderboards for linked data.

### Method
`api.getTop(field, limit)`
`api.getTop(field, limit, comparator)`
`api.getTopPaged(field, page, size)`
`api.getTopLinked(field, limit)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import net.swofty.LeaderboardEntry;
import net.swofty.Page;
import java.util.Comparator;

// Get top 10 players by coins (descending by default)
List<LeaderboardEntry<Integer>> topCoins = api.getTop(COINS, 10);
for (LeaderboardEntry<Integer> entry : topCoins) {
    System.out.printf("#%d %s: %d coins%n",
            entry.rank(), entry.playerId(), entry.value());
}

// Custom comparator (ascending order)
List<LeaderboardEntry<Integer>> lowestCoins = api.getTop(COINS, 10, Comparator.naturalOrder());

// Paginated leaderboards (1-indexed pages)
Page<LeaderboardEntry<Integer>> page1 = api.getTopPaged(COINS, 1, 50);
System.out.println("Page " + page1.page() + " of " + page1.totalPages());
System.out.println("Total players: " + page1.totalElements());
for (LeaderboardEntry<Integer> entry : page1.content()) {
    System.out.printf("#%d: %d coins%n", entry.rank(), entry.value());
}

// Next page
Page<LeaderboardEntry<Integer>> page2 = api.getTopPaged(COINS, 2, 50);

// Linked data leaderboards (e.g., top islands by level)
List<LeaderboardEntry<Integer>> topIslands = api.getTopLinked(ISLAND_LEVEL, 10);
```

### Response
#### Success Response (200)
- **List<LeaderboardEntry<T>>**: A list of leaderboard entries, where T is the type of the field being ranked.
- **Page<LeaderboardEntry<T>>**: A paginated response containing a list of leaderboard entries and pagination information.

#### Response Example
```java
// Example for getTop
[{"rank":1,"playerId":"uuid-1","value":15000},{"rank":2,"playerId":"uuid-2","value":12000}]

// Example for getTopPaged
{
  "content": [
    {"rank":1,"playerId":"uuid-1","value":15000},
    {"rank":2,"playerId":"uuid-2","value":12000}
  ],
  "page": 1,
  "totalPages": 5,
  "totalElements": 200
}
```
```

--------------------------------

### Bulk Updates API

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Perform bulk updates on player data, including updating all players or only those matching specific criteria.

```APIDOC
## Bulk Updates API

### Description
This API allows for efficient bulk updates to player data. You can update all players' metric values or selectively update only those players whose current metric value satisfies a given condition.

### Method
POST

### Endpoint
`/bulk-updates/{metric}`

### Parameters
#### Path Parameters
- **metric** (string) - Required - The metric to update (e.g., COINS).

#### Query Parameters
- **updateFunction** (string) - Required - A function defining how to update the metric (e.g., `c -> c + 100`).
- **condition** (string) - Optional - A predicate function to filter which players to update (e.g., `c -> c < 0`).

### Request Example
```java
// Add 100 coins to all players
int updatedAll = api.updateAll(COINS, c -> c + 100);

// Reset negative balances to 0
int resetNegative = api.updateWhere(COINS, c -> c < 0, c -> 0);
```

### Response
#### Success Response (200)
- **updatedCount** (integer) - The number of players whose data was updated.

#### Response Example
```json
{
  "updatedCount": 500
}
```
```

--------------------------------

### API Lifecycle Management

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Instructions on how to properly shut down the API and associated storage resources.

```APIDOC
## API Lifecycle Management

### Description
Properly managing the lifecycle of the `DataAPI` is crucial to ensure resources are released and background processes are stopped gracefully. Always call the `shutdown()` method on the `DataAPI` instance when your application is terminating. If you are using Redis storage, you must also explicitly close the `RedisDataStorage` instance after shutting down the API.

### Methods
- **`api.shutdown()`**: Stops expiration timers and closes Pub/Sub subscribers associated with the API.
- **`storage.close()`**: Closes the connection to the Redis storage.

### Usage Example
```java
// Initialize storage and API
RedisDataStorage storage = new RedisDataStorage("localhost", 6379);
DataAPI api = new DataAPIImpl(storage);

// ... application logic ...

// Shut down the API and close storage when done
api.shutdown();
storage.close();
```
```

--------------------------------

### LinkedField: Share Player Data Across Multiple Players (Java)

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Demonstrates how to use LinkedField to share data among multiple players using a common key. It covers defining player fields, link types, linked fields, linking players, setting/getting shared data, direct access by link key, and managing link status. Requires Swofty library imports.

```java
import net.swofty.LinkedField;
import net.swofty.LinkType;
import net.swofty.PlayerField;
import net.swofty.codec.Codecs;
import java.util.Optional;
import java.util.UUID;

// Step 1: Define the player field that holds the link key
PlayerField<UUID> ISLAND_ID = PlayerField.create(
        "skyblock", "island_id", Codecs.nullable(Codecs.UUID), null);

// Step 2: Define the link type
LinkType<UUID> ISLAND = LinkType.create("island", Codecs.UUID, ISLAND_ID);

// Step 3: Define linked fields
LinkedField<UUID, Integer> ISLAND_LEVEL = LinkedField.create(
        "island", "level", Codecs.INT, 1, ISLAND);
LinkedField<UUID, Long> ISLAND_BANK = LinkedField.create(
        "island", "bank", Codecs.LONG, 0L, ISLAND);
LinkedField<UUID, String> ISLAND_NAME = LinkedField.create(
        "island", "name", Codecs.STRING, "Unnamed Island", ISLAND);

// Step 4: Link players to shared data
UUID islandId = UUID.randomUUID();
UUID player1 = UUID.randomUUID();
UUID player2 = UUID.randomUUID();

api.link(player1, ISLAND, islandId);
api.link(player2, ISLAND, islandId);

// Both players share the same data
api.set(player1, ISLAND_BANK, 1000L);
long bankFromPlayer2 = api.get(player2, ISLAND_BANK);  // Returns 1000L

// Direct access by link key (useful for admin commands, scheduled tasks)
api.setDirect(islandId, ISLAND_LEVEL, 5);
api.updateDirect(islandId, ISLAND_BANK, bank -> bank + 500L);
int level = api.getDirect(islandId, ISLAND_LEVEL);     // Returns 5

// Check and manage link status
Optional<UUID> linkedIsland = api.getLinkKey(player1, ISLAND);
api.unlink(player1, ISLAND);  // Player leaves island

```

--------------------------------

### Leaderboards API

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Retrieve leaderboard entries, supporting natural ordering, custom comparators, pagination, and linked leaderboards.

```APIDOC
## Leaderboards API

### Description
This API allows you to retrieve leaderboard data. You can get the top entries based on a natural descending order, specify a custom comparator for ascending or other orderings, fetch paginated results, and query linked leaderboards.

### Method
GET

### Endpoint
`/leaderboards/{metric}`

### Parameters
#### Path Parameters
- **metric** (string) - Required - The metric for which to retrieve leaderboard data (e.g., COINS, ISLAND_LEVEL).

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of entries to retrieve.
- **page** (integer) - Optional - The page number for paginated results (1-indexed).
- **pageSize** (integer) - Optional - The number of entries per page.
- **comparator** (string) - Optional - A comparator string for custom ordering (e.g., `naturalOrder` for ascending).

### Request Example
```java
// Get top 10 entries for COINS
List<LeaderboardEntry<Integer>> topCoins = api.getTop(COINS, 10);

// Get top 50 entries for ISLAND_LEVEL, page 2
Page<LeaderboardEntry<Integer>> islandPage = api.getTopPaged(ISLAND_LEVEL, 2, 50);

// Get top 10 entries for COINS with ascending order
List<LeaderboardEntry<Integer>> topAscending = api.getTop(COINS, 10, Comparator.naturalOrder());
```

### Response
#### Success Response (200)
- **content** (List<LeaderboardEntry>) - The list of leaderboard entries for the current page or request.
- **page** (integer) - The current page number (for paginated results).
- **totalPages** (integer) - The total number of pages available (for paginated results).
- **totalElements** (integer) - The total number of entries across all pages (for paginated results).

#### Response Example
```json
{
  "content": [
    {
      "rank": 1,
      "playerId": "player-uuid-1",
      "value": 15000
    },
    {
      "rank": 2,
      "playerId": "player-uuid-2",
      "value": 12000
    }
  ],
  "page": 1,
  "totalPages": 5,
  "totalElements": 250
}
```
```

--------------------------------

### Cross-Server Event Distribution with Redis in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Details how events are automatically distributed across server instances using Redis Pub/Sub when employing RedisDataStorage. This enables listeners on one server to react to changes made on another.

```java
// Server A
DataAPI apiA = new DataAPIImpl(new RedisDataStorage("redis-host", 6379));
apiA.set(player, COINS, 1000);

// Server B -- listener fires automatically
DataAPI apiB = new DataAPIImpl(new RedisDataStorage("redis-host", 6379));
apiB.subscribe(COINS, (p, old, nw) -> {
    // This fires when Server A changes the value
});
```

--------------------------------

### Shut Down API and Storage in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Demonstrates the correct procedure for shutting down the DataAPI and, if applicable, the RedisDataStorage to release resources and stop background processes.

```java
api.shutdown(); // stops expiration timers, closes Pub/Sub subscribers

RedisDataStorage storage = new RedisDataStorage("localhost", 6379);
DataAPI api = new DataAPIImpl(storage);
// ...
api.shutdown();
storage.close();
```

--------------------------------

### Maven Dependency for SwoftyDataHandler

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Adds the SwoftyDataHandler library to your project using Maven. Include the 'jedis' dependency if you plan to use Redis storage.

```xml
<dependency>
    <groupId>net.swofty</groupId>
    <artifactId>SwoftyDataHandler</artifactId>
    <version>VERSION</version>
</dependency>

<!-- Only if using Redis storage -->
<dependency>
    <groupId>redis.clients</groupId>
    <artifactId>jedis</artifactId>
    <version>5.2.0</version>
</dependency>
```

--------------------------------

### Gradle Dependency for SwoftyDataHandler

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Adds the SwoftyDataHandler library to your project using Gradle. Include the 'jedis' dependency if you plan to use Redis storage.

```groovy
dependencies {
    implementation 'net.swofty:SwoftyDataHandler:<version>'

    // Only if using Redis storage
    implementation 'redis.clients:jedis:5.2.0'
}
```

--------------------------------

### Expiring Fields with TTL in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Shows how to define and use expiring fields with automatic Time-To-Live (TTL) management. It covers setting default TTL, custom TTL, extending TTL, and checking expiration status.

```java
ExpiringField<String> ACTIVE_BOOST = ExpiringField.<String>expiringBuilder("game", "boost")
        .codec(Codecs.STRING)
        .defaultValue(null)
        .defaultTtl(Duration.ofMinutes(30))
        .build();

api.set(player, ACTIVE_BOOST, "double_xp");                   // uses default 30min TTL
api.set(player, ACTIVE_BOOST, "double_xp", Duration.ofHours(1)); // custom TTL
api.extend(player, ACTIVE_BOOST, Duration.ofMinutes(15));      // add time
api.getTimeRemaining(player, ACTIVE_BOOST);                    // Optional<Duration>
api.isExpired(player, ACTIVE_BOOST);                           // boolean

// Expired fields return their default value on get()
```

```java
ExpiringLinkedField<UUID, Integer> ISLAND_BUFF =
        ExpiringLinkedField.<UUID, Integer>expiringBuilder("island", "buff", ISLAND)
                .codec(Codecs.INT)
                .defaultValue(0)
                .defaultTtl(Duration.ofHours(2))
                .build();
```

--------------------------------

### Cross-Server Events (Redis)

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

With RedisDataStorage, events are automatically distributed across all server instances via Redis Pub/Sub, ensuring real-time synchronization.

```APIDOC
## Cross-Server Events (Redis)

### Description
With RedisDataStorage, events are automatically distributed across all server instances via Redis Pub/Sub, ensuring real-time synchronization. Changes made on one server are visible and trigger events on all other connected servers.

### Method
`new RedisDataStorage("redis-host", port)`
`api.subscribe(field, listener)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
// Server A - makes changes
DataAPI apiServerA = new DataAPIImpl(new RedisDataStorage("redis-host", 6379));
apiServerA.set(player, COINS, 1000);

// Server B - receives events automatically
DataAPI apiServerB = new DataAPIImpl(new RedisDataStorage("redis-host", 6379));
apiServerB.subscribe(COINS, (p, oldVal, newVal) -> {
    // This fires when Server A changes the value
    System.out.println("Coins updated on another server: " + newVal);
});

// Both servers share the same Redis backend
// Changes on one server are visible and trigger events on all others
```

### Response
#### Success Response (200)
Events are propagated automatically. No direct response is returned for event propagation.

#### Response Example
N/A
```

--------------------------------

### Versioned Codec for PlayerStats in Java

Source: https://github.com/swofty-developments/swoftydatahandler/blob/main/README.md

Defines a versioned codec for PlayerStats, enabling automatic schema migration chains for handling data evolution. It supports legacy readers and migration paths between versions.

```java
VersionedCodec<PlayerStats> STATS_CODEC = VersionedCodec.builder(
        3,
        reader -> new PlayerStats(reader.readInt(), reader.readInt(), reader.readString()),
        (writer, stats) -> {
            writer.writeInt(stats.kills());
            writer.writeInt(stats.deaths());
            writer.writeString(stats.rank());
        }
)
    .legacyReader(1, reader -> new V1Stats(reader.readInt()))
    .legacyReader(2, reader -> new V2Stats(reader.readInt(), reader.readInt()))
    .migrate(1, 2, v1 -> new V2Stats(v1.kills(), 0))
    .migrate(2, 3, v2 -> new PlayerStats(v2.kills(), v2.deaths(), "unranked"))
    .build();
```

--------------------------------

### Time-To-Live Data with ExpiringField in Java

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Provides fields with automatic time-to-live (TTL), suitable for temporary buffs, cooldowns, or time-limited states. It allows setting default TTLs, custom TTLs, and managing expiration.

```java
import net.swofty.ExpiringField;
import net.swofty.ExpiringLinkedField;
import java.time.Duration;

// Define expiring player field
ExpiringField<String> ACTIVE_BOOST = ExpiringField.<String>expiringBuilder("game", "boost")
        .codec(Codecs.STRING)
        .defaultValue(null)
        .defaultTtl(Duration.ofMinutes(30))
        .build();

ExpiringField<Boolean> PVP_IMMUNITY = ExpiringField.<Boolean>expiringBuilder("game", "pvp_immune")
        .codec(Codecs.BOOL)
        .defaultValue(false)
        .defaultTtl(Duration.ofSeconds(10))
        .build();

// Usage
UUID player = UUID.randomUUID();

api.set(player, ACTIVE_BOOST, "double_xp");                      // Uses default 30min TTL
api.set(player, ACTIVE_BOOST, "triple_coins", Duration.ofHours(1)); // Custom TTL

// TTL management
Optional<Duration> remaining = api.getTimeRemaining(player, ACTIVE_BOOST);
remaining.ifPresent(d -> System.out.println("Boost expires in: " + d.toMinutes() + " minutes"));

api.extend(player, ACTIVE_BOOST, Duration.ofMinutes(15));        // Add 15 minutes
boolean expired = api.isExpired(player, ACTIVE_BOOST);           // Check if expired

// Expired fields return their default value
String boost = api.get(player, ACTIVE_BOOST);  // Returns null if expired

// Expiring linked fields (shared expiring data)
ExpiringLinkedField<UUID, Integer> ISLAND_BUFF = ExpiringLinkedField
        .<UUID, Integer>expiringBuilder("island", "buff", ISLAND)
        .codec(Codecs.INT)
        .defaultValue(0)
        .defaultTtl(Duration.ofHours(2))
        .build();

api.set(player, ISLAND_BUFF, 50);  // 50% buff for 2 hours, shared across island members
```

--------------------------------

### Composable Validators for Data Constraints in Java

Source: https://context7.com/swofty-developments/swoftydatahandler/llms.txt

Enforces data constraints using composable validators, throwing ValidationException on invalid values. Validators can be chained using '.and()' for complex validation rules.

```java
import net.swofty.validation.Validator;
import net.swofty.validation.Validators;
import net.swofty.validation.ValidationException;

// Built-in validators
Validator<Integer> nonNegative = Validators.nonNegative();       // value >= 0
Validator<Integer> levelRange = Validators.range(1, 100);        // 1 <= value <= 100
Validator<String> nameLength = Validators.maxLength(32);         // string.length() <= 32

// Chain validators with .and()
Validator<Integer> strictScore = Validators.nonNegative().and(Validators.range(0, 10000));

// Apply to fields
PlayerField<Integer> SCORE = PlayerField.<Integer>builder("game", "score")
        .codec(Codecs.INT)
        .defaultValue(0)
        .validator(Validators.nonNegative())
        .build();

PlayerField<String> DISPLAY_NAME = PlayerField.<String>builder("profile", "display_name")
        .codec(Codecs.STRING)
        .defaultValue("")
        .validator(Validators.maxLength(32))
        .build();

// Validation happens automatically on set()
try {
    api.set(player, SCORE, -100);  // Throws ValidationException
} catch (ValidationException e) {
    System.err.println("Invalid score: " + e.getMessage());
}
```
Tokens:
Raw