/* 
    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.wiki.auth.user;

import org.apache.wiki.api.core.Engine;
import org.apache.wiki.api.exceptions.NoRequiredPropertyException;
import org.apache.wiki.auth.NoSuchPrincipalException;
import org.apache.wiki.auth.WikiSecurityException;

import java.security.Principal;
import java.util.Properties;

/**
 * Defines an interface for loading, persisting and storing users.
 *
 * @since 2.3
 */
public interface UserDatabase {

    /**
     * Looks up and deletes the first {@link UserProfile} in the user database that matches a profile having a given login name. If the
     * user database does not contain a user with a matching attribute, throws a {@link NoSuchPrincipalException}. This method is intended
     * to be atomic; results cannot be partially committed. If the commit fails, it should roll back its state appropriately. Implementing
     * classes that persist to the file system may wish to make this method <code>synchronized</code>.
     *
     * @param loginName the login name of the user profile that shall be deleted
     */
    void deleteByLoginName( String loginName ) throws NoSuchPrincipalException, WikiSecurityException;

    /**
     * <p>
     * Looks up the Principals representing a user from the user database. These are defined as a set of Principals manufactured from the
     * login name, full name, and wiki name. The order of the Principals returned is not significant. If the user database does not contain
     * a user with the supplied identifier, throws a {@link NoSuchPrincipalException}.
     * </p>
     * <p>
     * Note that if an implementation wishes to mark one of the returned Principals as representing the user's common name, it should
     * instantiate this Principal using {@link org.apache.wiki.auth.WikiPrincipal#WikiPrincipal(String, String)} with the <code>type</code>
     * parameter set to {@link org.apache.wiki.auth.WikiPrincipal#WIKI_NAME}. The method
     * {@link org.apache.wiki.api.core.Session#getUserPrincipal()} will return this principal as the "primary" principal. Note that this method
     * can also be used to mark a WikiPrincipal as a login name or a wiki name.
     * </p>
     *
     * @param identifier the name of the user to retrieve; this corresponds to value returned by the user profile's {@link UserProfile#getLoginName()} method.
     * @return the array of Principals representing the user's identities
     * @throws NoSuchPrincipalException If the user database does not contain user with the supplied identifier
     */
    Principal[] getPrincipals( String identifier ) throws NoSuchPrincipalException;

    /**
     * Returns all WikiNames that are stored in the UserDatabase as an array of Principal objects. If the database does not
     * contain any profiles, this method will return a zero-length array.
     *
     * @return the WikiNames
     * @throws org.apache.wiki.auth.WikiSecurityException
     */
    Principal[] getWikiNames() throws WikiSecurityException;

    /**
     * Looks up and returns the first {@link UserProfile} in the user database that whose login name, full name, or wiki name matches the
     * supplied string. This method provides a "forgiving" search algorithm for resolving Principal names when the exact profile attribute
     * that supplied the name is unknown.
     *
     * @param index the login name, full name, or wiki name
     * @return non null
     * @throws org.apache.wiki.auth.NoSuchPrincipalException
     * @deprecated depending on the use case, this API's usage can be dangerous.
     * Recommend using other APIs for more explicit lookup types. see JSPWIKI-130
     * for additional details.
     */
    @Deprecated
    UserProfile find( String index ) throws NoSuchPrincipalException;

    /**
     * Looks up and returns the first {@link UserProfile} in the user database that matches a profile having a given e-mail address. If
     * the user database does not contain a user with a matching attribute, throws a {@link NoSuchPrincipalException}.
     *
     * @param index the e-mail address of the desired user profile
     * @return the user profile
     * @throws org.apache.wiki.auth.NoSuchPrincipalException
     */
    UserProfile findByEmail( String index ) throws NoSuchPrincipalException;

    /**
     * Looks up and returns the first {@link UserProfile} in the user database that matches a profile having a given login name. If the
     * user database does not contain a user with a matching attribute, throws a {@link NoSuchPrincipalException}.
     *
     * @param index the login name of the desired user profile
     * @return the user profile
     * @throws org.apache.wiki.auth.NoSuchPrincipalException
     */
    UserProfile findByLoginName( String index ) throws NoSuchPrincipalException;

