/*-
 * ~~~~~~licensing~~~~~~
 * jaas-management
 * ==========
 * Copyright (C) 2020 - 2025 EmDev LLC
 * ==========
 * You may not use this file except in accordance with the License Terms of the Copyright
 * Holder located at: https://entaxy.ru/eula . All copyrights, all intellectual property
 * rights to the Software and any copies are the property of the Copyright Holder. Unless
 * it is explicitly allowed the Copyright Holder, the User is prohibited from using the
 * Software for commercial purposes to provide services to third parties.
 * 
 * The Copyright Holder hereby declares that the Software is provided on an "AS IS".
 * Under no circumstances does the Copyright Holder guarantee or promise that the
 * Software provided by him will be suitable or not suitable for the specific purposes
 * of the User, that the Software will meet all commercial and personal subjective
 * expectations of the User, that the Software will work properly, without technical
 * errors, quickly and uninterruptedly.
 * 
 * Under no circumstances shall the Copyright Holder or its Affiliates is not liable
 * to the User for any direct or indirect losses of the User, his expenses or actual
 * damage, including, downtime; loss of bussines; lost profit; lost earnings; loss
 * or damage to data, property, etc.
 * ~~~~~~/licensing~~~~~~
 */
package ru.entaxy.platform.core.management.jaas;

import org.apache.karaf.jaas.boot.principal.GroupPrincipal;
import org.apache.karaf.jaas.boot.principal.UserPrincipal;

import ru.entaxy.esb.platform.base.management.core.api.*;

@MBeanAnnotated(policy = MBeanExportPolicy.ANNOTATED_ONLY)
public interface JaasLoginModuleWithBackingEngineMBean extends JaasLoginModuleMBean {

    /**
     * Create a new user.
     *
     * @param username the user name.
     * @param password the user password.
     */
    @Operation(desc = "Create a new user")
    void addUser(
            @Parameter(name = "username", desc = "Username") String username,
            @Parameter(name = "password", desc = "Password") String password);

    /**
     * Delete user.
     *
     * @param username the user name.
     */
    @Operation(desc = "Delete user")
    void deleteUser(@Parameter(name = "username", desc = "Username") String username);

    /**
     * List all users.
     *
     * @return the list of users.
     */
    @Operation(desc = "List all users")
    String listUsers();

    /**
     * List groups that a user is member of.
     *
     * @param username the user name.
     * @return the list of groups.
     */
    @Operation(desc = "List groups that a user is member of")
    String listGroupsForUser(@Parameter(name = "username", desc = "Username") String username);

    /**
     * List all groups.
     *
     * @return the groups.
     */
    @Operation(desc = "List all groups")
    String listGroups();

    /**
     * Add a user into a given group.
     *
     * @param username the user name.
     * @param group the group.
     */
    @Operation(desc = "Add a user into a given group")
    void addGroup(
            @Parameter(name = "username", desc = "Username") String username,
            @Parameter(name = "group", desc = "Group") String group);

    /**
     * Create a group
     *
     * @param group the group.
     */
    @Operation(desc = "Create a group")
    void createGroup(@Parameter(name = "group", desc = "Group") String group);

    /**
     * Remove a group from a user.
     *
     * @param username the user name.
     * @param group the group.
     */
    @Operation(desc = "Remove a group from a user")
    void deleteGroup(
            @Parameter(name = "username", desc = "Username") String username,
            @Parameter(name = "group", desc = "Group") String group);

    /**
     * Get profile associated with {@link UserPrincipal}.
     *
     * @param username the user name.
     * @return the associated profile name.
     */
    @Operation(desc = "Get profile associated with user")
    String getAssociatedProfile(@Parameter(name = "username", desc = "Username") String username);

    /**
     * Associate profile with {@link UserPrincipal}.
     *
     * @param username the user name.
     * @param profileName the name of the profile.
     */
    @Operation(desc = "Associate profile with a user")
    void associateProfile(
            @Parameter(name = "username", desc = "Username") String username,
            @Parameter(name = "profileName", desc = "Profile Name") String profileName);

    /**
     * List roles for a {@link UserPrincipal}.
     *
     * @param username the user name.
     * @return the list of roles.
     */
    @Operation(desc = "List roles for a user")
    String listRolesForUser(@Parameter(name = "username", desc = "Username") String username);

    /**
     * List roles for a {@link GroupPrincipal}.
     *
     * @param groupName the name of the group.
     * @return the list of roles.
     */
    @Operation(desc = "List roles for a group")
    String listRolesForGroup(@Parameter(name = "groupName", desc = "Group Name") String groupName);

    /**
     * Add a role to the user.
     *
     * @param username the user name.
     * @param role the role.
     */
    @Operation(desc = "Add a role to the user")
    void addRole(
            @Parameter(name = "username", desc = "Username") String username,
            @Parameter(name = "role", desc = "Role") String role);

    /**
     * Remove a role from a user.
     *
     * @param username the user name.
     * @param role the role.
     */
    @Operation(desc = "Remove a role from a user")
    void deleteRole(
            @Parameter(name = "username", desc = "Username") String username,
            @Parameter(name = "role", desc = "Role") String role);

    /**
     * Add a role in a group.
     *
     * @param group the group.
     * @param role the role.
     */
    @Operation(desc = "Add a role in a group")
    void addGroupRole(
            @Parameter(name = "group", desc = "Group") String group,
            @Parameter(name = "role", desc = "Role") String role);

    /**
     * Remove a role from a group.
     *
     * @param group the group.
     * @param role the role.
     */
    @Operation(desc = "Remove a role from a group")
    void deleteGroupRole(
            @Parameter(name = "group", desc = "Group") String group,
            @Parameter(name = "role", desc = "Role") String role);


}
