Package org.springframework.security.access.hierarchicalroles

# Class RoleHierarchyImpl

java.lang.Object
org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl

All Implemented Interfaces:
  `RoleHierarchy`

public class RoleHierarchyImpl extends Object implements RoleHierarchy

This class defines a role hierarchy for use with various access checking components.

Here is an example configuration of a role hierarchy (hint: read the ">" sign as "includes"):

         <property name="hierarchy">
             <value>
                 ROLE_A > ROLE_B
                 ROLE_B > ROLE_AUTHENTICATED
                 ROLE_AUTHENTICATED > ROLE_UNAUTHENTICATED
             </value>
         </property>

Explanation of the above:

- In effect every user with ROLE_A also has ROLE_B, ROLE_AUTHENTICATED and ROLE_UNAUTHENTICATED;
- every user with ROLE_B also has ROLE_AUTHENTICATED and ROLE_UNAUTHENTICATED;
- every user with ROLE_AUTHENTICATED also has ROLE_UNAUTHENTICATED.

Hierarchical Roles will dramatically shorten your access rules (and also make the access rules much more elegant).

Consider this access rule for Spring Security's RoleVoter (background: every user that is authenticated should be able to log out):

    /logout.html=ROLE_A,ROLE_B,ROLE_AUTHENTICATED

With hierarchical roles this can now be shortened to:

    /logout.html=ROLE_AUTHENTICATED

In addition to shorter rules this will also make your access rules more readable and your intentions clearer.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`RoleHierarchyImpl.Builder`
Builder class for constructing a `RoleHierarchyImpl` based on a hierarchical role structure.

## Constructor Summary

Constructors
Constructor
Description
`RoleHierarchyImpl()`
Deprecated.
Use `fromHierarchy(java.lang.String)` instead

## Method Summary

Modifier and Type
Method
Description
`static RoleHierarchyImpl`
`fromHierarchy(String hierarchy)`
Create a role hierarchy instance with the given definition, similar to the following:
`Collection<GrantedAuthority>`
`getReachableGrantedAuthorities(Collection<? extends GrantedAuthority> authorities)`
Returns an array of all reachable authorities.
`void`
`setHierarchy(String roleHierarchyStringRepresentation)`
Deprecated.
Use `fromHierarchy(java.lang.String)` instead
`static RoleHierarchyImpl.Builder`
`withDefaultRolePrefix()`
Factory method that creates a `RoleHierarchyImpl.Builder` instance with the default role prefix "ROLE_"
`static RoleHierarchyImpl.Builder`
`withRolePrefix(String rolePrefix)`
Factory method that creates a `RoleHierarchyImpl.Builder` instance with the specified role prefix.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### RoleHierarchyImpl

@Deprecated public RoleHierarchyImpl()
Deprecated.
Use `fromHierarchy(java.lang.String)` instead

## Method Details

### fromHierarchy

public static RoleHierarchyImpl fromHierarchy(String hierarchy)
Create a role hierarchy instance with the given definition, similar to the following:

         ROLE_A > ROLE_B
         ROLE_B > ROLE_AUTHENTICATED
         ROLE_AUTHENTICATED > ROLE_UNAUTHENTICATED

Parameters:
  `hierarchy` - the role hierarchy to use
Returns:
  a `RoleHierarchyImpl` that uses the given `hierarchy`

### withDefaultRolePrefix

public static RoleHierarchyImpl.Builder withDefaultRolePrefix()
Factory method that creates a `RoleHierarchyImpl.Builder` instance with the default role prefix "ROLE_"

Returns:
  a `RoleHierarchyImpl.Builder` instance with the default role prefix "ROLE_"
Since:
  6.3

### withRolePrefix

public static RoleHierarchyImpl.Builder withRolePrefix(String rolePrefix)
Factory method that creates a `RoleHierarchyImpl.Builder` instance with the specified role prefix.

Parameters:
  `rolePrefix` - the prefix to be used for the roles in the hierarchy.
Returns:
  a new `RoleHierarchyImpl.Builder` instance with the specified role prefix
Throws:
  `IllegalArgumentException` - if the provided role prefix is null
Since:
  6.3

### setHierarchy

@Deprecated public void setHierarchy(String roleHierarchyStringRepresentation)
Deprecated.
Use `fromHierarchy(java.lang.String)` instead
Set the role hierarchy and pre-calculate for every role the set of all reachable roles, i.e. all roles lower in the hierarchy of every given role. Pre-calculation is done for performance reasons (reachable roles can then be calculated in O(1) time). During pre-calculation, cycles in role hierarchy are detected and will cause a `CycleInRoleHierarchyException` to be thrown.

Parameters:
  `roleHierarchyStringRepresentation` - - String definition of the role hierarchy.

### getReachableGrantedAuthorities

public Collection<GrantedAuthority> getReachableGrantedAuthorities(Collection<? extends GrantedAuthority> authorities)
Description copied from interface: `RoleHierarchy`
Returns an array of all reachable authorities.

Reachable authorities are the directly assigned authorities plus all authorities that are (transitively) reachable from them in the role hierarchy.

Example:
Role hierarchy: ROLE_A > ROLE_B > ROLE_C.
Directly assigned authority: ROLE_A.
Reachable authorities: ROLE_A, ROLE_B, ROLE_C.

Specified by:
  `getReachableGrantedAuthorities` in interface `RoleHierarchy`
Parameters:
  `authorities` - - List of the directly assigned authorities.
Returns:
  List of all reachable authorities given the assigned authorities.