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, Lifecycle, Realm

    public class UserDatabaseRealm
    extends RealmBase

Implementation of `Realm` that is based on an implementation of `UserDatabase` made available through the global JNDI resources configured for this instance of Catalina. Set the `resourceName` parameter to the global 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`

### Field Summary

Fields
`protected UserDatabase` `database` The `UserDatabase` we will use to authenticate users and identify associated roles.
`protected static String` `info` Descriptive information about this Realm implementation.
`protected static String` `name` Descriptive information about this Realm implementation.
`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, digest, digestEncoding, md, md5Encoder, md5Helper, 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
`String` `getInfo()` Return descriptive information about this Realm implementation and the corresponding version number, in the format `<description>/<version>`.
`protected String` `getName()` Return a short name for this Realm implementation.
`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()` Return the global JNDI name of the `UserDatabase` resource we will be using.
`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` `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, backgroundProcess, compareCredentials, digest, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getDigest, getDigest, getDigestCharset, getDigestEncoding, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasUserDataPermission, initInternal, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setContainer, setDigest, setDigestEncoding, setRealmPath, setStripRealmForGss, 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, init, removeLifecycleListener, setState, setState, start, stop`

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

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

### Field Detail

#### database

    protected UserDatabase database

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

#### info

    protected static final String info

Descriptive information about this Realm implementation.

See Also:
  Constant Field Values

#### name

    protected static final String name

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

#### getInfo

    public String getInfo()

Return descriptive information about this Realm implementation and the corresponding version number, in the format `<description>/<version>`.

Specified by:
  `getInfo` in interface `Realm`
Overrides:
  `getInfo` in class `RealmBase`

#### getResourceName

    public String getResourceName()

Return 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

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

#### getName

    protected String getName()

Return a short name for this Realm implementation.

Specified by:
  `getName` 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`

#### getPrincipal

    protected Principal getPrincipal(String username)

Return the Principal associated with the given user name.

Specified by:
  `getPrincipal` in class `RealmBase`

#### startInternal

    protected void startInternal()
                          throws LifecycleException

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