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, 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.

Version:

$Id: JDBCRealm.java 1361770 2012-07-15 19:38:51Z markt $

Author:

Craig R. McClanahan, Carson McDonald, Ignacio Ortega

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase

RealmBase.AllRolesMode

Field Summary

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	info Descriptive information about this Realm implementation.
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, 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

JDBCRealm()

Method Summary

Principal	authenticate(Connection dbConnection, String username, String credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
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() Return the username to use to connect to the database.
String	getConnectionPassword() Return the password to use to connect to the database.
String	getConnectionURL() Return the URL to use to connect to the database.
String	getDriverName() Return the JDBC driver that will be used.
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	getRoleNameCol() Return the column in the user role table that names a role.
protected ArrayList<String>	getRoles(String username) Return the roles associated with the gven user name.
String	getUserCredCol() Return the column in the user table that holds the user's credentials.
String	getUserNameCol() Return the column in the user table that holds the user's name.
String	getUserRoleTable() Return the table that holds the relation between user's and roles.
String	getUserTable() Return the table that holds user data..
protected Connection	open() Open (if necessary) and return a database connection for use by this Realm.
protected void	release(Connection dbConnection) Deprecated. Unused
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, backgroundProcess, digest, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getDigest, getDigest, getDigestCharset, getDigestEncoding, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, 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

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.

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

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

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

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

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

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

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

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

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

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

Return the table that holds user data..

setUserTable

public void setUserTable(String userTable)

Set the table that holds user data.

Parameters:

userTable - The table name

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

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

authenticate

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

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

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

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

Throws:

SQLException - if a database error occurs

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

getRoles

protected ArrayList<String> getRoles(String username)

Return the roles associated with the gven user name.

open

protected Connection open()
                   throws SQLException

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

Throws:

SQLException - if a database error occurs

release

@Deprecated
protected void release(Connection dbConnection)

Deprecated. Unused

Release our use of this connection so that it can be recycled.

Parameters:

dbConnection - The connection to be released

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

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