```
public interface PermissionService
```
Represents a provider of permissions data.
This is the interface that a permissions plugin must implement and register to provide permissions for users on the server. Subject related method calls on Players and Users are redirected to the active permission service.

Implementations of PermissionService are expected to be thread-safe.

Distinctions are made throughout the service between data which is currently available, and data which may exist, but is not currently loaded.

Methods prefixed with "get" will typically only return data if it is already loaded into memory. Methods prefixed with "load" however will load data into memory if necessary.

CompletableFutures are used throughout the service in situations where it is possible that calls may take a considerable time to execute. CompletableFuture.thenAcceptAsync(Consumer, Executor) can be used to run a callback once the method has completed. Alternatively, CompletableFuture.join() can be used, but care should be taken to avoid blocking the server thread.

Field Summary

Fields
Modifier and Type	Field	Description
`static java.lang.String`	`SUBJECTS_COMMAND_BLOCK`	The standard identifier for the collection which stores command block subjects.
`static java.lang.String`	`SUBJECTS_DEFAULT`	The standard identifier for the collection which stores default subjects.
`static java.lang.String`	`SUBJECTS_GROUP`	The standard identifier for the collection which stores groups.
`static java.lang.String`	`SUBJECTS_ROLE_TEMPLATE`	The standard identifier for the collection which stores role templates.
`static java.lang.String`	`SUBJECTS_SYSTEM`	The standard identifier for the collection which stores "system" subjects.
`static java.lang.String`	`SUBJECTS_USER`	The standard identifier for the collection which stores users.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`java.util.concurrent.CompletableFuture<? extends java.util.Set<java.lang.String>>`	`allIdentifiers()`	Returns a set of the subject collection identifiers known to this service.
`java.util.Optional<? extends SubjectCollection>`	`collection(java.lang.String identifier)`	Returns a subject collection with the given identifier, if the collection is already loaded within this service.
`Subject`	`defaults()`	Gets the subject holding data that is applied by default to all subjects.
`java.util.Optional<? extends PermissionDescription>`	`description(java.lang.String permission)`	Gets the registered or generated `PermissionDescription` for the given permission if available.
`java.util.Collection<? extends PermissionDescription>`	`descriptions()`	Gets a immutable collection containing all registered or generated `PermissionDescription`s.
`SubjectCollection`	`groupSubjects()`	Returns the subject collection which holds groups.
`java.util.concurrent.CompletableFuture<java.lang.Boolean>`	`hasCollection(java.lang.String identifier)`	Returns whether a subject collection with the given identifier currently exists.
`java.util.function.Predicate<java.lang.String>`	`identifierValidityPredicate()`	Returns a predicate which determines whether or not a given identifier is valid for a subject collection held by this service.
`java.util.concurrent.CompletableFuture<? extends SubjectCollection>`	`loadCollection(java.lang.String identifier)`	Loads and returns a subject collection with the given identifier.
`java.util.Map<java.lang.String,? extends SubjectCollection>`	`loadedCollections()`	Returns an immutable copy of all currently loaded subject collections held by this permission service.
`PermissionDescription.Builder`	`newDescriptionBuilder(org.spongepowered.plugin.PluginContainer plugin)`	Creates a new description builder for the given plugin's permission.
`SubjectReference`	`newSubjectReference(java.lang.String collectionIdentifier, java.lang.String subjectIdentifier)`	Creates a new subject reference to represent the expressed subject.
`default java.util.Optional<? extends SubjectData>`	`roleTemplate(org.spongepowered.plugin.PluginContainer plugin, java.lang.String roleTemplate)`	Get data for a role template for a specific plugin.
`default java.util.Set<? extends java.util.Map.Entry<org.spongepowered.plugin.PluginContainer,? extends SubjectData>>`	`roleTemplates(java.lang.String roleTemplate)`	Get the data contained in role templates for all plugins providing data at the given key
`SubjectCollection`	`userSubjects()`	Returns the subject collection which holds users.

- Field Detail
  - SUBJECTS_USER
```
static final java.lang.String SUBJECTS_USER
```
    The standard identifier for the collection which stores users.
    
    See Also:
    
    Constant Field Values
  - SUBJECTS_GROUP
```
static final java.lang.String SUBJECTS_GROUP
```
    The standard identifier for the collection which stores groups.
    
    See Also:
    
    Constant Field Values
  - SUBJECTS_SYSTEM
