org.bonitasoft.engine.api

Interface UserAPI

All Known Subinterfaces:

IdentityAPI, IdentityAPI

public interface UserAPI

UserAPI forms part of the OrganizationAPI and gives access to all the Administration operations available on Users: creation, deletion, certain specific getXXX() methods, generic search methods, etc... It also to retrieve user ContactData.

Author:

Feng Hui, Matthieu Chaffotte, Emmanuel Duchastenier, Celine Souchet

See Also:

ContactData, SearchResult for general knowledege on Search mechanism in Bonita BPM.

Method Summary

Methods

Modifier and Type	Method and Description
User	createUser(String userName, String password) Creates a user.
User	createUser(String userName, String password, String firstName, String lastName) Creates a user.
User	createUser(UserCreator creator) Creates a user.
void	deleteUser(long userId) Deletes the user.
void	deleteUser(String userName) Deletes the user.
void	deleteUsers(List<Long> userIds) Deletes the users.
long	getNumberOfUsers() Returns the total number of users.
long	getNumberOfUsersInGroup(long groupId) Returns the total number of users of the group.
long	getNumberOfUsersInRole(long roleId) Returns the total number of users of the role.
User	getUser(long userId) Retrieves the user.
User	getUserByUserName(String userName) Retrieves the user.
ContactData	getUserContactData(long userId, boolean personal) Retrieves the contact data (personal or professional) of the user.
List<Long>	getUserIdsWithCustomUserInfo(String infoName, String infoValue, boolean usePartialMatch, int startIndex, int maxResults) Retrieves the list of user identifiers containing the chosen custom user information with the given value.
List<User>	getUsers(int startIndex, int maxResults, UserCriterion criterion) Retrieves the paginated list of users.
Map<Long,User>	getUsers(List<Long> userIds) Retrieves the users.
Map<String,User>	getUsersByUsernames(List<String> userNames) Retrieves the identifiers of the named users.
List<User>	getUsersInGroup(long groupId, int startIndex, int maxResults, UserCriterion criterion) Retrieves the paginated list of groups.
List<User>	getUsersInRole(long roleId, int startIndex, int maxResults, UserCriterion criterion) Retrieves the paginated list of roles.
UserWithContactData	getUserWithProfessionalDetails(long userId) Retrieves the professional details of the user.
SearchResult<User>	searchUsers(SearchOptions options) Searches users according to the criteria containing in the options.
User	updateUser(long userId, UserUpdater updater) Updates the user according to the updater values.

Method Detail

createUser

User createUser(String userName,
              String password)
                throws AlreadyExistsException,
                       CreationException

Creates a user. The password can't be empty.

Parameters:

userName - The name of the user

password - The password of the user

Returns:

The created user

Throws:

AlreadyExistsException - If the name is already taken by an existing user

CreationException - If an exception occurs during the user creation

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

createUser

User createUser(String userName,
              String password,
              String firstName,
              String lastName)
                throws AlreadyExistsException,
                       CreationException

Creates a user. The password can't be empty.

Parameters:

userName - The name of the user

password - The password of the user

firstName - The first name of the user

lastName - The last name of the user

Returns:

The created user

Throws:

AlreadyExistsException - If the name is already taken by an existing user

CreationException - If an exception occurs during the user creation

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

createUser

User createUser(UserCreator creator)
                throws AlreadyExistsException,
                       CreationException

Creates a user. It takes the values of the creator in order to create the user.

Parameters:

creator - The user to create

Returns:

The created user

Throws:

AlreadyExistsException - If the name is already taken by an existing user

CreationException - If an exception occurs during the user creation

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

updateUser

User updateUser(long userId,
              UserUpdater updater)
                throws UserNotFoundException,
                       UpdateException

Updates the user according to the updater values.

Parameters:

userId - The identifier of the user

updater - The user updater

Returns:

The updated user

Throws:

UserNotFoundException - If the user identifier does not refer to an existing user

UpdateException - If an exception occurs during the user update

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

deleteUser

void deleteUser(long userId)
                throws DeletionException

Deletes the user.

Use this method with caution: some artifacts like Applications and DesignProcessDefinitions may present display problems in the Bonita BPM Portal if the referenced user was deleted. Note that you can disable a user instead of deleting it. To do so, use the method updateUser(long, UserUpdater) to set the attribute 'enabled' to false

.

Parameters:

userId - The identifier of the user

Throws:

DeletionException - If an exception occurs during the user deletion

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

See Also:

updateUser(long, UserUpdater), Application, DesignProcessDefinition

deleteUser

void deleteUser(String userName)
                throws DeletionException

Deletes the user.

Use this method with caution: some artifacts like Applications and DesignProcessDefinitions may present display problems in the Bonita BPM Portal if the referenced user was deleted. Note that you can disable a user instead of deleting it. To do so, use the method updateUser(long, UserUpdater) to set the attribute 'enabled' to false

.

Parameters:

userName - The name of the user

Throws:

DeletionException - If an exception occurs during the user deletion

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

See Also:

updateUser(long, UserUpdater), Application, DesignProcessDefinition

deleteUsers

void deleteUsers(List<Long> userIds)
                 throws DeletionException

Deletes the users.

Use this method with caution: some artifacts like Applications and DesignProcessDefinitions may present display problems in the Bonita BPM Portal if the referenced user was deleted. Note that you can disable a user instead of deleting it. To do so, use the method updateUser(long, UserUpdater) to set the attribute 'enabled' to false

