public interface PermissionService extends ContextualService<Subject>
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.
CompletableFuture
s 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.
Modifier and Type | Field and Description |
---|---|
static String |
SUBJECTS_COMMAND_BLOCK
The standard identifier for the collection which stores command block
subjects.
|
static String |
SUBJECTS_DEFAULT
The standard identifier for the collection which stores default subjects.
|
static String |
SUBJECTS_GROUP
The standard identifier for the collection which stores groups.
|
static String |
SUBJECTS_ROLE_TEMPLATE
The standard identifier for the collection which stores role templates.
|
static String |
SUBJECTS_SYSTEM
The standard identifier for the collection which stores "system"
subjects.
|
static String |
SUBJECTS_USER
The standard identifier for the collection which stores users.
|
Modifier and Type | Method and Description |
---|---|
CompletableFuture<Set<String>> |
getAllIdentifiers()
Returns a set of the subject collection identifiers known to this
service.
|
Optional<SubjectCollection> |
getCollection(String identifier)
Returns a subject collection with the given identifier, if the
collection is already loaded within this service.
|
Subject |
getDefaults()
Gets the subject holding data that is applied by default to all
subjects.
|
Optional<PermissionDescription> |
getDescription(String permission)
Gets the registered or generated
PermissionDescription for the
given permission if available. |
Collection<PermissionDescription> |
getDescriptions()
Gets a immutable collection containing all registered or generated
PermissionDescription s. |
SubjectCollection |
getGroupSubjects()
Returns the subject collection which holds groups.
|
Predicate<String> |
getIdentifierValidityPredicate()
Returns a predicate which determines whether or not a given identifier
is valid for a subject collection held by this service.
|
Map<String,SubjectCollection> |
getLoadedCollections()
Returns an immutable copy of all currently loaded subject collections
held by this permission service.
|
SubjectCollection |
getUserSubjects()
Returns the subject collection which holds users.
|
CompletableFuture<Boolean> |
hasCollection(String identifier)
Returns whether a subject collection with the given identifier currently
exists.
|
CompletableFuture<SubjectCollection> |
loadCollection(String identifier)
Loads and returns a subject collection with the given identifier.
|
PermissionDescription.Builder |
newDescriptionBuilder(Object plugin)
Creates a new description builder for the given plugin's permission.
|
SubjectReference |
newSubjectReference(String collectionIdentifier,
String subjectIdentifier)
Creates a new subject reference to represent the expressed subject.
|
registerContextCalculator
static final String SUBJECTS_USER
static final String SUBJECTS_GROUP
static final String SUBJECTS_SYSTEM
These are subjects which store data for objects within the server. For example, the server "console".
static final String SUBJECTS_DEFAULT
By convention, the getDefaults()
subject is stored in this
collection under the name "default", and each SubjectCollection
s
SubjectCollection.getDefaults()
subject is stored in this
collection with the same identifier as the parent collection.
static final String SUBJECTS_COMMAND_BLOCK
static final String SUBJECTS_ROLE_TEMPLATE
Role templates are registered alongside PermissionDescription
s,
via PermissionDescription.Builder.assign(String, boolean)
.
SubjectCollection getUserSubjects()
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
.
SubjectCollection getGroupSubjects()
This method should return the same SubjectCollection as the result of
invoking loadCollection(String)
with SUBJECTS_GROUP
.
Subject getDefaults()
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.getTransientSubjectData()
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.
Predicate<String> getIdentifierValidityPredicate()
It is expected that as a minimum, the standard identifiers expressed as static parameters in this class will pass the predicate.
CompletableFuture<SubjectCollection> loadCollection(String 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.
identifier
- The identifier. All identifiers are case-insensitiveIllegalArgumentException
- If the collection identifier does not
pass the validity predicate for this
serviceOptional<SubjectCollection> getCollection(String identifier)
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.
identifier
- The identifierCompletableFuture<Boolean> hasCollection(String identifier)
identifier
- The identifier of the subject collectionMap<String,SubjectCollection> getLoadedCollections()
CompletableFuture<Set<String>> getAllIdentifiers()
SubjectReference newSubjectReference(String collectionIdentifier, String subjectIdentifier)
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.
collectionIdentifier
- The identifier of the collection holding the
subjectsubjectIdentifier
- The identifier of the subjectIllegalArgumentException
- If either identifiers do not pass the
the validity predicates for this
service / the collection.PermissionDescription.Builder newDescriptionBuilder(Object plugin)
plugin
- The plugin to create permission descriptions forIllegalArgumentException
- if plugin is not a plugin instanceOptional<PermissionDescription> getDescription(String permission)
PermissionDescription
for the
given permission if available.
If the given permission is not defined itself this might also return the associated permission template.
permission
- The permission to get the description forOptional.empty()
Collection<PermissionDescription> getDescriptions()
PermissionDescription
s.
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.