Package 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:
  `javax.management.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
`static 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
`protected UserDatabase` `database` The `UserDatabase` we will use to authenticate users and identify associated roles.
`protected java.lang.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
`UserDatabaseRealm()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`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 java.lang.String` `getPassword​(java.lang.String username)` Return the password associated with the given principal's user name.
`protected java.security.Principal` `getPrincipal​(java.lang.String username)` Return the Principal associated with the given user name.
`java.lang.String` `getResourceName()`
`static java.lang.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​(java.lang.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, getRoles, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasRoleInternal, hasUserDataPermission, initInternal, 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, 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.

#### resourceName

    protected java.lang.String resourceName

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

### Constructor Detail

#### UserDatabaseRealm

    public UserDatabaseRealm()

### Method Detail

#### getResourceName

    public java.lang.String getResourceName()

Returns:
  the global JNDI name of the `UserDatabase` resource we will be using.

#### setResourceName

    public void setResourceName​(java.lang.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 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()

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 java.lang.String getPassword​(java.lang.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.

#### getRoles

    public static java.lang.String[] getRoles​(User user)

#### getPrincipal

    protected java.security.Principal getPrincipal​(java.lang.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

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