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:
  `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, authenticate, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, 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 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 user name
Returns:
  the password associated with the given principal's user name.

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