Top Description Inners Fields Constructors Methods
org.apache.catalina.realm

public Class UserDatabaseRealm

extends RealmBase
Class Inheritance
Imports
java.io.ObjectStreamException, java.security.Principal, java.util.Arrays, .HashSet, .Iterator, .Set, javax.naming.Context, org.apache.catalina.Group, .LifecycleException, .Role, .Server, .User, .UserDatabase, org.apache.naming.ContextBindings, org.apache.tomcat.util.ExceptionUtils
Implementation of org.apache.catalina.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.
Author
Craig R. McClanahan
Since
4.1

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
UserDatabaseRealm.UserDatabasePrincipal

Field Summary

Modifier and TypeField and Description
protected volatile UserDatabase
database

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

private final Object
databaseLock

private boolean
localJndiResource

Obtain the UserDatabase from the context (rather than global) JNDI.

protected String
resourceName

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

private boolean
useStaticPrincipal

Use a static principal disconnected from the database.

Inherited from org.apache.catalina.realm.RealmBase:
allRolesModecontainercontainerLogrealmPathsmstripRealmForGsssupportUSER_ATTRIBUTES_DELIMITERUSER_ATTRIBUTES_WILDCARDuserAttributesuserAttributesListvalidatex509UsernameRetrieverx509UsernameRetrieverClassName

Constructor Summary

AccessConstructor and Description
public
UserDatabaseRealm()

Method Summary

Modifier and TypeMethod and Description
public void
backgroundProcess()

Overrides org.apache.catalina.realm.RealmBase.backgroundProcess.

Implements org.apache.catalina.Realm.backgroundProcess.

Calls UserDatabase#backgroundProcess().

public boolean

Returns:

true if a local JNDI context will be used, false if the the global JNDI context will be used
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
The user name
username)

Implements abstract org.apache.catalina.realm.RealmBase.getPassword.

Get the password for the specified user.

protected Principal
getPrincipal(String
The user name
username)

Implements abstract org.apache.catalina.realm.RealmBase.getPrincipal.

Get the principal associated with the specified user.

public String

Returns:

the global JNDI name of the UserDatabase resource we will be using.
getResourceName()

public static String[]
getRoles(User user)

private UserDatabase
getUserDatabase()

public boolean

Returns:

the useStaticPrincipal flag
getUseStaticPrincipal()

public boolean
isAvailable()

Overrides default org.apache.catalina.Realm.isAvailable.

Return the availability of the realm for authentication.

public void
setLocalJndiResource(boolean
true to use a local JNDI context, false to use the global JNDI context
localJndiResource)

Configure whether this Realm obtains the associated UserDatabase from the global JNDI context or a local (web application) JNDI context.

public void
setResourceName(String
The new global JNDI name
resourceName)

Set the global JNDI name of the UserDatabase resource we will be using.

public void
setUseStaticPrincipal(boolean
the new value
useStaticPrincipal)

Allows using a static principal disconnected from the user database.

protected void
startInternal()

Overrides org.apache.catalina.realm.RealmBase.startInternal.

Prepare for the beginning of active use of the public methods of this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

protected void
stopInternal()

Overrides org.apache.catalina.realm.RealmBase.stopInternal.

Gracefully terminate the active use of the public methods of this component and implement the requirements of org.apache.catalina.util.LifecycleBase#stopInternal().

Inherited from org.apache.catalina.realm.RealmBase:
addPropertyChangeListenerauthenticateauthenticateauthenticateauthenticateauthenticateauthenticateauthenticatefindSecurityConstraintsgetAllRolesModegetContainergetCredentialHandlergetDigestgetDigestgetDomainInternalgetObjectNameKeyPropertiesgetPrincipalgetPrincipalgetRealmPathgetRealmSuffixgetServergetTransportGuaranteeRedirectStatusgetUserAttributesgetValidategetX509UsernameRetrieverClassNamehasMessageDigesthasResourcePermissionhasRolehasRoleInternalhasUserDataPermissioninitInternalisStripRealmForGssmainparseUserAttributesremovePropertyChangeListenersetAllRolesModesetContainersetCredentialHandlersetRealmPathsetStripRealmForGsssetTransportGuaranteeRedirectStatussetUserAttributessetValidatesetX509UsernameRetrieverClassNametoString

Field Detail

databaseback to summary
protected volatile UserDatabase database

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

databaseLockback to summary
private final Object databaseLock
localJndiResourceback to summary
private boolean localJndiResource

Obtain the UserDatabase from the context (rather than global) JNDI.

resourceNameback to summary
protected String resourceName

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

useStaticPrincipalback to summary
private boolean useStaticPrincipal

Use a static principal disconnected from the database. This prevents live updates to users and roles having an effect on authenticated principals, but reduces use of the database.

Constructor Detail

UserDatabaseRealmback to summary
public UserDatabaseRealm()

Method Detail

backgroundProcessback to summary
public void backgroundProcess()

Overrides org.apache.catalina.realm.RealmBase.backgroundProcess.

Implements org.apache.catalina.Realm.backgroundProcess.

Calls UserDatabase#backgroundProcess().

