org.apache.james.userrepository
Class AbstractJdbcUsersRepository

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.james.impl.jamesuser.AbstractUsersRepository
          org.apache.james.userrepository.AbstractJdbcUsersRepository

All Implemented Interfaces:

org.apache.avalon.framework.activity.Initializable, org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.framework.logger.LogEnabled, org.apache.avalon.framework.service.Serviceable, UsersRepository, VirtualUserTable, JamesUsersRepository

Direct Known Subclasses:

DefaultUsersJdbcRepository, JamesUsersJdbcRepository, ListUsersJdbcRepository

public abstract class AbstractJdbcUsersRepository
extends AbstractUsersRepository
implements org.apache.avalon.framework.service.Serviceable, org.apache.avalon.framework.activity.Initializable

An abstract base class for creating UserRepository implementations which use a database for persistence. To implement a new UserRepository using by extending this class, you need to implement the 3 abstract methods defined below, and define the required SQL statements in an SQLResources file. The SQL statements used by this implementation are:

	Required
select	Select all users.
insert	Insert a user.
update	Update a user.
delete	Delete a user by name.
createTable	Create the users table.
	Optional
selectByLowercaseName	Select a user by name (case-insensitive lowercase).

Field Summary

protected java.util.Map

m_sqlParameters

Fields inherited from class org.apache.james.impl.jamesuser.AbstractUsersRepository

enableAliases, enableForwarding, ignoreCase

Fields inherited from interface org.apache.james.api.user.UsersRepository

ROLE, USER

Fields inherited from interface org.apache.james.api.vut.VirtualUserTable

ALIASDOMAIN_PREFIX, ERROR_PREFIX, REGEX_PREFIX, ROLE

Constructor Summary

AbstractJdbcUsersRepository()

Method Summary

void	configure(org.apache.avalon.framework.configuration.Configuration configuration) Configures the UserRepository for JDBC access. Requires a configuration element in the .conf.xml file of the form:
boolean	contains(java.lang.String name) Returns whether or not this user is in the repository
boolean	containsCaseInsensitive(java.lang.String name) Returns whether or not this user is in the repository.
int	countUsers() Returns a count of the users in the repository.
protected void	doAddUser(User user) Adds a user to the underlying Repository.
protected void	doRemoveUser(User user) Removes a user from the underlying repository.
protected void	doUpdateUser(User user) Updates a user record to match the supplied User.
java.lang.String	getRealName(java.lang.String name) Returns the user name of the user matching name on an equalsIgnoreCase basis.
User	getUserByName(java.lang.String name) Get the user object with the specified user name.
protected User	getUserByName(java.lang.String name, boolean ignoreCase) Gets a user by name, ignoring case if specified.
User	getUserByNameCaseInsensitive(java.lang.String name) Get the user object with the specified user name.
protected User	getUserByNameIterating(java.lang.String name, boolean ignoreCase) Gets a user by name, ignoring case if specified.
void	initialize() Initialises the JDBC repository.
java.util.Iterator	list() List users in repository.
protected java.util.Iterator	listAllUsers() Returns a list populated with all of the Users in the repository.
protected java.util.List	listUserNames() Produces the complete list of User names, with correct case.
protected abstract User	readUserFromResultSet(java.sql.ResultSet rsUsers) Reads properties for a User from an open ResultSet.
void	removeUser(java.lang.String userName) Removes a user from the repository
void	service(org.apache.avalon.framework.service.ServiceManager componentManager)
protected abstract void	setUserForInsertStatement(User user, java.sql.PreparedStatement userInsert) Set parameters of a PreparedStatement object with property values from a User instance.
protected abstract void	setUserForUpdateStatement(User user, java.sql.PreparedStatement userUpdate) Set parameters of a PreparedStatement object with property values from a User instance.
boolean	test(java.lang.String name, java.lang.String password) Test if user with name 'name' has password 'password'.

