/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.cassandra.auth;

import java.util.Map;
import java.util.Set;

import org.apache.cassandra.exceptions.ConfigurationException;
import org.apache.cassandra.exceptions.RequestExecutionException;
import org.apache.cassandra.exceptions.RequestValidationException;

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.
/**
 * 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.
 */
public interface IRoleManager
{

    
Supported options for CREATE ROLE/ALTER ROLE (and
CREATE USER/ALTER USER, which are aliases provided
for backwards compatibility).
/**
     * Supported options for CREATE ROLE/ALTER ROLE (and
     * CREATE USER/ALTER USER, which are aliases provided
     * for backwards compatibility).
     */
    public enum Option
    {
        SUPERUSER, PASSWORD, LOGIN, OPTIONS
    }

    
Set of options supported by CREATE ROLE and ALTER ROLE queries.
Should never return null - always return an empty set instead.
/**
     * Set of options supported by CREATE ROLE and ALTER ROLE queries.
     * Should never return null - always return an empty set instead.
     */
    Set<Option> supportedOptions();

    
Subset of supportedOptions that users are allowed to alter when performing ALTER ROLE [themselves].
Should never return null - always return an empty set instead.
/**
     * Subset of supportedOptions that users are allowed to alter when performing ALTER ROLE [themselves].
     * Should never return null - always return an empty set instead.
     */
    Set<Option> alterableOptions();

    
Called during execution of a CREATE ROLE statement.
options are guaranteed to be a subset of supportedOptions().
Params:
performer – User issuing the create role statement.
role – Rolei being created
options – Options the role will be created with
Throws:
RequestValidationException – 
RequestExecutionException – /**
     * Called during execution of a CREATE ROLE statement.
     * options are guaranteed to be a subset of supportedOptions().
     *
     * @param performer User issuing the create role statement.
     * @param role Rolei being created
     * @param options Options the role will be created with
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void createRole(AuthenticatedUser performer, RoleResource role, RoleOptions options)
    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.
Params:
performer – User issuing the drop role statement.
role – Role to be dropped.
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.
     *
     * @param performer User issuing the drop role statement.
     * @param role Role to be dropped.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void dropRole(AuthenticatedUser performer, RoleResource role) 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.
Params:
performer – User issuing the alter role statement.
role – Role that will be altered.
options – Options to alter.
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.
     *
     * @param performer User issuing the alter role statement.
     * @param role Role that will be altered.
     * @param options Options to alter.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void alterRole(AuthenticatedUser performer, RoleResource role, RoleOptions options)
    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.
Params:
performer – User issuing the grant statement.
role – Role to be granted to the grantee.
grantee – Role acting as the 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.
     *
     * @param performer User issuing the grant statement.
     * @param role Role to be granted to the grantee.
     * @param grantee Role acting as the grantee.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void grantRole(AuthenticatedUser performer, RoleResource role, RoleResource grantee)
    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.
Params:
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 – /**
     * 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.
     *
     * @param performer User issuing the revoke statement.
     * @param role Role to be revoked.
     * @param revokee Role from which the granted role is to be revoked.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void revokeRole(AuthenticatedUser performer, RoleResource role, RoleResource revokee)
    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.
Params:
grantee – Role whose granted roles will be listed.
includeInherited – if True will list inherited roles as well as those directly granted to the grantee.
Throws:
RequestValidationException – 
RequestExecutionException – 
Returns:
A list containing the granted roles for the user./**
     * Called during execution of a LIST ROLES query.
     * Returns a set of roles that have been granted to the grantee using GRANT ROLE.
     *
     * @param grantee Role whose granted roles will be listed.
     * @param includeInherited if True will list inherited roles as well as those directly granted to the grantee.
     * @return A list containing the granted roles for the user.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    Set<RoleResource> getRoles(RoleResource grantee, boolean includeInherited) throws RequestValidationException, RequestExecutionException;

    
Called during the execution of an unqualified LIST ROLES query.
Returns the total set of distinct roles in the system.
Throws:
RequestValidationException – 
RequestExecutionException – 
Returns:
the set of all roles in the system./**
     * Called during the execution of an unqualified LIST ROLES query.
     * Returns the total set of distinct roles in the system.
     *
     * @return the set of all roles in the system.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    Set<RoleResource> getAllRoles() throws RequestValidationException, RequestExecutionException;

    
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.
Params:
role – Role whose superuser status to verify
Returns:
true if the role exists and has superuser status, either
directly or transitively, otherwise false./**
     * 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.
     *
     * @param role Role whose superuser status to verify
     * @return true if the role exists and has superuser status, either
     * directly or transitively, otherwise false.
     */
    boolean isSuper(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
Params:
role – Role whose login privileges to verify
Returns:
true if the role exists and is permitted to login, otherwise false/**
     * 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
     *
     * @param role Role whose login privileges to verify
     * @return true if the role exists and is permitted to login, otherwise false
     */
    boolean canLogin(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. 
Params:
role – Role whose custom options are required
Returns:
Key/Value pairs representing the custom options for the Role/**
     * Where an implementation supports OPTIONS in CREATE and ALTER operations
     * this method should return the {@code 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.
     * @param role Role whose custom options are required
     * @return Key/Value pairs representing the custom options for the Role
     */
    Map<String, String> getCustomOptions(RoleResource role);

    
Return true is a Role with the given name exists in the system.
Params:
role – Role whose existence to verify
Returns:
true if the name identifies an extant Role in the system,
otherwise false/**
     * Return true is a Role with the given name exists in the system.
     *
     * @param role Role whose existence to verify
     * @return true if the name identifies an extant Role in the system,
     * otherwise false
     */
    boolean isExistingRole(RoleResource role);

    
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./**
     * Set of resources that should be made inaccessible to users and only accessible internally.
     *
     * @return Keyspaces and column families that will be unmodifiable by users; other resources.
     */
    Set<? extends IResource> protectedResources();

    
Hook to perform validation of an implementation's configuration (if supported).
Throws:
ConfigurationException – /**
     * Hook to perform validation of an implementation's configuration (if supported).
     *
     * @throws ConfigurationException
     */
    void validateConfiguration() throws ConfigurationException;

    
Hook to perform implementation specific initialization, called once upon system startup.
For example, use this method to create any required keyspaces/column families.
/**
     * Hook to perform implementation specific initialization, called once upon system startup.
     *
     * For example, use this method to create any required keyspaces/column families.
     */
    void setup();
}