Annotations
@Override
getLocalJndiResourceback to summary
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:boolean

true if a local JNDI context will be used, false if the the global JNDI context will be used

getPasswordback to summary
protected String getPassword(String username)

Implements abstract org.apache.catalina.realm.RealmBase.getPassword.

Doc from org.apache.catalina.realm.RealmBase.getPassword.

Get the password for the specified user.

Parameters
username:String

The user name

Returns:String

the password associated with the given principal's user name.

Annotations
@Override
getPrincipalback to summary
protected Principal getPrincipal(String username)

Implements abstract org.apache.catalina.realm.RealmBase.getPrincipal.

Doc from org.apache.catalina.realm.RealmBase.getPrincipal.

Get the principal associated with the specified user.

Parameters
username:String

The user name

Returns:Principal

the Principal associated with the given user name.

Annotations
@Override
getResourceNameback to summary
public String getResourceName()
Returns:String

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

getRolesback to summary
public static String[] getRoles(User user)
getUserDatabaseback to summary
private UserDatabase getUserDatabase()
getUseStaticPrincipalback to summary
public boolean getUseStaticPrincipal()
Returns:boolean

the useStaticPrincipal flag

isAvailableback to summary
public boolean isAvailable()

Overrides default org.apache.catalina.Realm.isAvailable.

Doc from org.apache.catalina.Realm.isAvailable.

Return the availability of the realm for authentication.

Returns:boolean

true if the realm is able to perform authentication

Annotations
@Override
setLocalJndiResourceback to summary
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:boolean

true to use a local JNDI context, false to use the global JNDI context

setResourceNameback to summary
public void setResourceName(String resourceName)

Set the global JNDI name of the UserDatabase resource we will be using.

Parameters
resourceName:String

The new global JNDI name

setUseStaticPrincipalback to summary
public void setUseStaticPrincipal(boolean useStaticPrincipal)

Allows using a static principal disconnected from the user database.

Parameters
useStaticPrincipal:boolean

the new value

startInternalback to summary
protected void startInternal() throws LifecycleException

Overrides org.apache.catalina.realm.RealmBase.startInternal.

Doc from org.apache.catalina.realm.RealmBase.startInternal.

Prepare for the beginning of active use of the public methods of this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

Annotations
@Override
Exceptions
LifecycleException:
if this component detects a fatal error that prevents this component from being used
stopInternalback to summary
protected void stopInternal() throws LifecycleException

Overrides org.apache.catalina.realm.RealmBase.stopInternal.

Doc from org.apache.catalina.realm.RealmBase.stopInternal.

Gracefully terminate the active use of the public methods of this component and implement the requirements of org.apache.catalina.util.LifecycleBase#stopInternal().

Annotations
@Override
Exceptions
LifecycleException:
if this component detects a fatal error that needs to be reported
org.apache.catalina.realm back to summary

public final Class UserDatabaseRealm.UserDatabasePrincipal

extends GenericPrincipal
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final transient UserDatabase
database

private static final long
serialVersionUID

Hides org.apache.catalina.realm.GenericPrincipal.serialVersionUID.

Inherited from org.apache.catalina.realm.GenericPrincipal:
attributesgssCredentialloginContextnamerolesuserPrincipal

Constructor Summary

AccessConstructor and Description
public
UserDatabasePrincipal(User user, UserDatabase database)

Method Summary

Modifier and TypeMethod and Description
public String[]
getRoles()

Overrides org.apache.catalina.realm.GenericPrincipal.getRoles.

public boolean
hasRole(String
Role to be tested
role)

Overrides org.apache.catalina.realm.GenericPrincipal.hasRole.

Does the user represented by this Principal possess the specified role?

private Object

Returns:

The object to serialize instead of this object
writeReplace()

Hides org.apache.catalina.realm.GenericPrincipal.writeReplace.

Magic method from java.io.Serializable.

Inherited from org.apache.catalina.realm.GenericPrincipal:
getAttributegetAttributeNamesgetGssCredentialgetNamegetUserPrincipallogoutsetGssCredentialtoString

Field Detail

databaseback to summary
private final transient UserDatabase database
serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.catalina.realm.GenericPrincipal.serialVersionUID.

Constructor Detail

UserDatabasePrincipalback to summary
public UserDatabasePrincipal(User user, UserDatabase database)

Method Detail

getRolesback to summary
public String[] getRoles()

Overrides org.apache.catalina.realm.GenericPrincipal.getRoles.

Annotations
@Override
hasRoleback to summary
public boolean hasRole(String role)

Overrides org.apache.catalina.realm.GenericPrincipal.hasRole.

Doc from org.apache.catalina.realm.GenericPrincipal.hasRole.

Does the user represented by this Principal possess the specified role?

Parameters
role:String

Role to be tested

Returns:boolean

true if this Principal has been assigned the given role, otherwise false

Annotations
@Override
writeReplaceback to summary
private Object writeReplace() throws ObjectStreamException

Hides org.apache.catalina.realm.GenericPrincipal.writeReplace.

Magic method from java.io.Serializable.

Returns:Object

The object to serialize instead of this object

Exceptions
ObjectStreamException:
Not thrown by this implementation