org.openmrs.api

Interface UserService

All Superinterfaces:

OpenmrsService

All Known Implementing Classes:

UserServiceImpl

@Transactional
public interface UserService
extends OpenmrsService

Contains methods pertaining to Users in the system Use:

 
 List<User> users = Context.getUserService().getAllUsers();
 

See Also:

Context

Method Summary

Modifier and Type	Method and Description
void	changeHashedPassword(User user, String hashedPassword, String salt) Changes the current user's password directly.
void	changePassword(String pw, String pw2) Changes the current user's password.
void	changePassword(User u, String pw) Changes the user's password ** Restricted to Super User access**
void	changeQuestionAnswer(String pw, String q, String a) Changes the current user's secret question and answer.
void	changeQuestionAnswer(User u, String question, String answer) Changes the passed user's secret question and answer.
User	createUser(User user, String password) Deprecated. replaced by saveUser(User, String)
void	deleteUser(User user) Deprecated. use purgeUser(User)
List<User>	findUsers(String name, List<String> roles, boolean includeVoided) Deprecated. use getUsers(String, List, boolean)
List<User>	findUsers(String givenName, String familyName, boolean includeVoided) Deprecated. use getUsersByName(String, String, boolean)
String	generateSystemId() Get/generate/find the next system id to be doled out.
List<Privilege>	getAllPrivileges() Returns all privileges currently possible for any User
List<Role>	getAllRoles() Returns all roles currently possible for any User
List<User>	getAllUsers() Returns all users in the system
List<User>	getAllUsers(List<Role> roles, boolean includeVoided) Deprecated. use getUsers(String, List, boolean)
Integer	getCountOfUsers(String name, List<Role> roles, boolean includeRetired) Return the number of users with a matching name or system id and have at least one of the given roles assigned to them
List<Role>	getInheritingRoles(Role role) Deprecated. use Role.getInheritedRoles()
Privilege	getPrivilege(String p) Returns Privilege in the system with given String privilege
Privilege	getPrivilegeByUuid(String uuid) Get Privilege by its UUID
List<Privilege>	getPrivileges() Deprecated. use getAllPrivileges()
Role	getRole(String r) Returns role object with given string role
Role	getRoleByUuid(String uuid) Get Role by its UUID
List<Role>	getRoles() Deprecated. use getAllRoles()
User	getUser(Integer userId) Get user by internal user identifier.
User	getUserByUsername(String username) Get user by username (user's login identifier)
User	getUserByUuid(String uuid) Get user by the given uuid.
List<User>	getUsers() Deprecated. use getAllUsers()
List<User>	getUsers(String nameSearch, List<Role> roles, boolean includeVoided) Return a list of users sorted by personName (see PersonByNameComparator) if any part of the search matches first/last/system id and the user has one at least one of the given roles assigned to them
List<User>	getUsers(String name, List<Role> roles, boolean includeRetired, Integer start, Integer length) Return a batch of users of a specific size sorted by personName (see PersonByNameComparator) if any part of the search matches first/last/system id and the user has one at least one of the given roles assigned to them.
List<User>	getUsersByName(String givenName, String familyName, boolean includeVoided) Search for a list of users by exact first name and last name.
List<User>	getUsersByPerson(Person person, boolean includeRetired) Get all user accounts that belong to a given person.
List<User>	getUsersByRole(Role role) Get users by role granted
void	grantUserRole(User user, Role role) Deprecated. use User.addRole(Role)
boolean	hasDuplicateUsername(User user) true/false if username or systemId is already in db in username or system_id columns
boolean	isSecretAnswer(User u, String answer) Compares answer against the user's secret answer.
void	notifyPrivilegeListeners(User user, String privilege, boolean hasPrivilege) Notifies privilege listener beans about any privilege check.
void	purgePrivilege(Privilege privilege) Completely remove a privilege from the database
void	purgeRole(Role role) Complete remove a role from the database
void	purgeUser(User user) Completely remove a location from the database (not reversible).
void	purgeUser(User user, boolean cascade) Completely remove a user from the database (not reversible).
User	removeUserProperty(User user, String key) Removes the property denoted by key from the user's properties.
User	retireUser(User user, String reason) Deactive a user account so that it can no longer log in.
void	revokeUserRole(User user, Role role) Deprecated. use User.removeRole(Role)
Privilege	savePrivilege(Privilege privilege) Save the given privilege in the database
Role	saveRole(Role role) Save the given role in the database
User	saveUser(User user, String password) Saves a user to the database.
User	setUserProperty(User user, String key, String value) Adds the key/value pair to the given user.
User	unretireUser(User user) Clears retired flag for a user.
User	unvoidUser(User user) Deprecated. use unretireUser(User)
void	updateUser(User user) Deprecated. replaced by saveUser(User, String)
User	voidUser(User user, String reason) Deprecated. use retireUser(User, String)

Methods inherited from interface org.openmrs.api.OpenmrsService

onShutdown, onStartup

Method Detail

saveUser

@Authorized(value={"Add Users","Edit Users"})
 @Logging(ignoredArgumentIndexes=1)
User saveUser(User user,
                                                                                                String password)
                                                                                         throws APIException

Saves a user to the database.

Parameters:

user -

password -

Returns:

a User object

Throws:

APIException

Should:

create new user with basic elements, should create user who is patient already, update users username, grant new roles in roles list to user, fail to create the user with a weak password

createUser

@Deprecated
 @Authorized(value="Add Users")
 @Logging(ignoredArgumentIndexes=1)
User createUser(User user,
                                                                                                String password)
                                                                                         throws APIException

Deprecated. replaced by saveUser(User, String)

Throws:

APIException

See Also:

saveUser(User, String)

getUser

@Transactional(readOnly=true)
 @Authorized(value="View Users")
User getUser(Integer userId)
                                                                     throws APIException

Get user by internal user identifier.

Parameters:

userId - internal identifier

Returns:

requested user

Throws:

APIException

Should:

fetch user with given userId

getUserByUuid

@Transactional(readOnly=true)
 @Authorized(value="View Users")
User getUserByUuid(String uuid)
                                                                           throws APIException

Get user by the given uuid.

Parameters:

uuid -

Returns:

Throws:

APIException

Should:

fetch user with given uuid, find object given valid uuid, return null if no object found with given uuid

getUserByUsername

@Transactional(readOnly=true)
 @Authorized(value="View Users")
User getUserByUsername(String username)
                                                                               throws APIException

Get user by username (user's login identifier)

Parameters:

username - user's identifier used for authentication

Returns:

requested user

Throws:

APIException

Should:

get user by username

hasDuplicateUsername

@Transactional(readOnly=true)
 @Authorized(value="View Users")
boolean hasDuplicateUsername(User user)
                                                                                     throws APIException

true/false if username or systemId is already in db in username or system_id columns

Parameters:

user - User to compare

Returns:

boolean

Throws:

APIException

Should:

verify that username and system id is unique

getUsersByRole

@Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getUsersByRole(Role role)
                                                                                  throws APIException

Get users by role granted

Parameters:

role - Role that the Users must have to be returned

Returns:

users with requested role

Throws:

APIException

Should:

fetch users assigned given role, not fetch user that does not belong to given role

updateUser

@Deprecated
 @Authorized(value="Edit Users")
void updateUser(User user)
                                                      throws APIException

Deprecated. replaced by saveUser(User, String)

Save changes to given user to the database.

Parameters:

user -

Throws:

APIException

See Also:

saveUser(User, String)

grantUserRole

@Deprecated
 @Authorized(value="Edit Users")
void grantUserRole(User user,
                                                                Role role)
                                                         throws APIException

Deprecated. use User.addRole(Role)

Use should be UserService.saveUser(user.addRole(role))

Throws:

APIException

revokeUserRole

@Deprecated
 @Authorized(value="Edit Users")
void revokeUserRole(User user,
                                                                 Role role)
                                                          throws APIException

Deprecated. use User.removeRole(Role)

Use UserService.saveUser(user.removeRole(role))

Throws:

APIException

voidUser

@Deprecated
 @Authorized(value="Edit Users")
User voidUser(User user,
                                                           String reason)
                                                    throws APIException

Deprecated. use retireUser(User, String)

Mark user as voided (effectively deleting user without removing their data — since anything the user touched in the database will still have their internal identifier and point to the voided user for historical tracking purposes.

Parameters:

user -

reason -

Returns:

the given user voided out

Throws:

APIException

Should:

void user and set attributes

unvoidUser

@Deprecated
 @Authorized(value="Edit Users")
User unvoidUser(User user)
                                                      throws APIException

Deprecated. use unretireUser(User)

Clear voided flag for user (equivalent to an "undelete" or Lazarus Effect for user)

Parameters:

user -

Returns:

the given user unvoided

Throws:

APIException

Should:

unvoid and unmark all attributes

retireUser

@Authorized(value="Edit Users")
User retireUser(User user,
                                                String reason)
                                         throws APIException

Deactive a user account so that it can no longer log in.

Parameters:

user -

reason -

Throws:

APIException

Should:

retire user and set attributes

unretireUser

@Authorized(value="Edit Users")
User unretireUser(User user)
                                           throws APIException

Clears retired flag for a user.

Parameters:

user -

reason -

Throws:

APIException

Should:

unretire and unmark all attributes

deleteUser

@Deprecated
 @Authorized(value="Delete Users")
void deleteUser(User user)
                                                        throws APIException

Deprecated. use purgeUser(User)

Throws:

APIException

See Also:

voidUser(User, String), purgeUser(User)

purgeUser

@Authorized(value="Purge Users")
void purgeUser(User user)
                                         throws APIException

Completely remove a location from the database (not reversible). This method delegates to #purgeLocation(location, boolean) method.

Parameters:

user - the User to remove from the database.

Throws:

APIException

Should:

delete given user

purgeUser

@Authorized(value="Purge Users")
void purgeUser(User user,
                                                boolean cascade)
                                         throws APIException

Completely remove a user from the database (not reversible). This is a delete from the database. This is included for troubleshooting and low-level system administration. Ideally, this method should never be called — Users should be voided and not deleted altogether (since many foreign key constraints depend on users, deleting a user would require deleting all traces, and any historical trail would be lost). This method only clears user roles and attempts to delete the user record. If the user has been included in any other parts of the database (through a foreign key), the attempt to delete the user will violate foreign key constraints and fail.

Parameters:

cascade - true to delete associated content

Throws:

APIException

Should:

throw APIException if cascade is true, delete given user when cascade equals false, not delete user roles for given user when cascade equals false

getPrivileges

@Deprecated
 @Transactional(readOnly=true)
List<Privilege> getPrivileges()
                                                                  throws APIException

Deprecated. use getAllPrivileges()

Throws:

APIException

getAllPrivileges

@Transactional(readOnly=true)
List<Privilege> getAllPrivileges()
                                                        throws APIException

Returns all privileges currently possible for any User

Returns:

Global list of privileges

Throws:

APIException

Should:

return all privileges in the system

getRoles

@Deprecated
 @Transactional(readOnly=true)
List<Role> getRoles()
                                                        throws APIException

Deprecated. use getAllRoles()

Throws:

APIException

getAllRoles

@Transactional(readOnly=true)
List<Role> getAllRoles()
                                              throws APIException

Returns all roles currently possible for any User

Returns:

Global list of roles

Throws:

APIException

Should:

return all roles in the system

getInheritingRoles

@Deprecated
 @Transactional(readOnly=true)
List<Role> getInheritingRoles(Role role)
                                                                  throws APIException

Deprecated. use Role.getInheritedRoles()

Throws:

APIException

saveRole

@Authorized(value="Manage Roles")
Role saveRole(Role role)
                                         throws APIException

Save the given role in the database

Parameters:

role - Role to update

Returns:

the saved role

Throws:

APIException

Should:

throw error if role inherits from itself, save given role to the database

purgeRole

@Authorized(value="Purge Roles")
void purgeRole(Role role)
                                         throws APIException

Complete remove a role from the database

Parameters:

role - Role to delete from the database

Throws:

APIException

Should:

throw error when role is a core role, return if role is null, delete given role from database

savePrivilege

@Authorized(value="Manage Privileges")
Privilege savePrivilege(Privilege privilege)
                                                        throws APIException

Save the given privilege in the database

Parameters:

privilege - Privilege to update

Returns:

the saved privilege

Throws:

APIException

Should:

save given privilege to the database

purgePrivilege

@Authorized(value="Purge Privileges")
void purgePrivilege(Privilege privilege)
                                                   throws APIException

Completely remove a privilege from the database

Parameters:

privilege - Privilege to delete

Throws:

APIException

Should:

delete given privilege from the database, throw error when privilege is core privilege

getRole

@Transactional(readOnly=true)
Role getRole(String r)
                                    throws APIException

Returns role object with given string role

Returns:

Role object for specified string

Throws:

APIException

Should:

fetch role for given role name

getRoleByUuid

@Transactional(readOnly=true)
Role getRoleByUuid(String uuid)
                                          throws APIException

Get Role by its UUID

Parameters:

uuid -

Returns:

Throws:

APIException

Should:

find object given valid uuid, return null if no object found with given uuid

getPrivilege

@Transactional(readOnly=true)
Privilege getPrivilege(String p)
                                              throws APIException

Returns Privilege in the system with given String privilege

Returns:

Privilege

Throws:

APIException

Should:

fetch privilege for given name

getPrivilegeByUuid

@Transactional(readOnly=true)
Privilege getPrivilegeByUuid(String uuid)
                                                    throws APIException

Get Privilege by its UUID

Parameters:

uuid -

Returns:

Throws:

APIException

Should:

find object given valid uuid, return null if no object found with given uuid, fetch privilege for given uuid

getUsers

@Deprecated
 @Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getUsers()
                                                                                         throws APIException

Deprecated. use getAllUsers()

Throws:

APIException

getAllUsers

@Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getAllUsers()
                                                                               throws APIException

Returns all users in the system

Returns:

Global list of users

Throws:

APIException

Should:

fetch all users in the system, not contains any duplicate users

changePassword

@Authorized(value="Edit User Passwords")
 @Logging(ignoredArgumentIndexes=1)
void changePassword(User u,
                                                                                                 String pw)
                                                                                          throws APIException

Changes the user's password ** Restricted to Super User access**

Parameters:

u - user

pw - new password

Throws:

APIException

Should:

change password for the given user and password

changePassword

@Logging(ignoredArgumentIndexes={0,1})
void changePassword(String pw,
                                                           String pw2)
                                                    throws APIException

Changes the current user's password.

Parameters:

pw - current password

pw2 - new password

Throws:

APIException

Should:

match on correctly hashed sha1 stored password, match on incorrectly hashed sha1 stored password, match on sha512 hashed password, be able to update password multiple times

changeHashedPassword

@Authorized(value="Edit User Passwords")
void changeHashedPassword(User user,
                                                                   String hashedPassword,
                                                                   String salt)
                                                            throws APIException

Changes the current user's password directly. This is most useful if migrating users from other systems and you want to retain the existing passwords. This method will simply save the passed hashed password and salt directly to the database.

Parameters:

user - the user whose password you want to change

hashedPassword - - the already hashed password to store

salt - - the salt which should be used with this hashed password

Throws:

APIException

Since:

1.5

Should:

change the hashed password for the given user

changeQuestionAnswer

@Authorized(value="Edit User Passwords")
 @Logging(ignoredArgumentIndexes={1,2})
void changeQuestionAnswer(User u,
                                                                                                           String question,
                                                                                                           String answer)
                                                                                                    throws APIException

Changes the passed user's secret question and answer.

Parameters:

u - User to change

question -

answer -

Throws:

APIException

Since:

1.5

Should:

change the secret question and answer for given user

changeQuestionAnswer

@Logging(ignoreAllArgumentValues=true)
void changeQuestionAnswer(String pw,
                                                                 String q,
                                                                 String a)
                                                          throws APIException

Changes the current user's secret question and answer.

Parameters:

pw - user's password

q - question

a - answer

Throws:

APIException

Should:

match on correctly hashed stored password, match on incorrectly hashed stored password

isSecretAnswer

@Transactional(readOnly=true)
 @Logging(ignoredArgumentIndexes=1)
boolean isSecretAnswer(User u,
                                                                                         String answer)
                                                                                  throws APIException

Compares answer against the user's secret answer.

Parameters:

u - user

answer -

Throws:

APIException

Should:

return true when given answer matches stored secret answer, return false when given answer does not match the stored secret answer

getUsers

@Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getUsers(String nameSearch,
                                                                                   List<Role> roles,
                                                                                   boolean includeVoided)
                                                                            throws APIException

Return a list of users sorted by personName (see PersonByNameComparator) if any part of the search matches first/last/system id and the user has one at least one of the given roles assigned to them

Parameters:

nameSearch - string to compare to the beginning of user's given/middle/family/family2 names

roles - all the Roles the user must contain

includeVoided - true/false whether to include voided users

Returns:

list of users matching the given attributes

Throws:

APIException

Should:

match search to familyName2, fetch voided users if includedVoided is true, not fetch voided users if includedVoided is false, fetch users with name that contains given nameSearch, fetch users with systemId that contains given nameSearch, fetch users with at least one of the given role objects, not fetch duplicate users, fetch all users if nameSearch is empty or null, not fail if roles are searched but name is empty

findUsers

@Deprecated
 @Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> findUsers(String name,
                                                                                                 List<String> roles,
                                                                                                 boolean includeVoided)
                                                                                          throws APIException

Deprecated. use getUsers(String, List, boolean)

Throws:

APIException

findUsers

@Deprecated
 @Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> findUsers(String givenName,
                                                                                                 String familyName,
                                                                                                 boolean includeVoided)
                                                                                          throws APIException

Deprecated. use getUsersByName(String, String, boolean)

Throws:

APIException

getUsersByName

@Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getUsersByName(String givenName,
                                                                                         String familyName,
                                                                                         boolean includeVoided)
                                                                                  throws APIException

Search for a list of users by exact first name and last name.

Parameters:

givenName -

familyName -

includeVoided -

Returns:

List object of users matching criteria

Throws:

APIException

Should:

fetch users exactly matching the given givenName and familyName, fetch voided users whenincludeVoided is true, not fetch any voided users when includeVoided is false, not fetch any duplicate users

getUsersByPerson

@Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getUsersByPerson(Person person,
                                                                                           boolean includeRetired)
                                                                                    throws APIException

Get all user accounts that belong to a given person.

Parameters:

person -

includeRetired -

Returns:

all user accounts that belong to person, including retired ones if specified

Throws:

APIException

Should:

fetch all accounts for a person when include retired is true, not fetch retired accounts when include retired is false

getAllUsers

@Deprecated
 @Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getAllUsers(List<Role> roles,
                                                                                                   boolean includeVoided)
                                                                                            throws APIException

Deprecated. use getUsers(String, List, boolean)

Throws:

APIException

setUserProperty

User setUserProperty(User user,
                     String key,
                     String value)
              throws APIException

Adds the key/value pair to the given user.

Implementations of this method should handle privileges

Parameters:

user -

key -

value -

Returns:

the user that was passed in and added to

Throws:

APIException

Should:

return null if user is null, throw error when user is not authorized to edit users, add property with given key and value when key does not already exist, modify property with given key and value when key already exists

removeUserProperty

User removeUserProperty(User user,
                        String key)
                 throws APIException

Removes the property denoted by key from the user's properties. Implementations of this method should handle privileges

Parameters:

user -

key -

Returns:

the user that was passed in and removed from

Throws:

APIException

Should:

return null if user is null, throw error when user is not authorized to edit users, remove user property for given user and key

generateSystemId

String generateSystemId()

Get/generate/find the next system id to be doled out. Assume check digit /not/ applied in this method

Returns:

new system id

getUsers

@Transactional(readOnly=true)
 @Authorized(value="View Users")
List<User> getUsers(String name,
                                                                                   List<Role> roles,
                                                                                   boolean includeRetired,
                                                                                   Integer start,
                                                                                   Integer length)
                                                                            throws APIException

Return a batch of users of a specific size sorted by personName (see PersonByNameComparator) if any part of the search matches first/last/system id and the user has one at least one of the given roles assigned to them. If start and length are not specified, then all matches are returned, If name is empty or null, then all all users will be returned taking into consideration the values of start and length arguments.

Parameters:

name - string to compare to the beginning of user's given/middle/family/family2 names

roles - all the Roles the user must contain

includeRetired - true/false whether to include voided users

start - beginning index for the batch

length - number of users to return in the batch

Returns:

list of matching users of a size based on the specified arguments

Throws:

APIException

Since:

1.8

Should:

return users whose roles inherit requested roles

getCountOfUsers

@Transactional(readOnly=true)
 @Authorized(value="View Users")
Integer getCountOfUsers(String name,
                                                                                       List<Role> roles,
                                                                                       boolean includeRetired)

Return the number of users with a matching name or system id and have at least one of the given roles assigned to them

Parameters:

name - patient name

roles - all the Roles the user must contain

includeRetired - Specifies whether voided users should be included

Returns:

the number of users matching the given attributes

Since:

1.8

notifyPrivilegeListeners

@Transactional(readOnly=true)
void notifyPrivilegeListeners(User user,
                                                            String privilege,
                                                            boolean hasPrivilege)

Notifies privilege listener beans about any privilege check.

It is called by UserContext.hasPrivilege(java.lang.String).

Parameters:

user - the authenticated user or null if not authenticated

privilege - the checked privilege

hasPrivilege - true if the authenticated user has the required privilege or if it is a proxy privilege

Since:

1.8.4, 1.9.1, 1.10

See Also:

PrivilegeListener