Package org.apache.wiki.auth.user

# Class AbstractUserDatabase

java.lang.Object
org.apache.wiki.auth.user.AbstractUserDatabase

All Implemented Interfaces:
  `UserDatabase`

Direct Known Subclasses:
  `DummyUserDatabase`, `JDBCUserDatabase`, `XMLUserDatabase`

public abstract class AbstractUserDatabase extends Object implements UserDatabase
Abstract UserDatabase class that provides convenience methods for finding profiles, building Principal collections and hashing passwords.

Since:
  2.3

## Field Summary

Fields
Modifier and Type
Field
Description
`protected static final org.apache.logging.log4j.Logger`
`LOG`
`protected static final String`
`SHA_PREFIX`
`protected static final String`
`SHA256_PREFIX`
`protected static final String`
`SSHA_PREFIX`

## Constructor Summary

Constructors
Constructor
Description
`AbstractUserDatabase()`

## Method Summary

Modifier and Type
Method
Description
`UserProfile`
`find(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.
`abstract UserProfile`
`findByEmail(String index)`
Looks up and returns the first `UserProfile` in the user database that matches a profile having a given e-mail address.
`abstract UserProfile`
`findByFullName(String index)`
Looks up and returns the first `UserProfile` in the user database that matches a profile having a given full name.
`abstract UserProfile`
`findByLoginName(String index)`
Looks up and returns the first `UserProfile` in the user database that matches a profile having a given login name.
`abstract UserProfile`
`findByWikiName(String index)`
Looks up and returns the first `UserProfile` in the user database that matches a profile having a given wiki name.
`protected static String`
`generateUid(UserDatabase db)`
Generates a new random user identifier (uid) that is guaranteed to be unique.
`protected String`
`getHash(String text)`
Private method that calculates the salted SHA-1 or SHA-256 hash of a given `String`.
`Principal[]`
`getPrincipals(String identifier)`
Looks up the Principals representing a user from the user database.
`abstract void`
`initialize(Engine engine, Properties props)`
Initializes the user database based on values from a Properties object.
`UserProfile`
`newProfile()`
Factory method that instantiates a new DefaultUserProfile with a new, distinct unique identifier.
`protected long`
`parseLong(String value)`
Parses a long integer from a supplied string, or returns 0 if not parsable.
`abstract void`
`save(UserProfile profile)`
Saves a `UserProfile`to the user database, overwriting the existing profile if it exists.
`boolean`
`validatePassword(String loginName, String password)`
Validates the password for a given user.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.apache.wiki.auth.user.UserDatabase

`deleteByLoginName, findByUid, getWikiNames, rename`

## Field Details

### LOG

protected static final org.apache.logging.log4j.Logger LOG

### SHA_PREFIX

protected static final String SHA_PREFIX

See Also:
  - Constant Field Values

### SSHA_PREFIX

protected static final String SSHA_PREFIX

See Also:
  - Constant Field Values

### SHA256_PREFIX

protected static final String SHA256_PREFIX

See Also:
  - Constant Field Values

## Constructor Details

### AbstractUserDatabase

public AbstractUserDatabase()

## Method Details

### find

public UserProfile find(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.

Specified by:
  `find` in interface `UserDatabase`
Parameters:
  `index` - the login name, full name, or wiki name
Throws:
  `NoSuchPrincipalException`
See Also:
  - `UserDatabase.find(java.lang.String)`

### findByEmail

public abstract UserProfile findByEmail(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`.

Specified by:
  `findByEmail` in interface `UserDatabase`
Parameters:
  `index` - the e-mail address of the desired user profile
Returns:
  the user profile
Throws:
  `NoSuchPrincipalException`
See Also:
  - `UserDatabase.findByEmail(java.lang.String)`

### findByFullName

