org.jasig.services.persondir.support

Class AbstractQueryPersonAttributeDao<QB>

java.lang.Object

org.jasig.services.persondir.support.BasePersonAttributeDao

org.jasig.services.persondir.support.AbstractFlatteningPersonAttributeDao

org.jasig.services.persondir.support.AbstractDefaultAttributePersonAttributeDao

org.jasig.services.persondir.support.AbstractQueryPersonAttributeDao<QB>

All Implemented Interfaces:

IPersonAttributeDao

Direct Known Subclasses:

AbstractJdbcPersonAttributeDao, ComplexStubPersonAttributeDao, LdapPersonAttributeDao, LdaptivePersonAttributeDao

public abstract class AbstractQueryPersonAttributeDao<QB>
extends AbstractDefaultAttributePersonAttributeDao

Provides common functionality for DAOs using a set of attribute values from the seed to perform a query. Ensures the nessesary attributes to run the query exist on the seed and organizes the values into an argument array.

Configuration:

Property	Description	Required	Default
queryAttributeMapping	A Map from attribute names used in the query Map to attribute names to use in the SQL. The values can be either String or Collection of String to use a single Map attribute under multiple names as in the SQL. If set only Map attributes listed will be used in the SQL. If not set all Map attributes are used as-is in the SQL.	No	null
resultAttributeMapping	A Map from SQL result names to returned attribute names. The values can be either String or Collection of String to use a single SQL result under multiple returned attributes. If set only SQL attributes listed will be returned. If not set all SQL attributes will be returned.	No	null
requireAllQueryAttributes	If the SQL should only be run if all attributes listed in the queryAttributeMapping exist in the query Map. Ignored if queryAttributeMapping is null	No	false
unmappedUsernameAttribute	The unmapped username attribute returned by the query. If null the value returned by the configured IUsernameAttributeProvider is used.	No	null

Version:

$Revision$

Author:

Eric Dalquist

Field Summary

Fields

Modifier and Type	Field and Description
static CaseCanonicalizationMode	DEFAULT_CASE_CANONICALIZATION_MODE
static CaseCanonicalizationMode	DEFAULT_USERNAME_CASE_CANONICALIZATION_MODE

Fields inherited from class org.jasig.services.persondir.support.BasePersonAttributeDao

logger

Fields inherited from interface org.jasig.services.persondir.IPersonAttributeDao

WILDCARD, WILDCARD_PATTERN

Constructor Summary

Constructors

Constructor and Description
AbstractQueryPersonAttributeDao()

Method Summary

