Package org.apache.catalina

## Interface UserDatabase

All Known Implementing Classes:
  `DataSourceUserDatabase`, `MemoryUserDatabase`, `SparseUserDatabase`

    public interface UserDatabase

Abstract representation of a database of `User`s and `Group`s that can be maintained by an application, along with definitions of corresponding `Role`s, and referenced by a `Realm` for authentication and access control.

Since:
  4.1
Author:
  Craig R. McClanahan

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`default void` `backgroundProcess()` Perform any background processing (e.g. checking for changes in persisted storage) required for the user database.
`void` `close()` Finalize access to this user database.
`Group` `createGroup​(String groupname, String description)` Create and return a new `Group` defined in this user database.
`Role` `createRole​(String rolename, String description)` Create and return a new `Role` defined in this user database.
`User` `createUser​(String username, String password, String fullName)` Create and return a new `User` defined in this user database.
`Group` `findGroup​(String groupname)`
`Role` `findRole​(String rolename)`
`User` `findUser​(String username)`
`Iterator<Group>` `getGroups()`
`String` `getId()`
`Iterator<Role>` `getRoles()`
`Iterator<User>` `getUsers()`
`default boolean` `isAvailable()` Is the database available.
`default boolean` `isSparse()` Is the database data loaded on demand.
`default void` `modifiedGroup​(Group group)` Signal the specified `Group` from this user database has been modified.
`default void` `modifiedRole​(Role role)` Signal the specified `Role` from this user database has been modified.
`default void` `modifiedUser​(User user)` Signal the specified `User` from this user database has been modified.
`void` `open()` Initialize access to this user database.
`void` `removeGroup​(Group group)` Remove the specified `Group` from this user database.
`void` `removeRole​(Role role)` Remove the specified `Role` from this user database.
`void` `removeUser​(User user)` Remove the specified `User` from this user database.
`void` `save()` Save any updated information to the persistent storage location for this user database.

### Method Detail

#### getGroups

    Iterator<Group> getGroups()

Returns:
  the set of `Group`s defined in this user database.

#### getId

    String getId()

Returns:
  the unique global identifier of this user database.

#### getRoles

    Iterator<Role> getRoles()

Returns:
  the set of `Role`s defined in this user database.

#### getUsers

    Iterator<User> getUsers()

Returns:
  the set of `User`s defined in this user database.

#### close

    void close()
        throws Exception

Finalize access to this user database.

Throws:
  `Exception` - if any exception is thrown during closing

#### createGroup

    Group createGroup​(String groupname,
                      String description)

Create and return a new `Group` defined in this user database.

Parameters:
  `groupname` - The group name of the new group (must be unique)
  `description` - The description of this group
Returns:
  The new group

#### createRole

    Role createRole​(String rolename,
                    String description)

Create and return a new `Role` defined in this user database.

Parameters:
  `rolename` - The role name of the new role (must be unique)
  `description` - The description of this role
Returns:
  The new role

#### createUser

    User createUser​(String username,
                    String password,
                    String fullName)

Create and return a new `User` defined in this user database.

Parameters:
  `username` - The logon username of the new user (must be unique)
  `password` - The logon password of the new user
  `fullName` - The full name of the new user
Returns:
  The new user

#### findGroup

    Group findGroup​(String groupname)

Parameters:
  `groupname` - Name of the group to return
Returns:
  the `Group` with the specified group name, if any; otherwise return `null`.

#### findRole

    Role findRole​(String rolename)

Parameters:
  `rolename` - Name of the role to return
Returns:
  the `Role` with the specified role name, if any; otherwise return `null`.

#### findUser

    User findUser​(String username)

Parameters:
  `username` - Name of the user to return
Returns:
  the `User` with the specified user name, if any; otherwise return `null`.

#### open

    void open()
       throws Exception

Initialize access to this user database.

Throws:
  `Exception` - if any exception is thrown during opening

#### removeGroup

    void removeGroup​(Group group)

Remove the specified `Group` from this user database.

Parameters:
  `group` - The group to be removed

#### removeRole

    void removeRole​(Role role)

Remove the specified `Role` from this user database.

Parameters:
  `role` - The role to be removed

#### removeUser

    void removeUser​(User user)

Remove the specified `User` from this user database.

Parameters:
  `user` - The user to be removed

#### modifiedGroup

    default void modifiedGroup​(Group group)

Signal the specified `Group` from this user database has been modified.

Parameters:
  `group` - The group that has been modified

#### modifiedRole

    default void modifiedRole​(Role role)

Signal the specified `Role` from this user database has been modified.

Parameters:
  `role` - The role that has been modified

#### modifiedUser

    default void modifiedUser​(User user)

Signal the specified `User` from this user database has been modified.

Parameters:
  `user` - The user that has been modified

#### save

    void save()
       throws Exception

Save any updated information to the persistent storage location for this user database.

Throws:
  `Exception` - if any exception is thrown during saving

#### backgroundProcess

    default void backgroundProcess()

Perform any background processing (e.g. checking for changes in persisted storage) required for the user database.

#### isAvailable

    default boolean isAvailable()

Is the database available.

Returns:
  true

#### isSparse

    default boolean isSparse()

Is the database data loaded on demand. This is used to avoid eager loading of the full database data, for example for JMX registration of all objects.

Returns:
  false