.

Parameters:

userIds - The identifiers of the users

Throws:

DeletionException - If an exception occurs during the user deletion

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

See Also:

updateUser(long, UserUpdater), Application, DesignProcessDefinition

getUser

User getUser(long userId)
             throws UserNotFoundException

Retrieves the user. It throws a UserNotFoundException if the user identifier equals the technical user identifier (-1).

Parameters:

userId - The identifier of the user

Returns:

The searched user

Throws:

UserNotFoundException - If the user identifier does not refer to an existing user

RetrieveException - If an exception occurs during the user retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUserByUserName

User getUserByUserName(String userName)
                       throws UserNotFoundException

Retrieves the user.

Parameters:

userName - The name of the user

Returns:

The role

Throws:

UserNotFoundException - If the user name does not refer to an existing user

RetrieveException - If an exception occurs during the role retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUserWithProfessionalDetails

UserWithContactData getUserWithProfessionalDetails(long userId)
                                                   throws UserNotFoundException

Retrieves the professional details of the user.

Parameters:

userId - The identifier of the user

Returns:

The user and the professional details

Throws:

UserNotFoundException - If the user identifier does not refer to an existing user, or is -1 (the technical user identifier)

RetrieveException - If an exception occurs while retrieving the user

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.1

getUserContactData

ContactData getUserContactData(long userId,
                             boolean personal)
                               throws UserNotFoundException

Retrieves the contact data (personal or professional) of the user.

Parameters:

userId - The identifier of the user

personal - true if the contact data is the personal one

Returns:

The contact data

Throws:

UserNotFoundException - If the user name does not refer to an existing user

RetrieveException - If an exception occurs during the role retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getNumberOfUsers

long getNumberOfUsers()

Returns the total number of users.

Returns:

The total number of users

Throws:

RetrieveException - If an exception occurs during the count retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUsers

List<User> getUsers(int startIndex,
                  int maxResults,
                  UserCriterion criterion)

Retrieves the paginated list of users. It retrieves from the startIndex to the startIndex + maxResults.

Parameters:

startIndex - The start index

maxResults - The max number of users

criterion - The sorting criterion

Returns:

The paginated list of users

Throws:

RetrieveException - If an exception occurs during the user retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUsers

Map<Long,User> getUsers(List<Long> userIds)

Retrieves the users. The map contains the couples userId/User. If a user does not exists, no exception is thrown and no value is added in the map.

Parameters:

userIds - The identifiers of the users

Returns:

The users

Throws:

RetrieveException - If an exception occurs during the user retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUsersByUsernames

Map<String,User> getUsersByUsernames(List<String> userNames)

Retrieves the identifiers of the named users. The map contains the couples userName/User. If a user does not exists, no exception is thrown and no value is added in the map.

Parameters:

userNames - The names of the users

Returns:

The users ordered by the user name ascending

Throws:

RetrieveException - If an exception occurs during the user retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.1

searchUsers

SearchResult<User> searchUsers(SearchOptions options)
                               throws SearchException

Searches users according to the criteria containing in the options.

Parameters:

options - The search criteria

Returns:

The search result

Throws:

SearchException - If an exception occurs during the user searching

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getNumberOfUsersInRole

long getNumberOfUsersInRole(long roleId)

Returns the total number of users of the role.

Parameters:

roleId - The identifier of the role

Returns:

The total number of users of the role

Throws:

RetrieveException - If an exception occurs during the count retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUsersInRole

List<User> getUsersInRole(long roleId,
                        int startIndex,
                        int maxResults,
                        UserCriterion criterion)

Retrieves the paginated list of roles. It retrieves from the startIndex to the startIndex + maxResults.

Parameters:

roleId - The identifier of the role

startIndex - The start index

maxResults - The max number of roles

criterion - The sorting criterion

Returns:

The paginated list of roles

Throws:

RetrieveException - If an exception occurs during the role retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getNumberOfUsersInGroup

long getNumberOfUsersInGroup(long groupId)
                             throws BonitaException

Returns the total number of users of the group.

Parameters:

groupId - The identifier of the group

Returns:

The total number of users of the group

Throws:

BonitaException

RetrieveException - If an exception occurs during the count retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUsersInGroup

List<User> getUsersInGroup(long groupId,
                         int startIndex,
                         int maxResults,
                         UserCriterion criterion)

Retrieves the paginated list of groups. It retrieves from the startIndex to the startIndex + maxResults.

Parameters:

groupId - The identifier of the group

startIndex - The start index

maxResults - The max number of groups

criterion - The sorting criterion

Returns:

The paginated list of groups

Throws:

RetrieveException - If an exception occurs during the group retrieving

InvalidSessionException - If the session is invalid (expired, unknown, ...)

Since:

6.0

getUserIdsWithCustomUserInfo

List<Long> getUserIdsWithCustomUserInfo(String infoName,
                                      String infoValue,
                                      boolean usePartialMatch,
                                      int startIndex,
                                      int maxResults)

Retrieves the list of user identifiers containing the chosen custom user information with the given value.

Parameters:

infoName - The custom user information name

infoValue - The custom user information value

usePartialMatch - Defines whether the custom user information value should use a partial match.

startIndex - The start index (the first valid value is zero)

maxResults - The max number of user identifiers to be retrieved

Returns:

the list of user identifiers containing the chosen custom user information with the given value.

Since:

6.3.2