Modifier and Type	Method and Description
protected abstract QB	appendAttributeToQuery(QB queryBuilder, String dataAttribute, List<Object> queryValues) Append the attribute and value to the queryBuilder.
protected QB	appendCanonicalizedAttributeToQuery(QB queryBuilder, String queryAttribute, String dataAttribute, List<Object> queryValues) Append the attribute and its canonicalized value/s to the queryBuilder.
protected List<Object>	canonicalizeAttribute(String key, List<Object> value, Map<String,CaseCanonicalizationMode> config) Canonicalize the attribute values if they are present in the config map.
protected QB	generateQuery(Map<String,List<Object>> query) Generates a query using the queryBuilder object passed by the subclass.
Set<String>	getAvailableQueryAttributes()
Locale	getCaseCanonicalizationLocale() Returns the Locale in which all casing canonicalizations will occur.
Map<String,CaseCanonicalizationMode>	getCaseInsensitiveQueryAttributes()
Map<String,CaseCanonicalizationMode>	getCaseInsensitiveResultAttributes()
protected String	getConfiguredUserNameAttribute() Indicates which attribute found by the subclass should be taken as the 'username' attribute.
CaseCanonicalizationMode	getDefaultCaseCanonicalizationMode() Returns the default CaseCanonicalizationMode.
protected abstract List<IPersonAttributes>	getPeopleForQuery(QB queryBuilder, String queryUserName) Executes the query for the generated queryBuilder object and returns a list where each entry is a Map of attributes for a single IPersonAttributes.
Set<IPersonAttributes>	getPeopleWithMultivaluedAttributes(Map<String,List<Object>> query)
Set<String>	getPossibleUserAttributeNames()
Map<String,Set<String>>	getQueryAttributeMapping()
Map<String,Set<String>>	getResultAttributeMapping()
String	getUnmappedUsernameAttribute() Returns the userNameAttribute
CaseCanonicalizationMode	getUsernameCaseCanonicalizationMode()
boolean	isRequireAllQueryAttributes()
boolean	isUseAllQueryAttributes()
protected boolean	isUserNameAttributeConfigured() Indicates whether the value from getConfiguredUserNameAttribute() was configured explicitly.
protected IPersonAttributes	mapPersonAttributes(IPersonAttributes person) Uses resultAttributeMapping to return a copy of the IPersonAttributes with only the attributes specified in resultAttributeMapping mapped to their result attribute names.
void	setCaseCanonicalizationLocale(Locale caseCanonicalizationLocale) Assign the Locale in which all casing canonicalizations will occur.
void	setCaseInsensitiveQueryAttributes(Map<String,CaseCanonicalizationMode> caseInsensitiveQueryAttributes) Keys are app-layer attributes, values are the casing canonicalization modes for each, as applied when mapping from an application layer query to a data layer query.
void	setCaseInsensitiveQueryAttributesAsCollection(Collection<String> caseInsensitiveQueryAttributes) Configuration convenience same as passing the given Set as the keys in the setCaseInsensitiveQueryAttributes(java.util.Map) Map and implicitly accepting the default canonicalization mode for each.
void	setCaseInsensitiveResultAttributes(Map<String,CaseCanonicalizationMode> caseInsensitiveResultAttributes) Keys are app-layer attributes, values are the casing canonicalization modes for each, as applied when mapping from data-layer to application attributes.
void	setCaseInsensitiveResultAttributesAsCollection(Collection<String> caseInsensitiveResultAttributes) Configuration convenience same as passing the given Set as the keys in the setCaseInsensitiveResultAttributes(java.util.Map) Map and implicitly accepting the default canonicalization mode for each.
void	setDefaultCaseCanonicalizationMode(CaseCanonicalizationMode defaultCaseCanonicalizationMode) Override the default CaseCanonicalizationMode (DEFAULT_CASE_CANONICALIZATION_MODE).
void	setQueryAttributeMapping(Map<String,?> queryAttributeMapping) Map from query attribute names to data-layer attribute names to use when building the query.
void	setRequireAllQueryAttributes(boolean requireAllQueryAttributes) If all attributes specified in the queryAttributeMapping keySet must be present to actually run the query
void	setResultAttributeMapping(Map<String,?> resultAttributeMapping) Set the Map to use for mapping from a data layer name to an attribute name or Set of attribute names.
void	setUnmappedUsernameAttribute(String userNameAttribute) The returned attribute to use as the userName for the mapped IPersons.
void	setUseAllQueryAttributes(boolean useAllQueryAttributes) If setQueryAttributeMapping(Map) is null this determines if no parameters should be specified or if all query attributes should be used as parameters.
void	setUsernameCaseCanonicalizationMode(CaseCanonicalizationMode usernameCaseCanonicalizationMode) Username canonicalization is a special case because mapPersonAttributes(org.jasig.services.persondir.IPersonAttributes) doesn't know where it came from.

Methods inherited from class org.jasig.services.persondir.support.AbstractDefaultAttributePersonAttributeDao

getPerson, getUsernameAttributeProvider, setUsernameAttributeProvider, toSeedMap

Methods inherited from class org.jasig.services.persondir.support.AbstractFlatteningPersonAttributeDao

getPeople, toMultivaluedSeed

Methods inherited from class org.jasig.services.persondir.support.BasePersonAttributeDao

flattenResults, getMultivaluedUserAttributes, getMultivaluedUserAttributes, getUserAttributes, getUserAttributes

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CASE_CANONICALIZATION_MODE

public static final CaseCanonicalizationMode DEFAULT_CASE_CANONICALIZATION_MODE

DEFAULT_USERNAME_CASE_CANONICALIZATION_MODE

public static final CaseCanonicalizationMode DEFAULT_USERNAME_CASE_CANONICALIZATION_MODE

Constructor Detail

AbstractQueryPersonAttributeDao

public AbstractQueryPersonAttributeDao()

Method Detail

isUseAllQueryAttributes

public boolean isUseAllQueryAttributes()

setUseAllQueryAttributes

public void setUseAllQueryAttributes(boolean useAllQueryAttributes)

If setQueryAttributeMapping(Map) is null this determines if no parameters should be specified or if all query attributes should be used as parameters. Defaults to true.

Parameters:

useAllQueryAttributes - True to use all query attributes as parameters

getQueryAttributeMapping

public Map<String,Set<String>> getQueryAttributeMapping()

Returns:

the queryAttributeMapping

setQueryAttributeMapping

public void setQueryAttributeMapping(Map<String,?> queryAttributeMapping)

Map from query attribute names to data-layer attribute names to use when building the query. If an ordered Map is passed in the order of the attributes will be honored when building the query. If not set query attributes will be used directly from the query Map.

Parameters:

queryAttributeMapping - the queryAttributeMapping to set

getResultAttributeMapping

public Map<String,Set<String>> getResultAttributeMapping()

Returns:

the resultAttributeMapping

setResultAttributeMapping

public void setResultAttributeMapping(Map<String,?> resultAttributeMapping)

Set the Map to use for mapping from a data layer name to an attribute name or Set of attribute names. Data layer names that are specified but have null mappings will use the column name for the attribute name. Data layer names that are not specified as keys in this Map will be ignored.
The passed Map must have keys of type String and values of type String or a Set of String.

Parameters:

resultAttributeMapping - Map from column names to attribute names, may not be null.

Throws:

IllegalArgumentException - If the Map doesn't follow the rules stated above.

See Also:

MultivaluedPersonAttributeUtils.parseAttributeToAttributeMapping(Map)

isRequireAllQueryAttributes

public boolean isRequireAllQueryAttributes()

Returns:

the requireAllQueryAttributes

setRequireAllQueryAttributes

public void setRequireAllQueryAttributes(boolean requireAllQueryAttributes)

If all attributes specified in the queryAttributeMapping keySet must be present to actually run the query

Parameters:

requireAllQueryAttributes - the requireAllQueryAttributes to set

getUnmappedUsernameAttribute

public String getUnmappedUsernameAttribute()

Returns the userNameAttribute

Returns:

the userNameAttribute

setUnmappedUsernameAttribute

public void setUnmappedUsernameAttribute(String userNameAttribute)

The returned attribute to use as the userName for the mapped IPersons. If null the AbstractDefaultAttributePersonAttributeDao.getUsernameAttributeProvider() value will be used and if that is null the AttributeNamedPersonImpl.DEFAULT_USER_NAME_ATTRIBUTE value is used.

Parameters:

userNameAttribute - the userNameAttribute to set

getPeopleWithMultivaluedAttributes

public final Set<IPersonAttributes> getPeopleWithMultivaluedAttributes(Map<String,List<Object>> query)

getAvailableQueryAttributes

public Set<String> getAvailableQueryAttributes()

getPossibleUserAttributeNames

public Set<String> getPossibleUserAttributeNames()

getPeopleForQuery

protected abstract List<IPersonAttributes> getPeopleForQuery(QB queryBuilder,
                                                             String queryUserName)

Executes the query for the generated queryBuilder object and returns a list where each entry is a Map of attributes for a single IPersonAttributes.

Parameters:

queryBuilder - The query generated by calls to appendAttributeToQuery(Object, String, List)

queryUserName - The username passed in the query map, if no username attribute existed in the query Map null is provided.

Returns:

The list of IPersons found by the query. The user attributes should be using the raw names from the data layer.

appendCanonicalizedAttributeToQuery

protected QB appendCanonicalizedAttributeToQuery(QB queryBuilder,
                                                 String queryAttribute,
                                                 String dataAttribute,
                                                 List<Object> queryValues)

Append the attribute and its canonicalized value/s to the queryBuilder. Uses queryAttribute to determine whether or not the value/s should be canonicalized. I.e. the behavior is controlled by setCaseInsensitiveQueryAttributes(java.util.Map).

This method is only concerned with canonicalizing the query attribute value. It is still up to the subclass to canonicalize the data-layer attribute value prior to comparison, if necessary. For example, if the data layer is a case-sensitive relational database and attributes therein are stored in mixed case, but comparison should be case-insensitive, the relational column reference would need to be wrapped in a lower() or upper() function. (This, of course, needs to be handled with care, since it can lead to table scanning if the store does not support function-based indexes.) Such data-layer canonicalization would be unnecessary if the data layer is case-insensitive or stores values in the same canonicalized form as has been configured for the app-layer attribute. See AbstractJdbcPersonAttributeDao.setCaseInsensitiveDataAttributes(java.util.Map)

Parameters:

queryBuilder - The sub-class specific query builder object

queryAttribute - The full attribute name to append

dataAttribute - The full attribute name to append

queryValues - The values for the data attribute

Returns:

An updated queryBuilder

appendAttributeToQuery

