# Class DataSourceUserDatabase

java.lang.Object
org.apache.catalina.users.SparseUserDatabase
org.apache.catalina.users.DataSourceUserDatabase

All Implemented Interfaces:
  `UserDatabase`

public class DataSourceUserDatabase extends SparseUserDatabase
UserDatabase backed by a data source.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final ConcurrentHashMap<String,Group>`
  `createdGroups`
  Groups that have been created but not yet persisted.
  `protected final ConcurrentHashMap<String,Role>`
  `createdRoles`
  Roles that have been created but not yet persisted.
  `protected final ConcurrentHashMap<String,User>`
  `createdUsers`
  Users that have been created but not yet persisted.
  `protected final DataSource`
  `dataSource`
  DataSource to use.
  `protected String`
  `dataSourceName`
  The name of the JNDI JDBC DataSource
  `protected String`
  `groupNameCol`
  The column in the user group table that names a group
  `protected String`
  `groupRoleTable`
  The table that holds the relation between groups and roles
  `protected String`
  `groupTable`
  The table that holds group data.
  `protected final String`
  `id`
  The unique global identifier of this user database.
  `protected final ConcurrentHashMap<String,Group>`
  `modifiedGroups`
  Groups that have been modified but not yet persisted.
  `protected final ConcurrentHashMap<String,Role>`
  `modifiedRoles`
  Roles that have been modified but not yet persisted.
  `protected final ConcurrentHashMap<String,User>`
  `modifiedUsers`
  Users that have been modified but not yet persisted.
  `protected boolean`
  `readonly`
  A flag, indicating if the user database is read only.
  `protected final ConcurrentHashMap<String,Group>`
  `removedGroups`
  Groups that have been removed but not yet persisted.
  `protected final ConcurrentHashMap<String,Role>`
  `removedRoles`
  Roles that have been removed but not yet persisted.
  `protected final ConcurrentHashMap<String,User>`
  `removedUsers`
  Users that have been removed but not yet persisted.
  `protected String`
  `roleAndGroupDescriptionCol`
  The column in the role and group tables for the description
  `protected String`
  `roleNameCol`
  The column in the user role table that names a role
  `protected String`
  `roleTable`
  The table that holds role data.
  `protected String`
  `userCredCol`
  The column in the user table that holds the user's credentials
  `protected String`
  `userFullNameCol`
  The column in the user table that holds the user's full name
  `protected String`
  `userGroupTable`
  The table that holds the relation between users and groups
  `protected String`
  `userNameCol`
  The column in the user table that holds the user's name
  `protected String`
  `userRoleTable`
  The table that holds the relation between users and roles
  `protected String`
  `userTable`
  The table that holds user data.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataSourceUserDatabase(DataSource dataSource, String id)`
  Create a new DataSourceUserDatabase.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Finalize access to this user database.
  `protected void`
  `closeConnection(Connection dbConnection)`
  Close the specified database connection.
  `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.
  `Group`
  `findGroupInternal(Connection dbConnection, String groupName)`
  Find a group by name using the provided database connection.
  `Role`
  `findRole(String rolename)`
  Find the `Role` with the specified role name.
  `Role`
  `findRoleInternal(Connection dbConnection, String roleName)`
  Find a role by name using the provided database connection.
  `User`
  `findUser(String username)`
  Find the `User` with the specified username.
  `User`
  `findUserInternal(Connection dbConnection, String userName)`
  Deprecated.
  Will be made private in Tomcat 12
  `String`
  `getDataSourceName()`
  Return the name of the JNDI JDBC DataSource.
  `String`
  `getGroupNameCol()`
  Return the column name used for group names.
  `String`
  `getGroupRoleTable()`
  Return the table that holds the relation between groups and roles.
  `Iterator<Group>`
  `getGroups()`
  Get the set of `Group`s defined in this user database.
  `String`
  `getGroupTable()`
  Return the table that holds group data.
  `String`
  `getId()`
  Get the unique global identifier of this user database.
  `boolean`
  `getReadonly()`
  Return whether the user database is read only.
  `String`
  `getRoleAndGroupDescriptionCol()`
  Return the column name used for role and group descriptions.
  `String`
  `getRoleNameCol()`
  Return the column in the user role table that names a role.
  `Iterator<Role>`
  `getRoles()`
  Get the set of `Role`s defined in this user database.
  `String`
  `getRoleTable()`
  Return the table that holds role data.
  `String`
  `getUserCredCol()`
  Return the column in the user table that holds the user's credentials.
  `String`
  `getUserFullNameCol()`
  Return the column name used for user full names.
  `String`
  `getUserGroupTable()`
  Return the table that holds the relation between users and groups.
  `String`
  `getUserNameCol()`
  Return the column in the user table that holds the user's name.
  `String`
  `getUserRoleTable()`
  Return the table that holds the relation between user's and roles.
  `Iterator<User>`
  `getUsers()`
  Get the set of `User`s defined in this user database.
  `String`
  `getUserTable()`
  Return the table that holds user data.
  `boolean`
  `isAvailable()`
  Is the database available.
  `protected boolean`
  `isGroupStoreDefined()`
  Only use groups if the tables are fully defined.
  `protected boolean`
  `isRoleStoreDefined()`
  Only use roles if the tables are fully defined.
  `protected boolean`
  `isUserRoleStoreDefined()`
  User role relationship storage.
  `protected boolean`
  `isUserStoreDefined()`
  User storage is mandatory.
  `void`
  `modifiedGroup(Group group)`
  Signal the specified `Group` from this user database has been modified.
  `void`
  `modifiedRole(Role role)`
  Signal the specified `Role` from this user database has been modified.
  `void`
  `modifiedUser(User user)`
  Signal the specified `User` from this user database has been modified.
  `void`
  `open()`
  Initialize access to this user database.
  `protected Connection`
  `openConnection()`
  Open the specified database connection.
  `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.
  `protected void`
  `saveInternal(Connection dbConnection)`
  Save all pending changes to the database using the provided connection.
  `void`
  `setDataSourceName(String dataSourceName)`
  Set the name of the JNDI JDBC DataSource.
  `void`
  `setGroupNameCol(String groupNameCol)`
  Set the column name used for group names.
  `void`
  `setGroupRoleTable(String groupRoleTable)`
  Set the table that holds the relation between groups and roles.
  `void`
  `setGroupTable(String groupTable)`
  Set the table that holds group data.
  `void`
  `setReadonly(boolean readonly)`
  Set whether the user database is read only.
  `void`
  `setRoleAndGroupDescriptionCol(String roleAndGroupDescriptionCol)`
  Set the column name used for role and group descriptions.
  `void`
  `setRoleNameCol(String roleNameCol)`
  Set the column in the user role table that names a role.
  `void`
  `setRoleTable(String roleTable)`
  Set the table that holds role data.
  `void`
  `setUserCredCol(String userCredCol)`
  Set the column in the user table that holds the user's credentials.
  `void`
  `setUserFullNameCol(String userFullNameCol)`
  Set the column name used for user full names.
  `void`
  `setUserGroupTable(String userGroupTable)`
  Set the table that holds the relation between users and groups.
  `void`
  `setUserNameCol(String userNameCol)`
  Set the column in the user table that holds the user's name.
  `void`
  `setUserRoleTable(String userRoleTable)`
  Set the table that holds the relation between user's and roles.
  `void`
  `setUserTable(String userTable)`
  Set the table that holds user data.

  ### Methods inherited from class SparseUserDatabase

  `isSparse`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface UserDatabase

  `backgroundProcess`

