Package ca.stellardrift.permissionsex.impl

Class PermissionsEx<P>

  • All Implemented Interfaces:
    ca.stellardrift.permissionsex.context.ContextDefinitionProvider, ca.stellardrift.permissionsex.datastore.DataStoreContext, ca.stellardrift.permissionsex.PermissionsEngine, Consumer<ca.stellardrift.permissionsex.context.ContextInheritance>
    public class PermissionsEx<P>
extends Object
implements Consumer<ca.stellardrift.permissionsex.context.ContextInheritance>, ca.stellardrift.permissionsex.context.ContextDefinitionProvider, ca.stellardrift.permissionsex.PermissionsEngine, ca.stellardrift.permissionsex.datastore.DataStoreContext
    The entry point to the PermissionsEx engine.

    The fastest way to get going with working with subjects is to access a subject type collection with subjects(SubjectType) and request a CalculatedSubjectImpl to query data from. Directly working with ToDataSubjectRefImpls is another option, preferable if most of the operations being performed are writes, or querying data directly defined on a subject.

    Keep in mind most of PEX's core data objects are immutable and must be resubmitted to their holders to apply updates. Most write operations are done asynchronously, and futures are returned that complete when the backend is finished writing out data. For larger operations, it can be useful to perform changes within performBulkOperation(Supplier), which will reduce unnecessary writes to the backing data store in some cases.

    • Method Detail

      • defaults

        public ca.stellardrift.permissionsex.subject.SubjectTypeCollection<ca.stellardrift.permissionsex.subject.SubjectType<?>> defaults()
        Specified by:
        defaults in interface ca.stellardrift.permissionsex.PermissionsEngine

      • defaultsType

        public ca.stellardrift.permissionsex.subject.SubjectType<ca.stellardrift.permissionsex.subject.SubjectType<?>> defaultsType()
        Specified by:
        defaultsType in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • fallbacks

        public ca.stellardrift.permissionsex.subject.SubjectTypeCollection<ca.stellardrift.permissionsex.subject.SubjectType<?>> fallbacks()
        Specified by:
        fallbacks in interface ca.stellardrift.permissionsex.PermissionsEngine

      • fallbacksType

        public ca.stellardrift.permissionsex.subject.SubjectType<ca.stellardrift.permissionsex.subject.SubjectType<?>> fallbacksType()
        Specified by:
        fallbacksType in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • registerSubjectTypes

        public void registerSubjectTypes​(ca.stellardrift.permissionsex.subject.SubjectType<?>... types)
        Specified by:
        registerSubjectTypes in interface ca.stellardrift.permissionsex.PermissionsEngine

      • subjects

        public <I> SubjectTypeCollectionImpl<I> subjects​(ca.stellardrift.permissionsex.subject.SubjectType<I> type)
        Get the collection of subjects of a given type. No data is loaded in this operation. Any string is supported as a subject type, but some common types have been provided as constants in this class for convenience.
        Specified by:
        subjects in interface ca.stellardrift.permissionsex.PermissionsEngine
        Parameters:
        type - The type identifier requested. Can be any string
        Returns:
        The subject type collection
        See Also:
        PermissionsEngine.defaults()

      • subjectType

        public ca.stellardrift.permissionsex.subject.SubjectType<?> subjectType​(String id)

      • loadedSubjectTypes

        public Collection<SubjectTypeCollectionImpl<?>> loadedSubjectTypes()
        Get a view of the currently cached subject types
        Specified by:
        loadedSubjectTypes in interface ca.stellardrift.permissionsex.PermissionsEngine
        Returns:
        Unmodifiable view of the currently cached subject types

      • knownSubjectTypes

        public Set<ca.stellardrift.permissionsex.subject.SubjectType<?>> knownSubjectTypes()
        Get all registered subject types in the active data store. The set is an immutable copy of the backend data.
        Specified by:
        knownSubjectTypes in interface ca.stellardrift.permissionsex.PermissionsEngine
        Returns:
        A set of registered subject types

      • engine

        public ca.stellardrift.permissionsex.PermissionsEngine engine()
        Specified by:
        engine in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • deserializeSubjectRef

        public ca.stellardrift.permissionsex.subject.SubjectRef<?> deserializeSubjectRef​(String type,
                                                                                 String name)
        Specified by:
        deserializeSubjectRef in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • lazySubjectRef

        public ca.stellardrift.permissionsex.subject.SubjectRef<?> lazySubjectRef​(String type,
                                                                          String identifier)
        Specified by:
        lazySubjectRef in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • performBulkOperation

        public <T> CompletableFuture<T> performBulkOperation​(Supplier<CompletableFuture<T>> func)
        Suppress writes to the data store for the duration of a specific operation. Only really useful for extremely large operations
        Type Parameters:
        T - The type of data that will be returned
        Parameters:
        func - The operation to perform
        Returns:
        A future that completes once all data has been written to the store

      • ladders

        public ca.stellardrift.permissionsex.rank.RankLadderCollection ladders()
        Access rank ladders through a cached interface
        Specified by:
        ladders in interface ca.stellardrift.permissionsex.PermissionsEngine
        Returns:
        Access to rank ladders

      • importDataFrom

        public CompletableFuture<?> importDataFrom​(String dataStoreIdentifier)
        Imports data into the currently active backend from another configured backend.
        Parameters:
        dataStoreIdentifier - The identifier of the backend to import from
        Returns:
        A future that completes once the import operation is complete

      • getNotifier

        public ca.stellardrift.permissionsex.logging.PermissionCheckNotifier getNotifier()
        Get the currently active notifier. This object has callbacks triggered on every permission check
        Returns:
        The active notifier

      • debugMode

        public boolean debugMode()
        Know whether or not debug mode is enabled
        Specified by:
        debugMode in interface ca.stellardrift.permissionsex.PermissionsEngine
        Returns:
        true if debug mode is enabled

      • debugMode

        public void debugMode​(boolean debug,
                      @Nullable Pattern filterPattern)
        Set whether or not debug mode is enabled. Debug mode logs all permission, option, and inheritance checks made to the console.
        Specified by:
        debugMode in interface ca.stellardrift.permissionsex.PermissionsEngine
        Parameters:
        debug - Whether to enable debug mode
        filterPattern - A pattern to filter which permissions are logged. Null for no filter.

      • initialize

        public void initialize​(PermissionsExConfiguration<P> config)
                throws ca.stellardrift.permissionsex.exception.PermissionsLoadingException
        Throws:
        ca.stellardrift.permissionsex.exception.PermissionsLoadingException

      • reload

        public CompletableFuture<Void> reload()
        Reload the configuration file in use and refresh backend data
        Returns:
        A future that completes once a reload has finished

      • close

        public void close()
        Shut down the PEX engine. Once this has been done, no further action can be taken until the engine is reinitialized with a fresh configuration.

      • logger

        public ca.stellardrift.permissionsex.logging.FormattedLogger logger()
        Specified by:
        logger in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • baseDirectory

        public Path baseDirectory()
        Specified by:
        baseDirectory in interface ca.stellardrift.permissionsex.datastore.DataStoreContext

      • asyncExecutor

        public Executor asyncExecutor()
        Get an executor to run tasks asynchronously on.
        Specified by:
        asyncExecutor in interface ca.stellardrift.permissionsex.datastore.DataStoreContext
        Returns:
        The async executor

      • config

        public PermissionsExConfiguration<P> config()
        Get the current configuration PEX is operating with. This object is immutable.
        Returns:
        The current configuration object

      • activeDataStore

        public ca.stellardrift.permissionsex.datastore.DataStore activeDataStore()

      • contextInheritance

        public CompletableFuture<ca.stellardrift.permissionsex.context.ContextInheritance> contextInheritance​(@Nullable Consumer<ca.stellardrift.permissionsex.context.ContextInheritance> listener)
        Get context inheritance data.

        The result of the future is immutable -- to take effect, the object returned by any update methods in ContextInheritance must be passed to contextInheritance(ContextInheritance). It follows that anybody else's changes will not appear in the returned inheritance object -- so if updates are desired providing a callback function is important.

        Specified by:
        contextInheritance in interface ca.stellardrift.permissionsex.PermissionsEngine
        Parameters:
        listener - A callback function that will be triggered whenever there is a change to the context inheritance
        Returns:
        A future providing the current context inheritance data

      • contextInheritance

        public CompletableFuture<ca.stellardrift.permissionsex.context.ContextInheritance> contextInheritance​(ca.stellardrift.permissionsex.context.ContextInheritance newInheritance)
        Update the context inheritance when values have been changed
        Specified by:
        contextInheritance in interface ca.stellardrift.permissionsex.PermissionsEngine
        Parameters:
        newInheritance - The modified inheritance object
        Returns:
        A future containing the latest context inheritance object

      • accept

        public void accept​(ca.stellardrift.permissionsex.context.ContextInheritance newData)
        Listener method that handles changes to context inheritance. Should not be called by outside users
        Specified by:
        accept in interface Consumer<P>
        Parameters:
        newData - The new data to replace cached information

      • usedContextTypes

        public CompletableFuture<Set<ca.stellardrift.permissionsex.context.ContextDefinition<?>>> usedContextTypes()
        Specified by:
        usedContextTypes in interface ca.stellardrift.permissionsex.context.ContextDefinitionProvider

      • registerContextDefinition

        public <T> boolean registerContextDefinition​(ca.stellardrift.permissionsex.context.ContextDefinition<T> contextDefinition)
        Specified by:
        registerContextDefinition in interface ca.stellardrift.permissionsex.context.ContextDefinitionProvider

      • registerContextDefinitions

        public int registerContextDefinitions​(ca.stellardrift.permissionsex.context.ContextDefinition<?>... definitions)
        Specified by:
        registerContextDefinitions in interface ca.stellardrift.permissionsex.context.ContextDefinitionProvider

      • registeredContextTypes

        public List<ca.stellardrift.permissionsex.context.ContextDefinition<?>> registeredContextTypes()
        Specified by:
        registeredContextTypes in interface ca.stellardrift.permissionsex.context.ContextDefinitionProvider

      • contextDefinition

        public @Nullable ca.stellardrift.permissionsex.context.ContextDefinition<?> contextDefinition​(String definitionKey,
                                                                                              boolean allowFallbacks)
        Specified by:
        contextDefinition in interface ca.stellardrift.permissionsex.context.ContextDefinitionProvider