UserDatabase (Apache Tomcat 9.0.120 API Documentation)
Description: declaration: package: org.apache.catalina, interface: UserDatabase

# 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

- ## Method Summary

  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(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)`
  Find the `Group` with the specified group name.
  `Role`
  `findRole(String rolename)`
  Find the `Role` with the specified role name.
  `User`
  `findUser(String username)`
  Find the `User` with the specified username.
  `Iterator<Group>`
  `getGroups()`
  Get the set of `Group`s defined in this user database.
  `String`
  `getId()`
  Get the unique global identifier of this user database.
  `Iterator<Role>`
  `getRoles()`
  Get the set of `Role`s defined in this user database.
  `Iterator<User>`
  `getUsers()`
  Get the set of `User`s defined in this user database.
  `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 Details

  - ### getGroups

    Iterator<Group> getGroups()
    Get the set of `Group`s defined in this user database.
    Returns:
      the set of `Group`s defined in this user database.

  - ### getId

    String getId()
    Get the unique global identifier of this user database.
    Returns:
      the unique global identifier of this user database.

  - ### getRoles

    Iterator<Role> getRoles()
    Get the set of `Role`s defined in this user database.
    Returns:
      the set of `Role`s defined in this user database.

  - ### getUsers

    Iterator<User> getUsers()
    Get the set of `User`s defined in this user database.
    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, or `null` if there's a pre-existing 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, or `null` if there's a pre-existing 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, or `null` if there's a pre-existing user

  - ### findGroup

    Group findGroup(String groupname)
    Find the `Group` with the specified group name.
    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)
    Find the `Role` with the specified role name.
    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)
    Find the `User` with the specified username.
    Parameters:
      `username` - Name of the user to return
    Returns:
      the `User` with the specified username, 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