com.atlassian.crowd.embedded.spi
Interface UserDao

public interface UserDao

Responsible for the persistence and retrieval of Users, PasswordCredentials and user attributes.

Method Summary

User	add(User user, com.atlassian.crowd.embedded.api.PasswordCredential credential) Creates a new user with the given details and credentials.
BatchResult<User>	addAll(Set<UserTemplateWithCredentialAndAttributes> users) Bulk add users.
TimestampedUser	findByExternalId(long directoryId, String externalId) Finds and returns the user with the given unique/external id and directory ID.
TimestampedUser	findByName(long directoryId, String userName) Finds and returns the user with the given name and directory ID.
UserWithAttributes	findByNameWithAttributes(long directoryId, String userName) Finds and returns the user with attributes with the given name and directory ID.
com.atlassian.crowd.embedded.api.PasswordCredential	getCredential(long directoryId, String userName) Returns the credential for the given user.
List<com.atlassian.crowd.embedded.api.PasswordCredential>	getCredentialHistory(long directoryId, String userName) Returns the previous credentials for the given user, starting with the oldest.
void	remove(User user) Removes the user.
BatchResult<String>	removeAllUsers(long directoryId, Set<String> userNames) Bulk remove all the given users from directory.
void	removeAttribute(User user, String attributeName) Removes the attributes for the user with the given name.
User	rename(User user, String newName) Changes the user's name to the provided new name.
<T> List<T>	search(long directoryId, EntityQuery<T> query) Returns users matching the search query in the given directory, ordered by name.
void	storeAttributes(User user, Map<String,Set<String>> attributes) Adds or updates a user's attributes with the new Map of attribute values.
User	update(User user) Updates all the user properties (except the username) of the user with the same directory and case-insensitive name.
void	updateCredential(User user, com.atlassian.crowd.embedded.api.PasswordCredential credential, int maxCredentialHistory) Updates the credential (password) of the user with the same directory and case-insensitive name.

Method Detail

findByName

TimestampedUser findByName(long directoryId,
                           String userName)
                           throws com.atlassian.crowd.exception.UserNotFoundException

Finds and returns the user with the given name and directory ID.

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user could not be found

findByExternalId

TimestampedUser findByExternalId(long directoryId,
                                 String externalId)
                                 throws com.atlassian.crowd.exception.UserNotFoundException

Finds and returns the user with the given unique/external id and directory ID.

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user could not be found

findByNameWithAttributes

UserWithAttributes findByNameWithAttributes(long directoryId,
                                            String userName)
                                            throws com.atlassian.crowd.exception.UserNotFoundException

Finds and returns the user with attributes with the given name and directory ID.

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user could not be found

getCredential

com.atlassian.crowd.embedded.api.PasswordCredential getCredential(long directoryId,
                                                                  String userName)
                                                                  throws com.atlassian.crowd.exception.UserNotFoundException

Returns the credential for the given user. It will always be encrypted.

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user could not be found

getCredentialHistory

List<com.atlassian.crowd.embedded.api.PasswordCredential> getCredentialHistory(long directoryId,
                                                                               String userName)
                                                                               throws com.atlassian.crowd.exception.UserNotFoundException

Returns the previous credentials for the given user, starting with the oldest. May be an empty list if there are no historical credentials.

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user could not be found

add

User add(User user,
         com.atlassian.crowd.embedded.api.PasswordCredential credential)
         throws com.atlassian.crowd.exception.UserAlreadyExistsException,
                IllegalArgumentException,
                com.atlassian.crowd.exception.DirectoryNotFoundException

Creates a new user with the given details and credentials. The user details cannot be null, but the credential can be.

Parameters:

user - the user to create

credential - the encrypted password for the user, which may be null if the user's password is not yet available

Returns:

the newly created user

Throws:

com.atlassian.crowd.exception.UserAlreadyExistsException - if a user with the same directory and name (case-insensitive) already exists

IllegalArgumentException - if the user name, directory or any details are null, or if the credential is not encrypted

com.atlassian.crowd.exception.DirectoryNotFoundException

storeAttributes

void storeAttributes(User user,
                     Map<String,Set<String>> attributes)
                     throws com.atlassian.crowd.exception.UserNotFoundException