    /**
     * Looks up and returns the first {@link UserProfile} in the user database that matches a profile having a given unique ID (uid). If
     * the user database does not contain a user with a unique ID, it throws a {@link NoSuchPrincipalException}.
     *
     * @param uid the unique identifier of the desired user profile
     * @return the user profile
     * @throws org.apache.wiki.auth.NoSuchPrincipalException
     * @since 2.8
     */
    UserProfile findByUid( String uid ) throws NoSuchPrincipalException;
    
    /**
     * Looks up and returns the first {@link UserProfile} in the user database that matches a profile having a given wiki name. If the user
     * database does not contain a user with a matching attribute, throws a {@link NoSuchPrincipalException}.
     *
     * @param index the wiki name of the desired user profile
     * @return the user profile
     * @throws org.apache.wiki.auth.NoSuchPrincipalException
     */
    UserProfile findByWikiName( String index ) throws NoSuchPrincipalException;

    /**
     * Looks up and returns the first {@link UserProfile} in the user database that matches a profile having a given full name. If the user
     * database does not contain a user with a matching attribute, throws a {@link NoSuchPrincipalException}.
     *
     * @param index the fill name of the desired user profile
     * @return the user profile
     * @throws org.apache.wiki.auth.NoSuchPrincipalException
     */
    UserProfile findByFullName( String index ) throws NoSuchPrincipalException;

    /** Initializes the user database based on values from a Properties object.
     * @param engine
     * @param props
     * @throws org.apache.wiki.api.exceptions.NoRequiredPropertyException
     * @throws org.apache.wiki.auth.WikiSecurityException */
    void initialize( Engine engine, Properties props ) throws NoRequiredPropertyException, WikiSecurityException;

    /**
     * Factory method that instantiates a new user profile. The {@link UserProfile#isNew()} method of profiles created using
     * this method should return <code>true</code>.
     * @return user profile
     */
    UserProfile newProfile();

    /**
     * <p>Renames a {@link UserProfile} in the user database by changing the profile's login name. Because the login name is the profile's
     * unique identifier, implementations should verify that the identifier is "safe" to change before actually changing it. Specifically:
     * the profile with the supplied login name must already exist, and the proposed new name must not be in use by another profile.</p>
     * <p>This method is intended to be atomic; results cannot be partially committed. If the commit fails, it should roll back its state
     * appropriately. Implementing classes that persist to the file system may wish to make this method <code>synchronized</code>.</p>
     *
     * @param loginName the existing login name for the profile
     * @param newName the proposed new login name
     * @throws NoSuchPrincipalException if the user profile identified by <code>loginName</code> does not exist
     * @throws DuplicateUserException if another user profile with the proposed new login name already exists
     * @throws WikiSecurityException if the profile cannot be renamed for any reason, such as an I/O error, database connection failure
     * or lack of support for renames.
     */
    void rename( String loginName, String newName ) throws NoSuchPrincipalException, DuplicateUserException, WikiSecurityException;

    /**
     * <p>
     * Saves a {@link UserProfile}to the user database, overwriting the existing profile if it exists. The user name under which the profile
     * should be saved is returned by the supplied profile's {@link UserProfile#getLoginName()} method.
     * </p>
     * <p>
     * The database implementation is responsible for detecting potential duplicate user profiles; specifically, the login name, wiki name,
     * and full name must be unique. The implementation is not required to check for validity of passwords or e-mail addresses. Special
     * case: if the profile already exists and the password is null, it should retain its previous value, rather than being set to null.
     * </p>
     * <p>Implementations are <em>required</em> to time-stamp the creation or modification fields of the UserProfile./p>
     * <p>This method is intended to be atomic; results cannot be partially committed. If the commit fails, it should roll back its state
     * appropriately. Implementing classes that persist to the file system may wish to make this method <code>synchronized</code>.</p>
     *
     * @param profile the user profile to save
     * @throws WikiSecurityException if the profile cannot be saved
     */
    void save( UserProfile profile ) throws WikiSecurityException;

    /**
     * Determines whether a supplied user password is valid, given a login name and password. It is up to the implementing class to
     * determine how the comparison should be made. For example, the password might be hashed before comparing it to the value persisted
     * in the back-end data store.
     *
     * @param loginName the login name
     * @param password the password
     * @return <code>true</code> if the password is valid, <code>false</code> otherwise
     */
    boolean validatePassword( String loginName, String password );

    /**
     * validates that the proposed password has not been recently used.
     * @param loginName
     * @param password
     * @return false if the password has been recently used, true otherwise
     * @since 3.0.0
     */
    boolean validatePasswordReuse( final String loginName, final String password );
}