protected abstract QB appendAttributeToQuery(QB queryBuilder,
                                             String dataAttribute,
                                             List<Object> queryValues)

Append the attribute and value to the queryBuilder.

Parameters:

queryBuilder - The sub-class specific query builder object

dataAttribute - The full attribute name to append

queryValues - The values for the data attribute

Returns:

An updated queryBuilder

generateQuery

protected final QB generateQuery(Map<String,List<Object>> query)

Generates a query using the queryBuilder object passed by the subclass. Attribute/Value pairs are added to the queryBuilder by calling appendCanonicalizedAttributeToQuery(Object, String, String, java.util.List) which calls appendAttributeToQuery(Object, String, java.util.List). Attributes are only added if there is an attributed mapped in the queryAttributeMapping.

Parameters:

query - The query Map to populate the queryBuilder with.

Returns:

The fully populated query builder.

mapPersonAttributes

protected final IPersonAttributes mapPersonAttributes(IPersonAttributes person)

Uses resultAttributeMapping to return a copy of the IPersonAttributes with only the attributes specified in resultAttributeMapping mapped to their result attribute names.

Parameters:

person - The IPersonAttributes to map attributes for

Returns:

A copy of the IPersonAttributes with mapped attributes, the original IPersonAttributes if resultAttributeMapping is null.

canonicalizeAttribute

protected List<Object> canonicalizeAttribute(String key,
                                             List<Object> value,
                                             Map<String,CaseCanonicalizationMode> config)

Canonicalize the attribute values if they are present in the config map.

Parameters:

key - attribute key

value - list of attribute values

config - map of attribute names to canonicalization key for the attribute

Returns:

if configured to do so, returns a canonicalized list of values.

getConfiguredUserNameAttribute

protected String getConfiguredUserNameAttribute()

Indicates which attribute found by the subclass should be taken as the 'username' attribute. (E.g. 'uid' or 'sAMAccountName') NOTE: Any two instances if BasePersonImpl with the same username are considered equal. Since AbstractDefaultAttributePersonAttributeDao.getUsernameAttributeProvider() should never return null, this method should never return null either.

Returns:

The name of the attribute corresponding to the user's username.

isUserNameAttributeConfigured

protected boolean isUserNameAttributeConfigured()

Indicates whether the value from getConfiguredUserNameAttribute() was configured explicitly. A return value of false means that the value from getConfiguredUserNameAttribute() is a default, and should not be used over a username passed in the query.

Returns:

true If the 'unmappedUsernameAttribute' property was set explicitly, otherwise false

getCaseInsensitiveResultAttributes

public Map<String,CaseCanonicalizationMode> getCaseInsensitiveResultAttributes()

Returns:

Map of attribute names and casing canonicalization modes

See Also:

setCaseInsensitiveResultAttributes(java.util.Map)

setCaseInsensitiveResultAttributes

public void setCaseInsensitiveResultAttributes(Map<String,CaseCanonicalizationMode> caseInsensitiveResultAttributes)

Keys are app-layer attributes, values are the casing canonicalization modes for each, as applied when mapping from data-layer to application attributes. null values treated as DEFAULT_CASE_CANONICALIZATION_MODE unless that default mode is overridden with setDefaultCaseCanonicalizationMode(org.jasig.services.persondir.util.CaseCanonicalizationMode).

Most commonly used for canonicalizing attributes used as unique identifiers, usually username. In that case it's a good idea to set that configuration here as well as via setUsernameCaseCanonicalizationMode(org.jasig.services.persondir.util.CaseCanonicalizationMode) to ensure you don't end up with different results from Principal.getName() and IPersonAttributes.getAttributeValue(String).

This config is separate from setCaseInsensitiveQueryAttributes(java.util.Map) because you may want to support case-insensitive searching on data layer attributes, but respond with attribute values which preserve the original data layer casing.

Parameters:

caseInsensitiveResultAttributes - Map of result attribute names and casing canonicalization modes

setCaseInsensitiveResultAttributesAsCollection

public void setCaseInsensitiveResultAttributesAsCollection(Collection<String> caseInsensitiveResultAttributes)

Configuration convenience same as passing the given Set as the keys in the setCaseInsensitiveResultAttributes(java.util.Map) Map and implicitly accepting the default canonicalization mode for each. Note that this setter will not assign canonicalization modes, meaning that you needn't ensure setDefaultCaseCanonicalizationMode(org.jasig.services.persondir.util.CaseCanonicalizationMode) has already been called.

Parameters:

caseInsensitiveResultAttributes - Set of result attribute names

setCaseInsensitiveQueryAttributesAsCollection

public void setCaseInsensitiveQueryAttributesAsCollection(Collection<String> caseInsensitiveQueryAttributes)

Configuration convenience same as passing the given Set as the keys in the setCaseInsensitiveQueryAttributes(java.util.Map) Map and implicitly accepting the default canonicalization mode for each. Note that this setter will not assign canonicalization modes, meaning that you needn't ensure setDefaultCaseCanonicalizationMode(org.jasig.services.persondir.util.CaseCanonicalizationMode) has already been called.

Parameters:

caseInsensitiveQueryAttributes - Set of query attribute names

setCaseInsensitiveQueryAttributes

public void setCaseInsensitiveQueryAttributes(Map<String,CaseCanonicalizationMode> caseInsensitiveQueryAttributes)

Keys are app-layer attributes, values are the casing canonicalization modes for each, as applied when mapping from an application layer query to a data layer query. null values treated as DEFAULT_CASE_CANONICALIZATION_MODE unless that default mode is overridden with setDefaultCaseCanonicalizationMode(org.jasig.services.persondir.util.CaseCanonicalizationMode).

Use this for any attribute for which you'd like to support case-insensitive search and where the underlying data layer is case-sensitive. Of course, if the data layer does not store these attributes in the canonical casing, the data layer itself would also need to be canonicalized in a subclass-specific fashion. For example, see AbstractJdbcPersonAttributeDao.setCaseInsensitiveDataAttributes(java.util.Map).

This config is separate from setCaseInsensitiveResultAttributes(java.util.Map) because you may want to support case-insensitive searching on data layer attributes, but respond with attribute values which preserve the original data layer casing.

Parameters:

caseInsensitiveQueryAttributes - Map of query attribute names and casing canonicalization modes

getCaseInsensitiveQueryAttributes

public Map<String,CaseCanonicalizationMode> getCaseInsensitiveQueryAttributes()

Returns:

Map of query attribute names and casing canonicalization modes

See Also:

setCaseInsensitiveQueryAttributes(java.util.Map)

setCaseCanonicalizationLocale

public void setCaseCanonicalizationLocale(Locale caseCanonicalizationLocale)

Assign the Locale in which all casing canonicalizations will occur. A null will be treated as Locale.getDefault().

Parameters:

caseCanonicalizationLocale - Case-canonicalization locale

getCaseCanonicalizationLocale

public Locale getCaseCanonicalizationLocale()

Returns the Locale in which all casing canonicalizations will occur.

Returns:

Case-canonicalization locale

setDefaultCaseCanonicalizationMode

public void setDefaultCaseCanonicalizationMode(CaseCanonicalizationMode defaultCaseCanonicalizationMode)

Override the default CaseCanonicalizationMode (DEFAULT_CASE_CANONICALIZATION_MODE). Cannot be unset. A null will have the same effect as reverting to the default.

Parameters:

defaultCaseCanonicalizationMode - Set the default CaseCanonicalizationMode

getDefaultCaseCanonicalizationMode

public CaseCanonicalizationMode getDefaultCaseCanonicalizationMode()

Returns the default CaseCanonicalizationMode.

Returns:

Default CaseCanonicalizationMode

setUsernameCaseCanonicalizationMode

public void setUsernameCaseCanonicalizationMode(CaseCanonicalizationMode usernameCaseCanonicalizationMode)

Username canonicalization is a special case because mapPersonAttributes(org.jasig.services.persondir.IPersonAttributes) doesn't know where it came from. It might have come from a data layer attribute. Or it might have been derived from the original query itself. There is no general way to query the IPersonAttributes to determine exactly what happened.

If you need to guarantee case-insensitive usernames in Principal.getName(), set this property to the same mode that you set for your app-layer username attribute(s) via setCaseInsensitiveResultAttributes(java.util.Map).

Otherwise, leave this property alone and no attempt will be made to canonicalize the value returned from Principal.getName()

That default behavior is consistent with the legacy behavior of being case sensitive w/r/t usernames.

Parameters:

usernameCaseCanonicalizationMode - CaseCanonicalizationMode to use for the username

getUsernameCaseCanonicalizationMode

public CaseCanonicalizationMode getUsernameCaseCanonicalizationMode()

Returns:

The CaseCanonicalizationMode to use for the username

See Also:

setUsernameCaseCanonicalizationMode(org.jasig.services.persondir.util.CaseCanonicalizationMode)