com.xdev.security.authorization

Interface Role

All Known Subinterfaces:

Role.Mutable

All Known Implementing Classes:

Role.Implementation

public interface Role

The type representing a role for the purpose of authorization management. A role is defined as a collection of permissions and other roles whose permissions are applied recursively to it. Application-specific types that shall be handled by the authorization framework have to implement this interface.

Author:

XDEV Software (TM)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Role.Creator Interface equivalent of a constructor for the interface type Role .
static class	Role.Implementation A simple Role.Mutable default implementation.
static interface	Role.Mutable Extension of the type Role with mutability methods.

Method Summary

Modifier and Type	Method and Description
static Map<Resource,Permission>	collectEffectivePermissions(Collection<Role> roles) Utility method that collects the effective permissions from a collection of passed roles.
static <M extends Map<Resource,Permission>> M	collectEffectivePermissions(Collection<Role> roles, Set<Role> handledRoles, Set<Permission> handledPermissions, Set<Resource> handledResources, M collectedPermissions)
static void	collectEffectivePermissions(Iterable<Permission> permissions, Set<Permission> handledPermissions, Set<Resource> handledResources, Map<Resource,Permission> effectivePermissions)
static void	collectEffectivePermissions(Resource resource, Permission permission, Set<Resource> handledResources, Map<Resource,Permission> effectivePermissions)
static <R,C extends Set<? super Role>> C	collectEffectiveRoles(Collection<Role> roles, C effectiveRoles)
default Map<Resource,Permission>	effectivePermissions() Returns the effective permissions of this Role instance, meaning a collection containing all the permissions that this instance has been defined by and the effective permissions of all its roles.
default Set<Role>	effectiveRoles() Returns the effective roles of this Role instance, meaning a collection containing all the roles that this instance has been defined by and all their effective roles.
String	name()
static Role	New(String name) Returns a new Role instance with the passed name that is otherwise empty.
static Role	New(String name, Permission... permissions) Returns a new Role instance defined by the passed values with no explicit parent roles.
static Role	New(String name, Role... roles) Returns a new Role instance defined by the passed values with no explicit permissions.
static Role	New(String name, Set<? extends Role> roles, Set<? extends Permission> permissions) Returns a new Role instance defined by the passed values.
static Role	NewFromPermissions(String name, Set<? extends Permission> permissions) Returns a new Role instance defined by the passed values with no explicit parent roles.
static Role	NewFromRoles(String name, Set<? extends Role> roles) Returns a new Role instance defined by the passed values with no explicit permissions.
Collection<Permission>	permissions()
static Role	provide(Role role, String name, Set<String> parentRoles, Set<String> permissions) Validates and returns a passed non-null Role instance or creates a new one in case of a null refrence.
Collection<Role>	roles()
static void	update(Role role, String name, Set<Role> parentRoles, Set<Permission> permissions) Updates the passed Role instance for the given values.

Method Detail

name

String name()

Returns:

The role's unchangable name that identifies a particular instance.

roles

Collection<Role> roles()

Returns:

The roles this role instance has been defined by.

permissions

Collection<Permission> permissions()

Returns:

The permissions this role instance has been defined by.

effectiveRoles

default Set<Role> effectiveRoles()

Returns the effective roles of this Role instance, meaning a collection containing all the roles that this instance has been defined by and all their effective roles. Every Role instance is only returned once (identity uniqueness).

Returns:

the effective roles.

effectivePermissions

default Map<Resource,Permission> effectivePermissions()

Returns the effective permissions of this Role instance, meaning a collection containing all the permissions that this instance has been defined by and the effective permissions of all its roles. For every unique Resource instance the permission with the highest absolute value is returned.

Returns:

the effective permissions.

collectEffectivePermissions

static Map<Resource,Permission> collectEffectivePermissions(Collection<Role> roles)

Utility method that collects the effective permissions from a collection of passed roles.

Parameters:

roles - the Role instances whose effective permissions shall be determined.

Returns:

the passed roles' collected effective permissions.

See Also:

effectivePermissions()

collectEffectivePermissions

static <M extends Map<Resource,Permission>> M collectEffectivePermissions(Collection<Role> roles,
                                                                          Set<Role> handledRoles,
                                                                          Set<Permission> handledPermissions,
                                                                          Set<Resource> handledResources,
                                                                          M collectedPermissions)

collectEffectiveRoles

static <R,C extends Set<? super Role>> C collectEffectiveRoles(Collection<Role> roles,
                                                               C effectiveRoles)

collectEffectivePermissions

static void collectEffectivePermissions(Iterable<Permission> permissions,
                                        Set<Permission> handledPermissions,
                                        Set<Resource> handledResources,
                                        Map<Resource,Permission> effectivePermissions)

collectEffectivePermissions

static void collectEffectivePermissions(Resource resource,
                                        Permission permission,
                                        Set<Resource> handledResources,
                                        Map<Resource,Permission> effectivePermissions)

New

static Role New(String name,
                Set<? extends Role> roles,
                Set<? extends Permission> permissions)

Returns a new Role instance defined by the passed values.

Parameters:

name - the unchangeable identifying name of the role.

roles - the parent roles of the new role, potentially none.

permissions - the explicitely granted permissions for the new role, potentially none.

Returns:

a new Role instance.

NewFromRoles

static Role NewFromRoles(String name,
                         Set<? extends Role> roles)

Returns a new Role instance defined by the passed values with no explicit permissions.

Parameters:

name - the unchangeable identifying name of the role.

roles - the parent roles of the new role, potentially none.

Returns:

a new Role instance.

NewFromPermissions

static Role NewFromPermissions(String name,
                               Set<? extends Permission> permissions)

Returns a new Role instance defined by the passed values with no explicit parent roles.

Parameters:

name - the unchangeable identifying name of the role.

permissions - the explicitely granted permissions for the new role, potentially none.

Returns:

a new Role instance.

New

static Role New(String name)

Returns a new Role instance with the passed name that is otherwise empty.

Parameters:

name - the unchangeable identifying name of the role.

Returns:

a new Role instance.

New

static Role New(String name,
                Role... roles)

Returns a new Role instance defined by the passed values with no explicit permissions.

Parameters:

name - the unchangeable identifying name of the role.

roles - the parent roles of the new role, potentially none.

Returns:

a new Role instance.

New

static Role New(String name,
                Permission... permissions)

Returns a new Role instance defined by the passed values with no explicit parent roles.

Parameters:

name - the unchangeable identifying name of the role.

permissions - the explicitely granted permissions for the new role, potentially none.

Returns:

a new Role instance.

provide

static Role provide(Role role,
                    String name,
                    Set<String> parentRoles,
                    Set<String> permissions)

Validates and returns a passed non-null Role instance or creates a new one in case of a null refrence. In this simple defeault implementation, validating simply means to check if the passed role's name is equal to the passed name.

Parameters:

role - an already existing Role instance for that name or null.

name - the indentifying name of the role. May not be null.

parentRoles - the names of the parent roles as per definition.

permissions - the names of the explicit permissions as per definition.

Returns:

the non-null passed Role instance, otherwise a new one.

update

static void update(Role role,
                   String name,
                   Set<Role> parentRoles,
                   Set<Permission> permissions)

Updates the passed Role instance for the given values. If inconsistencies are detected or the instance is not Role.Mutable, an IllegalArgumentException is thrown.

Parameters:

role - the Role instance to be updated.

name - the identifiying name of the role.

parentRoles - the parent roles that the passed Role instance shall be updated with.

permissions - the explicit permissions that the passed Role instance shall be updated with.

Throws:

IllegalArgumentException - if name is null, names do not match or the role is not Role.Mutable.