public abstract UserProfile findByFullName(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`.

Specified by:
  `findByFullName` in interface `UserDatabase`
Parameters:
  `index` - the fill name of the desired user profile
Returns:
  the user profile
Throws:
  `NoSuchPrincipalException`
See Also:
  - `UserDatabase.findByFullName(java.lang.String)`

### findByLoginName

public abstract UserProfile findByLoginName(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`.

Specified by:
  `findByLoginName` in interface `UserDatabase`
Parameters:
  `index` - the login name of the desired user profile
Returns:
  the user profile
Throws:
  `NoSuchPrincipalException`
See Also:
  - `UserDatabase.findByLoginName(java.lang.String)`

### findByWikiName

public abstract UserProfile findByWikiName(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`.

Specified by:
  `findByWikiName` in interface `UserDatabase`
Parameters:
  `index` - the wiki name of the desired user profile
Returns:
  the user profile
Throws:
  `NoSuchPrincipalException`
See Also:
  - `UserDatabase.findByWikiName(java.lang.String)`

### getPrincipals

public Principal[] getPrincipals(String identifier) throws NoSuchPrincipalException

Looks up the Principals representing a user from the user database. These are defined as a set of WikiPrincipals manufactured from the login name, full name, and wiki name. If the user database does not contain a user with the supplied identifier, throws a `NoSuchPrincipalException`.

When this method creates WikiPrincipals, the Principal containing the user's full name is marked as containing the common name (see `WikiPrincipal(String, String)`).

Specified by:
  `getPrincipals` in interface `UserDatabase`
Parameters:
  `identifier` - the name of the principal to retrieve; this corresponds to value returned by the user profile's `UserProfile.getLoginName()`method.
Returns:
  the array of Principals representing the user
Throws:
  `NoSuchPrincipalException` - If the user database does not contain user with the supplied identifier
See Also:
  - `UserDatabase.getPrincipals(java.lang.String)`

### initialize

public abstract void initialize(Engine engine, Properties props) throws NoRequiredPropertyException, WikiSecurityException
Initializes the user database based on values from a Properties object.

Specified by:
  `initialize` in interface `UserDatabase`
Throws:
  `NoRequiredPropertyException`
  `WikiSecurityException`
See Also:
  - `UserDatabase.initialize(org.apache.wiki.api.core.Engine, java.util.Properties)`

### newProfile

public UserProfile newProfile()
Factory method that instantiates a new DefaultUserProfile with a new, distinct unique identifier.

Specified by:
  `newProfile` in interface `UserDatabase`
Returns:
  A new, empty profile.

### save

public abstract void save(UserProfile profile) throws WikiSecurityException

Saves a `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 `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`.

Specified by:
  `save` in interface `UserDatabase`
Parameters:
  `profile` - the user profile to save
Throws:
  `WikiSecurityException` - if the profile cannot be saved
See Also:
  - `UserDatabase.save(org.apache.wiki.auth.user.UserProfile)`

### validatePassword

public boolean validatePassword(String loginName, String password)
Validates the password for a given user. If the user does not exist in the user database, this method always returns `false`. If the user exists, the supplied password is compared to the stored password. Note that if the stored password's value starts with `{SHA}`, the supplied password is hashed prior to the comparison.

Specified by:
  `validatePassword` in interface `UserDatabase`
Parameters:
  `loginName` - the user's login name
  `password` - the user's password (obtained from user input, e.g., a web form)
Returns:
  `true` if the supplied user password matches the stored password
See Also:
  - `UserDatabase.validatePassword(java.lang.String, java.lang.String)`

### generateUid

protected static String generateUid(UserDatabase db)
Generates a new random user identifier (uid) that is guaranteed to be unique.

Parameters:
  `db` - The database for which the UID should be generated.
Returns:
  A random, unique UID.

### getHash

protected String getHash(String text)
Private method that calculates the salted SHA-1 or SHA-256 hash of a given `String`. Note that as of JSPWiki 2.8, this method calculates a salted hash rather than a plain hash.

Parameters:
  `text` - the text to hash
Returns:
  the result hash

### parseLong

protected long parseLong(String value)
Parses a long integer from a supplied string, or returns 0 if not parsable.

Parameters:
  `value` - the string to parse
Returns:
  the value parsed