/*
 * Copyright 2005-2010 the original author or authors.
 * 
 * Licensed 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.wamblee.security.authentication;

import java.util.List;

/**
 * Interface for user administration. Manages the users and groups.
 * 
 * @author Erik Brakkee
 */
public interface UserAdministration {
    /**
     * Creates a new user.
     * 
     * @param aUser
     *            Username.
     * @param aPassword
     *            Password.
     * 
     * @return User.
     * 
     * @throws UserMgtException
     *             In case there is a conflict with an existing user.
     */
    void createUser(String aUser, String aPassword);

    /**
     * Creates a new group.
     * 
     * @param aName
     *            Group name.
     * 
     * @return Group
     * 
     * @throws UserMgtException
     *             In case there is a conflict with an existing group.
     */
    void createGroup(String aName);
    
    /**
     * Checks if a user exists. 
     * @param aUser User to check.
     * @return True iff user exists. 
     */
    boolean checkUser(String aUser);
    
    
    /**
     * Check if a group exists. 
     * @param aGroup Group. 
     * @return True iff group exists. 
     */
    boolean checkGroup(String aGroup);
    
    /**
     * Checks the password.
     * 
     * @param aUser 
     *            User to check password for.
     * @param aPassword
     *            Password to check.
     * @throws UserMgtException In case user does not exist. 
     * @return True iff password is ok. 
     */
    boolean checkPassword(String aUser, String aPassword);

    /**
     * Changes the password.
     * 
     * @param aUser
     *            User. 
     * @param aOldPassword
     *            Old password.
     * @param aNewPassword
     *            New password.
     * 
     * @throws UserMgtException Inc ase the user does not exist. 
     * @return True if the password was changed. 
     */
    boolean changePassword(String aUser, String aOldPassword, String aNewPassword);

    /**
     * 
     * @param aUser
     *            User.
     * @param aPassword
     *            The password to set.
     * 
     * @throws UserMgtException Inc ase the user does not exist.
     */
    void setPassword(String aUser, String aPassword);

    /**
     * Checks if the user belongs to the given group.
     * @param aUser User
     * @param aGroup Group. 
     * @return True iff user is in group
     * @throws UserMgtException In case the user or group do not exist. 
     */
    boolean isInGroup(String aUser, String aGroup); 

    /**
     * 
     * @return Number of users.
     */
    int getUserCount();

    /**
     * 
     * @return Number of groups.
     */
    int getGroupCount();

    /**
     * Get the users.
     * 
     * @return All known users.
     */
    List<String> getUsers();

    /**
     * Gets the users for a given group.
     * 
     * @param aGroup
     *            Group.
     * @return Set of users (always non-null).
     */
    List<String> getUsers(String aGroup);

    /**
     * Gets all groups.
     * 
     * @return Groups.
     */
    List<String> getGroups();

    /**
     * Gets all groups for a given user.
     * 
     * @param aUser user. 
     * @return Groups.
     */
    List<String> getGroups(String aUser);
    
    /**
     * Renames a user.
     * 
     * @param aOldUserName
     *            Current user name.
     * @param aUserName
     *            New user name.
     * 
     * @throws UserMgtException
     *             In case the user is not known or the new user name is already
     *             in use by another user.
     */
    void renameUser(String aOldUserName, String aUserName);

    /**
     * Renames a group.
     * 
     * @param aGroup
     *            Group to rename.
     * @param aGroupName
     *            New name for the group.
     * 
     * @throws UserMgtException
     *             In case the new group name is already used by another group
     *             of if the existing group is unknown.
     */
    void renameGroup(String aOldGroup, String aGroupName);

    /**
     * Removes the user.
     * 
     * @param aUser
     *            User to remove.
     * 
     * @throws UserMgtException
     *             In case the user does not exist.
     */
    void removeUser(String aUser);

    /**
     * Removes the group.
     * 
     * @param aGroup
     *            Group to remove.
     * 
     * @throws UserMgtException
     *             In case there are still users that are in the given group.
     */
    void removeGroup(String aGroup);

    /**
     * Adds a user to a group.
     * 
     * @param aUser
     *            User.
     * @param aGroup
     *            Group.
     * 
     * @throws UserMgtException
     *             In case the user or group or not known or if the user is
     *             already part of the group.
     */
    void addUserToGroup(String aUser, String aGroup);

    /**
     * Removes a user from a group.
     * 
     * @param aUser
     *            User
     * @param aGroup
     *            Group
     * 
     * @throws UserMgtException
     *             In case the user or group are unknown or if the user is not
     *             part of the group.
     */
    void removeUserFromGroup(String aUser, String aGroup);
}