- ## Field Details

  - ### dataSource

    protected final DataSource dataSource
    DataSource to use.

  - ### id

    protected final String id
    The unique global identifier of this user database.

  - ### createdUsers

    protected final ConcurrentHashMap<String,User> createdUsers
    Users that have been created but not yet persisted.

  - ### modifiedUsers

    protected final ConcurrentHashMap<String,User> modifiedUsers
    Users that have been modified but not yet persisted.

  - ### removedUsers

    protected final ConcurrentHashMap<String,User> removedUsers
    Users that have been removed but not yet persisted.

  - ### createdGroups

    protected final ConcurrentHashMap<String,Group> createdGroups
    Groups that have been created but not yet persisted.

  - ### modifiedGroups

    protected final ConcurrentHashMap<String,Group> modifiedGroups
    Groups that have been modified but not yet persisted.

  - ### removedGroups

    protected final ConcurrentHashMap<String,Group> removedGroups
    Groups that have been removed but not yet persisted.

  - ### createdRoles

    protected final ConcurrentHashMap<String,Role> createdRoles
    Roles that have been created but not yet persisted.

  - ### modifiedRoles

    protected final ConcurrentHashMap<String,Role> modifiedRoles
    Roles that have been modified but not yet persisted.

  - ### removedRoles

    protected final ConcurrentHashMap<String,Role> removedRoles
    Roles that have been removed but not yet persisted.

  - ### dataSourceName

    protected String dataSourceName
    The name of the JNDI JDBC DataSource

  - ### roleNameCol

    protected String roleNameCol
    The column in the user role table that names a role

  - ### roleAndGroupDescriptionCol

    protected String roleAndGroupDescriptionCol
    The column in the role and group tables for the description

  - ### groupNameCol

    protected String groupNameCol
    The column in the user group table that names a group

  - ### userCredCol

    protected String userCredCol
    The column in the user table that holds the user's credentials

  - ### userFullNameCol

    protected String userFullNameCol
    The column in the user table that holds the user's full name

  - ### userNameCol

    protected String userNameCol
    The column in the user table that holds the user's name

  - ### userRoleTable

    protected String userRoleTable
    The table that holds the relation between users and roles

  - ### userGroupTable

    protected String userGroupTable
    The table that holds the relation between users and groups

  - ### groupRoleTable

    protected String groupRoleTable
    The table that holds the relation between groups and roles

  - ### userTable

    protected String userTable
    The table that holds user data.

  - ### groupTable

    protected String groupTable
    The table that holds group data.

  - ### roleTable

    protected String roleTable
    The table that holds role data.

  - ### readonly

    protected boolean readonly
    A flag, indicating if the user database is read only.

