Package org.apache.wiki.auth.user

## Class XMLUserDatabase

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

All Implemented Interfaces:
  `UserDatabase`

    public class XMLUserDatabase
    extends AbstractUserDatabase

Manages `DefaultUserProfile` objects using XML files for persistence. Passwords are hashed using SHA1. User entries are simple `<user>` elements under the root. User profile properties are attributes of the element. For example:

> `<users>
> <user loginName="janne" fullName="Janne Jalkanen"
> wikiName="JanneJalkanen" email="janne@ecyrd.com"
> password="{SHA}457b08e825da547c3b77fbc1ff906a1d00a7daee"/>
> </users>`

In this example, the un-hashed password is `myP@5sw0rd`. Passwords are hashed without salt.

Since:
  2.3

### Field Summary

Fields
`static java.lang.String` `PROP_USERDATABASE` The jspwiki.properties property specifying the file system location of the user database.

### Fields inherited from class org.apache.wiki.auth.user.AbstractUserDatabase

`LOG, SHA_PREFIX, SHA256_PREFIX, SSHA_PREFIX`

### Constructor Summary

Constructors
`XMLUserDatabase()`

### Method Summary

All Methods Instance Methods Concrete Methods
`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` `findBy​(java.lang.String attr, java.lang.String value)`
`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[]` `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.
`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.

### Methods inherited from class org.apache.wiki.auth.user.AbstractUserDatabase

`find, generateUid, getHash, getPrincipals, newProfile, parseLong, validatePassword`

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

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

### Field Detail

#### PROP_USERDATABASE

    public static final java.lang.String PROP_USERDATABASE

The jspwiki.properties property specifying the file system location of the user database.

See Also:
  Constant Field Values

### Constructor Detail

#### XMLUserDatabase

    public XMLUserDatabase()

### Method Detail

#### deleteByLoginName

    public void deleteByLoginName​(java.lang.String loginName)
                           throws 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:
  `WikiSecurityException`

#### findByEmail

    public 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`.

Specified by:
  `findByEmail` in interface `UserDatabase`
Specified by:
  `findByEmail` in class `AbstractUserDatabase`
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 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`.

Specified by:
  `findByFullName` in interface `UserDatabase`
Specified by:
  `findByFullName` in class `AbstractUserDatabase`
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 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`.

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

#### findByUid

    public 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`

#### findByWikiName

    public 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`.

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

#### findBy

    public UserProfile findBy​(java.lang.String attr,
                              java.lang.String value)
                       throws NoSuchPrincipalException

Throws:
  `NoSuchPrincipalException`

#### getWikiNames

    public 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`

#### initialize

    public void initialize​(Engine engine,
                           java.util.Properties props)
                    throws NoRequiredPropertyException

Initializes the user database based on values from a Properties object.

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

#### rename

    public void rename​(java.lang.String loginName,
                       java.lang.String newName)
                throws 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:
  `DuplicateUserException` - if another user profile with the proposed new login name already exists
  `NoSuchPrincipalException` - if the user profile identified by `loginName` does not exist
  `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.
See Also:
  `UserDatabase.rename(String, String)`

#### save

    public 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`
Specified by:
  `save` in class `AbstractUserDatabase`
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)`