Package ru.tehkode.permissions

Interface PermissionEntity

All Known Subinterfaces:
PermissionGroup, PermissionUser
public interface PermissionEntity
Base contract for permission subjects (users and groups) in the classic ru.tehkode.permissions API.

Concrete implementations ship in permissionsex-core (AbstractPermissionEntity, PermissionUser, PermissionGroup).

Frozen public contract. Baseline commit 628215f. Do not extend this interface with new methods — use the modern API for new features.

World scope

A null world name denotes the global (common) scope: permissions, options, prefix/suffix, and parent groups assigned for all worlds unless overridden by world-specific data.

Direct (getOwn*) vs effective (get*)

Methods prefixed with getOwn return values stored directly on this entity only. Methods without Own resolve effective values by traversing parent groups and world inheritance (see PermissionManager.getWorldInheritance(String)).

Non-inheritable permissions

Permissions prefixed with NON_INHERITABLE_PREFIX ("#") are not propagated to child subjects through inheritance.

Timed permissions

Temporary grants are tracked separately from persisted permissions. A lifetime of PermissionManager.TRANSIENT_PERMISSION (0) means the grant is held in memory only and is not written to the backend.

See Also:

  • Field Details

  • Method Details

    • clearCache

      void clearCache()
      Clears in-memory caches for this entity (resolved permissions, inheritance, and related derived state).

      Implementations invoke this after mutating permissions, options, or parent groups so subsequent get* calls recompute effective values.

    • initialize

      void initialize()
      Completes post-construction initialization for this entity.

      Called by the owning PermissionManager after the entity and its backing data are fully constructed. Typically loads debug flags and other derived state from stored options.

    • getPermissionManager

      PermissionManager getPermissionManager()
      Returns the PermissionManager that owns and resolves this entity.
      Returns:
      the permission manager instance

    • getIdentifier

      String getIdentifier()
      Returns the stable backend identifier for this entity (UUID string for users, group name for groups).
      Returns:
      entity identifier; never null for a live instance

    • getName

      String getName()
      Returns the display name for this entity.

      May differ from getIdentifier() when a name option is set; otherwise falls back to the identifier.

      Returns:
      display name

    • getType

      PermissionEntity.Type getType()
      Returns whether this entity represents a user or a group.
      Returns:
      PermissionEntity.Type.USER or PermissionEntity.Type.GROUP

    • getOwnPrefix

      String getOwnPrefix()
      Returns the prefix stored directly on this entity in the global scope.

      Does not traverse parent groups. Returns null or empty when no own prefix is set.

      Returns:
      direct prefix, or null/empty if unset
      See Also:

    • getOwnPrefix

      String getOwnPrefix(String worldName)
      Returns the prefix stored directly on this entity for the given world.

      worldName == null selects the global scope. Does not traverse parent groups.

      Parameters:
      worldName - world name, or null for global scope
      Returns:
      direct prefix, or null/empty if unset
      See Also:

    • getOwnSuffix

      String getOwnSuffix()
      Returns the suffix stored directly on this entity in the global scope.

      Does not traverse parent groups. Returns null or empty when no own suffix is set.

      Returns:
      direct suffix, or null/empty if unset
      See Also:

    • getOwnSuffix

      String getOwnSuffix(String worldName)
      Returns the suffix stored directly on this entity for the given world.

      worldName == null selects the global scope. Does not traverse parent groups.

      Parameters:
      worldName - world name, or null for global scope
      Returns:
      direct suffix, or null/empty if unset
      See Also:

    • getPrefix

      String getPrefix()
      Returns the effective chat prefix in the global scope, including inheritance from parent groups.
      Returns:
      resolved prefix, or empty string when none is defined
      See Also:

    • getPrefix

      String getPrefix(String worldName)
      Returns the effective chat prefix for the given world, including inheritance from parent groups and world inheritance.

      worldName == null selects the global scope.

      Parameters:
      worldName - world name, or null for global scope
      Returns:
      resolved prefix, or empty string when none is defined
      See Also:

    • setPrefix

      void setPrefix(String prefix, String worldName)
      Sets the chat prefix stored directly on this entity for the given world.

      worldName == null stores the prefix in global scope. Clears entity cache after update.

      Parameters:
      prefix - new prefix value
      worldName - world name, or null for global scope

    • getSuffix

      String getSuffix(String worldName)
      Returns the effective chat suffix for the given world, including inheritance from parent groups and world inheritance.

      worldName == null selects the global scope.

      Parameters:
      worldName - world name, or null for global scope
      Returns:
      resolved suffix, or empty string when none is defined
      See Also:

    • getSuffix

      String getSuffix()
      Returns the effective chat suffix in the global scope, including inheritance from parent groups.
      Returns:
      resolved suffix, or empty string when none is defined
      See Also:

    • setSuffix

      void setSuffix(String suffix, String worldName)
      Sets the chat suffix stored directly on this entity for the given world.

      worldName == null stores the suffix in global scope. Clears entity cache after update.

      Parameters:
      suffix - new suffix value
      worldName - world name, or null for global scope

    • has

      boolean has(String permission)
      Checks whether this entity effectively holds the given permission in the default world context.

      Equivalent to has(String, String) with a server-default world name when worlds exist, or global scope (null) otherwise.

      Parameters:
      permission - permission node to check
      Returns:
      true if the permission is granted, false otherwise

    • has

      boolean has(String permission, String world)
      Checks whether this entity effectively holds the given permission in the specified world.

      Resolves inheritance, timed permissions, negated nodes (-node), and non-inheritable expressions. world == null uses global scope.

      Parameters:
      permission - permission node to check
      world - world name, or null for global scope
      Returns:
      true if the permission is granted, false otherwise

    • getPermissions

      List<String> getPermissions(String world)
      Returns the effective permission expressions for the given world, including inherited and timed grants.

      world == null selects global scope. Order reflects precedence for matching (see getMatchingExpression(String, String)).

      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of effective permission expressions
      See Also:

    • getPermissions

      List<String> getPermissions()
      Returns effective permission expressions in the global scope.
      Returns:
      unmodifiable list of effective permission expressions
      See Also:

    • getOwnPermissions

      List<String> getOwnPermissions(String world)
      Returns permission expressions assigned directly to this entity for the given world.

      Does not include inherited parent-group permissions or timed grants. world == null selects global scope.

      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of directly assigned permission expressions
      See Also:

    • getAllPermissions

      Map<String,List<String>> getAllPermissions()
      Returns all permission lists keyed by world name.

      Global-scope permissions are stored under a null key. Timed permissions for each world are merged into the corresponding entry.

      Returns:
      unmodifiable map of world name to permission expression list

    • addPermission

      void addPermission(String permission, String worldName)
      Adds a permission expression to this entity for the given world, placing it at highest precedence.

      If the expression already exists for that world, it is moved to the front of the list. worldName == null selects global scope.

      Parameters:
      permission - permission expression to add
      worldName - world name, or null for global scope

    • addPermission

      void addPermission(String permission)
      Adds a permission expression in global scope (worldName == null).
      Parameters:
      permission - permission expression to add
      See Also:

    • removePermission

      void removePermission(String permission, String worldName)
      Removes a permission expression (and any matching timed grant) from this entity for the given world.
      Parameters:
      permission - permission expression to remove
      worldName - world name, or null for global scope

    • removePermission

      void removePermission(String permission)
      Removes the given permission expression from every world where this entity defines permissions.
      Parameters:
      permission - permission expression to remove

    • setPermissions

      void setPermissions(List<String> permissions, String world)
      Replaces the direct permission list for the given world.

      world == null selects global scope. Clears entity cache after update.

      Parameters:
      permissions - new permission expression list
      world - world name, or null for global scope

    • setPermissions

      void setPermissions(List<String> permission)
      Replaces the direct permission list in global scope.
      Parameters:
      permission - new permission expression list
      See Also:

    • getOption

      String getOption(String option, String world, String defaultValue)
      Returns the effective string value of an option, traversing parent groups when not set locally.
      Parameters:
      option - option name
      world - world name, or null for global scope
      defaultValue - value returned when the option is unset after inheritance resolution
      Returns:
      resolved option value, or defaultValue if absent
      See Also:

    • getOption

      String getOption(String option)
      Returns the effective value of an option in global scope.
      Parameters:
      option - option name
      Returns:
      resolved option value, or null if unset
      See Also:

    • getOption

      String getOption(String option, String world)
      Returns the effective value of an option for the given world.
      Parameters:
      option - option name
      world - world name, or null for global scope
      Returns:
      resolved option value, or null if unset
      See Also:

    • getOptionInteger

      int getOptionInteger(String optionName, String world, int defaultValue)
      Returns the effective integer value of an option for the given world.
      Parameters:
      optionName - option name
      world - world name, or null for global scope
      defaultValue - value returned when the option is unset or not parseable as an integer
      Returns:
      parsed integer option value, or defaultValue

    • getOptionDouble

      double getOptionDouble(String optionName, String world, double defaultValue)
      Returns the effective double value of an option for the given world.
      Parameters:
      optionName - option name
      world - world name, or null for global scope
      defaultValue - value returned when the option is unset or not parseable as a double
      Returns:
      parsed double option value, or defaultValue

    • getOptionBoolean

      boolean getOptionBoolean(String optionName, String world, boolean defaultValue)
      Returns the effective boolean value of an option for the given world.
      Parameters:
      optionName - option name
      world - world name, or null for global scope
      defaultValue - value returned when the option is unset or not "true"/"false"
      Returns:
      parsed boolean option value, or defaultValue

    • setOption

      void setOption(String option, String value, String world)
      Sets an option value stored directly on this entity for the given world.

      Pass null as value to remove the option. world == null selects global scope.

      Parameters:
      option - option name
      value - option value, or null to remove
      world - world name, or null for global scope

    • setOption

      void setOption(String option, String value)
      Sets an option value in global scope.
      Parameters:
      option - option name
      value - option value, or null to remove
      See Also:

    • getOptions

      Map<String,String> getOptions(String world)
      Returns all options stored directly on this entity for the given world.

      Does not merge inherited parent options. world == null selects global scope.

      Parameters:
      world - world name, or null for global scope
      Returns:
      map of option name to value

    • getOptions

      Map<String,String> getOptions()
      Returns all options stored directly on this entity in global scope.
      Returns:
      map of option name to value
      See Also:

    • getAllOptions

      Map<String,Map<String,String>> getAllOptions()
      Returns all directly stored options keyed by world name.

      Global-scope options are stored under a null key.

      Returns:
      map of world name to option map

    • getOwnOption

      String getOwnOption(String option, String world, String defaultValue)
      Returns the value of an option stored directly on this entity for the given world.

      Does not traverse parent groups. world == null selects global scope.

      Parameters:
      option - option name
      world - world name, or null for global scope
      defaultValue - value returned when the option is not set on this entity
      Returns:
      direct option value, or defaultValue if absent
      See Also:

    • getOwnOption

      String getOwnOption(String option)
      Returns the value of an option stored directly on this entity in global scope.
      Parameters:
      option - option name
      Returns:
      direct option value, or null if unset
      See Also:

    • getOwnOption

      String getOwnOption(String option, String world)
      Returns the value of an option stored directly on this entity for the given world.
      Parameters:
      option - option name
      world - world name, or null for global scope
      Returns:
      direct option value, or null if unset
      See Also:

    • getOwnOptionInteger

      int getOwnOptionInteger(String optionName, String world, int defaultValue)
      Returns the integer value of an option stored directly on this entity.
      Parameters:
      optionName - option name
      world - world name, or null for global scope
      defaultValue - value returned when unset or not parseable
      Returns:
      parsed integer, or defaultValue
      See Also:

    • getOwnOptionBoolean

      boolean getOwnOptionBoolean(String optionName, String world, boolean defaultValue)
      Returns the boolean value of an option stored directly on this entity.
      Parameters:
      optionName - option name
      world - world name, or null for global scope
      defaultValue - value returned when unset or not "true"/"false"
      Returns:
      parsed boolean, or defaultValue
      See Also:

    • getOwnOptionDouble

      double getOwnOptionDouble(String optionName, String world, double defaultValue)
      Returns the double value of an option stored directly on this entity.
      Parameters:
      optionName - option name
      world - world name, or null for global scope
      defaultValue - value returned when unset or not parseable
      Returns:
      parsed double, or defaultValue
      See Also:

    • save

      void save()
      Persists in-memory changes for this entity to the active backend.

      Clears entity cache after a successful save.

    • remove

      void remove()
      Deletes this entity from the backend and clears associated in-memory state.

    • isVirtual

      boolean isVirtual()
      Returns whether this entity exists only in memory and has not yet been persisted.
      Returns:
      true if virtual (not yet saved), false if backed by storage

    • getWorlds

      Set<String> getWorlds()
      Returns world names for which this entity has stored permissions, options, or parent assignments.
      Returns:
      set of world names (may be empty)

    • getTimedPermissions

      List<String> getTimedPermissions(String world)
      Returns timed (temporary) permission expressions active for the given world on this entity.

      world == null selects global scope. Does not include inherited timed grants from parents.

      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of timed permission expressions

    • getTimedPermissionLifetime

      int getTimedPermissionLifetime(String permission, String world)
      Returns remaining lifetime in seconds for a timed permission on this entity.

      world == null selects global scope. Returns 0 when the permission is transient (PermissionManager.TRANSIENT_PERMISSION) or not timed.

      Parameters:
      permission - permission expression
      world - world name, or null for global scope
      Returns:
      seconds remaining, or 0 if not timed or already expired

    • addTimedPermission

      void addTimedPermission(String permission, String world, int lifeTime)
      Grants a timed permission on this entity for the given world.

      world == null selects global scope. lifeTime is in seconds; pass PermissionManager.TRANSIENT_PERMISSION (0) for a non-persisted in-memory grant that survives until reload.

      Parameters:
      permission - permission expression to grant
      world - world name, or null for global scope
      lifeTime - lifetime in seconds, or 0 for transient

    • removeTimedPermission

      void removeTimedPermission(String permission, String world)
      Revokes a timed permission from this entity for the given world.
      Parameters:
      permission - permission expression to revoke
      world - world name, or null for global scope

    • getMatchingExpression

      String getMatchingExpression(String permission, String world)
      Finds the highest-precedence permission expression that matches the requested node in the given world.

      Uses the entity's effective permission list for world (see getPermissions(String)).

      Parameters:
      permission - permission node to match
      world - world name, or null for global scope
      Returns:
      winning expression, or null if none matches

    • getMatchingExpression

      String getMatchingExpression(List<String> permissions, String permission)
      Finds the first expression in the supplied list that matches the requested permission node.
      Parameters:
      permissions - ordered list of permission expressions to search
      permission - permission node to match
      Returns:
      winning expression, or null if none matches

    • isMatches

      boolean isMatches(String expression, String permission, boolean additionalChecks)
      Tests whether a permission expression matches a concrete permission node.
      Parameters:
      expression - stored permission expression (may include wildcards or regex)
      permission - permission node being checked
      additionalChecks - when true, enables parent-node matching semantics in the matcher
      Returns:
      true if the expression matches the node

    • explainExpression

      boolean explainExpression(String expression)
      Interprets a permission expression as grant or deny.

      Expressions prefixed with - are negations and yield false; all other non-empty expressions yield true. null or empty expressions yield false.

      Parameters:
      expression - permission expression to interpret
      Returns:
      true if the expression grants access, false if denied or absent

    • isDebug

      boolean isDebug()
      Returns whether debug logging is enabled for this entity or its manager.
      Returns:
      true if entity-level or manager-level debug is active

    • setDebug

      void setDebug(boolean debug)
      Enables or disables debug logging for this entity only.

      Does not change manager-wide debug mode (see PermissionManager.setDebug(boolean)).

      Parameters:
      debug - true to enable entity debug output

    • getOwnParents

      List<PermissionGroup> getOwnParents(String world)
      Returns parent groups assigned directly to this entity for the given world.

      Does not traverse the group hierarchy. world == null selects global scope.

      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of directly assigned parent groups
      See Also:

    • getOwnParents

      List<PermissionGroup> getOwnParents()
      Returns parent groups assigned directly to this entity in global scope.
      Returns:
      unmodifiable list of directly assigned parent groups
      See Also:

    • getOwnParentIdentifiers

      List<String> getOwnParentIdentifiers(String world)
      Returns identifiers of parent groups assigned directly to this entity for the given world.
      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of parent group identifiers
      See Also:

    • getOwnParentIdentifiers

      List<String> getOwnParentIdentifiers()
      Returns identifiers of parent groups assigned directly to this entity in global scope.
      Returns:
      unmodifiable list of parent group identifiers
      See Also:

    • getParents

      List<PermissionGroup> getParents(String world)
      Returns all parent groups that contribute to this entity's effective inheritance for the given world.

      Includes ancestors reachable through the group hierarchy. world == null selects global scope.

      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of resolved parent groups
      See Also:

    • getParents

      List<PermissionGroup> getParents()
      Returns all parent groups that contribute to effective inheritance in global scope.
      Returns:
      unmodifiable list of resolved parent groups
      See Also:

    • getParentIdentifiers

      List<String> getParentIdentifiers(String world)
      Returns identifiers of all parent groups in the effective inheritance chain for the given world.
      Parameters:
      world - world name, or null for global scope
      Returns:
      unmodifiable list of parent group identifiers
      See Also:

    • getParentIdentifiers

      List<String> getParentIdentifiers()
      Returns identifiers of all parent groups in the effective inheritance chain in global scope.
      Returns:
      unmodifiable list of parent group identifiers
      See Also:

    • getAllParents

      Map<String,List<PermissionGroup>> getAllParents()
      Returns direct parent groups keyed by world name.

      Global-scope parents are stored under a null key. Values are direct assignments only (see getOwnParents(String)), not fully resolved inheritance chains.

      Returns:
      unmodifiable map of world name to parent group list

    • setParents

      void setParents(List<PermissionGroup> parents, String world)
      Replaces the direct parent group list for the given world.
      Parameters:
      parents - new parent groups
      world - world name, or null for global scope

    • setParents

      void setParents(List<PermissionGroup> parents)
      Replaces the direct parent group list in global scope.
      Parameters:
      parents - new parent groups
      See Also:

    • setParentsIdentifier

      void setParentsIdentifier(List<String> parentNames, String world)
      Replaces the direct parent group identifiers for the given world.
      Parameters:
      parentNames - parent group identifiers
      world - world name, or null for global scope

    • setParentsIdentifier

      void setParentsIdentifier(List<String> parentNames)
      Replaces the direct parent group identifiers in global scope.
      Parameters:
      parentNames - parent group identifiers
      See Also: