HuskSync/docs/UserData-API.md

HuskSync provides an API for fetching and retrieving UserData; a snapshot of a user's synchronization.

This page assumes you've read the API introduction and have imported the HuskSync API into your repository.

Table of contents

1. Creating a class to interface with the API
2. Checking if HuskSync is present and creating the hook
3. Getting an instance of the API
4. Getting a user by UUID
5. Getting a user's data
6. Getting a user's data
7. Getting a user's inventory contents
8. Updating a user's data

1. Creating a class to interface with the API

• Unless your plugin completely relies on HuskSync, you shouldn't put HuskSync API calls into your main class, otherwise if HuskSync is not installed you'll encounter ClassNotFoundExceptions

public class HuskSyncAPIHook {

    public HuskSyncAPIHook() {
        // Ready to do stuff with the API
    }

}

2. Checking if HuskSync is present and creating the hook

• Check to make sure the HuskSync plugin is present before instantiating the API hook class

public class MyPlugin extends JavaPlugin {

    public HuskSyncAPIHook huskSyncAPIHook;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().getPlugin("HuskSync") != null) {
            this.huskSyncAPIHook = new HuskSyncAPIHook();
        }
    }
}

3. Getting an instance of the API

• You can now get the API instance by calling HuskSyncAPI#getInstance()

import net.william278.husksync.api.HuskSyncAPI;

public class HuskSyncAPIHook {

    private final HuskSyncAPI huskSyncAPI;

    public HuskSyncAPIHook() {
        this.huskSyncAPI = HuskSyncAPI.getInstance();
    }

}

4. CompletableFuture and Optional basics

• HuskSync's API methods return CompletableFutures and Optionals.
• A CompletableFuture is an asynchronous callback mechanism. The method will be processed asynchronously and the data returned when it has been retrieved. While you can use CompletableFuture#join() to block the thread until the future has finished processing, it's smarter to use CompletableFuture#thenAccept(data -> {}) to do what you want to do with the data you requested after it has asynchronously been retrieved, to prevent lag.
• An Optional is a null-safe representation of data, or no data. You can check if the Optional is empty via Optional#isEmpty() (which will be returned by the API if no data could be found for the call you made). If the optional does contain data, you can get it via Optional#get().

5. Getting a user by UUID

• HuskSync has a User object, representing a user saved in the database. You can retrieve a user using HuskSyncAPI#getUser(uuid)
• If you have an online org.bukkit.Player object, you can use BukkitPlayer#adapt(player) to get an OnlineUser (extends User), representing a logged-in user.

public class HuskSyncAPIHook {

    private final HuskSyncAPI huskSyncAPI;

    public HuskSyncAPIHook() {
        this.huskSyncAPI = HuskSyncAPI.getInstance();
    }
    

    public void logUserName(UUID uuid) {
        // getUser() returns a CompletableFuture supplying an Optional<User>
        huskSyncAPI.getUser(uuid).thenAccept(optionalUser -> {
            // Check if we found a user by that UUID either online or on the database
            if (optionalUser.isEmpty()) {
                // If we didn't, we'll log that they don't exist
                System.out.println("User does not exist!");
                return;
            }
            // The User object has two fields; uuid and username.
            System.out.println("User name is: " + optionalUser.get().username);
        });
    }

}

6. Getting a user's data

• With a User object, we can now call HuskSyncAPI#getUserData() to fetch their latest data
• The UserData object contains eight data "modules", each holding certain parts of information.
• UserData does not have to contain any single data "module"; the modules contained in a given UserData object when user data is saved by the plugin are determined by the plugin config settings.
• You can fetch each module, which returns wrapped in an optional (empty if not present in the UserData object), via:
  • UserData#getStatus(); - The user's status (health, hunger, saturation, exp, game mode, etc)
  • UserData#getInventory(); - The user's inventory contents. Contains a Base 64 serialized ItemStack array.
  • UserData#getEnderChest(); - The user's ender chest contents. Contains a Base 64 serialized ItemStack array.
  • UserData#getPotionEffects(); - The user's active potion effects. Contains a Base 64 serialized PotionEffect array.
  • UserData#getAdvancements(); - List of a user's advancements and mapped awarded criteria
  • UserData#getStatistics(); - The user's statistics data containing four categories (untyped, items, blocks and entities)
  • UserData#getLocation(); - The user's location data, for servers that have location syncing turned on.
  • UserData#getPersistentDataContainer(); - The user's peristent data container, containing a map of keys to strings

public class HuskSyncAPIHook {

    // ... //

    public void logUserData(UUID uuid) {
        huskSyncAPI.getUser(uuid).thenAccept(optionalUser -> {
            // Optional#isPresent() is the opposite of #isEmpty()
            if (optionalUser.isPresent()) {
                logHealth(optionalUser.get());
            }
        });
    }

