Package org.apache.catalina

# Interface UserDatabase

All Known Implementing Classes:
  `MemoryUserDatabase`

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

  Modifier and Type
  Method
  Description
  `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()`
  `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()
    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

  - ### 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