org.apache.catalina.realm

## 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, GSSRealm, 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/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 and Description
    --- | ---
    `protected UserDatabase` | `database` The `UserDatabase` we will use to authenticate users and identify associated roles.
    `protected static String` | `name` Deprecated. This will be removed in Tomcat 9 onwards.
    `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, validate, x509UsernameRetriever, x509UsernameRetrieverClassName`

    - ### Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `mserver`

    - ### 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 and Description
    `UserDatabaseRealm()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `backgroundProcess()` Execute a periodic task, such as reloading, etc.
    `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` | `getName()` Deprecated.
    `protected String` | `getPassword(String username)` Return the password associated with the given principal's user name.
    `protected Principal` | `getPrincipal(String username)` Return the Principal associated with the given user name.
    `String` | `getResourceName()`
    `boolean` | `hasRole(Wrapper wrapper, Principal principal, String role)` Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.
    `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.
    `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, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getRoles, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRoleInternal, hasUserDataPermission, initInternal, isAvailable, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setContainer, setCredentialHandler, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setValidate, setX509UsernameRetrieverClassName, toString`

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

      `destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, 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 Detail

    - #### database

          protected volatile UserDatabase database

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

    - #### name

          @Deprecated
          protected static final String name

      Deprecated. This will be removed in Tomcat 9 onwards.
      Descriptive information about this Realm implementation.
      See Also:
        Constant Field Values

    - #### resourceName

          protected String resourceName

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

  - ### Constructor Detail

    - #### UserDatabaseRealm

          public UserDatabaseRealm()

  - ### Method Detail

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

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

    - #### hasRole

          public boolean hasRole(Wrapper wrapper,
                        Principal principal,
                        String role)

      Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`. This implementation returns `true` if the `User` has the role, or if any `Group` that the `User` is a member of has the role.
      Specified by:
        `hasRole` in interface `Realm`
      Overrides:
        `hasRole` in class `RealmBase`
      Parameters:
        `principal` - Principal for whom the role is to be checked
        `role` - Security role to be checked
        `wrapper` - wrapper context for evaluating role
      Returns:
        `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.

    - #### getName

          @Deprecated
          protected String getName()

      Deprecated.
      Specified by:
        `getName` in class `RealmBase`
      Returns:
        a short name for this Realm implementation, for use in log messages.

    - #### backgroundProcess

          public void backgroundProcess()

      Description copied from class: `RealmBase`
      Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.
      Specified by:
        `backgroundProcess` in interface `Realm`
      Overrides:
        `backgroundProcess` in class `RealmBase`

    - #### getPassword

          protected String getPassword(String username)

      Return the password associated with the given principal's user name.
      Specified by:
        `getPassword` in class `RealmBase`
      Parameters:
        `username` - The user name
      Returns:
        the password associated with the given principal's user name.

    - #### getPrincipal

          protected Principal getPrincipal(String username)

      Return the Principal associated with the given user name.
      Specified by:
        `getPrincipal` in class `RealmBase`
      Parameters:
        `username` - The user name
      Returns:
        the Principal associated with the given user name.

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

      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

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.