Package ru.tehkode.permissions.backends

Interface PermissionBackend

public interface PermissionBackend
Storage backend contract (ru.tehkode.permissions.backends).

Implementations persist and load permission data (users, groups, world inheritance, and related metadata). Concrete backend bodies live on AbstractPermissionBackend in permissionsex-core; aliases and factory helpers stay on this interface for classpath-stable static calls.

Each backend is constructed with a PermissionManager and a PEXBackendConfiguration and is responsible for schema versioning, reload, and lifecycle management.

  • Field Details

    • DEFAULT_BACKEND

      static final String DEFAULT_BACKEND
      Default backend alias used when no backend name is specified.
      See Also:

  • Method Details

    • getRegisteredBackendAliases

      static List<String> getRegisteredBackendAliases()
      Returns all registered backend aliases, sorted case-insensitively.
      Returns:
      an unmodifiable list of alias names; never null

    • getBackendClassName

      static String getBackendClassName(String alias)
      Resolves a backend alias to its fully qualified class name.

      If alias is a registered alias, returns the canonical name of the mapped class. Otherwise returns alias unchanged, treating it as a raw class name.

      Parameters:
      alias - backend alias or fully qualified class name
      Returns:
      the resolved class name; never null

    • getBackendClass

      static Class<? extends PermissionBackend> getBackendClass(String alias) throws ClassNotFoundException
      Resolves a backend alias or class name to a PermissionBackend implementation class.
      Parameters:
      alias - backend alias or fully qualified class name
      Returns:
      the resolved backend class; never null
      Throws:
      ClassNotFoundException - if alias is not registered and no class with that name exists
      IllegalArgumentException - if the resolved class does not extend PermissionBackend

    • registerBackendAlias

      static void registerBackendAlias(String alias, Class<? extends PermissionBackend> backendClass)
      Registers a short alias for a PermissionBackend implementation class.
      Parameters:
      alias - human-readable alias (for example "file" or "sql")
      backendClass - backend implementation class
      Throws:
      IllegalArgumentException - if backendClass is not a subclass of PermissionBackend

    • getBackendAlias

      static String getBackendAlias(Class<? extends PermissionBackend> backendClass)
      Returns the registered alias for a backend class, or the class name if no alias is registered.
      Parameters:
      backendClass - backend implementation class
      Returns:
      the alias associated with backendClass, or its fully qualified name

    • getBackend

      static PermissionBackend getBackend(String backendName, PermissionManager manager, PEXBackendConfiguration config) throws PermissionBackendException
      Instantiates a backend by name, falling back to DEFAULT_BACKEND on failure.
      Parameters:
      backendName - name or alias of the backend to initialize
      manager - permission manager that owns this backend
      config - backend-specific configuration
      Returns:
      a new backend instance
      Throws:
      PermissionBackendException - if the backend fails to initialize in a controlled manner
      RuntimeException - if the backend class cannot be loaded or constructed

    • getBackend

      static PermissionBackend getBackend(String backendName, PermissionManager manager, PEXBackendConfiguration config, String fallBackBackend) throws PermissionBackendException
      Instantiates a backend by name with an explicit fallback backend.

      If backendName is null or empty, DEFAULT_BACKEND is used. When the primary backend class cannot be found, fallBackBackend is attempted once unless it resolves to the same class name.

      Parameters:
      backendName - name or alias of the backend to initialize; may be null or empty
      manager - permission manager that owns this backend
      config - backend-specific configuration
      fallBackBackend - alias or class name to use when the primary backend is unknown; may be null
      Returns:
      a new backend instance
      Throws:
      PermissionBackendException - if the backend fails to initialize in a controlled manner
      RuntimeException - if neither the primary nor fallback backend can be loaded or constructed

    • getSchemaVersion

      int getSchemaVersion()
      Returns the schema version currently stored by this backend.
      Returns:
      the persisted schema version number

    • getLatestSchemaVersion

      int getLatestSchemaVersion()
      Returns the latest schema version supported by this backend implementation.
      Returns:
      the highest schema version this backend can read and write

    • reload

      void reload() throws PermissionBackendException
      Reloads all permission data from the underlying storage.
      Throws:
      PermissionBackendException - if the reload fails due to a storage or configuration error

    • getUserData

      PermissionsUserData getUserData(String userName)
      Returns mutable data for the user identified by userName.
      Parameters:
      userName - user identifier (name or UUID string, depending on backend mode)
      Returns:
      user data handle; never null for known identifiers

    • getGroupData

      PermissionsGroupData getGroupData(String groupName)
      Returns mutable data for the group identified by groupName.
      Parameters:
      groupName - group name
      Returns:
      group data handle; never null for known group names

    • hasUser

      boolean hasUser(String userName)
      Returns whether a user record exists in this backend.
      Parameters:
      userName - user identifier to check
      Returns:
      true if the user exists in storage

    • hasGroup

      boolean hasGroup(String group)
      Returns whether a group record exists in this backend.
      Parameters:
      group - group name to check
      Returns:
      true if the group exists in storage

    • getUserIdentifiers

      Collection<String> getUserIdentifiers()
      Returns all user identifiers known to this backend.
      Returns:
      collection of user identifiers; never null

    • getUserNames

      Collection<String> getUserNames()
      Returns all user display names known to this backend.
      Returns:
      collection of user names; never null

    • getGroupNames

      Collection<String> getGroupNames()
      Returns all group names known to this backend.
      Returns:
      collection of group names; never null

    • getWorldInheritance

      List<String> getWorldInheritance(String world)
      Returns the world inheritance chain for a specific world.

      World inheritance defines which groups apply in a given world before user-specific permissions are evaluated.

      Parameters:
      world - world name
      Returns:
      ordered list of inherited group names; never null

    • getAllWorldInheritance

      Map<String,List<String>> getAllWorldInheritance()
      Returns world inheritance mappings for all worlds.
      Returns:
      map from world name to ordered inheritance group lists; never null

    • setWorldInheritance

      void setWorldInheritance(String world, List<String> inheritance)
      Sets the world inheritance chain for a specific world.
      Parameters:
      world - world name
      inheritance - ordered list of group names to inherit in that world

    • close

      void close() throws PermissionBackendException
      Closes the backend and releases any held resources.
      Throws:
      PermissionBackendException - if shutdown or final persistence fails

    • getLogger

      Logger getLogger()
      Returns the logger used by this backend for diagnostic output.
      Returns:
      backend logger; never null

    • loadFrom

      void loadFrom(PermissionBackend backend)
      Replaces this backend's in-memory contents with data copied from another backend.
      Parameters:
      backend - source backend whose data should be loaded into this instance

    • revertUUID

      void revertUUID()
      Reverts user identifiers from UUID form back to legacy name-based identifiers.

      Used during migration or when switching away from UUID-backed storage.

    • setPersistent

      void setPersistent(boolean persistent)
      Enables or disables automatic persistence of in-memory changes.
      Parameters:
      persistent - true to write changes to storage immediately or on save; false to hold changes in memory only

    • writeContents

      void writeContents(Writer writer) throws IOException
      Writes a human-readable dump of backend contents to the given writer.
      Parameters:
      writer - destination writer
      Throws:
      IOException - if writing fails

    • diagnosticLabel

      String diagnosticLabel()
      Returns a short label describing this backend instance for diagnostics and logging.
      Returns:
      diagnostic label (for example backend type and connection target)