UserDatabase (Apache JSPWiki Main Jar 2.11.2 API)

All Known Implementing Classes:

AbstractUserDatabase, DummyUserDatabase, JDBCUserDatabase, XMLUserDatabase
```
public interface UserDatabase
```
Defines an interface for loading, persisting and storing users.

Since:

2.3

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`deleteByLoginName(java.lang.String loginName)` Looks up and deletes the first `UserProfile` in the user database that matches a profile having a given login name.
`UserProfile`	`find(java.lang.String index)` Looks up and returns the first `UserProfile` in the user database that whose login name, full name, or wiki name matches the supplied string.
`UserProfile`	`findByEmail(java.lang.String index)` Looks up and returns the first `UserProfile` in the user database that matches a profile having a given e-mail address.
`UserProfile`	`findByFullName(java.lang.String index)` Looks up and returns the first `UserProfile` in the user database that matches a profile having a given full name.
`UserProfile`	`findByLoginName(java.lang.String index)` Looks up and returns the first `UserProfile` in the user database that matches a profile having a given login name.
`UserProfile`	`findByUid(java.lang.String uid)` Looks up and returns the first `UserProfile` in the user database that matches a profile having a given unique ID (uid).
`UserProfile`	`findByWikiName(java.lang.String index)` Looks up and returns the first `UserProfile` in the user database that matches a profile having a given wiki name.
`java.security.Principal[]`	`getPrincipals(java.lang.String identifier)` Looks up the Principals representing a user from the user database.
`java.security.Principal[]`	`getWikiNames()` Returns all WikiNames that are stored in the UserDatabase as an array of Principal objects.
`void`	`initialize(Engine engine, java.util.Properties props)` Initializes the user database based on values from a Properties object.
`UserProfile`	`newProfile()` Factory method that instantiates a new user profile.
`void`	`rename(java.lang.String loginName, java.lang.String newName)` Renames a `UserProfile` in the user database by changing the profile's login name.
`void`	`save(UserProfile profile)` Saves a `UserProfile`to the user database, overwriting the existing profile if it exists.
`boolean`	`validatePassword(java.lang.String loginName, java.lang.String password)` Determines whether a supplied user password is valid, given a login name and password.

- Method Detail
  - deleteByLoginName
```
void deleteByLoginName(java.lang.String loginName)
                throws NoSuchPrincipalException,
                       WikiSecurityException
```
    Looks up and deletes the first 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 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 synchronized.
    
    Parameters:
    
    loginName - the login name of the user profile that shall be deleted
    
    Throws:
    
    NoSuchPrincipalException
    
    WikiSecurityException
  - getPrincipals
```
java.security.Principal[] getPrincipals(java.lang.String identifier)
                                 throws NoSuchPrincipalException
```
    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 NoSuchPrincipalException.
    
    Note that if an implememtation wishes to mark one of the returned Principals as representing the user's common name, it should instantiate this Principal using WikiPrincipal.WikiPrincipal(String, String) with the type parameter set to WikiPrincipal.WIKI_NAME. The method 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.
    
    Parameters:
    
    identifier - the name of the user to retrieve; this corresponds to value returned by the user profile's UserProfile.getLoginName() method.
    
    Returns:
    
    the array of Principals representing the user's identities
    
    Throws:
    
    NoSuchPrincipalException - If the user database does not contain user with the supplied identifier
  - getWikiNames
```
java.security.Principal[] getWikiNames()
                                throws WikiSecurityException
```
    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.
    
    Returns:
    
    the WikiNames
    
    Throws:
    
    WikiSecurityException
  - find
```
UserProfile find(java.lang.String index)
          throws NoSuchPrincipalException
```
    Looks up and returns the first 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.
    
    Parameters:
    
    index - the login name, full name, or wiki name
    
    Throws:
    
    NoSuchPrincipalException
  - findByEmail
```
UserProfile findByEmail(java.lang.String index)
                 throws NoSuchPrincipalException
```
    Looks up and returns the first 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 NoSuchPrincipalException.
    
    Parameters:
    
    index - the e-mail address of the desired user profile
    
    Returns:
    
    the user profile
    
    Throws:
    
    NoSuchPrincipalException
  - findByLoginName
```
UserProfile findByLoginName(java.lang.String index)
                     throws NoSuchPrincipalException
```
    Looks up and returns the first 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 NoSuchPrincipalException.
    
    Parameters:
    
    index - the login name of the desired user profile
    
    Returns:
    
    the user profile
    
    Throws:
    
    NoSuchPrincipalException
  - findByUid
```
UserProfile findByUid(java.lang.String uid)
               throws NoSuchPrincipalException
```
    Looks up and returns the first 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 NoSuchPrincipalException.
    
    Parameters:
    
    uid - the unique identifier of the desired user profile
    
    Returns:
    
    the user profile
    
    Throws:
    
    NoSuchPrincipalException
    
    Since:
    
    2.8
  - findByWikiName
```
UserProfile findByWikiName(java.lang.String index)
                    throws NoSuchPrincipalException
```
    Looks up and returns the first 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 NoSuchPrincipalException.
    
    Parameters:
    
    index - the wiki name of the desired user profile
    
    Returns:
    
    the user profile
    
    Throws:
    
    NoSuchPrincipalException
  - findByFullName
```
UserProfile findByFullName(java.lang.String index)
                    throws NoSuchPrincipalException
```
    Looks up and returns the first 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 NoSuchPrincipalException.
    
    Parameters:
    
    index - the fill name of the desired user profile
    
    Returns:
    
    the user profile
    
    Throws:
    
    NoSuchPrincipalException
  - initialize
```
void initialize(Engine engine,
                java.util.Properties props)
         throws NoRequiredPropertyException,
                WikiSecurityException
```
    Initializes the user database based on values from a Properties object.
    
    Throws:
    
    NoRequiredPropertyException
    
    WikiSecurityException
  - newProfile
```
UserProfile newProfile()
```
    Factory method that instantiates a new user profile. The UserProfile.isNew() method of profiles created using this method should return true.
  - rename
```
void rename(java.lang.String loginName,
            java.lang.String newName)
     throws NoSuchPrincipalException,
            DuplicateUserException,
            WikiSecurityException
```
    Renames a 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.
    
    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 synchronized.
    
    Parameters:
    
    loginName - the existing login name for the profile
    
    newName - the proposed new login name
    
    Throws:
    
    NoSuchPrincipalException - if the user profile identified by loginName does not exist
    
    DuplicateUserException - if another user profile with the proposed new login name already exists
    
    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.
  - save
```
void save(UserProfile profile)
   throws WikiSecurityException
```
    Saves a UserProfileto 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 UserProfile.getLoginName() method.
    
    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.
    
    Implementations are required to time-stamp the creation or modification fields of the UserProfile./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 synchronized.
    
    Parameters:
    
    profile - the user profile to save
    
    Throws:
    
    WikiSecurityException - if the profile cannot be saved
  - validatePassword
```
boolean validatePassword(java.lang.String loginName,
                         java.lang.String password)
```
    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.
    
    Parameters:
    
    loginName - the login name
    
    password - the password
    
    Returns:
    
    true if the password is valid, false otherwise

Interface UserDatabase

Method Summary

Method Detail

deleteByLoginName

getPrincipals

getWikiNames

find

findByEmail

findByLoginName

findByUid

findByWikiName

findByFullName

initialize

newProfile

rename

save

validatePassword