Package org.spongepowered.api.service.permission

Interface SubjectData

  • public interface SubjectData
    Container for a subject's data.

    This container updates live, and provides raw data for a subject not taking into account any sort of inheritance. This interface is meant to represent what's 'in the file', rather than the higher-level query methods available in Subject.

    Methods which modify the state of the data return CompletableFutures. This allows for the time which is taken to apply and persist the change to the implementations storage backend. These futures should return quickly for changes made to transient subject data, but may take longer to return for changes made to a subjects persistent data. Methods which use this data in Subject may not reflect the change until the future has returned.

    CompletableFuture.allOf(CompletableFuture[]) can be used to combine multiple futures into one, if the result of methods is not needed.

    • Field Detail

      • GLOBAL_CONTEXT

        static final Set<Context> GLOBAL_CONTEXT
        A convenience constant for the global context combination (the empty set), if you want your code to look especially fancy.

    • Method Detail

      • subject

        Subject subject()
        Gets the Subject which holds this data.
        Returns:
        The subject which holds this data

      • isTransient

        boolean isTransient()
        Return if this SubjectData is transient.
        Returns:
        If this SubjectData is transient
        See Also:
        Subject.transientSubjectData()

      • allPermissions

        Map<Set<Context>,​Map<String,​Boolean>> allPermissions()
        Return all permissions associated with this data object.
        Returns:
        An immutable copy of the mappings between contexts and lists of permissions containing every permission registered

      • permissions

        Map<String,​Boolean> permissions​(Set<Context> contexts)
        Returns the list of permissions set for the given context.

        This list is immutable and is not a live view. If no permissions have been set, it returns an empty list.

        Parameters:
        contexts - The particular context combination to check
        Returns:
        Any permissions set

      • setPermission

        CompletableFuture<Boolean> setPermission​(Set<Context> contexts,
                                         String permission,
                                         Tristate value)
        Sets a permission to a given value.

        Setting value as Tristate.UNDEFINED unsets the permission.

        An empty set of contexts applies this permission to the global context.

        Parameters:
        contexts - The particular combination of contexts to set this permission in
        permission - The permission to set
        value - The value to set this permission to
        Returns:
        Whether the operation was successful

      • setPermissions

        CompletableFuture<Boolean> setPermissions​(Set<Context> contexts,
                                          Map<String,​Boolean> permissions,
                                          TransferMethod method)
        Sets permissions in a given context combination.

        An empty set of contexts applies these permissions to the global context.

        Depending on the TransferMethod chosen, this will either replace all existing options or add to the existing options.

        Parameters:
        contexts - The particular combination of contexts to set these permissions in
        permissions - The permissions to set
        method - How to treat existing values in this subject
        Returns:
        Whether the operation was successful

      • fallbackPermissionValue

        Tristate fallbackPermissionValue​(Set<Context> contexts)
        Get the permission value that will be returned if no more specific permission setting matches.
        Parameters:
        contexts - The context combination to set this permission in.
        Returns:
        The tristate

      • allFallbackPermissionValues

        Map<Set<Context>,​Tristate> allFallbackPermissionValues()
        Get all fallback permission values set on this subject data
        Returns:
        An immutable map from context combination to fallback value

      • setFallbackPermissionValue

        CompletableFuture<Boolean> setFallbackPermissionValue​(Set<Context> contexts,
                                                      Tristate fallback)
        Set the permission value at the root of the node tree, that will be returned as a response to permissions queries when no more specific permission matches.
        Parameters:
        contexts - The context combination
        fallback - The new fallback value. Tristate.UNDEFINED unsets the fallback value.
        Returns:
        A future completing when the change has been applied

      • clearFallbackPermissionValues

        CompletableFuture<Boolean> clearFallbackPermissionValues()
        Clear all fallback permission values from this subject
        Returns:
        A future completing when the change has been applied

      • clearPermissions

        CompletableFuture<Boolean> clearPermissions()
        Clear all permissions set in any context.
        Returns:
        Whether any change occurred

      • clearPermissions

        CompletableFuture<Boolean> clearPermissions​(Set<Context> contexts)
        Clear all permissions set in a given context combination.

        Passing an empty context set clears permissions in the global context.

        Parameters:
        contexts - The context combination to clear permissions in
        Returns:
        Whether any change occurred

      • allParents

        Map<Set<Context>,​? extends List<? extends SubjectReference>> allParents()
        Return all registered parent subjects for all contexts.

        The returned map is immutable and not a live view. The results of this method do not traverse any sort of inheritance structure a permissions plugin may implement.

        Returns:
        All registered parents and the context they are registered in

      • parents

        List<? extends SubjectReference> parents​(Set<Context> contexts)
        Return all registered parent subjects for a given context.

        The returned list is immutable and not a live view. The results of this method do not traverse any sort of inheritance structure a permissions plugin may implement.

        Parameters:
        contexts - The context to check
        Returns:
        names of parents valid in the given context

      • setParents

        CompletableFuture<Boolean> setParents​(Set<Context> contexts,
                                      List<? extends SubjectReference> parents,
                                      TransferMethod method)
        Sets the parents in a particular context combination.

        Passing an empty context combination means the parents are set in the global context.

        Depending on the TransferMethod chosen, this will either replace all existing options or add to the existing options.

        Parameters:
        contexts - The context combination this operation is applicable to
        parents - A list of the parents this subject should have
        Returns:
        Whether the operation was successful

      • addParent

        CompletableFuture<Boolean> addParent​(Set<Context> contexts,
                                     SubjectReference parent)
        Adds a parent in a particular context combination.

        Passing an empty context combination means the parent is added in the global context.

        Parameters:
        contexts - The context combination this operation is applicable to
        parent - The name of the parent to add
        Returns:
        Whether the operation was successful

      • removeParent

        CompletableFuture<Boolean> removeParent​(Set<Context> contexts,
                                        SubjectReference parent)
        Removes a parent in a particular context combination.

        Passing an empty context combination means the parent is removed in the global context.

        Parameters:
        contexts - The context combination this operation is applicable to
        parent - The name of the parent to remove
        Returns:
        Whether the operation was successful

      • clearParents

        CompletableFuture<Boolean> clearParents()
        Remove all parents in any context combination.
        Returns:
        Whether any change occurred

      • clearParents

        CompletableFuture<Boolean> clearParents​(Set<Context> contexts)
        Remove all parents in a given context combination.

        Passing an empty context set clears parents in the global context.

        Parameters:
        contexts - The context combination to clear the parents of
        Returns:
        Whether any change occurred

      • allOptions

        Map<Set<Context>,​Map<String,​String>> allOptions()
        Return all options for all context combinations currently registered.
        Returns:
        An immutable snapshot of all options data

      • options

        Map<String,​String> options​(Set<Context> contexts)
        Gets options for a specific context combination.
        Parameters:
        contexts - The context combination to get options for
        Returns:
        All available options, returning an empty map if none are present

      • setOption

        CompletableFuture<Boolean> setOption​(Set<Context> contexts,
                                     String key,
                                     @Nullable String value)
        Sets a specific option to a value.

        Passing a null value will unset the option.

        Parameters:
        contexts - The context combination to set the given option in
        key - The key to set. Case-insensitive.
        value - The value to set.
        Returns:
        Whether the operation was successful

      • setOptions

        CompletableFuture<Boolean> setOptions​(Set<Context> contexts,
                                      Map<String,​String> options,
                                      TransferMethod method)
        Sets all options in a particular context.

        Depending on the TransferMethod chosen, this will either replace all existing options or add to the existing options.

        Parameters:
        contexts - The context combination to set the options in
        options - The map of options to set
        Returns:
        Whether the operation was successful

      • clearOptions

        CompletableFuture<Boolean> clearOptions()
        Clear all options.
        Returns:
        Whether the operation was successful

      • clearOptions

        CompletableFuture<Boolean> clearOptions​(Set<Context> contexts)
        Clear all options in the given context combination.

        Passing an empty context set clears options in the global context.

        Parameters:
        contexts - The context combination
        Returns:
        Whether the operation was successful (any options were removed)

      • copyFrom

        CompletableFuture<Boolean> copyFrom​(SubjectData other,
                                    TransferMethod method)
        Copy all data from another subject data instance into this one, preserving the original subject. It is expected that the other subject data is provided by the same permissions service. This methods's behaviour is undefined otherwise.
        Parameters:
        other - The other subject to copy data from
        method - How to treat existing values in this subject
        Returns:
        A future completing with true if the operation is successful

      • moveFrom

        CompletableFuture<Boolean> moveFrom​(SubjectData other,
                                    TransferMethod method)
        Move all data from another subject data instance into this one, clearing the source It is expected that the other subject data is provided by the same permissions service. This methods's behaviour is undefined otherwise.
        Parameters:
        other - The other subject to move data from
        method - How to treat existing values in this subject
        Returns:
        A future completing with true if the operation is successful