org.apache.cassandra.auth

## Interface IRoleManager

All Known Implementing Classes:
  CassandraRoleManager

    public interface IRoleManager

Responsible for managing roles (which also includes what used to be known as users), including creation, deletion, alteration and the granting and revoking of roles to other roles.

### Nested Class Summary

Nested Classes
`static class` `IRoleManager.Option` Supported options for CREATE ROLE/ALTER ROLE (and CREATE USER/ALTER USER, which are aliases provided for backwards compatibility).

### Method Summary

All Methods Instance Methods Abstract Methods
`java.util.Set<IRoleManager.Option>` `alterableOptions()` Subset of supportedOptions that users are allowed to alter when performing ALTER ROLE [themselves].
`void` `alterRole(AuthenticatedUser performer, RoleResource role, RoleOptions options)` Called during execution of ALTER ROLE statement.
`boolean` `canLogin(RoleResource role)` Return true if there exists a Role with the given name which has login privileges.
`void` `createRole(AuthenticatedUser performer, RoleResource role, RoleOptions options)` Called during execution of a CREATE ROLE statement.
`void` `dropRole(AuthenticatedUser performer, RoleResource role)` Called during execution of DROP ROLE statement, as well we removing any main record of the role from the system this implies that we want to revoke this role from all other roles that it has been granted to.
`java.util.Set<RoleResource>` `getAllRoles()` Called during the execution of an unqualified LIST ROLES query.
`java.util.Map<java.lang.String,java.lang.String>` `getCustomOptions(RoleResource role)` Where an implementation supports OPTIONS in CREATE and ALTER operations this method should return the `Map<String, String>` representing the custom options associated with the role, as supplied to CREATE or ALTER.
`java.util.Set<RoleResource>` `getRoles(RoleResource grantee, boolean includeInherited)` Called during execution of a LIST ROLES query.
`void` `grantRole(AuthenticatedUser performer, RoleResource role, RoleResource grantee)` Called during execution of GRANT ROLE query.
`boolean` `isExistingRole(RoleResource role)` Return true is a Role with the given name exists in the system.
`boolean` `isSuper(RoleResource role)` Return true if there exists a Role with the given name that also has superuser status.
`java.util.Set<? extends IResource>` `protectedResources()` Set of resources that should be made inaccessible to users and only accessible internally.
`void` `revokeRole(AuthenticatedUser performer, RoleResource role, RoleResource revokee)` Called during the execution of a REVOKE ROLE query.
`void` `setup()` Hook to perform implementation specific initialization, called once upon system startup.
`java.util.Set<IRoleManager.Option>` `supportedOptions()` Set of options supported by CREATE ROLE and ALTER ROLE queries.
`void` `validateConfiguration()` Hook to perform validation of an implementation's configuration (if supported).

### Method Detail

#### supportedOptions

    java.util.Set<IRoleManager.Option> supportedOptions()

Set of options supported by CREATE ROLE and ALTER ROLE queries. Should never return null - always return an empty set instead.

#### alterableOptions

    java.util.Set<IRoleManager.Option> alterableOptions()

Subset of supportedOptions that users are allowed to alter when performing ALTER ROLE [themselves]. Should never return null - always return an empty set instead.

#### createRole

    void createRole(AuthenticatedUser performer,
                    RoleResource role,
                    RoleOptions options)
             throws RequestValidationException,
                    RequestExecutionException

Called during execution of a CREATE ROLE statement. options are guaranteed to be a subset of supportedOptions().

Parameters:
  `performer` - User issuing the create role statement.
  `role` - Rolei being created
  `options` - Options the role will be created with
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### dropRole

    void dropRole(AuthenticatedUser performer,
                  RoleResource role)
           throws RequestValidationException,
                  RequestExecutionException

Called during execution of DROP ROLE statement, as well we removing any main record of the role from the system this implies that we want to revoke this role from all other roles that it has been granted to.

Parameters:
  `performer` - User issuing the drop role statement.
  `role` - Role to be dropped.
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### alterRole

    void alterRole(AuthenticatedUser performer,
                   RoleResource role,
                   RoleOptions options)
            throws RequestValidationException,
                   RequestExecutionException

