userdatabase.java

这是linux下ssl vpn的实现程序

/*
 *  SSL-Explorer
 *
 *  Copyright (C) 2003-2006 3SP LTD. All Rights Reserved
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; either version 2 of
 *  the License, or (at your option) any later version.
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public
 *  License along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
			
package com.sslexplorer.security;

import java.util.List;
import java.util.Properties;

import com.sslexplorer.core.Database;
import com.sslexplorer.policyframework.Principal;

/**
 * <p>Implementations of this interface will provide basic user and role related
 * services such as retrieving a user account, retrieving a role, authenticating
 * a user etc.
 * 
 * <p>Some implementations will now support account creation or password
 * changing and as such should return appropriate values for {@link #supportsAccountCreation()}
 * and {@link #supportsPasswordChange()}.
 * <p>
 * User database implementations are also required to store arbitrary 
 * attributes against a user. To support the user interface, it must also
 * provide methods to persist and retrieve {@link com.sslexplorer.security.UserAttributeDefinition}
 *  
 *  
 * @author Lee David Painter
 * @version $Revision: 1.27 $
 */
public interface UserDatabase extends Database {

    /**
     * Get a readable description of the database.
     * 
     * @return description
     */
    public String getDatabaseDescription();

    /**
     * Get if the database is currently 'open'.
     * 
     * @return open
     */
    public boolean isOpen();

    /**
     * Authenticates the given username/password pair, returning the user object
     * on success or <tt>null</tt> on failure.
     * 
     * @param username
     * @param password
     * @return user object
     * @throws UserDatabaseException
     * @throws InvalidLoginCredentialsException
     * @throws AccountLockedException
     */
    public User logon(String username, String password) throws UserDatabaseException, InvalidLoginCredentialsException,
                    AccountLockedException;

    /**
     * Check the given username/password pair but do not actually logon.
     * <tt>true</tt> is returned on success and <tt>false</tt> on failure.
     * 
     * @param username
     * @param password
     * @return password ok
     * @throws UserDatabaseException
     * @throws InvalidLoginCredentialsException
     */
    public boolean checkPassword(String username, String password) throws UserDatabaseException, InvalidLoginCredentialsException;

    /**
     * Change a users password. A <code>UserDatabaseException</code> may be
     * thrown if the implementation doesn't support this function.
     * 
     * @param username username
     * @param password new password
     * @param forcePasswordChangeAtLogon force password change at next logon
     * @throws UserDatabaseException
     * @throws InvalidLoginCredentialsException
     */
    public void changePassword(String username, String password, boolean forcePasswordChangeAtLogon) throws UserDatabaseException,
                    InvalidLoginCredentialsException;

    /**
     * Get if this implementation supports changine of passwords
     * 
     * @return password change supported
     */
    public boolean supportsPasswordChange();

    /**
     * Logout a user.
     * 
     * @param user
     */
    public void logout(User user);

    /**
     * List all the users currently registered with the system. This is the list
     * of all users rather than those that are granted access
     * 
     * @param filter filter a filter to apply to the search
     * @return an array of {@link User}s
     * @throws Exception
     */
    public User[] listAllUsers(String filter) throws Exception;

    /**
     * List all the principals currently registered with the system
     * 
     * @return an array of {@link Principal}s
     * @throws Exception
     */
    public Principal[] listAvailablePrincipals() throws Exception;

    /**
     * Get the account details that belong to the given username.
     * 
     * @param username
     * @return user
     * @throws Exception
     */
    public User getAccount(String username) throws Exception;

    /**
     * Identify whether this implementation supports the creation of user
     * accounts.
     * 
     * @return <tt>true</tt> if account creation is supported, otherwise
     *         <tt>false</tt>.
     */
    public boolean supportsAccountCreation();

    /**
     * Create a new {@link User}account. This method is optional and should
     * only work when {@link #supportsAccountCreation()} returns <tt>true</tt>.
     * 
     * @param username username
     * @param password password
     * @param email email address
     * @param fullname full name
     * @param roles array of roles
     * @param attributes initial user attributes
     * @return user user object
     * @throws Exception on any error
     */
    public User createAccount(String username, String password, String email, String fullname, Role[] roles, Properties attributes) throws Exception;

