Package de.hybris.platform.servicelayer.security.permissions

Interface PermissionManagementService

  • All Known Implementing Classes:
    DefaultPermissionManagementService
    public interface PermissionManagementService
    Service for managing permissions and permission assignments.

    This service does not provide permissions checking operations; use PermissionCheckingService for that. However, permission management operations provided here can be used to build custom permission-checking logic if the PermissionCheckingService does not provide required functionality.

    Permission is a single object representing an abstract "user right", uniquely identified by name. Permission assignment is a relationship between permission, principal and some object that exists within the platform.

    Conceptually permission assignment is defined by a tuple: PA=(Object, Principal, Name, Value), where:

    • Object is one of: item instance, item type, attribute descriptor or special implicit "global" object used to specify "global permission assignments".
    • Principal is an user or user group for which the permission is granted or denied.
    • Name is the name of a permission. Permission is uniquely identified by its name.
    • Value one of: DENIED or GRANTED.
    Note that this service do not use such a tuple to manage permission assignments, this is only a conceptual model.

    There is a restriction over possible tuple values: It is not possible to define two permission assignments that refer to the same Object, Principal and Name, but have different Value e.g. PA1(O1,P1,N1,GRANTED) and PA2(O1,P1,N1,DENIED). When using this service to define such assignments, only one of them will be actually stored in the system (previously defined assignment will be overwritten).

    This service allows to manage permission assignments defined by possible values of the tuple PA (as defined above), that is:

    • grant/deny a permission to an item instance for a principal
    • grant/deny a permission to a type for a principal
    • grant/deny a permission to an attribute descriptor for a principal
    • grant/deny a permission globally for a principal
    where a principal is a user or a user group.

    Permission assignments to objects such as items, types and attributes allow to express arbitrary constraints on user access to these objects. One can for example define permissions that allow/forbid certain users to read items of specific type, or to restrict reading to only some attributes of the type, and so on.

    Global permission assignments are special in that they do not refer to any specific platform object, they just define a relation between a permission and a principal. This can be useful to express constraints that are not related with any item/type/attribute. For example one might introduce "platform_initialization" permission, that enables a user to perform platform initialisation. Such a permission is not related to any specific item or type, so it's best modelled as global permission assignment. Global permission assignment can also be used to provide fall-back permission values when implementing complex permission checking scheme (e.g. "when no assignment has been found on an object, check global assignments").

    Permissions and permission assignments defined and managed by this service are not automatically enforced in other core platform services, unless explicitly indicated in the service API. This generally means that the permissions will be "effective" only if some piece of client code performs explicit permission checking.

    • Note 1) This service only allows to do permission assignments management. This is quite different from permission assignment checking (verifying), because for checking some additional rules could be used. For example one may define a rule that grants a permission for a principal when the permission is granted for one of the groups the principal is a member of. When such a rule is used, there might be no explicit permission assignment to the principal, but the permission is granted anyway. Other rules might involve checking item types hierarchy, and so on. For these reasons, this service should not be directly used for checking permissions - use PermissionCheckingService instead.
    • Note 2) This service also does not define any "meaning" for permissions. Permissions as defined here are totally abstract and it's up to the users of permission-related services (client code) to define the behaviour of a system when a permission to an object is granted/denied for a principal.

    • Method Detail

      • createPermission

        void createPermission​(java.lang.String permissionName)
        Creates a new permission with a given name.
        Parameters:
        permissionName - name for permission.
        Throws:
        ModelSavingException - when a permission with given name already exists.

      • getDefinedPermissions

        java.util.Collection<java.lang.String> getDefinedPermissions()
        Returns a collection of names of all defined permissions.

      • getItemPermissions

        java.util.Collection<PermissionAssignment> getItemPermissions​(ItemModel item)
        Returns a collection representing all permission assigned to given item.

      • getItemPermissionsForPrincipal

        java.util.Collection<PermissionAssignment> getItemPermissionsForPrincipal​(ItemModel item,
                                                                          PrincipalModel... principal)
        Returns a collection representing permissions assigned to given item for specified principal(s).

      • getItemPermissionsForName

        java.util.Collection<PermissionAssignment> getItemPermissionsForName​(ItemModel item,
                                                                     java.lang.String... permissionName)
        Returns a collection representing permissions with specified name(s) assigned to given item.

      • addItemPermission

        void addItemPermission​(ItemModel item,
                       PermissionAssignment... permissionAssignment)
        Adds a permission assignment(s) to an item.

        Corner case: This method will overwrite existing permission assignment if it involves the same item, principal and permission, but with opposite value of "isGranted" flag. In other words a permission to an item cannot be assigned twice: as "granted" and as "denied" for the same principal.

      • setItemPermissions

        void setItemPermissions​(ItemModel item,
                        java.util.Collection<PermissionAssignment> permissionAssignments)
        Replaces permission assignments to an item with the ones in given collection.

      • removeItemPermission

        void removeItemPermission​(ItemModel item,
                          PermissionAssignment... permissionAssignment)
        Removes permission assignments from an item. The value of "isGranted" flag in the permissionAssignment argument(s) is ignored. This means that an existing "denying" permission assignment will be removed even if given permissionAssignment argument "granted" flag is true.

      • removeItemPermissionsForPrincipal

        void removeItemPermissionsForPrincipal​(ItemModel item,
                                       PrincipalModel... principal)
        Removes all permission assignments from an item that refer to given principal(s).

      • removeItemPermissionsForName

        void removeItemPermissionsForName​(ItemModel item,
                                  java.lang.String... permissionName)
        Removes all permission assignments from an item that refer to given permission name(s).

      • clearItemPermissions

        void clearItemPermissions​(ItemModel item)
        Remove all permission assignments from a given item.

      • getTypePermissionsForPrincipal

        java.util.Collection<PermissionAssignment> getTypePermissionsForPrincipal​(ComposedTypeModel type,
                                                                          PrincipalModel... principal)
        Returns a collection representing permissions assigned to given type for specified principal(s).

      • getTypePermissionsForName

        java.util.Collection<PermissionAssignment> getTypePermissionsForName​(ComposedTypeModel type,
                                                                     java.lang.String... permissionName)
        Returns a collection representing permissions with specified name(s) assigned to given type.

      • addTypePermission

        void addTypePermission​(ComposedTypeModel type,
                       PermissionAssignment... permissionAssignment)
        Adds a permission assignment(s) to a type.

        Corner case: This method will overwrite existing permission assignment if it involves the same type, principal and permission, but with opposite value of "isGranted" flag. In other words a permission to a type cannot be assigned twice: as "granted" and as "denied" for the same principal.

      • setTypePermissions

        void setTypePermissions​(ComposedTypeModel type,
                        java.util.Collection<PermissionAssignment> permissionAssignments)
        Replaces existing permission assignments to a type with the ones in given collection.

      • removeTypePermission

        void removeTypePermission​(ComposedTypeModel type,
                          PermissionAssignment... permissionAssignment)
        Removes permission assignments from a type. The value of "isGranted" flag in the permissionAssignment argument(s) is ignored. This means that an existing "denying" permission assignment will be removed even if permissionAssignment argument "granted" flag is true..

      • removeTypePermissionsForPrincipal

        void removeTypePermissionsForPrincipal​(ComposedTypeModel type,
                                       PrincipalModel... principal)
        Removes all permission assignments from a type that refer to given principal(s).

      • removeTypePermissionsForName

        void removeTypePermissionsForName​(ComposedTypeModel type,
                                  java.lang.String... permissionName)
        Removes all permission assignments from a type that refer to given permission name(s).

      • clearTypePermissions

        void clearTypePermissions​(ComposedTypeModel type)
        Remove all permission assignments from a given type.

      • getAttributePermissionsForName

        java.util.Collection<PermissionAssignment> getAttributePermissionsForName​(AttributeDescriptorModel attribute,
                                                                          java.lang.String... permissionName)
        Returns a collection representing permissions with specified name(s) assigned to given attribute.

      • addAttributePermission

        void addAttributePermission​(AttributeDescriptorModel attribute,
                            PermissionAssignment... permissionAssignment)
        Adds a permission assignment(s) to an attribute descriptor.

        Corner case: This method will overwrite existing permission assignment if it involves the same attribute, principal and permission, but with opposite value of "isGranted" flag. In other words a permission to an attribute cannot be assigned twice: as "granted" and as "denied" for the same principal.

      • setAttributePermissions

        void setAttributePermissions​(AttributeDescriptorModel attribute,
                             java.util.Collection<PermissionAssignment> permissionAssignments)
        Replaces permission assignments to an attribute descriptor with the ones in given collection.

      • removeAttributePermission

        void removeAttributePermission​(AttributeDescriptorModel attribute,
                               PermissionAssignment... permissionAssignment)
        Removes permission assignments from an attribute descriptor. The value of "isGranted" flag in the permissionAssignment argument(s) is ignored. This means that an existing "denying" permission assignment will be removed even if given permissionAssignment argument "granted" flag is true.

      • removeAttributePermissionsForPrincipal

        void removeAttributePermissionsForPrincipal​(AttributeDescriptorModel attribute,
                                            PrincipalModel... principal)
        Removes all permission assignments from an attribute descriptor that refer to given principal(s).

      • removeAttributePermissionsForName

        void removeAttributePermissionsForName​(AttributeDescriptorModel attribute,
                                       java.lang.String... permissionName)
        Removes all permission assignments from an attribute descriptor that refer to given permission name(s).

      • clearAttributePermissions

        void clearAttributePermissions​(AttributeDescriptorModel attribute)
        Remove all permission assignments from a given attribute descriptor.

      • getGlobalPermissionsForPrincipal

        java.util.Collection<PermissionAssignment> getGlobalPermissionsForPrincipal​(PrincipalModel... principal)
        Returns a collection representing all global permission assignments for specified principal(s).

      • getGlobalPermissionsForName

        @Deprecated
java.util.Collection<PermissionAssignment> getGlobalPermissionsForName​(java.lang.String... permissionName)
        Deprecated.
        since 6.0.0 - this method is for remove in future version
        Returns a collection representing all global permission assignments with specified permission name(s).

      • addGlobalPermission

        void addGlobalPermission​(PermissionAssignment... permissionAssignment)
        Adds new global permission assignments.

        Corner case: This method will overwrite existing permission assignment if it involves the same principal and permission, but with opposite value of "isGranted" flag. In other words a permission cannot be globally assigned twice: as "granted" and as "denied" for the same principal.

      • removeGlobalPermission

        void removeGlobalPermission​(PermissionAssignment... permissionAssignment)
        Removes global permission assignment(s). The value of "isGranted" flag in the permissionAssignment argument(s) is ignored. This means that an existing global "denying" permission assignment will be removed even if given permissionAssignment argument "granted" flag is true.

      • removeGlobalPermissionsForPrincipal

        void removeGlobalPermissionsForPrincipal​(PrincipalModel... principal)
        Removes all global permission assignments that refer to given principal(s).

      • removeGlobalPermissionsForName

        void removeGlobalPermissionsForName​(java.lang.String... permissionName)
        Removes all global permission assignments that refer to given permission name(s).