Adds or updates a user's attributes with the new Map of attribute values. The attributes map represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing attribute. Attributes with values of empty sets in the attributes parameter are removed from the user.

Parameters:

user - the user to store attributes for

attributes - new or updated attributes (attributes that don't need changing should not appear in this Map).

Throws:

com.atlassian.crowd.exception.UserNotFoundException - user with supplied username does not exist.

update

User update(User user)
            throws com.atlassian.crowd.exception.UserNotFoundException,
                   IllegalArgumentException

Updates all the user properties (except the username) of the user with the same directory and case-insensitive name.

When the username itself changes then the rename(User, String) method is called first, and this method may be called afterwards if other details (eg email or display name) have also changed.

Even if the username is changed in case only (eg from "mary" to "Mary") then the rename() method will be called first. This implies that the implementation of this method should only need to change the cwd_user table.

Parameters:

user - the user details, which should have the same name as the user to modify

Returns:

the updated user

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if there is no user with the same name (case-insensitive) and directory as the user provided

IllegalArgumentException - if the user name, directory or any details are null

See Also:

rename(User, String)

updateCredential

void updateCredential(User user,
                      com.atlassian.crowd.embedded.api.PasswordCredential credential,
                      int maxCredentialHistory)
                      throws com.atlassian.crowd.exception.UserNotFoundException,
                             IllegalArgumentException

Updates the credential (password) of the user with the same directory and case-insensitive name. The credential must be encrypted.

Parameters:

user - the user whose password will be modified

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if there is no user with the same name (case-insensitive) and directory as the user provided

IllegalArgumentException - if the credential is null or not encrypted

rename

User rename(User user,
            String newName)
            throws com.atlassian.crowd.exception.UserNotFoundException,
                   com.atlassian.crowd.exception.UserAlreadyExistsException,
                   IllegalArgumentException

Changes the user's name to the provided new name.

This method will be called for any change to a username including a case-only change (eg from "alice" to "Alice"). If there are changes to the username as well as to other user properties (eg email, display name) then callers must call the rename() method first followed by the update() method.

Implementations of this method will normally need to update the cwd_user table as well as cwd_membership, whereas the update() method implies a change to only the cwd_user table.

Parameters:

user - the user to rename

newName - the new name of the user

Returns:

the updated user

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user cannot be found

com.atlassian.crowd.exception.UserAlreadyExistsException - if the new name is already used by a different user

IllegalArgumentException - if the new name is null

See Also:

update(User)

removeAttribute

void removeAttribute(User user,
                     String attributeName)
                     throws com.atlassian.crowd.exception.UserNotFoundException

Removes the attributes for the user with the given name. Does nothing if the attribute doesn't exist.

Parameters:

user - the user whose attribute will be removed

attributeName - the name of the attribute to be removed

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user cannot be found

remove

void remove(User user)
            throws com.atlassian.crowd.exception.UserNotFoundException

Removes the user.

Parameters:

user - the user to remove

Throws:

com.atlassian.crowd.exception.UserNotFoundException - if the user does not exist

search

<T> List<T> search(long directoryId,
                   EntityQuery<T> query)

Returns users matching the search query in the given directory, ordered by name. Returns an empty list if no users match.

Type Parameters:

T - the type of objects to return, which is normally either User or String

Parameters:

directoryId - the ID of the directory to search

query - the search query

Returns:

the list of matching users, or an empty list if no users match

addAll

BatchResult<User> addAll(Set<UserTemplateWithCredentialAndAttributes> users)

Bulk add users. Implementations must make sure that changes in bulk methods such as this are immediately visible to other bulk methods. For example, if this is run in a transaction, either that transaction must be committed when this method returns, or all other bulk method implementations must guarantee to reuse the same transaction.

Parameters:

users - to be added

Returns:

a list of Users that failed to be added

removeAllUsers

BatchResult<String> removeAllUsers(long directoryId,
                                   Set<String> userNames)

Bulk remove all the given users from directory. Implementations must make sure that changes in bulk methods such as this are immediately visible to other bulk methods. For example, if this is run in a transaction, either that transaction must be committed when this method returns, or all other bulk method implementations must guarantee to reuse the same transaction.

Parameters:

directoryId - the ID of the directory to remove users from

userNames - set of users to be removed

Returns:

batch result containing successes (removed users) and failures (users which were not removed)