- ## Constructor Details

  - ### DataSourceUserDatabase

    public DataSourceUserDatabase(DataSource dataSource, String id)
    Create a new DataSourceUserDatabase.
    Parameters:
      `dataSource` - The data source to use
      `id` - The unique identifier for this user database

- ## Method Details

  - ### getDataSourceName

    public String getDataSourceName()
    Return the name of the JNDI JDBC DataSource.
    Returns:
      the DataSource name

  - ### setDataSourceName

    public void setDataSourceName(String dataSourceName)
    Set the name of the JNDI JDBC DataSource.
    Parameters:
      `dataSourceName` - the name of the JNDI JDBC DataSource to use

  - ### getRoleNameCol

    public String getRoleNameCol()
    Return the column in the user role table that names a role.
    Returns:
      the role name column

  - ### setRoleNameCol

    public void setRoleNameCol(String roleNameCol)
    Set the column in the user role table that names a role.
    Parameters:
      `roleNameCol` - The column name to use

  - ### getUserCredCol

    public String getUserCredCol()
    Return the column in the user table that holds the user's credentials.
    Returns:
      the credentials column

  - ### setUserCredCol

    public void setUserCredCol(String userCredCol)
    Set the column in the user table that holds the user's credentials.
    Parameters:
      `userCredCol` - The column name to use

  - ### getUserNameCol

    public String getUserNameCol()
    Return the column in the user table that holds the user's name.
    Returns:
      the user name column

  - ### setUserNameCol

    public void setUserNameCol(String userNameCol)
    Set the column in the user table that holds the user's name.
    Parameters:
      `userNameCol` - The column name to use

  - ### getUserRoleTable

    public String getUserRoleTable()
    Return the table that holds the relation between user's and roles.
    Returns:
      the user-role table name

  - ### setUserRoleTable

    public void setUserRoleTable(String userRoleTable)
    Set the table that holds the relation between user's and roles.
    Parameters:
      `userRoleTable` - The table name to use

  - ### getUserTable

    public String getUserTable()
    Return the table that holds user data.
    Returns:
      the user table name

  - ### setUserTable

    public void setUserTable(String userTable)
    Set the table that holds user data.
    Parameters:
      `userTable` - The table name to use

  - ### getRoleAndGroupDescriptionCol

    public String getRoleAndGroupDescriptionCol()
    Return the column name used for role and group descriptions.
    Returns:
      the role and group description column name

  - ### setRoleAndGroupDescriptionCol

    public void setRoleAndGroupDescriptionCol(String roleAndGroupDescriptionCol)
    Set the column name used for role and group descriptions.
    Parameters:
      `roleAndGroupDescriptionCol` - the column name to use

  - ### getGroupNameCol

    public String getGroupNameCol()
    Return the column name used for group names.
    Returns:
      the group name column

  - ### setGroupNameCol

    public void setGroupNameCol(String groupNameCol)
    Set the column name used for group names.
    Parameters:
      `groupNameCol` - the column name to use

  - ### getUserFullNameCol

    public String getUserFullNameCol()
    Return the column name used for user full names.
    Returns:
      the user full name column

  - ### setUserFullNameCol

    public void setUserFullNameCol(String userFullNameCol)
    Set the column name used for user full names.
    Parameters:
      `userFullNameCol` - the column name to use

  - ### getUserGroupTable

    public String getUserGroupTable()
    Return the table that holds the relation between users and groups.
    Returns:
      the user-group table name

  - ### setUserGroupTable

    public void setUserGroupTable(String userGroupTable)
    Set the table that holds the relation between users and groups.
    Parameters:
      `userGroupTable` - the table name to use

  - ### getGroupRoleTable

    public String getGroupRoleTable()
    Return the table that holds the relation between groups and roles.
    Returns:
      the group-role table name

  - ### setGroupRoleTable

    public void setGroupRoleTable(String groupRoleTable)
    Set the table that holds the relation between groups and roles.
    Parameters:
      `groupRoleTable` - the table name to use

  - ### getGroupTable

    public String getGroupTable()
    Return the table that holds group data.
    Returns:
      the group table name

  - ### setGroupTable

    public void setGroupTable(String groupTable)
    Set the table that holds group data.
    Parameters:
      `groupTable` - the table name to use

  - ### getRoleTable

    public String getRoleTable()
    Return the table that holds role data.
    Returns:
      the role table name

  - ### setRoleTable

    public void setRoleTable(String roleTable)
    Set the table that holds role data.
    Parameters:
      `roleTable` - the table name to use

  - ### getReadonly

    public boolean getReadonly()
    Return whether the user database is read only.
    Returns:
      true if the database is read only

  - ### setReadonly

    public void setReadonly(boolean readonly)
    Set whether the user database is read only.
    Parameters:
      `readonly` - true to make the database read only

  - ### getId

    public String getId()
    Description copied from interface: `UserDatabase`
    Get the unique global identifier of this user database.
    Returns:
      the unique global identifier of this user database.

  - ### getGroups

    public Iterator<Group> getGroups()
    Description copied from interface: `UserDatabase`
    Get the set of `Group`s defined in this user database.
    Returns:
      the set of `Group`s defined in this user database.

  - ### getRoles

    public Iterator<Role> getRoles()
    Description copied from interface: `UserDatabase`
    Get the set of `Role`s defined in this user database.
    Returns:
      the set of `Role`s defined in this user database.

  - ### getUsers

    public Iterator<User> getUsers()
    Description copied from interface: `UserDatabase`
    Get the set of `User`s defined in this user database.
    Returns:
      the set of `User`s defined in this user database.

  - ### close

    public void close() throws Exception
    Description copied from interface: `UserDatabase`
    Finalize access to this user database.
    Throws:
      `Exception` - if any exception is thrown during closing

  - ### createGroup

    public Group createGroup(String groupname, String description)
    Description copied from interface: `UserDatabase`
    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

    public Role createRole(String rolename, String description)
    Description copied from interface: `UserDatabase`
    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

    public User createUser(String username, String password, String fullName)
    Description copied from interface: `UserDatabase`
    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

    public Group findGroup(String groupname)
    Description copied from interface: `UserDatabase`
    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`.

  - ### findGroupInternal

    public Group findGroupInternal(Connection dbConnection, String groupName)
    Find a group by name using the provided database connection.
    Parameters:
      `dbConnection` - The database connection to use
      `groupName` - The name of the group to find
    Returns:
      the group, or null if not found

  - ### findRole

    public Role findRole(String rolename)
    Description copied from interface: `UserDatabase`
    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`.

  - ### findRoleInternal

    public Role findRoleInternal(Connection dbConnection, String roleName)
    Find a role by name using the provided database connection.
    Parameters:
      `dbConnection` - The database connection to use
      `roleName` - The name of the role to find
    Returns:
      the role, or null if not found

  - ### findUser

    public User findUser(String username)
    Description copied from interface: `UserDatabase`
    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`.

  - ### findUserInternal

    @Deprecated public User findUserInternal(Connection dbConnection, String userName)
    Deprecated.
    Will be made private in Tomcat 12
    Find a user by name using the provided database connection.
    Parameters:
      `dbConnection` - The database connection to use
      `userName` - The name of the user to find
    Returns:
      the user, or null if not found

  - ### modifiedGroup

    public void modifiedGroup(Group group)
    Description copied from interface: `UserDatabase`
    Signal the specified `Group` from this user database has been modified.
    Parameters:
      `group` - The group that has been modified

  - ### modifiedRole

    public void modifiedRole(Role role)
    Description copied from interface: `UserDatabase`
    Signal the specified `Role` from this user database has been modified.
    Parameters:
      `role` - The role that has been modified

  - ### modifiedUser

    public void modifiedUser(User user)
    Description copied from interface: `UserDatabase`
    Signal the specified `User` from this user database has been modified.
    Parameters:
      `user` - The user that has been modified

  - ### open

    public void open() throws Exception
    Description copied from interface: `UserDatabase`
    Initialize access to this user database.
    Throws:
      `Exception` - if any exception is thrown during opening

  - ### removeGroup

    public void removeGroup(Group group)
    Description copied from interface: `UserDatabase`
    Remove the specified `Group` from this user database.
    Parameters:
      `group` - The group to be removed

  - ### removeRole

    public void removeRole(Role role)
    Description copied from interface: `UserDatabase`
    Remove the specified `Role` from this user database.
    Parameters:
      `role` - The role to be removed

  - ### removeUser

    public void removeUser(User user)
    Description copied from interface: `UserDatabase`
    Remove the specified `User` from this user database.
    Parameters:
      `user` - The user to be removed

  - ### save

    public void save() throws Exception
    Description copied from interface: `UserDatabase`
    Save any updated information to the persistent storage location for this user database.
    Throws:
      `Exception` - if any exception is thrown during saving

  - ### saveInternal

    protected void saveInternal(Connection dbConnection) throws SQLException
    Save all pending changes to the database using the provided connection.
    Parameters:
      `dbConnection` - The database connection to use
    Throws:
      `SQLException` - when a database error occurs

  - ### isAvailable

    public boolean isAvailable()
    Description copied from interface: `UserDatabase`
    Is the database available.
    Returns:
      true

  - ### isUserStoreDefined

    protected boolean isUserStoreDefined()
    User storage is mandatory.
    Returns:
      true when users are properly configured

  - ### isUserRoleStoreDefined

    protected boolean isUserRoleStoreDefined()
    User role relationship storage.
    Returns:
      true when user roles relationship are properly configured

  - ### isGroupStoreDefined

    protected boolean isGroupStoreDefined()
    Only use groups if the tables are fully defined.
    Returns:
      true when groups are used

  - ### isRoleStoreDefined

    protected boolean isRoleStoreDefined()
    Only use roles if the tables are fully defined.
    Returns:
      true when roles are used

  - ### openConnection

    protected Connection openConnection()
    Open the specified database connection.
    Returns:
      Connection to the database

  - ### closeConnection

    protected void closeConnection(Connection dbConnection)
    Close the specified database connection.
    Parameters:
      `dbConnection` - The connection to be closed