Package dev.polv.taleapi.permission

Interface PermissionProvider

All Known Implementing Classes:
DefaultPermissionProvider
public interface PermissionProvider
Service Provider Interface (SPI) for permission backends.

This interface defines the contract for permission providers. The game engine provides a default JSON-based implementation, but third-party plugins (like a custom plugin) can register their own high-performance SQL/Redis-backed provider.

SPI Pattern

The Game Engine defines the Contract (Interface), but does not force a Strategy (Implementation). This allows hot-swapping the permission backend without changing any game code.

Implementation Requirements

  • Providers must be thread-safe
  • Query operations should be fast (preferably cached)
  • Load/save operations may be async
See Also:

  • Method Details

    • getId

      String getId()
      Returns the unique identifier for this provider.

      Examples: "default", "mysql", "redis"

      Returns:
      the provider identifier

    • getName

      String getName()
      Returns a human-readable name for this provider.
      Returns:
      the provider name

    • query

      PermissionResult query(TalePlayer player, String key)
      Queries a permission for a player.

      This is the primary query method. It should return quickly, preferably from a cached permission tree.

      Parameters:
      player - the player to check
      key - the permission key
      Returns:
      the permission result

    • query

      PermissionResult query(TalePlayer player, String key, ContextSet context)
      Queries a permission for a player with context.

      Context-aware permissions allow different results based on world, server, gamemode, or custom conditions.

      Parameters:
      player - the player to check
      key - the permission key
      context - the context to check against
      Returns:
      the permission result

    • getPlayerTree

      PermissionTree getPlayerTree(TalePlayer player)
      Gets the cached permission tree for a player.

      This returns the player's flattened permission tree, which can be queried directly for maximum performance.

      Parameters:
      player - the player
      Returns:
      the player's permission tree, or null if not loaded

    • setPermission

      CompletableFuture<Void> setPermission(TalePlayer player, PermissionNode node)
      Sets a permission for a player.
      Parameters:
      player - the player
      node - the permission node to set
      Returns:
      a future that completes when the permission is saved

    • removePermission

      CompletableFuture<Void> removePermission(TalePlayer player, String key)
      Removes a permission from a player.
      Parameters:
      player - the player
      key - the permission key to remove
      Returns:
      a future that completes when the permission is removed

    • getClientSyncedNodes

      Set<String> getClientSyncedNodes(TalePlayer player)
      Returns the permission nodes that should be synced to the client.

      This is used for client-side UI prediction. Only permissions that affect UI should be included (e.g., "ui.button.admin").

      Parameters:
      player - the player
      Returns:
      a set of permission keys to sync

    • loadPlayer

      CompletableFuture<Void> loadPlayer(TalePlayer player)
      Called when a player joins the server.

      Implementations should load and cache the player's permissions here.

      Parameters:
      player - the player who joined
      Returns:
      a future that completes when loading is done

    • unloadPlayer

      void unloadPlayer(TalePlayer player)
      Called when a player leaves the server.

      Implementations should clean up any cached data here.

      Parameters:
      player - the player who left

    • invalidateCache

      CompletableFuture<Void> invalidateCache(TalePlayer player)
      Invalidates the cached permissions for a player.

      Called when permissions are externally modified and need to be reloaded.

      Parameters:
      player - the player to invalidate
      Returns:
      a future that completes when the cache is refreshed

    • onEnable

      default void onEnable()
      Called when this provider is registered with the permission service.

      Use this for initialization (database connections, etc.).

    • onDisable

      default void onDisable()
      Called when this provider is unregistered or the server shuts down.

      Use this for cleanup (closing connections, saving data).