```
static final java.lang.String SUBJECTS_SYSTEM
```
    The standard identifier for the collection which stores "system" subjects.
    These are subjects which store data for objects within the server. For example, the server "console".
    
    See Also:
    
    Constant Field Values
  - SUBJECTS_DEFAULT
```
static final java.lang.String SUBJECTS_DEFAULT
```
    The standard identifier for the collection which stores default subjects.
    By convention, the defaults() subject is stored in this collection under the name "default", and each SubjectCollections SubjectCollection.defaults() subject is stored in this collection with the same identifier as the parent collection.
    
    See Also:
    
    Constant Field Values
  - SUBJECTS_COMMAND_BLOCK
```
static final java.lang.String SUBJECTS_COMMAND_BLOCK
```
    The standard identifier for the collection which stores command block subjects.
    
    See Also:
    
    Constant Field Values
  - SUBJECTS_ROLE_TEMPLATE
```
static final java.lang.String SUBJECTS_ROLE_TEMPLATE
```
    The standard identifier for the collection which stores role templates.
    Role templates are registered alongside PermissionDescriptions, via PermissionDescription.Builder.assign(String, boolean).
    
    See Also:
    
    Constant Field Values
- Method Detail
  - userSubjects
```
SubjectCollection userSubjects()
```
    Returns the subject collection which holds users.
    User identifiers are expected to be UUIDs in RFC4122 string format (This *does* have dashes).
    
    This method should return the same SubjectCollection as the result of invoking loadCollection(String) with SUBJECTS_USER.
    
    Returns:
    
    A subject collection for users
  - groupSubjects
```
SubjectCollection groupSubjects()
```
    Returns the subject collection which holds groups.
    This method should return the same SubjectCollection as the result of invoking loadCollection(String) with SUBJECTS_GROUP.
    
    Returns:
    
    A subject collection for groups
  - defaults
```
Subject defaults()
```
    Gets the subject holding data that is applied by default to all subjects.
    This subject is at the root of all inheritance trees, below even SubjectCollection defaults, meaning it has the lowest priority when all other weighting is equal.
    
    Note: This data may be persisted, so plugins that add permissions to this subject must take care to not override permissions already set or modified.
    
    It is also recommended to use Subject.transientSubjectData() where possible to avoid persisting unnecessary data.
    
    Assigning default permissions should be used sparingly, and by convention, only in situations where "default" game behaviour is restored by granting a certain permission.
    
    Returns:
    
    The subject holding defaults for all other subjects.
  - roleTemplate
```
default java.util.Optional<? extends SubjectData> roleTemplate(org.spongepowered.plugin.PluginContainer plugin,
                                                               java.lang.String roleTemplate)
```
    Get data for a role template for a specific plugin. If the plugin has not set any permissions for the given role template, an empty Optional will be returned. Whether role template information is persistent or transient is implementation-dependent, though the final choice should most likely be up to the user.
    
    Parameters:
    
    plugin - The plugin to query the role template for.
    
    roleTemplate - The specific role template identifier. Any string may be used, but PermissionDescription contains some common suggestions.
    
    Returns:
    
    An optional possibly containing the subject data for the given role template
  - roleTemplates
```
default java.util.Set<? extends java.util.Map.Entry<org.spongepowered.plugin.PluginContainer,? extends SubjectData>> roleTemplates(java.lang.String roleTemplate)
```
    Get the data contained in role templates for all plugins providing data at the given key
    
    Parameters:
    
    roleTemplate - The specific role template identifier. Any string may be used, but PermissionDescription contains some common suggestions.
    
    Returns:
    
    An immutable set of mappings from plugin to subject data holder.
  - identifierValidityPredicate
```
java.util.function.Predicate<java.lang.String> identifierValidityPredicate()
```
    Returns a predicate which determines whether or not a given identifier is valid for a subject collection held by this service.
    It is expected that as a minimum, the standard identifiers expressed as static parameters in this class will pass the predicate.
    
    Returns:
    
    The predicate
  - loadCollection