Called during execution of ALTER ROLE statement. options are always guaranteed to be a subset of supportedOptions(). Furthermore, if the actor performing the query is not a superuser and is altering themself, then options are guaranteed to be a subset of alterableOptions(). Keep the body of the method blank if your implementation doesn't support modification of any options.

Parameters:
  `performer` - User issuing the alter role statement.
  `role` - Role that will be altered.
  `options` - Options to alter.
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### grantRole

    void grantRole(AuthenticatedUser performer,
                   RoleResource role,
                   RoleResource grantee)
            throws RequestValidationException,
                   RequestExecutionException

Called during execution of GRANT ROLE query. Grant an role to another existing role. A grantee that has a role granted to it will inherit any permissions of the granted role.

Parameters:
  `performer` - User issuing the grant statement.
  `role` - Role to be granted to the grantee.
  `grantee` - Role acting as the grantee.
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### revokeRole

    void revokeRole(AuthenticatedUser performer,
                    RoleResource role,
                    RoleResource revokee)
             throws RequestValidationException,
                    RequestExecutionException

Called during the execution of a REVOKE ROLE query. Revoke an granted role from an existing role. The revokee will lose any permissions inherited from the role being revoked.

Parameters:
  `performer` - User issuing the revoke statement.
  `role` - Role to be revoked.
  `revokee` - Role from which the granted role is to be revoked.
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### getRoles

    java.util.Set<RoleResource> getRoles(RoleResource grantee,
                                         boolean includeInherited)
                                  throws RequestValidationException,
                                         RequestExecutionException

Called during execution of a LIST ROLES query. Returns a set of roles that have been granted to the grantee using GRANT ROLE.

Parameters:
  `grantee` - Role whose granted roles will be listed.
  `includeInherited` - if True will list inherited roles as well as those directly granted to the grantee.
Returns:
  A list containing the granted roles for the user.
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### getAllRoles

    java.util.Set<RoleResource> getAllRoles()
                                     throws RequestValidationException,
                                            RequestExecutionException

Called during the execution of an unqualified LIST ROLES query. Returns the total set of distinct roles in the system.

Returns:
  the set of all roles in the system.
Throws:
  `RequestValidationException`
  `RequestExecutionException`

#### isSuper

    boolean isSuper(RoleResource role)

Return true if there exists a Role with the given name that also has superuser status. Superuser status may be inherited from another granted role, so this method should return true if either the named Role, or any other Role it is transitively granted has superuser status.

Parameters:
  `role` - Role whose superuser status to verify
Returns:
  true if the role exists and has superuser status, either directly or transitively, otherwise false.

#### canLogin

    boolean canLogin(RoleResource role)

Return true if there exists a Role with the given name which has login privileges. Such privileges is not inherited from other granted Roles and so must be directly granted to the named Role with the LOGIN option of CREATE ROLE or ALTER ROLE

Parameters:
  `role` - Role whose login privileges to verify
Returns:
  true if the role exists and is permitted to login, otherwise false

#### getCustomOptions

    java.util.Map<java.lang.String,java.lang.String> getCustomOptions(RoleResource role)

Where an implementation supports OPTIONS in CREATE and ALTER operations this method should return the `Map<String, String>` representing the custom options associated with the role, as supplied to CREATE or ALTER. It should never return null; if the implementation does not support OPTIONS or if none were supplied then it should return an empty map.

Parameters:
  `role` - Role whose custom options are required
Returns:
  Key/Value pairs representing the custom options for the Role

#### isExistingRole

    boolean isExistingRole(RoleResource role)

Return true is a Role with the given name exists in the system.

Parameters:
  `role` - Role whose existence to verify
Returns:
  true if the name identifies an extant Role in the system, otherwise false

#### protectedResources

    java.util.Set<? extends IResource> protectedResources()

Set of resources that should be made inaccessible to users and only accessible internally.

Returns:
  Keyspaces and column families that will be unmodifiable by users; other resources.

#### validateConfiguration

    void validateConfiguration()
                        throws ConfigurationException

Hook to perform validation of an implementation's configuration (if supported).

Throws:
  `ConfigurationException`

#### setup

    void setup()

Hook to perform implementation specific initialization, called once upon system startup. For example, use this method to create any required keyspaces/column families.