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

public Class DataSourceRealm

extends RealmBase
Class Inheritance
Imports
java.security.Principal, java.sql.Connection, .PreparedStatement, .ResultSet, .SQLException, java.util.ArrayList, javax.naming.Context, javax.sql.DataSource, org.apache.catalina.LifecycleException, .Server, org.apache.naming.ContextBindings
Implementation of Realm that works with any JDBC JNDI DataSource. See the Realm How-To for more details on how to set up the database and for configuration options.
Authors
Glenn L. Nielsen, Craig R. McClanahan, Carson McDonald, Ignacio Ortega

Field Summary

Modifier and TypeField and Description
private volatile boolean
connectionSuccess

Last connection attempt.

protected String
dataSourceName

The name of the JNDI JDBC DataSource

protected boolean
localDataSource

Context local datasource.

private String
preparedCredentials

The generated string for the credentials PreparedStatement

private String
preparedRoles

The generated string for the roles PreparedStatement

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.

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

Constructor Summary

AccessConstructor and Description
public
DataSourceRealm()

Method Summary

Modifier and TypeMethod and Description
public Principal
authenticate(String
Username of the Principal to look up
username, String
Password or other credentials to use in authenticating this username
credentials)

Overrides org.apache.catalina.realm.RealmBase.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Try to authenticate using the specified username and credentials.

protected Principal

Returns:

the associated principal, or null if there is none.
authenticate(Connection
The database connection to be used
dbConnection, String
Username of the Principal to look up
username, String
Password or other credentials to use in authenticating this username
credentials)

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

protected void
close(Connection
The connection to be closed
dbConnection)

Close the specified database connection.

public String

Returns:

the name of the JNDI JDBC DataSource.
getDataSourceName()

public boolean

Returns:

if the datasource will be looked up in the webapp JNDI Context.
getLocalDataSource()

protected String

Returns:

the password associated with the given principal's user name.
getPassword(String
The user name
username)

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

Get the password for the specified user.

protected String

Returns:

the password for the specified user
getPassword(Connection
The database connection to be used
dbConnection, String
Username for which password should be retrieved
username)

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

protected Principal

Returns:

the principal object
getPrincipal(String
the user name
username)

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

Return the Principal associated with the given user name.

public String

Returns:

the column in the user role table that names a role.
getRoleNameCol()

protected ArrayList<String>

Returns:

an array list of the role names
getRoles(String
User name for which roles should be retrieved
username)

Return the roles associated with the given user name.

protected ArrayList<String>

Returns:

an array list of the role names
getRoles(Connection
The database connection to be used
dbConnection, String
User name for which roles should be retrieved
username)

Return the roles associated with the given user name.

public String

Returns:

the column in the user table that holds the user's credentials.
getUserCredCol()

public String

Returns:

the column in the user table that holds the user's name.
getUserNameCol()

public String

Returns:

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

public String

Returns:

the table that holds user data..
getUserTable()

public boolean
isAvailable()

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

Return the availability of the realm for authentication.

private boolean
isRoleStoreDefined()

protected Connection

Returns:

Connection to the database
open()

Open the specified database connection.

public void
setDataSourceName(String
the name of the JNDI JDBC DataSource
dataSourceName)

Set the name of the JNDI JDBC DataSource.

public void
setLocalDataSource(boolean
the new flag value
localDataSource)

Set to true to cause the datasource to be looked up in the webapp JNDI Context.

public void
setRoleNameCol(String
The column name
roleNameCol)

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

public void
setUserCredCol(String
The column name
userCredCol)

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

public void
setUserNameCol(String
The column name
userNameCol)

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

public void
setUserRoleTable(String
The table name
userRoleTable)

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

public void
setUserTable(String
The table name
userTable)

Set the table that holds user data.

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

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

Field Detail

connectionSuccessback to summary
private volatile boolean connectionSuccess

Last connection attempt.

dataSourceNameback to summary
protected String dataSourceName

The name of the JNDI JDBC DataSource

localDataSourceback to summary
protected boolean localDataSource

Context local datasource.

preparedCredentialsback to summary
private String preparedCredentials

The generated string for the credentials PreparedStatement

