public interface Authorizer extends Configurable {

    /**
     * @param session   the session being authorized
     * @param operation type of operation client is trying to perform on resource
     * @param resource  resource the client is trying to access
     * @return true if the session is authorized to perform the operation on the resource, else false
     *
     * @throws org.apache.kafka.common.errors.InvalidResourceException if resource does not exist
     * @throws org.apache.kafka.common.errors.InvalidOperationException if requested operation is not
     *          supported on the resource
     */
    public boolean authorize(Session session, Operation operation, Resource resource);

    /**
     * Implementation specific description, like, supported principal types.
     *
     * @return implementation specific description
     */
    public String description();

    /**
     * Add the acls to resource, this is an additive operation so existing acls will not be overwritten, instead these new
     * acls will be added to existing acls.
     *
     * @param acls     set of acls to add to existing acls
     * @param resource the resource to which these acls should be attached
     *
     * @throws org.apache.kafka.common.errors.AuthorizationException if not authorized to add acls for the resource
     * @throws org.apache.kafka.common.errors.InvalidResourceException if resource does not exist
     * @throws org.apache.kafka.common.errors.InvalidAclException if an invalid acl is being added
     */
    public void addAcls(Set<Acl> acls, Resource resource);

    /**
     * Remove these acls from the resource.
     *
     * @param acls     set of acls to be removed
     * @param resource resource from which the acls should be removed
     * @return true if some acl got removed, false if no acl was removed
     *
     * @throws org.apache.kafka.common.errors.AuthorizationException if not authorized to remove acls for the resource
     * @throws org.apache.kafka.common.errors.InvalidResourceException if resource does not exist
     * @throws org.apache.kafka.common.errors.InvalidAclException if an invalid acl is being removed
     */
    public boolean removeAcls(Set<Acl> acls, Resource resource);

    /**
     * Remove a resource along with all of its acls from acl store.
     *
     * @param resource  resource that is to be removed
     * @return true if resource existed and got deleted, else false
     *
     * @throws org.apache.kafka.common.errors.AuthorizationException if not authorized to remove acls for the resource
     * @throws org.apache.kafka.common.errors.InvalidResourceException if resource does not exist
     */
    public boolean removeAcls(Resource resource);

    /**
     * Get set of acls for this resource.
     *
     * @param resource resource whose acls are to be returned
     * @return empty set if no acls are found, otherwise the acls for the resource
     *
     * @throws org.apache.kafka.common.errors.AuthorizationException if not authorized to access acls for the resource
     * @throws org.apache.kafka.common.errors.InvalidResourceException if resource does not exist
     */
    public Set<Acl> acls(Resource resource);

    /**
     * Get acls for this principal.
     *
     * @param principal principal whole acls are to be returned
     * @return empty Map if no acls exist for this principal, otherwise a map of resource -> acls for the principal
     *
     * @throws org.apache.kafka.common.errors.AuthorizationException if not authorized to access acls for the principal
     * @throws org.apache.kafka.common.errors.InvalidPrincipalException if principal is invalid
     */
    public Map<Resource, Set<Acl>> acls(KafkaPrincipal principal);

    /**
     * Gets map of resource to acls for all resources.
     */
    public Map<Resource, Set<Acl>> acls();

    /**
     * Closes this instance.
     */
    public void close();

}