org.apache.catalina.realm

Class JDBCRealm

java.lang.Object

org.apache.catalina.util.LifecycleBase

org.apache.catalina.util.LifecycleMBeanBase

org.apache.catalina.realm.RealmBase

org.apache.catalina.realm.JDBCRealm

All Implemented Interfaces:

MBeanRegistration, JmxEnabled, Lifecycle, Realm

public class JDBCRealm
extends RealmBase

Implementation of Realm that works with any JDBC supported database. See the JDBCRealm.howto for more details on how to set up the database and for configuration options.

For a Realm implementation that supports connection pooling and doesn't require synchronisation of authenticate(), getPassword(), roles() and getPrincipal() or the ugly connection logic use the DataSourceRealm.

Author:

Craig R. McClanahan, Carson McDonald, Ignacio Ortega

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 String	connectionName The connection username to use when trying to connect to the database.
protected String	connectionPassword The connection URL to use when trying to connect to the database.
protected String	connectionURL The connection URL to use when trying to connect to the database.
protected Connection	dbConnection The connection to the database.
protected Driver	driver Instance of the JDBC Driver class we use as a connection factory.
protected String	driverName The JDBC driver to use.
protected static String	name Descriptive information about this Realm implementation.
protected PreparedStatement	preparedCredentials The PreparedStatement to use for authenticating users.
protected PreparedStatement	preparedRoles The PreparedStatement to use for identifying the roles for a specified user.
protected String	roleNameCol The column in the user role table that names a role
protected String	userCredCol The column in the user table that holds the user's credentials
protected String	userNameCol The column in the user table that holds the user's name
protected String	userRoleTable The table that holds the relation between user's and roles
protected String	userTable The table that holds user data.

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
JDBCRealm()

Method Summary

