Package ru.tehkode.permissions

Interface PermissionManager

public interface PermissionManager
Classic PermissionsEx permission manager contract (ru.tehkode.permissions, baseline 628215f).

Registered on Bukkit ServicesManager as PermissionManager.class on game servers. Runtime extensions (PlatformAdapter, entity bus dispatches, internal scheduling) are implemented on dev.rono.permissions.core.InternalPermissionManager and are not part of this surface.

Classic methods remain for binary compatibility but are deprecated — use PermissionsExApi via PermissionsEx.getApi().

World scope

A null world name denotes the global (common) scope shared across worlds unless overridden by world-specific data. World inheritance (getWorldInheritance(String)) further links named worlds to parent worlds when resolving effective permissions.

Inheritance flag overloads

getUsers(String, String, boolean) and getGroups(String, String, boolean) accept an inheritance parameter: when true, descendant groups of the named group are included; when false, only direct members or child groups are returned. Two-argument overloads default inheritance to false.

Cache and reset semantics

  • cacheUser(String, String) — pre-materializes a user during async login (thread-safe).
  • clearUserCache(String) — clears resolved permission state on a cached user without dropping the in-memory user object.
  • resetUser(String) — removes the in-memory user; the next lookup reloads from the backend.
  • resetGroup(String) — removes the in-memory group; the next lookup reloads from the backend.
  • reset() — clears all in-memory users and groups, reloads the backend, and optionally fires a reload event.

Timed permissions

initTimer() starts the scheduler used to expire timed grants. TRANSIENT_PERMISSION (0) marks a timed grant as non-persisted (in-memory only until reload).

Holder-based permissions

