Package dev.polv.taleapi.permission

Class PermissionTree

java.lang.Object
dev.polv.taleapi.permission.PermissionTree
public final class PermissionTree extends Object
A Radix Tree (Trie) data structure for efficient permission lookups.

This hierarchical structure provides O(k) lookup time where k is the length of the permission string, regardless of how many permissions exist in the tree.

Performance Advantages

  • Wildcards are instant: If traversal hits a * node, it stops immediately
  • No string parsing: Permissions are naturally segmented by dots
  • Organization: Related permissions are grouped (cmd.teleport, cmd.give)

Example Structure

 root
 ├── cmd
 │   ├── teleport [ALLOW]
 │   ├── give [DENY]
 │   └── * [ALLOW]        // Wildcard: cmd.anything = ALLOW
 └── plots
     ├── create [ALLOW]
     └── limit [ALLOW, payload=5]

Thread Safety

This implementation uses ConcurrentHashMap for thread-safe reads. For bulk modifications, external synchronization is recommended.

See Also:

  • Field Details

    • WILDCARD

      public static final String WILDCARD
      The wildcard character that matches any permission segment.
      See Also:

  • Constructor Details

    • PermissionTree

      public PermissionTree()
      Creates an empty permission tree.

    • PermissionTree

      public PermissionTree(Collection<PermissionNode> nodes)
      Creates a permission tree from a collection of nodes.
      Parameters:
      nodes - the permission nodes to add

  • Method Details

    • set

      public void set(PermissionNode node)
      Sets a permission in the tree.
      Parameters:
      node - the permission node to set

    • allow

      public void allow(String key)
      Sets a simple permission (ALLOW with no payload).
      Parameters:
      key - the permission key

    • deny

      public void deny(String key)
      Sets a simple deny permission.
      Parameters:
      key - the permission key

    • remove

      public boolean remove(String key)
      Removes all permission nodes for a key.
      Parameters:
      key - the permission key to remove
      Returns:
      true if any nodes were removed

    • query

      public PermissionResult query(String key)
      Queries the tree for a permission result.

      This method traverses the tree, checking for wildcards at each level. If a wildcard is found, it returns immediately.

      Parameters:
      key - the permission key to query
      Returns:
      the permission result

    • query

      public PermissionResult query(String key, ContextSet context)
      Queries the tree for a permission result with context.

      This method traverses the tree segment by segment:

      1. At each level, check for a wildcard (*) node
      2. If wildcard exists and matches context, return its result
      3. Continue to the specific segment if no wildcard match
      4. At the final segment, return the node's result if it matches context
      Parameters:
      key - the permission key to query
      context - the current context to match against
      Returns:
      the permission result

    • has

      public boolean has(String key)
      Checks if a permission is allowed (returns true for ALLOW state).
      Parameters:
      key - the permission key
      Returns:
      true if the permission is ALLOW

    • has

      public boolean has(String key, ContextSet context)
      Checks if a permission is allowed with context.
      Parameters:
      key - the permission key
      context - the current context
      Returns:
      true if the permission is ALLOW

    • getAllNodes

      public List<PermissionNode> getAllNodes()
      Gets all permission nodes in this tree.
      Returns:
      an unmodifiable list of all nodes

    • getAllKeys

      public List<String> getAllKeys()
      Gets all permission keys in this tree.
      Returns:
      a list of all permission keys

    • size

      public int size()
      Returns the number of permission nodes in this tree.
      Returns:
      the total node count

    • isEmpty

      public boolean isEmpty()
      Checks if this tree is empty.
      Returns:
      true if no permissions are set

    • clear

      public void clear()
      Clears all permissions from this tree.

    • merge

      public void merge(PermissionTree other)
      Merges another tree into this one.

      Nodes from the other tree are added to this tree. Existing nodes with the same key are not replaced.

      Parameters:
      other - the tree to merge from

    • flatten

      public static PermissionTree flatten(PermissionTree... trees)
      Creates a flattened tree by merging multiple trees with priority.

      Trees are merged in order, with later trees having higher priority. This is used for permission resolution (Personal > Group > Default).

      Parameters:
      trees - the trees to merge, in ascending priority order
      Returns:
      a new flattened tree