preparedRolesback to summary
private String preparedRoles

The generated string for the roles PreparedStatement

roleNameColback to summary
protected String roleNameCol

The column in the user role table that names a role

userCredColback to summary
protected String userCredCol

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

userNameColback to summary
protected String userNameCol

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

userRoleTableback to summary
protected String userRoleTable

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

userTableback to summary
protected String userTable

The table that holds user data.

Constructor Detail

DataSourceRealmback to summary
public DataSourceRealm()

Method Detail

authenticateback to summary
public Principal authenticate(String username, String credentials)

Overrides org.apache.catalina.realm.RealmBase.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Doc from org.apache.catalina.Realm.authenticate.

Try to authenticate using the specified username and credentials.

If there are any errors with the JDBC connection, executing the query or anything this method returns null (doesn't authenticate). This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.

Parameters
username:String

Username of the Principal to look up

credentials:String

Password or other credentials to use in authenticating this username

Returns:Principal

the associated principal, or null if there is none

Annotations
@Override
authenticateback to summary
protected 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:Connection

The database connection to be used

username:String

Username of the Principal to look up

credentials:String

Password or other credentials to use in authenticating this username

Returns:Principal

the associated principal, or null if there is none.

closeback to summary
protected void close(Connection dbConnection)

Close the specified database connection.

Parameters
dbConnection:Connection

The connection to be closed

getDataSourceNameback to summary
public String getDataSourceName()
Returns:String

the name of the JNDI JDBC DataSource.

getLocalDataSourceback to summary
public boolean getLocalDataSource()
Returns:boolean

if the datasource will be looked up in the webapp JNDI Context.

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
getPasswordback to summary
protected String getPassword(Connection dbConnection, String username)

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

Parameters
dbConnection:Connection

The database connection to be used

username:String

Username for which password should be retrieved

Returns:String

the password for the specified user

getPrincipalback to summary
protected Principal getPrincipal(String username)

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

Return the Principal associated with the given user name.

Parameters
username:String

the user name

Returns:Principal

the principal object

Annotations
@Override
getRoleNameColback to summary
public String getRoleNameCol()
Returns:String

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

getRolesback to summary
protected ArrayList<String> getRoles(String username)

Return the roles associated with the given user name.

Parameters
username:String

User name for which roles should be retrieved

Returns:ArrayList<String>

an array list of the role names

getRolesback to summary
protected ArrayList<String> getRoles(Connection dbConnection, String username)

Return the roles associated with the given user name.

Parameters
dbConnection:Connection

The database connection to be used

username:String

User name for which roles should be retrieved

Returns:ArrayList<String>

an array list of the role names

getUserCredColback to summary
public String getUserCredCol()
Returns:String

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

getUserNameColback to summary
public String getUserNameCol()
Returns:String

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

getUserRoleTableback to summary
public String getUserRoleTable()
Returns:String

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

getUserTableback to summary
public String getUserTable()
Returns:String

the table that holds user data..

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
isRoleStoreDefinedback to summary
private boolean isRoleStoreDefined()
openback to summary
protected Connection open()

Open the specified database connection.

Returns:Connection

Connection to the database

setDataSourceNameback to summary
public void setDataSourceName(String dataSourceName)

Set the name of the JNDI JDBC DataSource.

Parameters
dataSourceName:String

the name of the JNDI JDBC DataSource

setLocalDataSourceback to summary
public void setLocalDataSource(boolean localDataSource)

Set to true to cause the datasource to be looked up in the webapp JNDI Context.

Parameters
localDataSource:boolean

the new flag value

setRoleNameColback to summary
public void setRoleNameCol(String roleNameCol)

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

Parameters
roleNameCol:String

The column name

setUserCredColback to summary
public void setUserCredCol(String userCredCol)

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

Parameters
userCredCol:String

The column name

setUserNameColback to summary
public void setUserNameCol(String userNameCol)

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

Parameters
userNameCol:String

The column name

setUserRoleTableback to summary
public void setUserRoleTable(String userRoleTable)

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

Parameters
userRoleTable:String

The table name

setUserTableback to summary
public void setUserTable(String userTable)

Set the table that holds user data.

Parameters
userTable:String

The table name

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