The addPermission(PermissionHolder, String), removePermission(PermissionHolder, String), hasPermission(PermissionHolder, String), and getPermissions(PermissionHolder) methods operate on PermissionHolder identities (for example User#asHolder() from the modern user API, group/world/ladder holders, etc.). Resolve the manager via PermissionsEx.getApi().getPermissionManager(). World context for advanced adds is supplied through PermissionAddRequest.

See Also:

  • Field Details

  • Method Details

    • addPermission

      PermissionNode addPermission(PermissionHolder holder, String permission)
      Grants a permission to the given holder in the global scope (not world-specific).

      The grant is persisted when the underlying entity is saved. For timed or world-scoped grants, use addPermission(PermissionHolder, String, Duration) or addPermission(PermissionAddRequest).

      Parameters:
      holder - permission target; must not be null
      permission - permission node to grant; must not be null or empty
      Returns:
      metadata describing the added node
      See Also:

    • addPermission

      PermissionNode addPermission(PermissionHolder holder, String permission, Duration duration)
      Grants a permission to the holder in the global scope for a limited duration.

      When duration is null, behaves like addPermission(PermissionHolder, String). Timed grants expire automatically after the scheduler runs (initTimer()).

      Parameters:
      holder - permission target; must not be null
      permission - permission node to grant; must not be null or empty
      duration - lifetime of the grant, or null for a permanent direct assignment
      Returns:
      metadata describing the added node (including expiry when timed)
      See Also:

    • addPermission

      PermissionNode addPermission(PermissionAddRequest request)
      Grants a permission using a fully specified add request (world context, expiry, source metadata).

      Build requests with PermissionAddRequest.builder(). World keys in the request context map to world-scoped storage; an empty context uses the global scope.

      Parameters:
      request - add specification; must not be null
      Returns:
      metadata describing the added node
      See Also:

    • removePermission

      void removePermission(PermissionHolder holder, String permission)
      Removes a direct permission assignment from the holder in the global scope.

      Does not remove inherited permissions. Does not clear timed nodes in world-specific scopes; use PermissionEntity.removeTimedPermission(String, String) on the resolved classic entity when needed.

      Parameters:
      holder - permission target; must not be null
      permission - permission node to remove; must not be null

    • hasPermission

      boolean hasPermission(PermissionHolder holder, String permission)
      Checks whether the holder effectively holds the permission in the global scope.

      Includes inheritance and parent groups for user/group holders. For per-world effective checks, use the classic has(Player, String, String) API or hasPermission(PermissionHolder, String, Map) with a world context entry.

      Parameters:
      holder - permission target; must not be null
      permission - permission node to check; must not be null
      Returns:
      true if granted after inheritance, false otherwise
      See Also:

    • hasPermission

      boolean hasPermission(PermissionHolder holder, String permission, Map<String,String> context)
      Checks whether the holder effectively holds the permission in the scope described by context.

      The world entry in context selects the world/realm namespace (same as classic per-world checks). An empty or missing context uses the global namespace.

      Parameters:
      holder - permission target; must not be null
      permission - permission node to check; must not be null
      context - optional context map (for example Map.of("world", player.getWorld().getName()))
      Returns:
      true if granted after inheritance, false otherwise
      See Also:

    • hasPermission

      default boolean hasPermission(PermissionHolder holder, String permission, PermissionContext context)
      Checks whether the holder effectively holds the permission in context.
      Parameters:
      holder - permission target; must not be null
      permission - permission node to check; must not be null
      context - permission scope
      Returns:
      true if granted after inheritance, false otherwise

    • getPermissions

      List<PermissionNode> getPermissions(PermissionHolder holder)
      Returns direct permission assignments for the holder in the global scope.

      Does not include inherited nodes or world-specific assignments. Each entry is a PermissionNode without expiry metadata for permanent grants.

      Parameters:
      holder - permission target; must not be null
      Returns:
      immutable list of direct global permissions (may be empty)
      See Also:

    • shouldCreateUserRecords

      @Deprecated boolean shouldCreateUserRecords()
      Deprecated.
      Returns whether the engine should create user records automatically when unknown players are resolved.
      Returns:
      true if new user records should be created (config-driven)
      See Also:

    • getConfiguration

      @Deprecated PermissionsExConfig getConfiguration()
      Deprecated.
      Returns the read-only PermissionsEx configuration view.
      Returns:
      configuration instance

    • has

      @Deprecated boolean has(org.bukkit.entity.Player player, String permission)
      Deprecated.
      Checks whether the given online player holds a permission in their current world.
      Parameters:
      player - online player
      permission - permission node to check
      Returns:
      true if granted, false otherwise

    • has

      @Deprecated boolean has(org.bukkit.entity.Player player, String permission, String world)
      Deprecated.
      Checks whether the given online player holds a permission in the named world.
      Parameters:
      player - online player
      permission - permission node to check
      world - world name
      Returns:
      true if granted, false otherwise

    • has

      @Deprecated boolean has(String playerName, String permission, String world)
      Deprecated.
      Checks whether the user identified by name holds a permission in the named world.

      Resolves offline and online users via the active backend. Returns false when the user cannot be resolved.

      Parameters:
      playerName - player name or UUID string
      permission - permission node to check
      world - world name, or null for global scope
      Returns:
      true if granted, false otherwise

    • has

      @Deprecated boolean has(UUID playerId, String permission, String world)
      Deprecated.
      Checks whether the user identified by UUID holds a permission in the named world.
      Parameters:
      playerId - player UUID
      permission - permission node to check
      world - world name, or null for global scope
      Returns:
      true if granted, false if denied or the user is unknown

    • getUser

      @Deprecated PermissionUser getUser(String username)
      Deprecated.
      Resolves or materializes a PermissionUser by identifier (UUID string or legacy name).
      Parameters:
      username - user identifier or display name
      Returns:
      user instance
      Throws:
      IllegalArgumentException - if username is null or empty
      IllegalStateException - if the user does not exist in the backend and cannot be created

    • cacheUser

      @Deprecated void cacheUser(String ident, String fallbackName)
      Deprecated.
      Pre-caches a user during asynchronous login before the player is fully online.

      Thread-safe; stores the resolved user in the manager's in-memory cache using ident as key and fallbackName for UUID conversion fallbacks.

      Parameters:
      ident - stable user identifier (typically UUID string)
      fallbackName - player name used when converting legacy name-based records

    • getUser

      @Deprecated PermissionUser getUser(org.bukkit.entity.Player player)
      Deprecated.
      Resolves or materializes a PermissionUser for an online player.
      Parameters:
      player - online player
      Returns:
      user instance

    • getUser

      @Deprecated PermissionUser getUser(UUID uid)
      Deprecated.
      Resolves or materializes a PermissionUser by UUID.
      Parameters:
      uid - player UUID
      Returns:
      user instance

    • getUsers

      @Deprecated Set<PermissionUser> getUsers()
      Deprecated.
      Returns all users known to the backend, materializing instances as needed.
      Returns:
      unmodifiable set of users

    • getActiveUsers

      @Deprecated Set<PermissionUser> getActiveUsers()
      Deprecated.
      Returns users currently held in the manager's in-memory cache.
      Returns:
      copy of cached users (may be a subset of getUsers())

    • getUserIdentifiers

      @Deprecated Collection<String> getUserIdentifiers()
      Deprecated.
      Returns stable user identifiers stored in the backend.
      Returns:
      collection of user identifiers (typically UUID strings)

    • getUserNames

      @Deprecated Collection<String> getUserNames()
      Deprecated.
      Returns display names stored in the backend.
      Returns:
      collection of user names

    • getUsers

      @Deprecated Set<PermissionUser> getUsers(String groupName, String worldName)
      Deprecated.
      Returns users that are direct members of the named group in the given world.

      Equivalent to getUsers(String, String, boolean) with inheritance == false.

      Parameters:
      groupName - group identifier
      worldName - world name, or null for global scope
      Returns:
      unmodifiable set of matching users

    • getUsers

      @Deprecated Set<PermissionUser> getUsers(String groupName)
      Deprecated.
      Returns users that are direct members of the named group in global scope.

      Equivalent to getUsers(String, boolean) with inheritance == false.

      Parameters:
      groupName - group identifier
      Returns:
      unmodifiable set of matching users

    • getUsers

      @Deprecated Set<PermissionUser> getUsers(String groupName, String worldName, boolean inheritance)
      Deprecated.
      Returns users in the named group for the given world, optionally including descendant groups.
      Parameters:
      groupName - group identifier
      worldName - world name, or null for global scope
      inheritance - when true, includes users in child/descendant groups
      Returns:
      unmodifiable set of matching users

    • getUsers

      @Deprecated Set<PermissionUser> getUsers(String groupName, boolean inheritance)
      Deprecated.
      Returns users in the named group across all worlds (including global scope), optionally including descendant groups.
      Parameters:
      groupName - group identifier
      inheritance - when true, includes users in child/descendant groups
      Returns:
      unmodifiable set of matching users

    • resetUser

      @Deprecated void resetUser(String userName)
      Deprecated.
      Removes the in-memory PermissionUser for the given identifier.

      Does not delete backend data; the next getUser(String) reloads from storage. Differs from clearUserCache(String), which retains the cached object and only clears resolved permission state.

      Parameters:
      userName - user identifier or name

    • resetUser

      @Deprecated void resetUser(org.bukkit.entity.Player player)
      Deprecated.
      Removes the in-memory PermissionUser for the given player.
      Parameters:
      player - online player whose cached user object should be dropped
      See Also:

    • clearUserCache

      @Deprecated void clearUserCache(String userName)
      Deprecated.
      Clears resolved permission cache for the user identified by name without removing the cached user object.
      Parameters:
      userName - user identifier or name
      See Also:

    • clearUserCache

      @Deprecated void clearUserCache(UUID uid)
      Deprecated.
      Clears resolved permission cache for the user identified by UUID.
      Parameters:
      uid - player UUID
      See Also:

    • clearUserCache

      @Deprecated void clearUserCache(org.bukkit.entity.Player player)
      Deprecated.
      Clears resolved permission cache for the given online player.
      Parameters:
      player - online player
      See Also:

    • getGroup

      @Deprecated PermissionGroup getGroup(String groupname)
      Deprecated.
      Resolves or materializes a PermissionGroup by name.
      Parameters:
      groupname - group identifier
      Returns:
      group instance, or null if groupname is null or empty

    • getGroupList

      @Deprecated List<PermissionGroup> getGroupList()
      Deprecated.
      Returns all groups known to the backend.
      Returns:
      unmodifiable list of groups

    • getGroups

      @Deprecated PermissionGroup[] getGroups()
      Deprecated.
      prefer getGroupList()
      Returns all groups as an array.
      Returns:
      array of all groups

    • getGroupNames

      @Deprecated Collection<String> getGroupNames()
      Deprecated.
      prefer resolving groups via getGroupList() or the backend
      Returns names of all groups in the backend.
      Returns:
      collection of group names

    • getGroups

      @Deprecated List<PermissionGroup> getGroups(String groupName, String worldName)
      Deprecated.
      Returns child groups of groupName in the given world (direct children only).

      Equivalent to getGroups(String, String, boolean) with inheritance == false.

      Parameters:
      groupName - parent group identifier
      worldName - world name, or null for global scope
      Returns:
      unmodifiable list of child groups

    • getGroups

      @Deprecated List<PermissionGroup> getGroups(String groupName)
      Deprecated.
      Returns child groups of groupName in global scope (direct children only).
      Parameters:
      groupName - parent group identifier
      Returns:
      unmodifiable list of child groups
      See Also:

    • getGroups

      @Deprecated List<PermissionGroup> getGroups(String groupName, String worldName, boolean inheritance)
      Deprecated.
      Returns child or descendant groups of groupName in the given world.
      Parameters:
      groupName - parent group identifier
      worldName - world name, or null for global scope
      inheritance - when true, includes all descendant groups; when false, direct children only
      Returns:
      unmodifiable list of matching groups

    • getGroups

      @Deprecated List<PermissionGroup> getGroups(String groupName, boolean inheritance)
      Deprecated.
      Returns child or descendant groups of groupName aggregated across all worlds and global scope.
      Parameters:
      groupName - parent group identifier
      inheritance - when true, includes all descendant groups; when false, direct children only
      Returns:
      unmodifiable, sorted list of matching groups

    • getDefaultGroups

      @Deprecated List<PermissionGroup> getDefaultGroups(String worldName)
      Deprecated.
      Returns groups marked as default for the given world.

      Includes groups default in global scope (worldName == null on the group) when querying a specific world.

      Parameters:
      worldName - world name, or null to query global defaults only
      Returns:
      unmodifiable list of default groups (may be empty)

    • resetGroup

      @Deprecated PermissionGroup resetGroup(String groupName)
      Deprecated.
      Removes the in-memory PermissionGroup for the given name.

      Does not delete backend data; the next getGroup(String) reloads from storage.

      Parameters:
      groupName - group identifier
      Returns:
      the removed cached group, or null if none was cached

    • setDebug

      @Deprecated void setDebug(boolean debug)
      Deprecated.
      Enables or disables manager-wide debug logging.
      Parameters:
      debug - true to enable debug output

    • isDebug

      @Deprecated boolean isDebug()
      Deprecated.
      Returns whether manager-wide debug logging is enabled.
      Returns:
      true if debug mode is active

    • getRankLadder

      @Deprecated Map<Integer,PermissionGroup> getRankLadder(String ladderName)
      Deprecated.
      Returns groups on the named rank ladder keyed by rank number.
      Parameters:
      ladderName - ladder name (case-insensitive match)
      Returns:
      map of rank to group; empty if the ladder does not exist

    • getWorldInheritance

      @Deprecated List<String> getWorldInheritance(String worldName)
      Deprecated.
      Returns parent worlds from which the named world inherits permissions and options.
      Parameters:
      worldName - world name
      Returns:
      ordered list of parent world names; empty if none configured

    • setWorldInheritance

      @Deprecated void setWorldInheritance(String world, List<String> parentWorlds)
      Deprecated.
      Configures parent-world inheritance for the named world.

      Clears cached permission state on all active users after the change.

      Parameters:
      world - world whose inheritance is being set
      parentWorlds - ordered list of parent world names

    • getBackend

      @Deprecated PermissionBackend getBackend()
      Deprecated.
      Returns the active permission storage backend.
      Returns:
      current PermissionBackend instance

    • setBackend

      @Deprecated void setBackend(String backendName) throws PermissionBackendException
      Deprecated.
      Switches the active backend to the named type, reloading data.
      Parameters:
      backendName - backend type identifier (e.g. file, sql)
      Throws:
      PermissionBackendException - if the backend cannot be created or initialized

    • createBackend

      @Deprecated PermissionBackend createBackend(String backendName) throws PermissionBackendException
      Deprecated.
      Creates a new PermissionBackend instance without activating it.
      Parameters:
      backendName - backend type identifier
      Returns:
      newly created backend
      Throws:
      PermissionBackendException - if the backend cannot be created

    • reset

      @Deprecated void reset() throws PermissionBackendException
      Deprecated.
      Clears all in-memory users and groups, reloads the active backend, and fires a reload event.
      Throws:
      PermissionBackendException - if the backend reload fails
      See Also:

    • reset

      @Deprecated void reset(boolean callEvent) throws PermissionBackendException
      Deprecated.
      Clears all in-memory users and groups and reloads the active backend.
      Parameters:
      callEvent - when true, publishes a system reload event after reload completes
      Throws:
      PermissionBackendException - if the backend reload fails

    • end

      @Deprecated void end()
      Deprecated.
      Shuts down the manager: closes the backend, clears caches, and stops the scheduler.

    • initTimer

      @Deprecated void initTimer()
      Deprecated.
      (Re)initializes the scheduled executor used for timed permission and timed group expiration.

      Called during startup and after reset() cache clears. Tasks scheduled with TRANSIENT_PERMISSION lifetime are not persisted.

    • getPermissionMatcher

      @Deprecated PermissionMatcher getPermissionMatcher()
      Deprecated.
      Returns the permission expression matcher used for node checks.
      Returns:
      current PermissionMatcher

    • setPermissionMatcher

      @Deprecated void setPermissionMatcher(PermissionMatcher matcher)
      Deprecated.
      Replaces the permission expression matcher.
      Parameters:
      matcher - new matcher implementation

    • getLogger

      @Deprecated Logger getLogger()
      Deprecated.
      Returns the engine logger.
      Returns:
      PermissionsEx logger instance

    • getExecutor

      @Deprecated ScheduledExecutorService getExecutor()
      Deprecated.
      Returns the scheduled executor service used for timed tasks.
      Returns:
      scheduler, or null after end()

    • shouldSaveDefaultGroup

      @Deprecated boolean shouldSaveDefaultGroup()
      Deprecated.
      Returns whether default group membership should be persisted when saving users.
      Returns:
      true if default groups are written to storage (config-driven)
      See Also: