Advanced usage

Changing how UUID lookups work (Unstable API!)

Speaking of UUID lookups, it is possible to change the behaviour of UUID lookups, but this api design is NOT FINAL and MAY CHANGE AT ANY TIME. If you use these APIs, it is strongly recommended that you maintain your own fork of InvSee++.

Having said that, let us see some code samples. The snippet below shows how to obtain the lookuper:

InvseeAPI api = ...
NamesAndUUIDs lookup = api.namesAndUuidsLookup();

Now, the lookuper maintains two lists of resolving strategies that are used internally: uuidResolveStrategies and nameResolveStrategies. Both follow the same pattern: UUIDResolveStrategy tries to resolve a UUID for a given username, and NameResolveStrategy tries to resolve a username for a given UUID. InvSe++ just traverses these lists from front to back, until a strategy succeeds. A collection of built-in strategies can be found here.

At the time of writing, the order of strategies is as follows:

1. Get it from the player in case they are online.
2. If step 1 didn't succeed, get it from the cache of recenly logged out players.
3. If step 2 didn't succeed, get it from the offline player cache in Paper-api enabled servers.
4. If step 3 didn't succeed, get it from the permission plugin (supports LuckPerms, GroupManager, BungeePerms and UltraPermissions).
5. If step 4 didn't succeed, get it from the proxy server using plugin messages (supports BungeeCord and Velocity).
6. If step 5 didn't succeed, get it by making a REST api call to Mojang.
7. If step 6 didn't succeed, get it from the player save files directly.

Say for example, that you are running your own player database, you could implement your own custom strategy:

package com.example;

import com.janboerman.invsee.spigot.api.resolve.UUIDResolveStrategy;
import java.sql.*;
import java.util.concurrent.*;
import java.util.*;

public class DatabaseStrategy implements UUIDResolveStrategy {

    private final DataSource session; //hikari data source, or whatever
    private final Executor async;

    public DatabaseStrategy(DataSource session, Executor async) {
        this.session = session;
        tins.async = async
    }

    @Override
    public CompletableFuture<Optional<UUID>> resolveUniqueId(String userName) {
        //hypothetical SQL example
        return CompletableFuture.supplyAsync(() -> {
            try (Connection connection = session.getConnection();
                PreparedStatement statement = connection.prepareStatement("SELECT uuid FROM users WHERE name = ?;")) {
                statement.setString(1, userName);
                try (ResultSet resultSet = statement.executeQuery()) {
                    UUID found = null;
                    while (resultSet.next()) {
                        if (found == null) {
                            found = (UUID) resultSet.getObject(1);
                        } else {
                            //duplicate
                            return Optional.empty();
                        }
                    }
                    return Optional.ofNullable(found);
                }
            }
        }, async);
    }

}

And then you could add this to the list of UUID resolve strategies:

MyPlugin myPlugin = ...
InvseeAPI api = ...
NamesAndUUIDs lookup = api.namesAndUuidsLookup();
DataSource session = myPlugin.getSession();

List<UUIDResolveStrategy> uuidResolveStrategies = lookup.uuidResolveStrategies;
uuidResolveStrategies.add(3, new DatabaseStrategy(session, api.getScheduler()::executeAsync));

This would ensure that InvSee++ attempts to use the DatabaseStrategy after it tried to get it from an online player, recently logged out players, or Paper's cache, but before it tries to attempt to obtain the UUID via the permission plugin.

NamesAndUUIDs maintains an internal cache (currently hardcoded to a maximum size of 200), so you do not need to handle that yourself.