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 users = Context.getUserService().getAllUsers();
 

See Also:

Context

Method Summary

void	changePassword(java.lang.String pw, java.lang.String pw2) Changes the current user's password.
void	changePassword(User u, java.lang.String pw) Changes the user's password ** Restricted to Super User access**
void	changeQuestionAnswer(java.lang.String pw, java.lang.String q, java.lang.String a) Changes the current user's secret question and answer.
User	createUser(User user, java.lang.String password) Deprecated. replaced by saveUser(User, String)
void	deleteUser(User user) Deprecated. use purgeUser(User)
java.util.List<User>	findUsers(java.lang.String name, java.util.List<java.lang.String> roles, boolean includeVoided) Deprecated. use getUsers(String, List, boolean)
java.util.List<User>	findUsers(java.lang.String givenName, java.lang.String familyName, boolean includeVoided) Deprecated. use getUsersByName(String, String, boolean)
java.lang.String	generateSystemId() Get/generate/find the next system id to be doled out.
java.util.List<Privilege>	getAllPrivileges() Returns all privileges currently possible for any User
java.util.List<Role>	getAllRoles() Returns all roles currently possible for any User
java.util.List<User>	getAllUsers() Returns all users in the system
java.util.List<User>	getAllUsers(java.util.List<Role> roles, boolean includeVoided) Deprecated. use getUsers(String, List, boolean)
java.util.List<Role>	getInheritingRoles(Role role) Deprecated. use Role.getInheritedRoles()
Privilege	getPrivilege(java.lang.String p) Returns Privilege in the system with given String privilege
java.util.List<Privilege>	getPrivileges() Deprecated. use getAllPrivileges()
Role	getRole(java.lang.String r) Returns role object with given string role
java.util.List<Role>	getRoles() Deprecated. use getAllRoles()
User	getUser(java.lang.Integer userId) Get user by internal user identifier.
User	getUserByUsername(java.lang.String username) Get user by username (user's login identifier)
java.util.List<User>	getUsers() Deprecated. use getAllUsers()
java.util.List<User>	getUsers(java.lang.String nameSearch, java.util.List<Role> roles, boolean includeVoided) Return a user 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
java.util.List<User>	getUsersByName(java.lang.String givenName, java.lang.String familyName, boolean includeVoided) Search for a list of users by exact first name and last name.
java.util.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, java.lang.String answer) Compares answer against the user's secret answer.
void	purgePrivilege(Privilege privilege) Complete 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, java.lang.String key) Removes the property denoted by key from the user's properties.
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, java.lang.String password) Saves a user to the database.
User	setUserProperty(User user, java.lang.String key, java.lang.String value) Adds the key/value pair to the given user.
User	unvoidUser(User user) Clear voided flag for user (equivalent to an "undelete" or Lazarus Effect for user)
void	updateUser(User user) Deprecated. replaced by saveUser(User, String)
User	voidUser(User user, java.lang.String reason) 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.

Methods inherited from interface org.openmrs.api.OpenmrsService

onShutdown, onStartup

Method Detail

saveUser

@Authorized(value={"Add Users","Edit Users"})
User saveUser(User user,
                              java.lang.String password)
              throws APIException

Saves a user to the database.

Parameters:

user -

password -

Throws:

APIException

createUser

@Authorized(value="Add Users")
User createUser(User user,
                                java.lang.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(java.lang.Integer userId)
             throws APIException

Get user by internal user identifier.

Parameters:

userId - internal identifier

Returns:

requested user

Throws:

APIException

getUserByUsername

@Transactional(readOnly=true)
@Authorized(value="View Users")
User getUserByUsername(java.lang.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

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 - to compare

Returns:

boolean

Throws:

APIException

getUsersByRole

@Transactional(readOnly=true)
@Authorized(value="View Users")
java.util.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

updateUser

@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

@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

@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

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

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

unvoidUser

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

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

Parameters:

user -

Returns:

the given user unvoided

Throws:

APIException

deleteUser

@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

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

getPrivileges

@Transactional(readOnly=true)
java.util.List<Privilege> getPrivileges()
                                        throws APIException

Deprecated. use getAllPrivileges()

Throws:

APIException

getAllPrivileges

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

Returns all privileges currently possible for any User

Returns:

Global list of privileges

Throws:

APIException

getRoles

@Transactional(readOnly=true)
java.util.List<Role> getRoles()
                              throws APIException

Deprecated. use getAllRoles()

Throws:

APIException

getAllRoles

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

Returns all roles currently possible for any User

Returns:

Global list of roles

Throws:

APIException

getInheritingRoles

@Transactional(readOnly=true)
java.util.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 - to update

Returns:

the saved role

Throws:

APIException

purgeRole

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

Complete remove a role from the database

Parameters:

Role - to delete from the database

Throws:

APIException

savePrivilege

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

Save the given privilege in the database

Parameters:

Privilege - to update

Returns:

the saved privilege

Throws:

APIException

purgePrivilege

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

Complete remove a privilege from the database

Parameters:

Privilege - to delete

Throws:

APIException

getRole

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

Returns role object with given string role

Returns:

Role

Throws:

APIException

getPrivilege

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

Returns Privilege in the system with given String privilege

Returns:

Privilege

Throws:

APIException

getUsers

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

Deprecated. use getAllUsers()

Throws:

APIException

getAllUsers

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

Returns all users in the system

Returns:

Global list of users

Throws:

APIException

changePassword

@Authorized(value="Edit Users")
void changePassword(User u,
                                    java.lang.String pw)
                    throws APIException

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

Parameters:

u - user

pw2 - new password

Throws:

APIException

changePassword

void changePassword(java.lang.String pw,
                    java.lang.String pw2)
                    throws APIException

Changes the current user's password.

Parameters:

pw - current password

pw2 - new password

Throws:

APIException

changeQuestionAnswer

void changeQuestionAnswer(java.lang.String pw,
                          java.lang.String q,
                          java.lang.String a)
                          throws APIException

Changes the current user's secret question and answer.

Parameters:

pw - user's password

question -

answer -

Throws:

APIException

isSecretAnswer

@Transactional(readOnly=true)
boolean isSecretAnswer(User u,
                                     java.lang.String answer)
                       throws APIException

Compares answer against the user's secret answer.

Parameters:

user -

answer -

Throws:

APIException

getUsers

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

Return a user 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 -

roles -

includeVoided -

Returns:

Throws:

APIException

findUsers

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

Deprecated. use getUsers(String, List, boolean)

Throws:

APIException

findUsers

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

Deprecated. use getUsersByName(String, String, boolean)

Throws:

APIException

getUsersByName

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

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

Parameters:

givenName -

familyName -

includeVoided -

Returns:

Throws:

APIException

getAllUsers

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

Deprecated. use getUsers(String, List, boolean)

Throws:

APIException

setUserProperty

User setUserProperty(User user,
                     java.lang.String key,
                     java.lang.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

removeUserProperty

User removeUserProperty(User user,
                        java.lang.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

generateSystemId

java.lang.String generateSystemId()
                                  throws APIException

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

Returns:

new system id

Throws:

APIException