org.apache.james.userrepository
Class AbstractJdbcUsersRepository

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

All Implemented Interfaces:

org.apache.avalon.framework.activity.Initializable, org.apache.avalon.framework.component.Component, org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.framework.context.Contextualizable, org.apache.avalon.framework.logger.LogEnabled, org.apache.avalon.framework.service.Serviceable, UsersRepository

Direct Known Subclasses:

DefaultUsersJdbcRepository, JamesUsersJdbcRepository, ListUsersJdbcRepository

public abstract class AbstractJdbcUsersRepository
extends AbstractUsersRepository
implements org.apache.avalon.framework.context.Contextualizable, org.apache.avalon.framework.service.Serviceable, org.apache.avalon.framework.configuration.Configurable, 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 org.apache.avalon.framework.context.Context	context The Avalon context used by the instance
protected java.util.Map	m_sqlParameters

Fields inherited from interface org.apache.james.services.UsersRepository

ROLE, USER

Constructor Summary

AbstractJdbcUsersRepository()

Method Summary

void	configure(org.apache.avalon.framework.configuration.Configuration configuration) Configures the UserRepository for JDBC access.
void	contextualize(org.apache.avalon.framework.context.Context context)
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.
protected User	getUserByName(java.lang.String name, boolean ignoreCase) Gets a user by name, ignoring case if specified.
void	initialize() Initialises the JDBC 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	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.

Methods inherited from class org.apache.james.userrepository.AbstractUsersRepository

addUser, addUser, addUser, contains, containsCaseInsensitive, countUsers, getRealName, getUserByName, getUserByNameCaseInsensitive, list, removeUser, test, 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

Field Detail

context

protected org.apache.avalon.framework.context.Context context

The Avalon context used by the instance

m_sqlParameters

protected java.util.Map m_sqlParameters

Constructor Detail

AbstractJdbcUsersRepository

public AbstractJdbcUsersRepository()

Method Detail

contextualize

public void contextualize(org.apache.avalon.framework.context.Context context)
                   throws org.apache.avalon.framework.context.ContextException

Specified by:

contextualize in interface org.apache.avalon.framework.context.Contextualizable

Throws:

org.apache.avalon.framework.context.ContextException

See Also:

Contextualizable.contextualize(Context)

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:

org.apache.avalon.framework.service.Serviceable#compose(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

Throws:

org.apache.avalon.framework.configuration.ConfigurationException

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

listUserNames

protected java.util.List listUserNames()

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

Overrides:

listUserNames in class AbstractUsersRepository

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.

Specified by:

listAllUsers in class AbstractUsersRepository

Returns:

an Iterator of JamesUsers.

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 be added

doRemoveUser

protected void doRemoveUser(User user)

Removes a user from the underlying repository. If the user doesn't exist this method doesn't throw an exception.

Specified by:

doRemoveUser in class AbstractUsersRepository

Parameters:

user - the user to be removed

doUpdateUser

protected void doUpdateUser(User user)

Updates a user record to match the supplied User.

Specified by:

doUpdateUser in class AbstractUsersRepository

Parameters:

user - the updated user record

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.

Overrides:

getUserByName in class AbstractUsersRepository

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.