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 Details

    • 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 Details

    • 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:

    • 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