Package org.opencms.security

Class CmsRole

  • public final class CmsRole
extends java.lang.Object
    A role is used in the OpenCms security system to check if a user has access to a certain system function.

    Roles are used to ensure access permissions to system function that are not file based. For example, roles are used to check permissions to functions like "the user can schedule a job in the CmsScheduleManager" or "the user can export (or import) the OpenCms database".

    All roles are based on CmsGroup. This means to have access to a role, the user has to be a member in a certain predefined system group. Each role has exactly one group that contains all "direct" members of this role.

    All roles have (optional) parent roles. If a user not a member of the role group of a role, but he is a member of at last one of the parent role groups, he/she also has full access to this role. This is called "indirect" membership to the role.

    Please note that "indirect" membership does grant the user the same full access to a role that "direct" membership does. For example, the ROOT_ADMIN role is a parent group of all other roles. So all users that are members of ROOT_ADMIN have access to the functions of all other roles.

    Please do not perform automated sorting of members on this compilation unit. That leads to NPE's

    Since:
    6.0.0

    • Constructor Detail

      • CmsRole

        public CmsRole​(java.lang.String roleName,
               CmsRole parentRole,
               java.lang.String groupName,
               boolean ouDependent)
        Creates a user defined role.

        Parameters:
        roleName - the name of this role
        groupName - the name of the group the members of this role are stored in
        parentRole - the parent role of this role
        ouDependent - if the role is organizational unit dependent

    • Method Detail

      • applySystemRoleOrder

        public static void applySystemRoleOrder​(java.util.List<CmsRole> roles)
        Applies the system role order to a list of roles.

        Parameters:
        roles - the roles

      • getSystemRoles

        public static java.util.List<CmsRole> getSystemRoles()
        Returns the list of system defined roles (instances of CmsRole).

        Returns:
        the list of system defined roles

      • hasPrefix

        public static boolean hasPrefix​(java.lang.String principalName)
        Checks if the given String starts with PRINCIPAL_ROLE followed by a dot.

        • Works if the given String is null.
        • Removes white spaces around the String before the check.
        • Also works with prefixes not being in upper case.
        • Does not check if the role after the prefix actually exists.
        Parameters:
        principalName - the potential role name to check
        Returns:
        true in case the String starts with PRINCIPAL_ROLE

      • removePrefix

        public static java.lang.String removePrefix​(java.lang.String principalName)
        Removes the prefix if the given String starts with PRINCIPAL_ROLE followed by a dot.

        • Works if the given String is null.
        • If the given String does not start with PRINCIPAL_ROLE followed by a dot it is returned unchanged.
        • Removes white spaces around the role name.
        • Also works with prefixes not being in upper case.
        • Does not check if the role after the prefix actually exists.
        Parameters:
        principalName - the role name to remove the prefix from
        Returns:
        the given String with the prefix PRINCIPAL_ROLE and the following dot removed

      • valueOf

        public static CmsRole valueOf​(CmsGroup group)
        Returns the role for the given group.

        Parameters:
        group - a group to check for role representation
        Returns:
        the role for the given group

      • valueOfGroupName

        public static CmsRole valueOfGroupName​(java.lang.String groupName)
        Returns the role for the given group name.

        Parameters:
        groupName - a group name to check for role representation
        Returns:
        the role for the given group name

      • valueOfId

        public static CmsRole valueOfId​(CmsUUID roleId)
        Returns the role for the given id.

        Parameters:
        roleId - the id to check for role representation
        Returns:
        the role for the given role id

      • valueOfRoleName

        public static CmsRole valueOfRoleName​(java.lang.String roleName)
        Returns the role for the given role name.

        Parameters:
        roleName - a role name to check for role representation
        Returns:
        the role for the given role name

      • createRoleViolationException

        public CmsRoleViolationException createRoleViolationException​(CmsRequestContext requestContext)
        Returns a role violation exception configured with a localized, role specific message for this role.

        Parameters:
        requestContext - the current users OpenCms request context
        Returns:
        a role violation exception configured with a localized, role specific message for this role

      • createRoleViolationExceptionForOrgUnit

        public CmsRoleViolationException createRoleViolationExceptionForOrgUnit​(CmsRequestContext requestContext,
                                                                        java.lang.String orgUnitFqn)
        Returns a role violation exception configured with a localized, role specific message for this role.

        Parameters:
        requestContext - the current users OpenCms request context
        orgUnitFqn - the organizational unit used for the role check, it may be null
        Returns:
        a role violation exception configured with a localized, role specific message for this role

      • createRoleViolationExceptionForResource

        public CmsRoleViolationException createRoleViolationExceptionForResource​(CmsRequestContext requestContext,
                                                                         CmsResource resource)
        Returns a role violation exception configured with a localized, role specific message for this role.

        Parameters:
        requestContext - the current users OpenCms request context
        resource - the resource used for the role check, it may be null
        Returns:
        a role violation exception configured with a localized, role specific message for this role

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
        See Also:
        Object.equals(java.lang.Object)

      • forOrgUnit

        public CmsRole forOrgUnit​(java.lang.String ouFqn)
        Creates a new role based on this one for the given organizational unit.

        Parameters:
        ouFqn - fully qualified name of the organizational unit
        Returns:
        a new role based on this one for the given organizational unit

      • getChildren

        public java.util.List<CmsRole> getChildren​(boolean recursive)
        Returns a list of all sub roles.

        Parameters:
        recursive - if not set just direct children are returned
        Returns:
        all sub roles as a list of CmsRole objects

      • getDescription

        public java.lang.String getDescription​(java.util.Locale locale)
        Returns a localized role description.

        Parameters:
        locale - the locale
        Returns:
        the localized role description

      • getDisplayName

        public java.lang.String getDisplayName​(CmsObject cms,
                                       java.util.Locale locale)
                                throws CmsException
        Returns the display name of this role including the organizational unit.

        Parameters:
        cms - the cms context
        locale - the locale
        Returns:
        the display name of this role including the organizational unit
        Throws:
        CmsException - if the organizational unit could not be read

      • getDistinctGroupNames

        public java.util.List<java.lang.String> getDistinctGroupNames()
        Returns the distinct group names of this role.

        This group names are not fully qualified (organizational unit dependent).

        Returns:
        the distinct group names of this role

      • getFqn

        public java.lang.String getFqn()
        Returns the fully qualified name of this role.

        Returns:
        the fqn of this role

      • getGroupName

        public java.lang.String getGroupName()
        Returns the name of the group this role is mapped to in the OpenCms database.

        Here the fully qualified group name is returned.

        Returns:
        the name of the group this role is mapped to in the OpenCms database

      • getId

        public CmsUUID getId()
        Returns the id of this role.

        Does not differentiate for organizational units.

        Returns:
        the id of this role

      • getName

        public java.lang.String getName​(java.util.Locale locale)
        Returns a localized role name.

        Parameters:
        locale - the locale
        Returns:
        the localized role name

      • getOuFqn

        public java.lang.String getOuFqn()
        Returns the fully qualified name of the organizational unit.

        Returns:
        the fully qualified name of the organizational unit

      • getParentRole

        public CmsRole getParentRole()
        Returns the parent role of this role.

        Returns:
        the parent role of this role

      • getRoleName

        public java.lang.String getRoleName()
        Returns the name of the role.

        Returns:
        the name of the role

      • getVirtualGroupFlags

        public int getVirtualGroupFlags()
        Returns the flags needed for a group to emulate this role.

        Returns:
        the flags needed for a group to emulate this role

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Object.hashCode()

      • isOrganizationalUnitIndependent

        public boolean isOrganizationalUnitIndependent()
        Checks if this role is organizational unit independent.

        Returns:
        true if this role is organizational unit independent

      • isSystemRole

        public boolean isSystemRole()
        Check if this role is a system role.

        Returns:
        true if this role is a system role

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        See Also:
        Object.toString()