Package dev.polv.taleapi.permission

Class PermissionService

java.lang.Object
dev.polv.taleapi.permission.PermissionService
public final class PermissionService extends Object
The main entry point for the permission system.

PermissionService acts as a facade over the active PermissionProvider. It handles provider registration, query routing, and event firing.

SPI Architecture

                ┌──────────────────────┐
                │  PermissionService   │  ← Public API
                │    (Facade)          │
                └──────────┬───────────┘
                           │
            ┌──────────────┴──────────────┐
            ▼                             ▼
    ┌───────────────┐             ┌───────────────┐
    │DefaultProvider│             │ Custom Plugin │
    │   (JSON)      │             │   Provider    │
    └───────────────┘             └───────────────┘

The Hook

After the provider calculates the result, a PermissionCheckCallback event fires. This allows plugins to temporarily override permissions (e.g., "Deny all commands during a minigame match").

Example Usage


 // Query a simple permission
 if (permService.query(player, "plots.claim").isAllowed()) {
     // Player can claim plots
 }

 // Query a permission with payload (dynamic limit)
 int maxPlots = permService.query(player, "plots.limit").asInt(1);

 // Context-aware query
 ContextSet context = ContextSet.of(ContextKey.WORLD, "creative");
 if (permService.query(player, "build.creative", context).isAllowed()) {
     // Player can build in creative world
 }
See Also:

  • Method Details

    • getInstance

      public static PermissionService getInstance()
      Returns the singleton instance of the permission service.
      Returns:
      the permission service

    • setProvider

      public void setProvider(PermissionProvider newProvider)
      Registers a permission provider.

      If a provider is already registered, it will be disabled and replaced.

      Parameters:
      newProvider - the provider to register
      Throws:
      NullPointerException - if provider is null

    • getProvider

      public PermissionProvider getProvider()
      Returns the currently active provider.
      Returns:
      the active provider, or null if none registered

    • hasProvider

      public boolean hasProvider()
      Checks if a provider is registered.
      Returns:
      true if a provider is active

    • query

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

      This method:

      1. Delegates to the active provider
      2. Fires a PermissionCheckCallback event
      3. Returns the (possibly modified) result
      Parameters:
      player - the player to check
      key - the permission key
      Returns:
      the permission result
      Throws:
      IllegalStateException - if no provider is registered

    • query

      public PermissionResult query(TalePlayer player, String key, ContextSet context)
      Queries a permission for a player with context.
      Parameters:
      player - the player to check
      key - the permission key
      context - the context to check against
      Returns:
      the permission result
      Throws:
      IllegalStateException - if no provider is registered

    • has

      public boolean has(TalePlayer player, String key)
      Convenience method to check if a permission is allowed.
      Parameters:
      player - the player to check
      key - the permission key
      Returns:
      true if the permission is ALLOW

    • has

      public boolean has(TalePlayer player, String key, ContextSet context)
      Convenience method to check if a permission is allowed with context.
      Parameters:
      player - the player to check
      key - the permission key
      context - the context
      Returns:
      true if the permission is ALLOW

    • getPlayerTree

      public PermissionTree getPlayerTree(TalePlayer player)
      Gets the cached permission tree for a player.
      Parameters:
      player - the player
      Returns:
      the player's permission tree
      Throws:
      IllegalStateException - if no provider is registered

    • setPermission

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

    • removePermission

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

    • getClientSyncedNodes

      public Set<String> getClientSyncedNodes(TalePlayer player)
      Returns permission keys to sync to the client.
      Parameters:
      player - the player
      Returns:
      set of client-synced permission keys

    • loadPlayer

      public CompletableFuture<Void> loadPlayer(TalePlayer player)
      Called when a player joins. Loads their permissions.
      Parameters:
      player - the player
      Returns:
      future completing when loaded

    • unloadPlayer

      public void unloadPlayer(TalePlayer player)
      Called when a player leaves. Unloads their permissions.
      Parameters:
      player - the player

    • invalidateCache

      public CompletableFuture<Void> invalidateCache(TalePlayer player)
      Invalidates and refreshes a player's permission cache.
      Parameters:
      player - the player
      Returns:
      future completing when refreshed

    • shutdown

      public void shutdown()
      Shuts down the permission service.

      Called on server shutdown. Disables the active provider.