UserDatabaseRealm (Apache Tomcat 11.0.8 API Documentation)
Description: declaration: package: org.apache.catalina.realm, class: UserDatabaseRealm

# Class UserDatabaseRealm

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.realm.RealmBase
org.apache.catalina.realm.UserDatabaseRealm

All Implemented Interfaces:
  `MBeanRegistration`, `Contained`, `JmxEnabled`, `Lifecycle`, `Realm`

public class UserDatabaseRealm extends RealmBase
Implementation of `Realm` that is based on an implementation of `UserDatabase` made available through the JNDI resources configured for this instance of Catalina. Set the `resourceName` parameter to the JNDI resources name for the configured instance of `UserDatabase` that we should consult.

Since:
  4.1
Author:
  Craig R. McClanahan

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `UserDatabaseRealm.UserDatabasePrincipal`

  ### Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase

  `RealmBase.AllRolesMode`

  ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected UserDatabase`
  `database`
  The `UserDatabase` we will use to authenticate users and identify associated roles.
  `protected String`
  `resourceName`
  The global JNDI name of the `UserDatabase` resource we will be utilizing.

  ### Fields inherited from class org.apache.catalina.realm.RealmBase

  `allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassName`

  ### Fields inherited from interface org.apache.catalina.Lifecycle

  `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UserDatabaseRealm()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `backgroundProcess()`
  Calls `UserDatabase.backgroundProcess()`.
  `boolean`
  `getLocalJndiResource()`
  Determines whether this Realm is configured to obtain the associated `UserDatabase` from the global JNDI context or a local (web application) JNDI context.
  `protected String`
  `getPassword(String username)`
  Get the password for the specified user.
  `protected Principal`
  `getPrincipal(String username)`
  Get the principal associated with the specified user.
  `String`
  `getResourceName()`
  `static String[]`
  `getRoles(User user)`
  `boolean`
  `getUseStaticPrincipal()`
  `boolean`
  `isAvailable()`
  Return the availability of the realm for authentication.
  `void`
  `setLocalJndiResource(boolean localJndiResource)`
  Configure whether this Realm obtains the associated `UserDatabase` from the global JNDI context or a local (web application) JNDI context.
  `void`
  `setResourceName(String resourceName)`
  Set the global JNDI name of the `UserDatabase` resource we will be using.
  `void`
  `setUseStaticPrincipal(boolean useStaticPrincipal)`
  Allows using a static principal disconnected from the user database.
  `protected void`
  `startInternal()`
  Prepare for the beginning of active use of the public methods of this component and implement the requirements of `LifecycleBase.startInternal()`.
  `protected void`
  `stopInternal()`
  Gracefully terminate the active use of the public methods of this component and implement the requirements of `LifecycleBase.stopInternal()`.

  ### Methods inherited from class org.apache.catalina.realm.RealmBase

  `addPropertyChangeListener, authenticate, authenticate, authenticate, authenticate, authenticate, authenticate, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getUserAttributes, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, parseUserAttributes, removePropertyChangeListener, setAllRolesMode, setContainer, setCredentialHandler, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setUserAttributes, setValidate, setX509UsernameRetrieverClassName, toString`

  ### Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

  `destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

  ### Methods inherited from class org.apache.catalina.util.LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### database

    protected volatile UserDatabase database
    The `UserDatabase` we will use to authenticate users and identify associated roles.

  - ### resourceName

    protected String resourceName
    The global JNDI name of the `UserDatabase` resource we will be utilizing.

- ## Constructor Details

  - ### UserDatabaseRealm

    public UserDatabaseRealm()

- ## Method Details

  - ### getResourceName

    public String getResourceName()
    Returns:
      the global JNDI name of the `UserDatabase` resource we will be using.

  - ### setResourceName

    public void setResourceName(String resourceName)
    Set the global JNDI name of the `UserDatabase` resource we will be using.
    Parameters:
      `resourceName` - The new global JNDI name

  - ### getUseStaticPrincipal

    public boolean getUseStaticPrincipal()
    Returns:
      the useStaticPrincipal flag

  - ### setUseStaticPrincipal

    public void setUseStaticPrincipal(boolean useStaticPrincipal)
    Allows using a static principal disconnected from the user database.
    Parameters:
      `useStaticPrincipal` - the new value

  - ### getLocalJndiResource

    public boolean getLocalJndiResource()
    Determines whether this Realm is configured to obtain the associated `UserDatabase` from the global JNDI context or a local (web application) JNDI context.
    Returns:
      `true` if a local JNDI context will be used, `false` if the global JNDI context will be used

  - ### setLocalJndiResource

    public void setLocalJndiResource(boolean localJndiResource)
    Configure whether this Realm obtains the associated `UserDatabase` from the global JNDI context or a local (web application) JNDI context.
    Parameters:
      `localJndiResource` - `true` to use a local JNDI context, `false` to use the global JNDI context

  - ### backgroundProcess

    public void backgroundProcess()
    Calls `UserDatabase.backgroundProcess()`.
    Specified by:
      `backgroundProcess` in interface `Realm`
    Overrides:
      `backgroundProcess` in class `RealmBase`

  - ### getPassword

    protected String getPassword(String username)
    Description copied from class: `RealmBase`
    Get the password for the specified user.
    Specified by:
      `getPassword` in class `RealmBase`
    Parameters:
      `username` - The username
    Returns:
      the password associated with the given principal's username.

  - ### getRoles

    public static String[] getRoles(User user)

  - ### getPrincipal

    protected Principal getPrincipal(String username)
    Description copied from class: `RealmBase`
    Get the principal associated with the specified user.
    Specified by:
      `getPrincipal` in class `RealmBase`
    Parameters:
      `username` - The username
    Returns:
      the Principal associated with the given username.

  - ### startInternal

    protected void startInternal() throws LifecycleException
    Description copied from class: `RealmBase`
    Prepare for the beginning of active use of the public methods of this component and implement the requirements of `LifecycleBase.startInternal()`.
    Overrides:
      `startInternal` in class `RealmBase`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  - ### stopInternal

    protected void stopInternal() throws LifecycleException
    Description copied from class: `RealmBase`
    Gracefully terminate the active use of the public methods of this component and implement the requirements of `LifecycleBase.stopInternal()`.
    Overrides:
      `stopInternal` in class `RealmBase`
    Throws:
      `LifecycleException` - if this component detects a fatal error that needs to be reported

  - ### isAvailable

    public boolean isAvailable()
    Description copied from interface: `Realm`
    Return the availability of the realm for authentication.
    Returns:
      `true` if the realm is able to perform authentication