```
java.util.concurrent.CompletableFuture<? extends SubjectCollection> loadCollection(java.lang.String identifier)
```
    Loads and returns a subject collection with the given identifier.
    The returned future will complete exceptionally if the subject collection with the given identifier cannot be loaded.
    
    A IllegalArgumentException will be thrown directly by this method if the identifier does not pass the identifier validity predicate.
    
    Parameters:
    
    identifier - The identifier. All identifiers are case-insensitive
    
    Returns:
    
    A subject collection for the given identifier
    
    Throws:
    
    java.lang.IllegalArgumentException - If the collection identifier does not pass the validity predicate for this service
  - collection
```
java.util.Optional<? extends SubjectCollection> collection(java.lang.String identifier)
```
    Returns a subject collection with the given identifier, if the collection is already loaded within this service.
    It is important to note that a subject collection with the given identifier may still exist, even if this method returns an empty optional. Checking for the presence of a subject collection should be done using hasCollection(String).
    
    If the collection identifier does not pass the validity predicate, this method will return an empty optional, and not throw an exception.
    
    Parameters:
    
    identifier - The identifier
    
    Returns:
    
    A subject collection for the given identifier
  - hasCollection
```
java.util.concurrent.CompletableFuture<java.lang.Boolean> hasCollection(java.lang.String identifier)
```
    Returns whether a subject collection with the given identifier currently exists.
    
    Parameters:
    
    identifier - The identifier of the subject collection
    
    Returns:
    
    If the collection currently exists
  - loadedCollections
```
java.util.Map<java.lang.String,? extends SubjectCollection> loadedCollections()
```
    Returns an immutable copy of all currently loaded subject collections held by this permission service. This map is immutable.
    
    Returns:
    
    The loaded collections for this service
  - allIdentifiers
```
java.util.concurrent.CompletableFuture<? extends java.util.Set<java.lang.String>> allIdentifiers()
```
    Returns a set of the subject collection identifiers known to this service.
    
    Returns:
    
    A set of collection identifiers
  - newSubjectReference
```
SubjectReference newSubjectReference(java.lang.String collectionIdentifier,
                                     java.lang.String subjectIdentifier)
```
    Creates a new subject reference to represent the expressed subject.
    Note that instances of SubjectReference must be capable of resolving the identifier to a Subject without being passed a reference to the service.
    
    A IllegalArgumentException will be thrown directly by this method if either identifiers do not pass the identifier validity predicates.
    
    Parameters:
    
    collectionIdentifier - The identifier of the collection holding the subject
    
    subjectIdentifier - The identifier of the subject
    
    Returns:
    
    A subject reference to represent the expressed subject
    
    Throws:
    
    java.lang.IllegalArgumentException - If either identifiers do not pass the the validity predicates for this service / the collection.
  - newDescriptionBuilder
```
PermissionDescription.Builder newDescriptionBuilder(org.spongepowered.plugin.PluginContainer plugin)
```
    Creates a new description builder for the given plugin's permission.
    
    Parameters:
    
    plugin - The plugin to create permission descriptions for
    
    Returns:
    
    The newly created permission description builder
    
    Throws:
    
    java.lang.IllegalArgumentException - if plugin is not a plugin instance
  - description
```
java.util.Optional<? extends PermissionDescription> description(java.lang.String permission)
```
    Gets the registered or generated PermissionDescription for the given permission if available.
    If the given permission is not defined itself this might also return the associated permission template.
    
    Parameters:
    
    permission - The permission to get the description for
    
    Returns:
    
    The description for the given permission or Optional.empty()
  - descriptions
```
java.util.Collection<? extends PermissionDescription> descriptions()
```
    Gets a immutable collection containing all registered or generated PermissionDescriptions.
    Implementations may generate descriptions automatically for permissions in use on the server, based upon permissions stored in subject data, or based upon checks being performed.
    
    Returns:
    
    An immutable collection contain all registered or generated descriptions

Interface PermissionService

Field Summary

Method Summary

Field Detail

SUBJECTS_USER

SUBJECTS_GROUP

SUBJECTS_SYSTEM

SUBJECTS_DEFAULT

SUBJECTS_COMMAND_BLOCK

SUBJECTS_ROLE_TEMPLATE

Method Detail

userSubjects

groupSubjects

defaults

roleTemplate

roleTemplates

identifierValidityPredicate

loadCollection

collection

hasCollection

loadedCollections

allIdentifiers

newSubjectReference

newDescriptionBuilder

description

descriptions