Modifier and Type	Method and Description
Principal	authenticate(Connection dbConnection, String username, String credentials) Attempt to authenticate the user with the provided credentials.
Principal	authenticate(String username, String credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
protected void	close(Connection dbConnection) Close the specified database connection.
protected PreparedStatement	credentials(Connection dbConnection, String username) Return a PreparedStatement configured to perform the SELECT required to retrieve user credentials for the specified username.
String	getConnectionName()
String	getConnectionPassword()
String	getConnectionURL()
String	getDriverName()
protected String	getName()
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	getRoleNameCol()
protected ArrayList<String>	getRoles(String username) Return the roles associated with the given user name.
String	getUserCredCol()
String	getUserNameCol()
String	getUserRoleTable()
String	getUserTable()
protected Connection	open() Open (if necessary) and return a database connection for use by this Realm.
protected PreparedStatement	roles(Connection dbConnection, String username) Return a PreparedStatement configured to perform the SELECT required to retrieve user roles for the specified username.
void	setConnectionName(String connectionName) Set the username to use to connect to the database.
void	setConnectionPassword(String connectionPassword) Set the password to use to connect to the database.
void	setConnectionURL(String connectionURL) Set the URL to use to connect to the database.
void	setDriverName(String driverName) Set the JDBC driver that will be used.
void	setRoleNameCol(String roleNameCol) Set the column in the user role table that names a role.
void	setUserCredCol(String userCredCol) Set the column in the user table that holds the user's credentials.
void	setUserNameCol(String userNameCol) Set the column in the user table that holds the user's name.
void	setUserRoleTable(String userRoleTable) Set the table that holds the relation between user's and roles.
void	setUserTable(String userTable) Set the table that holds user data.
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, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getRoles, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, 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

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

connectionName

protected String connectionName

The connection username to use when trying to connect to the database.

connectionPassword

protected String connectionPassword

The connection URL to use when trying to connect to the database.

connectionURL

protected String connectionURL

The connection URL to use when trying to connect to the database.

dbConnection

protected Connection dbConnection

The connection to the database.

driver

protected Driver driver

Instance of the JDBC Driver class we use as a connection factory.

driverName

protected String driverName

The JDBC driver to use.

name

protected static final String name

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

preparedCredentials

protected PreparedStatement preparedCredentials

The PreparedStatement to use for authenticating users.

preparedRoles

protected PreparedStatement preparedRoles

The PreparedStatement to use for identifying the roles for a specified user.

roleNameCol

protected String roleNameCol

The column in the user role table that names a role

userCredCol

protected String userCredCol

The column in the user table that holds the user's credentials

userNameCol

protected String userNameCol

The column in the user table that holds the user's name

userRoleTable

protected String userRoleTable

The table that holds the relation between user's and roles

userTable

protected String userTable

The table that holds user data.

Constructor Detail

JDBCRealm

public JDBCRealm()

Method Detail

getConnectionName

public String getConnectionName()

Returns:

the username to use to connect to the database.

setConnectionName

public void setConnectionName(String connectionName)

Set the username to use to connect to the database.

Parameters:

connectionName - Username

getConnectionPassword

public String getConnectionPassword()

Returns:

the password to use to connect to the database.

setConnectionPassword

public void setConnectionPassword(String connectionPassword)

Set the password to use to connect to the database.

Parameters:

connectionPassword - User password

getConnectionURL

public String getConnectionURL()

Returns:

the URL to use to connect to the database.

setConnectionURL

public void setConnectionURL(String connectionURL)

Set the URL to use to connect to the database.

Parameters:

connectionURL - The new connection URL

getDriverName

public String getDriverName()

Returns:

the JDBC driver that will be used.

setDriverName

public void setDriverName(String driverName)

Set the JDBC driver that will be used.

Parameters:

driverName - The driver name

getRoleNameCol

public String getRoleNameCol()

Returns:

the column in the user role table that names a role.

setRoleNameCol

public void setRoleNameCol(String roleNameCol)

Set the column in the user role table that names a role.

Parameters:

roleNameCol - The column name

getUserCredCol

public String getUserCredCol()

Returns:

the column in the user table that holds the user's credentials.

setUserCredCol

public void setUserCredCol(String userCredCol)

Set the column in the user table that holds the user's credentials.

Parameters:

userCredCol - The column name

getUserNameCol

public String getUserNameCol()

Returns:

the column in the user table that holds the user's name.

setUserNameCol

public void setUserNameCol(String userNameCol)

Set the column in the user table that holds the user's name.

Parameters:

userNameCol - The column name

getUserRoleTable

public String getUserRoleTable()

Returns:

the table that holds the relation between user's and roles.

setUserRoleTable

public void setUserRoleTable(String userRoleTable)

Set the table that holds the relation between user's and roles.

Parameters:

userRoleTable - The table name

getUserTable

public String getUserTable()

Returns:

the table that holds user data..

setUserTable

public void setUserTable(String userTable)

Set the table that holds user data.

Parameters:

userTable - The table name

authenticate

public Principal authenticate(String username,
                              String credentials)

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null. If there are any errors with the JDBC connection, executing the query or anything we return null (don't authenticate). This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.

Specified by:

authenticate in interface Realm

Overrides:

authenticate in class RealmBase

Parameters:

username - Username of the Principal to look up

credentials - Password or other credentials to use in authenticating this username

Returns:

the associated principal, or null if there is none.

authenticate

public Principal authenticate(Connection dbConnection,
                              String username,
                              String credentials)

Attempt to authenticate the user with the provided credentials.

Parameters:

dbConnection - The database connection to be used

username - Username of the Principal to look up

credentials - Password or other credentials to use in authenticating this username

Returns:

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

close

protected void close(Connection dbConnection)

Close the specified database connection.

Parameters:

dbConnection - The connection to be closed

credentials

protected PreparedStatement credentials(Connection dbConnection,
                                        String username)
                                 throws SQLException

Return a PreparedStatement configured to perform the SELECT required to retrieve user credentials for the specified username.

Parameters:

dbConnection - The database connection to be used

username - Username for which credentials should be retrieved

Returns:

the prepared statement

Throws:

SQLException - if a database error occurs

getName

protected String getName()

Specified by:

getName in class RealmBase

Returns:

a short name for this Realm implementation.

getPassword

protected String getPassword(String username)

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.

getPrincipal

protected Principal getPrincipal(String username)

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.

getRoles

protected ArrayList<String> getRoles(String username)

Return the roles associated with the given user name.

Parameters:

username - The user name

Returns:

an array list of the role names

open

protected Connection open()
                   throws SQLException

Open (if necessary) and return a database connection for use by this Realm.

Returns:

the opened connection

Throws:

SQLException - if a database error occurs

roles

protected PreparedStatement roles(Connection dbConnection,
                                  String username)
                           throws SQLException

Return a PreparedStatement configured to perform the SELECT required to retrieve user roles for the specified username.

Parameters:

dbConnection - The database connection to be used

username - Username for which roles should be retrieved

Returns:

the prepared statement

Throws:

SQLException - if a database error occurs

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