/*
 * 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.
 */ 
/**
 * This package provides support for managing users and their authentication. 
 * 
 * <h1>Supported use cases</h1>
 * 
 * in particular, it supports the following use cases: 
 * <ul>
 *   <li> Dynamically manage users and groups from an application. 
 *   </li>
 *   <li> Authenticate users
 *   </li>
 *   <li> Store users and groups in a database. 
 *   </li>    
 * </ul> 
 * 
 * An overview is given below: 
 * <br/>
 * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__main.jpg" alt="overview"</img>
 * <br/>
 * 
 * The user of the package interacts with the {@link UserAdministration} interface for the following tasks: 
 * <ul>
 *   <li>Adding users and removing users</li>
 *   <li>Adding users to groups and removing them from groups</li>
 *   <li>Renaming users and groups</li>
 *   <li>Modifying the user's password</li>
 *   <li>Populate with initial users upon first startup</li>
 * </ul>
 * In addition, it provides methods for authenticating the user. Note however that it is also possible
 * to use declarative Java EE security using the appropriate security realm. See for instance, 
 * <a href="http://flexiblejdbcrealm.wamblee.org">flexible JDBC realm</a> for a Glassfish based solution.
 * 
 * {@link UserAdminInitializer} can be used to automatically initialize the user administration with 
 * initial users and groups when there are no users defined yet. 
 * 
 * To use the user administration interface, several implementation classes must be wired together. This is 
 * explained below. 
 * 
 * There is one implementation {@link UserAdministrationImpl} of this interface that must be constructed
 * with a {@link UserSet} and {@link GroupSet} implementation, together with two validators: one for
 * user names and another for group names. 
 * 
 * For user and groups sets there are two implementations, one inmemory and another with database persistence.
 * Typically the one with database persistence is used but for testing other code, the inmemory implementation
 * can be used. 
 * <br/>
 * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__sets.jpg"/>
 * <br/>
 * 
 * At construction of the userset, a password validator is required as well as a digest algorithm to 
 * compute a digest of the password to store in the database and also to validate users against. 
 * <br/>
 * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__digester.jpg"/>
 * <br/>
 * 
 * Finally, there is the basic model for users and groups that is used under the covers. As a user
 * of the security library these objects will typically not be used. 
 * <br/>
 * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__digester.jpg"/>
 * <br/>
 */
package org.wamblee.security.authentication;