Methods inherited from class org.apache.james.impl.jamesuser.AbstractUsersRepository

addUser, addUser, getMappings, setEnableAliases, setEnableForwarding, setIgnoreCase, updateUser

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.james.api.user.UsersRepository

addUser

Field Detail

m_sqlParameters

protected java.util.Map m_sqlParameters

Constructor Detail

AbstractJdbcUsersRepository

public AbstractJdbcUsersRepository()

Method Detail

removeUser

public void removeUser(java.lang.String userName)

Removes a user from the repository

Specified by:

removeUser in interface UsersRepository

Parameters:

userName - the user to be removed

getUserByName

public User getUserByName(java.lang.String name)

Get the user object with the specified user name. Return null if no such user.

Specified by:

getUserByName in interface UsersRepository

Parameters:

name - the name of the user to retrieve

Returns:

the user if found, null otherwise

Since:

James 1.2.2

getUserByNameCaseInsensitive

public User getUserByNameCaseInsensitive(java.lang.String name)

Get the user object with the specified user name. Match user naems on a case insensitive basis. Return null if no such user.

Specified by:

getUserByNameCaseInsensitive in interface UsersRepository

Parameters:

name - the name of the user to retrieve

Returns:

the user if found, null otherwise

Since:

James 1.2.2

getRealName

public java.lang.String getRealName(java.lang.String name)

Returns the user name of the user matching name on an equalsIgnoreCase basis. Returns null if no match.

Specified by:

getRealName in interface UsersRepository

Parameters:

name - the name of the user to retrieve

Returns:

the correct case sensitive name of the user

contains

public boolean contains(java.lang.String name)

Returns whether or not this user is in the repository

Specified by:

contains in interface UsersRepository

Parameters:

name - the name to check in the repository

Returns:

true or false

containsCaseInsensitive

public boolean containsCaseInsensitive(java.lang.String name)

Returns whether or not this user is in the repository. Names are matched on a case insensitive basis.

Specified by:

containsCaseInsensitive in interface UsersRepository

Parameters:

name - the name to check in the repository

Returns:

true or false

test

public boolean test(java.lang.String name,
                    java.lang.String password)

Test if user with name 'name' has password 'password'.

Specified by:

test in interface UsersRepository

Parameters:

name - the name of the user to be tested

password - the password to be tested

Returns:

true if the test is successful, false if the password is incorrect or the user doesn't exist

Since:

James 1.2.2

countUsers

public int countUsers()

Returns a count of the users in the repository.

Specified by:

countUsers in interface UsersRepository

Returns:

the number of users in the repository

list

public java.util.Iterator list()

List users in repository.

Specified by:

list in interface UsersRepository

Returns:

Iterator over a collection of Strings, each being one user in the repository.

service

public void service(org.apache.avalon.framework.service.ServiceManager componentManager)
             throws org.apache.avalon.framework.service.ServiceException

Specified by:

service in interface org.apache.avalon.framework.service.Serviceable

Throws:

org.apache.avalon.framework.service.ServiceException

See Also:

Serviceable.service(ServiceManager)

configure

public void configure(org.apache.avalon.framework.configuration.Configuration configuration)
               throws org.apache.avalon.framework.configuration.ConfigurationException

Configures the UserRepository for JDBC access.

Requires a configuration element in the .conf.xml file of the form:

   <repository name="LocalUsers"
       class="org.apache.james.userrepository.JamesUsersJdbcRepository">
       <!-- Name of the datasource to use -->
       <data-source>MailDb</data-source>
       <!-- File to load the SQL definitions from -->
       <sqlFile>dist/conf/sqlResources.xml</sqlFile>
       <!-- replacement parameters for the sql file -->
       <sqlParameters table="JamesUsers"/>
   </repository>
 

Specified by:

configure in interface org.apache.avalon.framework.configuration.Configurable

Overrides:

configure in class AbstractUsersRepository

Throws:

org.apache.avalon.framework.configuration.ConfigurationException

See Also:

Configurable.configure(Configuration)

initialize

public void initialize()
                throws java.lang.Exception

Initialises the JDBC repository.

1) Tests the connection to the database.

2) Loads SQL strings from the SQL definition file, choosing the appropriate SQL for this connection, and performing parameter substitution,

3) Initialises the database with the required tables, if necessary.

Specified by:

initialize in interface org.apache.avalon.framework.activity.Initializable

Throws:

java.lang.Exception - if an error occurs

See Also:

Initializable.initialize()

listUserNames

protected java.util.List listUserNames()

Produces the complete list of User names, with correct case.

Returns:

a List of Strings representing user names.

listAllUsers

protected java.util.Iterator listAllUsers()

Returns a list populated with all of the Users in the repository.

Returns:

an Iterator of Users.

doAddUser

protected void doAddUser(User user)

Adds a user to the underlying Repository. The user name must not clash with an existing user.

Specified by:

doAddUser in class AbstractUsersRepository

Parameters:

user - the user to add

doRemoveUser

protected void doRemoveUser(User user)

Removes a user from the underlying repository. If the user doesn't exist, returns ok.

Parameters:

user - the user to remove

doUpdateUser

protected void doUpdateUser(User user)

Updates a user record to match the supplied User.

Specified by:

doUpdateUser in class AbstractUsersRepository

Parameters:

user - the user to update

getUserByNameIterating

protected User getUserByNameIterating(java.lang.String name,
                                      boolean ignoreCase)

Gets a user by name, ignoring case if specified. This implementation gets the entire set of users, and scrolls through searching for one matching name.

Parameters:

name - the name of the user being retrieved

ignoreCase - whether the name is regarded as case-insensitive

Returns:

the user being retrieved, null if the user doesn't exist

getUserByName

protected User getUserByName(java.lang.String name,
                             boolean ignoreCase)

Gets a user by name, ignoring case if specified. If the specified SQL statement has been defined, this method overrides the basic implementation in AbstractUsersRepository to increase performance.

Parameters:

name - the name of the user being retrieved

ignoreCase - whether the name is regarded as case-insensitive

Returns:

the user being retrieved, null if the user doesn't exist

readUserFromResultSet

protected abstract User readUserFromResultSet(java.sql.ResultSet rsUsers)
                                       throws java.sql.SQLException

Reads properties for a User from an open ResultSet. Subclass implementations of this method must have knowledge of the fields presented by the "select" and "selectByLowercaseName" SQL statements. These implemenations may generate a subclass-specific User instance.

Parameters:

rsUsers - A ResultSet with a User record in the current row.

Returns:

A User instance

Throws:

java.sql.SQLException - if an exception occurs reading from the ResultSet

setUserForInsertStatement

protected abstract void setUserForInsertStatement(User user,
                                                  java.sql.PreparedStatement userInsert)
                                           throws java.sql.SQLException

Set parameters of a PreparedStatement object with property values from a User instance. Implementations of this method have knowledge of the parameter ordering of the "insert" SQL statement definition.

Parameters:

user - a User instance, which should be an implementation class which is handled by this Repostory implementation.

userInsert - a PreparedStatement initialised with SQL taken from the "insert" SQL definition.

Throws:

java.sql.SQLException - if an exception occurs while setting parameter values.

setUserForUpdateStatement

protected abstract void setUserForUpdateStatement(User user,
                                                  java.sql.PreparedStatement userUpdate)
                                           throws java.sql.SQLException

Set parameters of a PreparedStatement object with property values from a User instance. Implementations of this method have knowledge of the parameter ordering of the "update" SQL statement definition.

Parameters:

user - a User instance, which should be an implementation class which is handled by this Repostory implementation.

userUpdate - a PreparedStatement initialised with SQL taken from the "update" SQL definition.

Throws:

java.sql.SQLException - if an exception occurs while setting parameter values.