    private void logHealth(User user) {
        // A user might not have data, if it's deleted by an admin or they're brand new
        huskSyncAPI.getUserData(user).thenAccept(optionalUserData -> {
            if (optionalUserData.isPresent()) {
                // Get the StatusData from the UserData object
                Optional<StatusData> statusData = optionalUserData.get().getStatus();
                // Print the health from the fields, if the user has a status object
                statusData.ifPresent(status -> {
                    System.out.println(user.username + "'s health: " + status.health + "/" + status.maxHealth);
                });
            }
        });
    }

}

7. Getting a user's inventory contents

• The API provides methods for deserialzing ItemData used to hold Base 64 serialized inventory and ender chest ItemStack array contents into actual ItemStack array data.
• For deserialziing inventories, use HuskSyncAPI#deserializeInventory(serializedItems)
• For deserialziing ender chests, use HuskSyncAPI#deserializeItemStackArray(serializedItems)
• Alternatively, the HuskSyncAPI#getPlayerInventory(user) and HuskSyncAPI#getPlayerEnderChest(user) methods will do this for you nice and easily. Note though if the last UserData module does not contain UserData, the ItemData returned here will be representative of an empty ItemStack array.
• Serialization and deserialization methods are also available for Potion Effects.

public class HuskSyncAPIHook {

    // ... //

    private void printInventoryItems(User user) {
        huskSyncAPI.getUserData(user).thenAccept(optionalUserData -> {
            if (optionalUserData.isPresent()) {
                // Get the ItemData and make sure it's present
                Optional<ItemData> inventoryDataOptional = optionalUserData.get().getInventory();
                if (inventoryDataOptional.isEmpty) {
                    return;
                }
                ItemData inventoryData = inventoryDataOptional.get();

                // Get the ItemStack[] array as a BukkitInventoryMap.
                // This returns a future, but we're using #join() to block the thread until it's done
                BukkitInventoryMap inventory = huskSyncAPI.deserializeInventory(inventoryData.serializedItems).join();
                
                // A BukkitInventoryMap is simply a wrapper for an ItemStack array.
                // It provides a few handy methods for getting the player's armor, their offhand item, etc.
                // To get the ItemStack array from it, just call BukkitInventoryMap#getContents();
                for (ItemStack item : inventory.getContents()) {
                    // Print out the item material types of every item in the player's inventory
                    System.out.println(item.getType().name());
                }
            }
        });
    }

}

HuskSyncAPI#getPlayerInventory()

private void printInventoryItems(User user) {
    huskSyncAPI.getPlayerInventory(user).thenAccept(inventory -> {
        if (inventory.isPresent()) {
            for (ItemStack item : inventory.get().getContents()) {
                System.out.println(item.getType().name());
            }
        }
    });
}

HuskSyncAPI#getPlayerEnderChest()

private void printEnderChestItems(User user) {
    huskSyncAPI.getPlayerEnderChest(user).thenAccept(enderChest -> {
        if (enderChest.isPresent()) {
            for (ItemStack item : enderChest.get()) {
                System.out.println(item.getType().name());
            }
        }
    });
}

8. Updating a user's data

• You can use HuskSyncAPI#setUserData(user, userData) to set a user's modified data to the database.
• If you need to modify user data every time it's updated, you may want to look at listening to one of HuskSync's provided events instead.
• You can use HuskSyncAPI#serializeItemStackArray(itemStack[]) to serialize an array of ItemStacks into Base 64.
• Alternatively, you can use HuskSyncAPI#setInventoryData(user, bukkitInventoryMap) to set a user's inventory, or HuskSyncAPI#setEnderChestData(user, itemStack[]) to set a user's ender chest.
• Updating UserData will overwrite the player's current "live" data. HuskSync does not track the player's "live" data constantly by design, only "snapshots" of their data when it is saved. In other words, getting and updating a user's data may actually end up rolling them back.

public class HuskSyncAPIHook {

    // Set a user's health to 20
    private void updateUserHealth(User user) {
        huskSyncAPI.getUserData(user).thenAccept(optionalUserData -> {
            if (optionalUserData.isPresent()) {
                UserData data = optionalUserData.get();
                Optional<StatusData> statusDataOptional = data.getStatus();
                StatusData statusData = statusDataOptional.get();            
                statusData.health = 20;
    
                // This returns a CompletableFuture<Void> that will invoke #thenRun() when it has completed
                huskSyncAPI.setUserData(user, data).thenRun(() -> {
                    System.out.println("Healed " + user.username + "!");
                });
            }
        });
    }

}