public interface Subject
Authorization checks are made using "permission strings."
Permission strings are hierarchical with each level separated by periods
(full stops). An example of a valid permission string is example.function
. Inheritance is implicit; that is, if a subject has been
granted example
, then the subject should have also be automatically
granted example.function
, example.another
, example.deeper.nesting
, and so on. However, implementations may allow
administrators to configure "negation" such that example
and all
child levels would granted but example.access
would denied (for
example).
Plugins may opt to implement "dynamic" permissions such as example.region.define.<region>
where region
would be a
dynamically added level based on the context, though some attention should be
made towards the handling of periods / full stops in such cases.
Due to the implicit inheritance, it is recommended that commands that allow a
user to "apply" an effect to other users use example.function.self
as
the permission for applying this effect to one's self. This allows
administrators to grant example.function.self
to permit usage on
one's self and grant example.function
to grant usage on other users.
Use a PermissionService
to create instances.
PermissionService
Modifier and Type | Method and Description |
---|---|
Set<Context> |
getActiveContexts()
Calculate active contexts, using the
ContextCalculator s
from PermissionService.registerContextCalculator(org.spongepowered.api.service.permission.context.ContextCalculator) . |
Optional<CommandSource> |
getCommandSource()
If this subject represents an actual user currently connected, this
method returns this user.
|
SubjectCollection |
getContainingCollection()
Returns the subject collection this subject is a member of.
|
String |
getIdentifier()
Returns the identifier associated with this subject.
|
List<Subject> |
getParents()
Return all parents that this group has in its current context
combination.
|
List<Subject> |
getParents(Set<Context> contexts)
Return all parents that this group has.
|
Tristate |
getPermissionValue(Set<Context> contexts,
String permission)
Returns the calculated value set for a given permission.
|
SubjectData |
getSubjectData()
The container for permissions data that *may* be persisted if the service
provider supports it.
|
SubjectData |
getTransientSubjectData()
Returns container for subject data that is guaranteed to be transient
(only lasting for the duration of the subject's session, not persisted).
|
boolean |
hasPermission(Set<Context> contexts,
String permission)
Test whether the subject is permitted to perform an action given as the
given permission string.
|
boolean |
hasPermission(String permission)
Test whether the subject is permitted to perform an action given as the
given permission string.
|
boolean |
isChildOf(Set<Context> contexts,
Subject parent)
Check if this subject is a child of the given parent in the given context
combination, traversing inheritance.
|
boolean |
isChildOf(Subject parent)
Check if this subject is a child of the given parent in the subject's
current context, traversing inheritance.
|
String getIdentifier()
Optional<CommandSource> getCommandSource()
SubjectCollection getContainingCollection()
SubjectData getSubjectData()
SubjectData getTransientSubjectData()
getSubjectData()
if the provider
for this service does not implement persistence for permissions databoolean hasPermission(Set<Context> contexts, String permission)
contexts
- The set of contexts that represents the subject's current environmentpermission
- The permission stringboolean hasPermission(String permission)
permission
- The permission stringTristate getPermissionValue(Set<Context> contexts, String permission)
contexts
- The contexts to check for permissions inpermission
- The permission to checkboolean isChildOf(Subject parent)
parent
- The parent to check for inheritanceboolean isChildOf(Set<Context> contexts, Subject parent)
contexts
- The context combination to check inparent
- The parent to check for inheritanceList<Subject> getParents()
List<Subject> getParents(Set<Context> contexts)
contexts
- The set of contexts that represents the subject's current environmentSet<Context> getActiveContexts()
ContextCalculator
s
from PermissionService.registerContextCalculator(org.spongepowered.api.service.permission.context.ContextCalculator)
.
The result of these calculations may be cached.