org.spongepowered.api.service.permission

Interface PermissionDescription

public interface PermissionDescription

A description object for permissions.

The description is meant to provide human readable descriptions and meta data for a permission.

Descriptions DO NOT have any impact on permission check, and are only provided and registered for an informational purpose.

Instances can be built using PermissionService.newDescriptionBuilder(Object).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	PermissionDescription.Builder A builder for permission descriptions.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ROLE_ADMIN The standard role for admins.
static String	ROLE_STAFF The standard role for staff.
static String	ROLE_USER The standard role for users.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Map<SubjectReference,Boolean>>	findAssignedSubjects(String collectionIdentifier) Gets all subjects that have this permission set in the given collection.
Map<Subject,Boolean>	getAssignedSubjects(String collectionIdentifier) Gets all loaded subjects that have this permission set in the given collection.
Optional<Text>	getDescription() Gets a short description of the linked permission.
String	getId() Gets the permission id this description belongs to.
Optional<PluginContainer>	getOwner() Gets the owning plugin the permission belongs to.

Field Detail

ROLE_USER

static final String ROLE_USER

The standard role for users.

The user role should be assigned to permissions where everyone should have basic access. For example: joining in an arena.

See Also:

Constant Field Values

ROLE_STAFF

static final String ROLE_STAFF

The standard role for staff.

The staff role should be assigned to permissions only meant for users with elevated access permissions. For example: force start an arena.

See Also:

Constant Field Values

ROLE_ADMIN

static final String ROLE_ADMIN

The standard role for admins.

The admin role should be assigned to permissions only meant for users with full access to administrate the server. For example: setup an arena.

See Also:

Constant Field Values

Method Detail

getId

String getId()

Gets the permission id this description belongs to.

The permission id must be of the specified format as specified using EBNF:

• CHARACTER = "A" - "Z" | "a" - "z" | "0" - "9" | "_" | "-"
• NAME = CHARACTER , { CHARACTER }
• TEMPLATE = "<" , NAME , ">"
• PART = NAME | TEMPLATE
• PERMISSION = NAME , { "." , PART }

The following examples shall help you to structure your permissions well:

• "myplugin" - Grants everything in myPlugin
• "myplugin.give" - Grants everything related to give including all ItemTypes and Enchantments
• "myplugin.give.execute" - Allows the execution of give
• "myplugin.give.type" - Grants all ItemTypes
• "myplugin.give.type.<ItemType>" - A template should not be granted to anybody
• "myplugin.give.type.minecraft.diamond" - Only grants minecraft:diamond
• "myplugin.give.enchantment" - Grants all Enchantments
• "myplugin.give.others" - Allow giving to other players

The addition of the "execute" permission instead of just "myPlugin.give" permission is useful to prevent unauthorized access to sub-permissions that are not documented or have been added lately.

So if you want to allow someone to give themself only DIAMONDs, you would assign them the following permissions:

• "myPlugin.give.execute"
• "myPlugin.give.type.DIAMOND"

Note: Permission ids are case insensitive! Permission ids should start with the owning plugin's id.

Returns:

The permission id

getDescription

Optional<Text> getDescription()

Gets a short description of the linked permission.

May include a link to a more detailed description on the plugin's web page.

Will return an empty optional for descriptions which have been automatically generated, or where a description was omitted when the PermissionDescription was created.

Returns:

A short description of the linked permission

getOwner

Optional<PluginContainer> getOwner()

Gets the owning plugin the permission belongs to.

Will return an empty optional for descriptions which have been automatically generated.

Returns:

The owning plugin the permission belongs to

findAssignedSubjects

CompletableFuture<Map<SubjectReference,Boolean>> findAssignedSubjects(String collectionIdentifier)

Gets all subjects that have this permission set in the given collection.

If you want to know to which role-templates this permission is assigned, use PermissionService.SUBJECTS_ROLE_TEMPLATE.

This method is equivalent to calling SubjectCollection.getAllWithPermission(String) for the given collection, using getId() as the permission.

Parameters:

collectionIdentifier - The subject collection to query

Returns:

A reference to any subject known to have this permission set, and the value this permission is set to

See Also:

SubjectCollection.getAllWithPermission(String)

getAssignedSubjects

Map<Subject,Boolean> getAssignedSubjects(String collectionIdentifier)

Gets all loaded subjects that have this permission set in the given collection.

If you want to know to which role-templates this permission is assigned, use PermissionService.SUBJECTS_ROLE_TEMPLATE.

This method is equivalent to calling SubjectCollection.getLoadedWithPermission(String) for the given collection, using getId() as the permission.

This method will return an empty map if the given collection is not loaded or does not exist.

Parameters:

collectionIdentifier - The subject collection to query

Returns:

An immutable map of subjects that have this permission set

See Also:

SubjectCollection.getLoadedWithPermission(String)