    /**
     * Update the details of a {@link User}account. This method is optional and
     * should only work when {@link #supportsAccountCreation()} returns
     * <tt>true</tt>.#
     * 
     * @param user
     * @param email
     * @param fullname
     * @param roles
     * @param attributes
     * @throws Exception
     */
    public void updateAccount(User user, String email, String fullname, Role[] roles, Properties attributes) throws Exception;

    /**
     * Delete a {@link User} account. This method is optional and should only
     * work when {@link #supportsAccountCreation()} returns <tt>true</tt>.
     * 
     * @param user
     * @throws Exception
     */
    public void deleteAccount(User user) throws Exception;


    /**
     * Get a single role given its name
     * 
     * @param rolename role name
     * @return role
     * @throws Exception on any error
     */
    public Role getRole(String rolename) throws Exception;

    /**
     * List all available roles
     * 
     * @param filter filter
     * @return array of roles
     * @throws Exception on any error
     */
    public Role[] listAllRoles(String filter) throws Exception;

    /**
     * Create a new role if the underlying database supports it.
     * 
     * @param rolename role name
     * @return role object
     * @throws Exception on any error
     */
    public Role createRole(String rolename) throws Exception;

    /**
     * Delete a new role
     * 
     * @param rolename role name
     * @throws Exception on any error
     */
    public void deleteRole(String rolename) throws Exception;

    /**
     * If the user database requires additional configuration during
     * the install wizard, the category for the property definitions
     * should be returned here. Return <code>-1</code> if the database
     * has no such configuration.
     * 
     * @return installation property category
     */
    public int getInstallationPropertyCategory();
    
    /**
     * Get the a list of {@link com.sslexplorer.security.User}s that are in
     * a specified role
     * 
     * @param role role
     * @return users in role
     * @throws Exception on any error
     */
    public User[] getUsersInRole(Role role) throws Exception;

    /**
     * Update the users attributes. Implementations <strong>must</strong>
     * support the storing of user attributes even if they are read-only.
     * 
     * @param principalName
     * @param attributes
     * @throws Exception on any error
     */
    public void updateAttributes(String principalName, Properties attributes) throws  Exception;
    
    /**
     * Update the users attribute. Implementations <strong>must</strong>
     * support the storing of user attributes even if they are read-only.
     * 
     * @param principalName
     * @param key
     * @param value
     * @throws Exception on any error
     */
    public void updateAttribute(String principalName, String key, String value) throws  Exception;

    /**
     * Register a new <i>System</i> user attribute definition. This does not persist the
     * definition to the database so is useful for plugins who wish to add
     * user attribute definitions.
     *
     * @param definition definition to store
     * @throws Exception on any error
     */
    public void registerUserAttributeDefinition(UserAttributeDefinition definition) throws Exception;    
    
    /**
     * Deregister a  <i>System</i>  user attribute definition. This does not 
     * remove any records from the database.
     *
     * @param definitionName definition to store
     * @throws Exception on any error
     */
    public void deregisterUserAttributeDefinition(String definitionName) throws Exception;
    
    /**
     * Store a new user attribute definition. 
     *
     * @param definition definition to store
     * @throws Exception on any error
     */
    public void createUserAttributeDefinition(UserAttributeDefinition definition) throws Exception;
    
    /**
     * Update an existing user attribute definition.
     *
     * @param definition definition to update
     * @throws Exception on any error
     */
    public void updateUserAttributeDefinition(UserAttributeDefinition definition) throws Exception;
    
    /**
     * Delete an existing user attribute definition.
     *
     * @param definitionName definition name to delete
     * @throws Exception on any error
     */
    public void deleteUserAttributeDefinition(String definitionName) throws Exception;
    
    /**
     * Get a list of all user attribute definition.
     *
     * @return list of user attribute definitions
     * @throws Exception on any error
     */
    public List getUserAttributeDefinitions() throws Exception;

    /**
     * Get a user attribute definition given its name. <code>null</code> will
     * be returned if no such attribute exists.
     * 
     * @param name
     * @return user attribute definition or null if doesn't exist
     * @throws Exception on any error
     */
    public UserAttributeDefinition getUserAttributeDefinition(String name) throws Exception;

    /**
     * Load a users attributes.
     * 
     * @param user user
     * @throws Exception on any error
     */
    public void loadAttributes(User user) throws Exception;
    
}