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
    Modifier and Type | Method | Description
    --- | --- | ---
    `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​(java.lang.String groupname, java.lang.String description)` | Create and return a new `Group` defined in this user database.
    `Role` | `createRole​(java.lang.String rolename, java.lang.String description)` | Create and return a new `Role` defined in this user database.
    `User` | `createUser​(java.lang.String username, java.lang.String password, java.lang.String fullName)` | Create and return a new `User` defined in this user database.
    `Group` | `findGroup​(java.lang.String groupname)` |
    `Role` | `findRole​(java.lang.String rolename)` |
    `User` | `findUser​(java.lang.String username)` |
    `java.util.Iterator<Group>` | `getGroups()` |
    `java.lang.String` | `getId()` |
    `java.util.Iterator<Role>` | `getRoles()` |
    `java.util.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

          java.util.Iterator<Group> getGroups()

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

    - #### getId

          java.lang.String getId()

      Returns:
        the unique global identifier of this user database.

    - #### getRoles

          java.util.Iterator<Role> getRoles()

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

    - #### getUsers

          java.util.Iterator<User> getUsers()

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

    - #### close

          void close()
              throws java.lang.Exception

      Finalize access to this user database.
      Throws:
        `java.lang.Exception` - if any exception is thrown during closing

    - #### createGroup

          Group createGroup​(java.lang.String groupname,
                            java.lang.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​(java.lang.String rolename,
                          java.lang.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​(java.lang.String username,
                          java.lang.String password,
                          java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.Exception

      Initialize access to this user database.
      Throws:
        `java.lang.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 java.lang.Exception

      Save any updated information to the persistent storage location for this user database.
      Throws:
        `java.lang.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