Package 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 metadata for a permission, and a central point for the plugin registering each permission.

    Descriptions are primarily informational, but some default value information may be provided here.

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

    • Nested Class Summary

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

    • Field Summary

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

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.Map<? extends Subject,​java.lang.Boolean> assignedSubjects​(java.lang.String collectionIdentifier)
      Gets all loaded subjects that have this permission set in the given collection.
      Tristate defaultValue()
      Gets the default value this permission should have on this server.
      java.util.Optional<Component> description()
      Gets a short description of the linked permission.
      java.util.concurrent.CompletableFuture<? extends java.util.Map<? extends SubjectReference,​java.lang.Boolean>> findAssignedSubjects​(java.lang.String collectionIdentifier)
      Gets all subjects that have this permission set in the given collection.
      java.lang.String id()
      Gets the permission id this description belongs to.
      java.util.Optional<org.spongepowered.plugin.PluginContainer> owner()
      Gets the owning plugin the permission belongs to.
      boolean query​(Subject subj)
      Check if the given subject has the permission described.
      boolean query​(Subject subj, java.lang.String parameter)
      Check if the given subject has the permission described.
      boolean query​(Subject subj, java.lang.String... parameters)
      Check if the given subject has the permission described.
      boolean query​(Subject subj, ResourceKey key)
      Check if the given subject has the permission described.

    • Field Detail

      • ROLE_USER

        static final java.lang.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 java.lang.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 java.lang.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

      • id

        java.lang.String id()
        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 , ">"
        • PERMISSION = NAME , { "." , NAME }, {".", TEMPLATE}

        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.<item-type>" - 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.minecraft.diamond"

        Note: Permission ids are case insensitive! If permission ids do not start with the plugin ID, implementations will prepend the plugin ID (so command.give will turn into myplugin.command.give)

        Returns:
        The permission id

      • description

        java.util.Optional<Component> description()
        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

      • owner

        java.util.Optional<org.spongepowered.plugin.PluginContainer> owner()
        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

      • defaultValue

        Tristate defaultValue()
        Gets the default value this permission should have on this server. This value will have been applied to the default subject.
        Returns:
        The default value for this permission.

      • findAssignedSubjects

        java.util.concurrent.CompletableFuture<? extends java.util.Map<? extends SubjectReference,​java.lang.Boolean>> findAssignedSubjects​(java.lang.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.allWithPermission(String) for the given collection, using id() 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.allWithPermission(String)

      • assignedSubjects

        java.util.Map<? extends Subject,​java.lang.Boolean> assignedSubjects​(java.lang.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.loadedWithPermission(String) for the given collection, using id() 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.loadedWithPermission(String)

      • query

        boolean query​(Subject subj)
        Check if the given subject has the permission described.

        If id() contains any template parameters, they will be stripped out. See overloads if parameters are desired.

        Parameters:
        subj - The subject to query
        Returns:
        Whether the given subject has this permission.

      • query

        boolean query​(Subject subj,
              ResourceKey key)
        Check if the given subject has the permission described.

        Template parameters will be trimmed, and the catalog key will be appended in the format Key.namespace().Key.value().

        Parameters:
        subj - The subject to query
        key - The catalog key to relativize this permission for
        Returns:
        Whether the given subject has this permission.

      • query

        boolean query​(Subject subj,
              java.lang.String... parameters)
        Check if the given subject has the permission described.

        Template parameters will be trimmed from the permission, and the given parameters will be appended joined by ..

        Parameters:
        subj - The subject to query
        parameters - The parameters to append to the permission being checked
        Returns:
        Whether the given subject has this permission.

      • query

        boolean query​(Subject subj,
              java.lang.String parameter)
        Check if the given subject has the permission described.

        Template parameters will be trimmed from the permission, and the given parameter will be appended

        Parameters:
        subj - The subject to query
        parameter - The parameter to append to the permission when checking
        Returns:
        Whether the given subject has this permission.